feat: add ESM support, type definitions, and synchronous APIs to all @webref/* packages

[nberlette]

Hello there! I'm opening this issue to start a discussion with the maintainers about some changes I'd like to propose for the @webref/* packages, with the goal of improving compatibility, usability, and IDE support.

The data offered by these packages is unparalleled, and I'm a huge fan of this and all the other greak work done by you folks at @w3c. That being said, I was more than a bit dismayed to discover there are no TypeScript definitions for the webref packages published to npm (and apparently I'm not alone; see #937). I was also a bit shocked to find out that the packages only provide CommonJS entry points (in 2026?!).

I threw together a quick patch late last night to address these pain points (and a couple other minor things) for all of the packages in the webref workspace. It introduces the following changes:

• introduces well-documented type definitions to each package
• modernizes all packages to be ESM by default, maintaining CJS support via conditional exports
• introduces synchronous variants for all async APIs, improving alignment with common usage patterns
• migrates the root package.json to use npm workspaces instead of file:packages/* depedencies

I'll open up a draft PR with the above changes for any and all feedback you may have. If there are parts that don't align with the scope of the project, please let me know and I'll edit it as needed. This is my first contribution to the project — apologies if I've overlooked anything!

Thanks for your time,

Nick

[tidoust]

introduces well-documented type definitions to each package

That matches #937 indeed and it seems valuable to add these types.

One thing I'd like to avoid is having to maintain the information in 3 different places. We already have:

1. JSON Schemas in Reffy that are used to validate the extracts in Webref. For example, see the JSON schema for the consolidate CSS file.
2. The README that now documents individual properties, at least for the CSS package

Adding types would introduce another place that describes the same structure. At a minimum, there should be tests that validate that extracts match the types to make sure that we don't forget to update them when we make changes. Ideally, the types would be automatically derived from the JSON schemas.

modernizes all packages to be ESM by default, maintaining CJS support via conditional exports

I note that the packages can be imported as ESM already. Now, it's fine to modernize the code to switch to ESM. If we do that, I'm not sure that we should keep CommonJS support at all.

introduces synchronous variants for all async APIs, improving alignment with common usage patterns

That seems doable.

migrates the root package.json to use npm workspaces instead of file:packages/* depedencies

Hmm, why?