docs: one section per package, with an icon rail and a playground

AGENTS.md

@@ -33,7 +33,7 @@ A pnpm workspace. Every package in `packages/` is published to npm under its own
   - `src/script.ts` is the browser script. `script()` is self-contained because the HTML renderer inlines its source. `src/client.ts` exports `start()`, which runs it with the bundled styles; Vue, React, and Svelte components call it on mount and stop it on unmount.
   - `src/theme.ts` resolves the shared `--comark-*` tokens, and `comark-zoom/theme` exports it alone. `comark-github-callouts`, `comark-embed`, and `comark-tabs` have it as a dev dependency and bundle only this entry, so they don't install zoom or carry its styles.
   - `src/html.ts`, `src/vue.ts`, `src/react.ts`, and `src/svelte/` are the renderers. They all output the same markup.
-- `docs/` builds the docs site with the plugins themselves. Cloudflare serves it from `docs/dist`.
+- `docs/` builds the docs site with the plugins themselves. Cloudflare serves it from `docs/dist`. Each package has a folder in `docs/pages/` with an overview, getting started, components or syntax, and guides; `docs/build.ts` lists the sections. `docs/play.ts` is the playground, bundled with Vite; its presets are the examples at the top of each page.
 
 ## Rules
 

docs/highlight.ts

@@ -0,0 +1,19 @@
+// Colors the playground's editor with Comark's own grammar, the one the docs' code blocks get from the Shiki plugin.
+// The JavaScript regex engine keeps WebAssembly out of the page.
+import { comarkLanguages } from "comark/plugins/shiki/language-comark";
+import { createHighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+import dark from "shiki/themes/vitesse-dark.mjs";
+import light from "shiki/themes/vitesse-light.mjs";
+
+const highlighter = await createHighlighterCore({
+  themes: [light, dark],
+  langs: comarkLanguages,
+  engine: createJavaScriptRegexEngine({ forgiving: true }),
+});
+
+export const highlight = (code: string) =>
+  highlighter.codeToHtml(code, {
+    lang: "mdc",
+    themes: { light: "vitesse-light", dark: "vitesse-dark" },
+  });