[lukewagner]

This commit adds a new Explainer.md that attempts to provide a better introductory experience to the CM for folks already thinking at the WAT level by walking through the CM's (pre-0.3) features, starting with a "hello, world" WAT component and then progressively introducing CM features through new examples. The target audience here is CG folks already familiar with WAT and evaluating this as a new spec proposal and perhaps thinking about runtime/toolchain implementations... not general audiences (for that, component-model.bytecodealliance.org is still linked to as the better starting point).

@eqrion pointed out that a good explainer should also start with a nice crisp updated-for-2026 Problem Statement, but that's something I think we can iterate on separately (perhaps as part of the first one or two CM SG meetings) so for now there's just a short placeholder section at the beginning with a "TODO" and link to design/high-level/ (which have historically sorta served this purpose).

There are also JS API links left as "TODO" that are intended to be resolved by the new Markdown files added in #686, which I'd like to focus on getting merged next, before this PR (at which point I'll rebase and update this PR to link to the new docs); I'm mostly just posting this now to parallelize feedback. Also, in the last CG meeting, @tlively asked if there was any good CM SG "pre-reading" for anyone so motivated and I think perhaps this PR might serve that purpose.

[vados-cosmonic]

This is fantastic -- I did have one ask though, could the new walkthrough style explainer be multiple files rather than one massive one?

Also I do wonder if renaming Explainer.md is a good idea given all the links out there to it...

[lukewagner]

@vados-cosmonic Thanks! Personally, I think single-page documents are convenient, because you can ctrl-F skip around the page, see your progress as you go down the page, and see the automatic ToC. Also, the CM repo already uses this single-page-explainer convention. If page-load times were bad, that might be a reason to break it up, but it seems to load quite fast. As for renaming old Explainer.md to Text.md, I think it might not be too bad; I think mostly folks were linking to the top-level repo or README.md or just https://component-model.bytecodealliance.org.

[tlively]

Thanks for the nice explainer. These comments are mostly about ways to improve the exposition, but a few design questions slipped in there, too. I have plenty more design questions that I'll reserve for a better forum :)

[rossberg]

This is great. Super helpful to be able to understand it without all the WIT idiosyncrasies.

How about including the donut wrapping example? You refer to it several times, and it's almost the only piece missing to make this doc self-contained.

Some suggestions and questions below. Most of the questions are probably outside the scope of this doc, but popped up during my read-through.

[lukewagner]

Thanks @rossberg! It's a good idea to pull in a donut wrapping example; it can serve as a sortof "capstone" at the end of the walkthrough that uses everything already introduced to do something kinda impressive. This commit extends the existing Component Linking section's example with lite version and then adds a new "Virtualization" section at the end that takes it farther.

With that, I think all the above comments are addressed; if there's nothing else and no new comments on the new section at the end, in a few days I'll rebase this PR, fill in the TODOs with JS-Explainer.md links now that #686 is merged, and merge.

[rossberg]

Hm, I think I still don't quite understand what the external-id actually names in general and what for. Concretely, what would go wrong if you left out the external-id clauses on "a" and "b"? Likewise, what would go wrong if you omitted the implements clauses on "c" and "d"? Also, if I omit both, is the export name used as an external id, as an implements clause, or neither, or does it depend on its shape?

I believe I understand the general intention that you want to be able to select "known" external components either "by implementation" or "by interface", but would have expected that these choices are (a) mutually exclusive, and (b) expressed simply by different forms of URI.

[lukewagner]

I'm sure there's plenty more to discuss in the CM SG about rationale and why can't we just __, but just to provide some quick answers here and perhaps resolve this thread for the purpose of merging this walkthrough PR:

Concretely, what would go wrong if you left out the external-id clauses on "a" and "b"?

With the most-recently-proposed ESM-integration, the external-id is used as the module specifier; if there is no external-id, the import name is used as the module specifier (and you'll probably need to use an import map to prevent a load-time error because kebab-case strings aren't URLs). It's not in the JS API reference yet, but I think WebAssembly.Module.{imports,exports} would be extended with externalId fields, which you'd use to polyfill ESM-integration and in general could be fed into an algorithm to compute the import values passed into WebAssembly.instantiate(). Note that, unlike core wasm which, due to duplicate import names, technically has to use positional indices as the unique "keys" when passing import values into module_instantiate, with components, we use import/export names as the unique keys (to avoid fragile-base-class problems) and thus require uniqueness. But there are valid scenarios where you might actually need to use the same external-id for two different imports, and so the name/external-id split handles this.

Likewise, what would go wrong if you omitted the implements clauses on "c" and "d"?

Currently implements is ignored by the JS/web binding. But some outside-the-browser embeddings today mechanically interpret implements to select a concrete host implementation that is parameterized by the name+external-id as data. Thus, removing the implements attribute may result in a load-/deploy-time error.

Also, if I omit both, is the export name used as an external id, as an implements clause, or neither, or does it depend on its shape?

As already mentioned for ESM-integration above and in general: the idea is that if you want an external-id, you'll fall back to the import/export name if there is no external-id attribute. A plain name cannot take the place of implements since it doesn't have the "ns:pkg/interface" 3-tuple, and so a plain name without an implements attribute is "naked" and declares no contract. (When you don't want to import multiple implementations of the same contract, instead of importing multiple (plain-name+implements), you just have one "ns:pkg/interface"-named import (no implements allowed).)

[lukewagner]

From the SG meeting today, added a short note about the CM's use of names for linking.