Rewrite the spec in Bikeshed

[zgroza]

For a while now I wanted to rewrite this spec in Bikeshed, here it is! This gives us a pre-compiled, static HTML spec that loads way faster and doesn't rely on client-side JS to render.

Most of this is just changing the language while maintaining the same content, however there are a few changes:

• Variable Types: Bikeshed's linter isn't a fan of ReSpec's inline |var:Type| syntax. I refactored those into standard prose (Let |var| of type {{Type}}) to keep the hyperlinked types without upsetting the compiler.
• Note Titles: Bikeshed ignores HTML title attributes on <aside> tags, so I moved the note titles directly into the markdown text so they're actually visible.

Since PR Preview doesn't seem to work well with the exact moment of migration, please see the (thanks to the Spec Generator):

• new Bikeshed version here
• old ReSpec version here

---

💥 Error: 400 Bad Request 💥

PR Preview failed to build. (Last tried on Apr 28, 2026, 1:58 PM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Spec Generator - Spec Generator is the web service used to build bikeshed/ReSpec specs

🔗 Related URL

Error output:

404 status received from raw.githubusercontent.com request (check URL?)

This seems to be an issue with the Spec Generator service. PR Preview doesn't manage this service and so has no control over it. If you've identified an issue with it, you can report the issue to the maintainers of Spec Generator directly. Please be courteous. Thank you!

If you don't have enough information above to solve the error by yourself or if the issue doesn't seem related to Spec Generator, you can file an issue with PR Preview.

[dandrader]

The bikeshed code is indeed more readable. So migrating to it is a win indeed. As a bonus I see we're also getting this IDL Index for free as well.

I think the challenge here is ensuring nothing was lost, "corrupted" or altered in the translation.
It's way too large to be verified manually (tedious). And diffing the generated HTML will probaly have a lot of noise as well.

But if you somehow found a way to check this with enough confidence. Great.

I spent some minutes comparing the two versions and it looks ok.

[zgroza]

Regarding checking, I did the following:

• I let a few different Gemini-based tools look through both and try to find any inconsistencies.
• I opened both specs side-by-side and manually went through them line-by-line (it was tedious as hell, yes, but kinda necessary).

Neither step was completely mistake-proof, of course. But now I have reasonable faith in not having missed anything.