[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.