@waveso/docs 0.2.0 → 0.4.0

package/README.md

@@ -11,6 +11,35 @@
 
 </div>
 
+<br />
+
+<!--
+  ⚠️ ABSOLUTE `raw.githubusercontent.com` URLS, PINNED TO A TAG.
+
+  npm rewrites relative markdown image paths onto its own CDN, but it does NOT
+  rewrite `<source srcset>` inside a `<picture>` — so a relative path here shows
+  a broken image on npmjs.com. And pinning to `main` rather than a tag means an
+  old version's README displays a future product: someone reading 0.3.0 in 2027
+  would see whatever the shell looks like then.
+
+  `pnpm shoot` regenerates these from the real site build; CI runs
+  `pnpm shoot --check` on any pull request touching the stylesheet, the React
+  layer or the site.
+-->
+<picture>
+  <source
+    media="(prefers-color-scheme: dark)"
+    srcset="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.3.0/docs/media/hero-dark.png"
+  />
+  <img
+    src="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.3.0/docs/media/hero-light.png"
+    alt="A documentation page rendered by @waveso/docs: a navigation sidebar, prose with syntax-highlighted code frames, and a table of contents."
+    width="100%"
+  />
+</picture>
+
+<p align="center"><em>The default page, with no CSS of your own. <a href="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.3.0/docs/media/search.png">Search dialog →</a></em></p>
+
 ---
 
 ## Why Wave Docs
@@ -55,9 +84,30 @@ That is not a style preference. `.extend()` produces a schema only as trustworth
 
 There is no `image-size` peer either. An `imageResolver` you write is welcome to read dimensions with it — but it is your dependency, in your own `package.json`. Declaring it here installed nothing and did not make `await import('image-size')` resolve for you; it only looked like it helped.
 
+## What it costs
+
+Every figure below is a **ceiling**, and `pnpm size` fails the build if the measurement passes it — in CI and again in `prepublishOnly`. So these are numbers this package is held to, not numbers somebody remembered to update.
+
+| | At most |
+| --- | --- |
+| Everything the quick start ships, gzipped | 13.0 KB |
+| Search dialog and router wiring | 9.0 KB |
+| Navigation: sidebar and mobile drawer | 2.2 KB |
+| Table of contents | 0.9 KB |
+| Copy-button runtime | 0.9 KB |
+| hast over the wire vs HTML, prose page | 1.20× |
+| hast over the wire vs HTML, code and tables | 1.12× |
+| Highlighting vs no highlighting | 2.00× |
+
+The first row is the honest total: a reader who lands on a page of your documentation downloads under 13 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
+
+The one real cost is the middle pair: shipping a tree instead of a string is about 20% more brotli on a prose page, and about 12% on a page with code and tables, where Shiki's token spans dominate both representations equally. That is the price of never handing markup to `dangerouslySetInnerHTML`, and it is the first number a skeptical reviewer should ask for.
+
+`size-budget.json` holds a second, looser ceiling per entry with a note explaining what to do when it is hit — and a build fails if the table above ever promises worse than that file enforces.
+
 ## Quick start
 
-**Two route files are required.** `[...slug]` does not match `/docs` itself, so the index needs its own `page.tsx`. An optional catch-all (`[[...slug]]`) does match, but leaves `/docs/index` live and serving byte-identical HTML with no canonical between them.
+**Three route files, and each one earns its place.** `[...slug]` does not match `/docs` itself, so the index needs its own `page.tsx` — an optional catch-all (`[[...slug]]`) does match, but leaves `/docs/index` live and serving byte-identical HTML with no canonical between them. The third serves the search index, which the layout's search trigger reads.
 
 Create the route once, in a module every route file imports:
 
@@ -86,6 +136,22 @@ export default docs.IndexPage;
 export const generateMetadata = docs.generateMetadata;
 ```
 
+```tsx
+// app/docs/layout.tsx
+import '@waveso/docs/styles.css';
+import { docs } from '@/lib/docs';
+
+export default docs.Layout;
+```
+
+```ts
+// app/docs/search-index.json/route.ts
+import { docs } from '@/lib/docs';
+
+export const GET = docs.searchIndex;
+export const dynamic = 'force-static';
+```
+
 ```
 content/docs/
   index.md
@@ -95,7 +161,9 @@ content/docs/
     authentication.md
 ```
 
-That is a working documentation site.
+That is a working documentation site: routing, a navigation sidebar, a table of contents, syntax highlighting, search, a mobile drawer and a skip link.
+
+The search route is in the quick start rather than in a section further down because `docs.Layout` renders the search trigger by default — leave the route out and a reader gets a control that opens onto "Search is unavailable". If you genuinely do not want search, `export default function Layout(props) { return docs.Layout({ ...props, search: false }) }` drops both the trigger and this file. See [Search](#search) for tuning.
 
 > [!IMPORTANT]
 > `dynamicParams` must be written out as `false`. Route segment config is parsed statically before the module runs, so `export const dynamicParams = docs.dynamicParams` fails `next build`. Without it, Next invokes the route on a server at request time for every unlisted URL, to produce a 404 that was already knowable at build time — and `output: 'export'` refuses to build at all.
@@ -108,73 +176,127 @@ There is no root export. Every entry point is a subpath, so an import always nam
 | --- | --- | --- |
 | `@waveso/docs/next` | Node | `createDocsRoute`, `createDocsSitemap`, `createDocsRedirects` |
 | `@waveso/docs/source` | Node | `createDocsSource`, `resolveDocsConfig` |
-| `@waveso/docs/render` | Node | `createDocsRenderer` |
-| `@waveso/docs/highlighter` | Node | `createDocsHighlighter`, `DEFAULT_DOCS_LANGS` |
-| `@waveso/docs/search-index` | Node | `extractSearchRecords`, `buildSearchIndex`, `writeSearchIndex` |
-| `@waveso/docs/react/*` | Browser + RSC | See [Components](#components) |
+| `@waveso/docs/render` | Node | `createDocsRenderer`, `resolveMarkdownLink` |
+| `@waveso/docs/highlighter` | Node | `createDocsHighlighter`, `DEFAULT_DOCS_LANGS`, `DEFAULT_DOCS_THEMES` |
+| `@waveso/docs/search-index` | Node | `extractSearchRecords`, `buildSearchIndex` |
+| `@waveso/docs/react/<name>` | Browser + RSC | Nine components, one per subpath — see [Components](#components) |
 | `@waveso/docs/frontmatter` | Any | `docFrontmatterSchema`, `parseFrontmatter`, `z` |
-| `@waveso/docs/search-options` | Any | `SEARCH_INDEX_OPTIONS` |
 | `@waveso/docs/types` | Any | Every shared type. Type-only |
+| `@waveso/docs/errors` | Any | `DocsErrorCode`, `DocsError`, `isDocsError`, `DOCS_ERROR_PREFIX` |
 | `@waveso/docs/styles.css` | — | The stylesheet |
 
-The Node-only subpaths carry `"browser": null`, so importing one from client code fails with a located *module not found* rather than quietly bundling `node:fs`.
+The Node-only subpaths carry `"browser": null`, so importing one from client code fails with a located *module not found* rather than resolving.
+
+That is about **weight, not about `node:fs`** — and the distinction matters, because three of the five would bundle perfectly happily. `render`, `highlighter` and `search-index` require no Node builtins at all; the markdown pipeline runs wherever JavaScript does, and Shiki is loaded through its JavaScript regex engine rather than WASM on purpose. What a bundler would do with them is succeed, and ship `unified`, `remark-parse` and every Shiki grammar to a reader — the exact outcome this package exists to prevent, arriving with no error to notice. Only `source` and `next` genuinely need the filesystem.
+
+`entry-runtime.test.ts` asserts each set exactly, so a new builtin three modules deep fails the build instead of silently ruling out a non-Node runtime.
+
+### Layout tokens
+
+Five custom properties size the shell, all layered so an unlayered `:root` of your own still wins. The full contract is in [`docs/adr/001-shell-contract.md`](./docs/adr/001-shell-contract.md).
+
+| Token | Default | Controls |
+| --- | --- | --- |
+| `--wave-docs-measure` | `46rem` | Prose column width. `none` opts out |
+| `--wave-docs-header-height` | `3.5rem` | Header, and the offset sticky columns park below |
+| `--wave-docs-sidebar-width` | `16rem` | Sidebar track |
+| `--wave-docs-toc-width` | `15rem` | Table-of-contents track |
+| `--wave-docs-shell-width` | `100rem` | Maximum shell width |
+
+The shell has three breakpoints, in `rem` so they scale with the reader's base font size: the sidebar appears at **64rem**, the table of contents at **80rem**, and the whole grid stops growing at **100rem**. 64rem is arithmetic rather than taste — a 16rem sidebar plus a 46rem measure plus two 1.5rem gutters is 65rem, so anything narrower introduces the sidebar exactly where it starts eating the measure it frames.
+
+Set `--wave-docs-font-sans: inherit` to hand the whole package your own typeface.
+
+Every subpath is enumerated in `exports` — there is no wildcard. A name that is not documented here is not importable, and that is a guarantee rather than an intention: `manifest.test.ts` enumerates the runtime exports of every built subpath and fails the build on one this README does not mention.
 
 ## Components
 
-Every component takes data as props and imports nothing from `next/*` — the adapter injects `next/link` and `next/image`. That keeps the renderer host-agnostic and testable without a router.
+Every component takes data as props and imports nothing from `next/*` — the adapter injects `next/link` and `next/image`. That keeps the renderer host-agnostic and testable without a router. `DocsSearch` is the one exception, and it exists precisely so that the exception is ours rather than yours: it is the fifteen-line wrapper you would otherwise write around `SearchDialog`.
 
 | Component | Subpath | Notes |
 | --- | --- | --- |
-| `DocContent` | `react/doc-content` | Renders a hast tree. Server Component |
+| `DocContent` | `react/doc-content` | Renders a hast tree, inside `.wave-docs-prose`. Server Component |
 | `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver` |
-| `SearchDialog` | `react/search-dialog` | ⌘K, arrow keys, focus trap |
-| `Callout` | `react/callout` | Note · tip · important · warning · caution |
+| `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
+| `SearchDialog` | `react/search-dialog` | ⌘K, arrow keys, focus trap. Host-agnostic |
+| `Callout` | `react/callout` | Note · tip · important · warning · caution. `CALLOUT_TYPES` is the list |
 | `YouTube` | `react/youtube` | Click-to-load facade |
-| `SkipLink` | `react/skip-link` | Targets `docs.Page`'s `<article>` |
-| `createMarkdownComponents` | `react/markdown-components` | The element → component map |
+| `SkipLink` | `react/skip-link` | Targets `docs.Page`'s `<main>`; `DOCS_CONTENT_ID` is that id. `docs.Layout` renders one |
+| `createMarkdownComponents` | `react/markdown-components` | The element → component map. `defaultMarkdownComponents` is the unwired one |
 
 ### Layout
 
-App Router layouts are Server Components and `usePathname` is client-only, so the one client boundary in a docs layout is a wrapper around the sidebar:
+`export default docs.Layout` — the one line from the [quick start](#quick-start) — is a Server Component that renders the whole shell: skip link, sticky header, sidebar column, mobile drawer, and the grid that arranges them. It reads the navigation tree and the search index URL itself, so there is nothing to fetch and nothing to pass.
 
-```tsx
-// components/docs-nav.tsx
-'use client';
+Your layout stays a Server Component. The two pieces that need a client — the navigation's `usePathname`, the search dialog — carry their own `'use client'` boundaries inside the package.
 
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
-import { DocsSidebar } from '@waveso/docs/react/sidebar';
-import type { DocNavNode } from '@waveso/docs/types';
-
-export function DocsNav({ nav }: { nav: DocNavNode[] }) {
-  return <DocsSidebar nav={nav} pathname={usePathname()} Link={Link} />;
-}
-```
+To put your own chrome in the header, call it instead of re-exporting it:
 
 ```tsx
-// app/docs/layout.tsx
 import type { ReactNode } from 'react';
-import { SkipLink } from '@waveso/docs/react/skip-link';
-import { DocsNav } from '@/components/docs-nav';
-import { docs } from '@/lib/docs';
 import '@waveso/docs/styles.css';
+import { docs } from '@/lib/docs';
 
-export default async function DocsLayout({ children }: { children: ReactNode }) {
-  const nav = await docs.source.nav();
+export default function DocsLayout({ children }: { children: ReactNode }) {
   return (
-    <>
-      <SkipLink />
-      <DocsNav nav={nav} />
+    <docs.Layout
+      title="Wave"
+      actions={<a href="https://github.com/waveso/docs">GitHub</a>}
+    >
       {children}
-    </>
+    </docs.Layout>
   );
 }
 ```
 
-A page that needs the table of contents renders itself from `docs.getPage(segments)` instead of re-exporting `docs.Page`:
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | — | Brand, at the header start |
+| `actions` | `ReactNode` | — | Header end, after search |
+| `search` | `boolean \| DocsSearchProps` | `true` | The search trigger. An object configures the dialog |
+| `labels` | `DocsLabels` | English | The four strings the shell renders itself |
+
+Five props, and two of them are small objects. That is deliberate, and it is the difference between this and an eleven-slot layout: everything else a docs shell gets asked for is already reachable. An announcement banner goes *above* `<docs.Layout>` in your own layout, because this does not own `<body>`. A content footer goes inside `children`. Sidebar links, social icons and separators are `DocNavNode`s you author in `meta.json`. The header bar was the one region nothing else could reach — hence `actions`. Two node props can become a slots map later; a slots map cannot become two props.
+
+`search` takes anything `DocsSearch` takes except `indexUrl`, which stays derived from your `basePath`. You do not need to repeat `miniSearchOptions` here to match `createDocsRoute` — the route's own value is forwarded, so the object that built the index is the object that queries it.
+
+`labels` is the whole of what a site not in English has to say to the shell; everything else a reader sees is your markdown or your `title`.
+
+The same `app/docs/layout.tsx` as the quick start, written out instead of re-exported, because passing a prop needs a function:
 
 ```tsx
+import type { ReactNode } from 'react';
+import '@waveso/docs/styles.css';
+import { docs } from '@/lib/docs';
+
+export default function Layout(props: { children: ReactNode }) {
+  return docs.Layout({
+    ...props,
+    labels: {
+      nav: 'Documentação',
+      openNav: 'Abrir navegação',
+      closeNav: 'Fechar navegação',
+      skipToContent: 'Ir para o conteúdo',
+    },
+  });
+}
+```
+
+Each key falls back on its own, so a partial map is not a half-translated shell.
+
+#### The mobile drawer
+
+Below 64rem the sidebar is a `<dialog>` opened by a server-rendered `<button command="show-modal">` — so it works on the first tap, before hydration, and with JavaScript disabled. Focus moves inside and Tab stays there, Escape closes it and returns focus to the trigger, a click on the backdrop dismisses it, and the page behind does not scroll. All of that is the browser's, not ours.
+
+At 64rem and above the same element becomes the sticky column, via `display: contents`. One navigation in the DOM at every width: one landmark, one copy of the links in the payload, nothing to keep in step.
+
+#### Composing it yourself
+
+`docs.Layout` is one opinion, not a tax. The components underneath are exported individually and take data as props, so a shell of your own is `DocsSidebar` + `DocsToc` + `SkipLink` + `DocsSearch` with your own CSS — and `docs.getPage(segments)` gives you the parts a custom page needs:
+
+```tsx
+// The catch-all page, written out instead of re-exporting `docs.Page`.
 import { notFound } from 'next/navigation';
 import { DocContent } from '@waveso/docs/react/doc-content';
 import { DocsToc } from '@waveso/docs/react/toc';
@@ -187,15 +309,25 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
 
   return (
     <>
-      <article id="docs-content" tabIndex={-1} className="wave-docs-prose">
+      <main className="wave-docs-layout__main" id="docs-content" tabIndex={-1}>
         <DocContent hast={doc.hast} />
-      </article>
-      <DocsToc entries={doc.toc} />
+      </main>
+      {doc.toc.length === 0 ? null : (
+        <aside className="wave-docs-layout__toc">
+          <DocsToc entries={doc.toc} />
+        </aside>
+      )}
     </>
   );
 }
 ```
 
+`docs.Page` returns exactly this shape: the `<main>` and the table of contents as **two siblings**, not one wrapped element. They land as direct children of the grid, which is what puts them in separate columns — so if you compose your own page inside `docs.Layout`, return a fragment rather than a wrapper.
+
+**The two class names are load-bearing**, and they are the part of this that is easy to leave off. `wave-docs-layout__main` carries `min-width: 0`, without which a wide table pushes the whole document into horizontal scroll (measured: 1048px of document inside a 1024px viewport). `wave-docs-layout__toc` is what the grid reserves its third track with, via `:has()` — unclassed, the table of contents auto-places into the next row underneath the sidebar above 80rem, and renders inline on a phone instead of being hidden. Both are frozen in [`docs/adr/001-shell-contract.md`](docs/adr/001-shell-contract.md), so they are safe to write by hand.
+
+The `null` is load-bearing too: `:has()` matches an empty `<aside>` exactly as well as a full one, so a page with no headings would give up 15rem to nothing.
+
 ## Frontmatter
 
 ```yaml
@@ -227,6 +359,9 @@ export const frontmatterSchema = docFrontmatterSchema.extend({
 ```
 
 ```ts
+import { createDocsRoute } from '@waveso/docs/next';
+import { frontmatterSchema } from '@/content/docs-schema';
+
 const docs = createDocsRoute({ contentDir: 'content/docs', frontmatterSchema });
 
 const doc = await docs.getPage(['api', 'auth']);
@@ -240,6 +375,7 @@ Four things are worth knowing before you write one.
 
 **Let the type be inferred — never name it.** Naming it explicitly *and* omitting the schema type-checks and then lies, because nothing validates the type you named:
 
+<!-- typecheck: skip — the two lines are the point; imports would bury them -->
 ```ts
 // ⚠️ Compiles. Every extra field is `undefined` at runtime, typed as present.
 const docs = createDocsRoute<MyFrontmatter>({ contentDir: 'content/docs' });
@@ -312,6 +448,95 @@ above a file called `server.cfg`.
 
 Anything outside that set falls back to plain text rather than throwing. Pass `langs` to change the set, or `highlighter` to supply your own. Fence languages are matched case-insensitively, so ```` ```JSON ```` and ```` ```Bash ```` highlight like their lowercase spellings rather than silently shipping monochrome.
 
+### Code blocks
+
+Every highlighted fence is wrapped in a `<figure>` with a copy button. Add a title and it gets a bar:
+
+````md
+```ts title="app/page.tsx"
+export default function Page() {
+  return <h1>Hello</h1>;
+}
+```
+````
+
+The title lands in three places at once — the caption, the button's accessible name (`Copy code from app/page.tsx`, rather than eight controls all called "Copy code"), and the search index.
+
+Anything else in the meta string is left alone, so `{1,3-5}` and `showLineNumbers` pass through to Shiki untouched. A `title=` that is not double-quoted fails the build naming the document, because the alternative is a caption that silently truncates at the first space.
+
+The copy button is one delegated listener for the whole page, mounted by `DocContent` — not a client component per code block. A page with no fences ships none of it. And it is `visibility: hidden` until that listener attaches, so a reader with JavaScript disabled sees no button and finds no dead tab stop where a control should be.
+
+The `<figure>` carries `data-lang` (the folded language, so ```` ```JSON ```` gives `json`). No badge is rendered by default; one rule turns it on:
+
+```css
+.wave-docs-code[data-lang]::before {
+  content: attr(data-lang);
+}
+```
+
+Keeping it in CSS is deliberate — a real element would enter the search index and `textContent`, so every code block would pollute search results with its language name and the copy button would copy it.
+
+#### Fences you render yourself
+
+`excludeLangs` tells Shiki to leave a language alone, so the `<pre>` reaches your own component untouched — for diagrams, or anything that is not really code:
+
+```ts
+import { createDocsRoute } from '@waveso/docs/next';
+
+// In `lib/docs.ts`, beside the rest of your configuration.
+export const docs = createDocsRoute({
+  contentDir: 'content/docs',
+  excludeLangs: ['mermaid'],
+});
+```
+
+Those fences are deliberately **not** framed: a copy button on a rendered diagram copies its source, which is not what the reader clicked. They still get the same background, border and horizontal scroll as a highlighted block, so `excludeLangs` on its own produces a page that looks deliberate rather than unstyled.
+
+To render them, map `pre`:
+
+```tsx
+import { isValidElement, type ReactNode } from 'react';
+
+/** Yours: a `'use client'` component wrapping whichever renderer you like. */
+declare function Mermaid(props: { children: string }): ReactNode;
+
+function textOf(node: ReactNode): string {
+  if (typeof node === 'string') return node;
+  if (Array.isArray(node)) return node.map(textOf).join('');
+  if (isValidElement<{ children?: ReactNode }>(node)) {
+    return textOf(node.props.children);
+  }
+  return '';
+}
+
+export const components = {
+  pre: (props: { children?: ReactNode }) => {
+    const child = props.children;
+    const className = isValidElement<{ className?: string | string[] }>(child)
+      ? child.props.className
+      : undefined;
+
+    /*
+     * ⚠️ AN ARRAY, NOT A STRING. An excluded fence never reached Shiki, so its
+     * `<code>` still carries hast's `["language-mermaid"]` — Shiki's own
+     * output is a string. A `className === 'language-mermaid'` check compiles,
+     * reads correctly, and silently never matches, so every diagram renders as
+     * its own source.
+     */
+    const languages = Array.isArray(className) ? className : [className];
+
+    if (languages.includes('language-mermaid')) {
+      return <Mermaid>{textOf(props.children)}</Mermaid>;
+    }
+    return <pre {...props} />;
+  },
+};
+```
+
+Pass it as `components` to `createDocsRoute`, or to `DocContent` directly.
+
+`Mermaid` is yours — a `'use client'` component wrapping whichever renderer you like. This package deliberately does not ship one: several hundred kilobytes of client JavaScript with its own CVE history, behind an option most sites never set, in a package with three peer dependencies against Fumadocs' eighteen.
+
 ### Images
 
 **Absolute and external sources just work.** Put the file in `public/` and write `![](/diagram.png)`.
@@ -327,10 +552,17 @@ A **relative** source is a different thing. Nothing in `public/` corresponds to
 An `imageResolver` receives the source already folded against the markdown file's directory (`./diagram.png` in `guides/deploying.md` arrives as `guides/diagram.png`) and returns a public URL plus intrinsic dimensions — which `next/image` requires and markdown does not carry:
 
 ```ts
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { imageSize } from 'image-size';
+import { createDocsRoute } from '@waveso/docs/next';
+
 createDocsRoute({
   contentDir: 'content/docs',
   imageResolver: async (src) => {
-    const { width, height } = await imageSize(path.join('content/docs', src));
+    const { width, height } = imageSize(
+      await readFile(path.join('content/docs', src)),
+    );
     return { src: `/docs-assets/${src}`, width, height };
   },
 });
@@ -384,6 +616,7 @@ page it is dropped into, so it now switches only when the host says to.
 
 If your site really does follow the OS and has no theme toggle, say so once:
 
+<!-- typecheck: skip — one tag, shown as markup rather than as a module -->
 ```tsx
 <html lang="en" data-theme="system">
 ```
@@ -401,53 +634,113 @@ To restyle rather than retheme, override the classes — `.wave-docs-prose`,
 
 Build-time index, client-side dialog, MiniSearch. Records are section-scoped — one per `h2`–`h6` — so a hit deep-links to the right heading instead of dropping the reader at the top of a 2,000-word page.
 
-Nothing builds the index for you. `docs.renderAll()` exists for exactly this, and shares the scan, the highlighter and the render cache with your routes:
+Nothing to set up: `docs.Layout` renders the trigger, and the [route file in the quick start](#quick-start) serves the index. The index is a route rather than a build script, so it is rebuilt by the same `next build` that builds your pages, and in `next dev` it re-reads the disk per request — a page you add is searchable on the next keystroke, with no restart and no script to remember.
 
-```ts
-// scripts/build-search-index.ts — run before `next build`
-import { extractSearchRecords, writeSearchIndex } from '@waveso/docs/search-index';
-import { docs } from '../lib/docs';
+Outside `docs.Layout`, `<DocsSearch indexUrl={docs.searchIndexUrl} />` puts the trigger wherever it belongs. `DocsSearch` carries its own `'use client'` boundary, so the layout around it stays a Server Component.
 
-const rendered = await docs.renderAll();
-const records = rendered.flatMap((doc) => extractSearchRecords(doc));
-await writeSearchIndex(records, 'public/search-index.json');
-```
+`docs.searchIndexUrl` is derived from your `basePath`, so it is right whether the docs are mounted at `/`, at `/docs` or under a nested prefix. Pass it rather than a literal.
 
-```tsx
-'use client';
+MiniSearch is `import()`ed and the index fetched on hover, focus or first open — never on page load.
 
-import Link from 'next/link';
-import { useRouter } from 'next/navigation';
-import { SearchDialog } from '@waveso/docs/react/search-dialog';
+> [!WARNING]
+> **`export const dynamic = 'force-static'` is not optional, and it has to be a literal** — route segment config is parsed out of the module before any of it runs, exactly like `dynamicParams`. Without it Next marks the route `ƒ` (Dynamic) and re-renders your whole corpus on every request, from markdown that output tracing did not put in the deployment bundle. On a serverless host that does not degrade, it throws — at the reader, inside the dialog. The build prints no warning, so the handler detects it and throws with `code: 'search-index-dynamic'`, naming the file to fix.
 
-export function Search() {
-  const router = useRouter();
-  return <SearchDialog indexUrl="/search-index.json" navigate={router.push} Link={Link} />;
-}
-```
+Under `output: 'export'` the same route is written out as a plain `docs/search-index.json`. Both modes are asserted by a real `next build` in this repository's CI.
 
-MiniSearch is `import()`ed and the index fetched on hover, focus or first open — never on page load.
+### Caching
+
+The response carries `cache-control: public, max-age=0, must-revalidate` and a strong `ETag`, replacing Next's default of a year of `s-maxage` with no validator — which, on a URL that never changes, is a CDN serving a stale index until someone purges it by hand. `next start` does not honour `If-None-Match` itself (it answers 200 with the full body); a CDN or reverse proxy in front of it does.
+
+If your site sets Next's own `basePath` config, prefix `indexUrl` yourself: Next applies it to `<Link>` and to navigation, but never to a client `fetch()`.
 
 ### What gets indexed
 
 **The whole section**, not a preview of it. `extractSearchRecords` once truncated `text` to 300 characters *before* indexing, which dropped roughly 80% of a normal corpus — and because the default `combineWith: 'AND'` requires every term to land in the same record, a two-word query against a page that plainly contained both words returned nothing. Indexing and display are now separate concerns: the full text is searchable, and `storeFields` carries only what the dialog renders.
 
+Drafts are excluded, and code blocks are skipped — after Shiki a fence is hundreds of token spans that index as a bag of punctuation. Inline `code` is kept, because `useMemo` is exactly the sort of thing people search for.
+
 ### CJK and other scripts
 
 Tokenisation uses `Intl.Segmenter` where available, so Chinese, Japanese and Thai — which do not delimit words with spaces — index and query as words rather than as whole clauses. Without it, `search('安装')` matched nothing on a page that was entirely about 安装.
 
-Both halves of the seam take the same overrides, and they must agree — an index built with one `tokenize` and queried with another matches nothing at all:
+### Tuning
+
+Both halves of the seam take the same overrides and **they must agree** — an index built with one `tokenize` and queried with another matches nothing at all, silently. So the option has one name on both sides:
 
 ```ts
-buildSearchIndex(records, { fuzzy: 0.1, prefix: true });
+import { createDocsRoute } from '@waveso/docs/next';
+
+export const docs = createDocsRoute({
+  contentDir: 'content/docs',
+  miniSearchOptions: { searchOptions: { fuzzy: 0.1, prefix: true } },
+});
 ```
 
 ```tsx
-<SearchDialog indexUrl="/search-index.json" searchOptions={{ fuzzy: 0.1, prefix: true }} />
+import { DocsSearch } from '@waveso/docs/react/next-search';
+import { docs } from '@/lib/docs';
+
+export function Search() {
+  return (
+    <DocsSearch
+      indexUrl={docs.searchIndexUrl}
+      miniSearchOptions={{ searchOptions: { fuzzy: 0.1, prefix: true } }}
+    />
+  );
+}
+```
+
+`fuzzy`, `prefix`, `combineWith` and `boost` are MiniSearch *query* defaults, so they nest under `searchOptions`; `fields`, `storeFields`, `tokenize` and `processTerm` sit at the top level. The nesting is easy to get wrong and wrong is silent — a stray `fuzzy` at the top level is simply never read — so both examples above are type-checked in CI.
+
+### Building the index yourself
+
+Only if the route cannot express what you need — a second index per locale, say, or an artifact consumed by something other than the dialog:
+
+```ts
+import { buildSearchIndex, extractSearchRecords } from '@waveso/docs/search-index';
+import { docs } from '@/lib/docs';
+
+const rendered = await docs.renderAll();
+const json = buildSearchIndex(rendered.flatMap((doc) => extractSearchRecords(doc)));
+```
+
+`docs.searchIndex` is exactly this, served — asserted byte-for-byte by a test, so the escape hatch cannot drift from the route.
+
+## Plugins
+
+Two slots, at the two positions that are actually useful:
+
+```ts
+import type { Plugin } from 'unified';
+import { createDocsRoute } from '@waveso/docs/next';
+
+// Whatever you install — `remark-math` and `rehype-katex` here.
+declare const remarkMath: Plugin;
+declare const rehypeKatex: Plugin;
+
+export const mathDocs = createDocsRoute({
+  contentDir: 'content/docs',
+  remarkPlugins: [remarkMath],
+  rehypePlugins: [rehypeKatex],
+});
 ```
 
+`remarkPlugins` attach after GFM and **before link resolution**, so anything they emit is folded, contained and asserted exactly like authored markdown — a plugin writing `[x](../other/page.md)` gets the same resolution an author would, and one writing `![i](./x.png)` throws without an `imageResolver` for the same reason.
+
+`rehypePlugins` attach after heading ids and permalinks exist and **before Shiki**, so a code fence is still `<pre><code class="language-ts">` with the author's text in it rather than several hundred token spans. Fences named by `excludeLangs` are not disguised yet either, so a plugin sees every code block the same way.
+
+There is no after-Shiki slot. Code-block internals belong to Shiki's own `transformers`, and the honest documentation for an after-Shiki hook would be a list of things you must not do.
+
+The table of contents is captured **last**, after your plugins and after everything else, so it describes the same document the search index does. A plugin that adds or removes a heading changes both together; there is no validation pass because there is nothing to validate.
+
+> [!NOTE]
+> The pipeline is built and frozen once and shared by every file, so a plugin
+> holding state accumulates it across the whole build rather than per document.
+> Keep them pure, or key what they hold on the vfile.
+
 ## Configuration
 
+<!-- typecheck: skip — a reference listing of the type, not a module -->
 ```ts
 interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
   contentDir: string;        // relative paths resolve against process.cwd()
@@ -467,24 +760,28 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
 | `highlighter` | built-in | Supply your own for grammars outside the set |
 | `titleHeading` | `true` | Build an `<h1>` from `frontmatter.title` when the markdown has none |
 | `components` | built-in map | Override any element → component mapping |
-| `contentId` | `'docs-content'` | The id `SkipLink` targets; `false` if your layout owns it |
-| `rescanPerRequest` | dev only | Re-scan the content directory per request |
 | `siteUrl` | — | Makes canonical URLs absolute |
 | `linkResolver` · `imageResolver` | — | Override link rewriting and image dimensions. An `imageResolver` receives a folded, contained src — except an absolute `/logo.png` or a schemed `https://…`, which arrive unfolded, so branch on them |
 
 `titleHeading` defaults on because a document with no `h1` has a broken heading outline and fails every accessibility audit. Turn it off if your layout renders the title itself.
 
+The `<main>` always carries `id="docs-content"`, which is what `SkipLink` targets by default — there is no option to change it, because there was no matching option on `SkipLink` to follow it with, so changing it silently pointed the skip link at nothing. Outside `NODE_ENV=production` the content directory is always re-scanned per request; `docs.source.invalidate()` is the escape hatch if you need to force one.
+
 ### Redirects and sitemap
 
 Separate calls, usable from `next.config.ts` and `app/sitemap.ts` — neither loads the Next runtime:
 
 ```ts
-import { createDocsRedirects, createDocsSitemap } from '@waveso/docs/next';
-
 // next.config.ts
+import { createDocsRedirects } from '@waveso/docs/next';
+
 export default { redirects: () => createDocsRedirects({ contentDir: 'content/docs' }) };
+```
 
+```ts
 // app/sitemap.ts
+import { createDocsSitemap } from '@waveso/docs/next';
+
 export default () =>
   createDocsSitemap({ contentDir: 'content/docs', siteUrl: 'https://example.com' });
 ```
@@ -508,11 +805,75 @@ Markdown files are not in Next's module graph, so nothing recompiles a route mod
 
 The rescan is shared. Next runs `generateMetadata` and your page concurrently, and a layout calling `nav()` is a third reader; invalidation is wrapped in `React.cache`, so the first of them re-reads the disk and the rest see that scan. Without it each invalidated the others' work in flight — measured at 22 `readdir` + 824 `readFile` per request on a 401-file tree, against 11 + 412 for one scan.
 
+## Runtimes
+
+What each entry point *requires*, measured by bundling it with no runtime assumed and asserted exactly — not approximately — by `src/entry-runtime.test.ts`:
+
+| Entry | Node builtins |
+| --- | --- |
+| `@waveso/docs/types` | none |
+| `@waveso/docs/frontmatter` | none |
+| `@waveso/docs/highlighter` | none |
+| `@waveso/docs/render` | none |
+| `@waveso/docs/search-index` | none |
+| `@waveso/docs/source` | `node:fs/promises`, `node:path` |
+| `@waveso/docs/next` | `node:crypto`, `node:fs/promises`, `node:path` |
+| `@waveso/docs/react/*` | none |
+
+The markdown pipeline needs no filesystem and no `.wasm` — Shiki is loaded through its JavaScript regex engine deliberately, not its WASM one. So parsing and highlighting run wherever JavaScript does; only reading a directory of `.md` files needs Node, which is what `source` is for.
+
+That is a statement about requirements and not a blessing. A bundle that resolves is not a runtime, and this package is tested on Node. If you run it elsewhere, note that `render` bundles to roughly 2.8 MB with all eighteen grammars inlined — narrow `langs` for anything with a size limit, since grammars are dynamic imports.
+
+## Errors
+
+Every failure this package raises carries a `code`, so a host can branch on the kind of thing that went wrong rather than on message text:
+
+```ts
+import { isDocsError } from '@waveso/docs/errors';
+import { docs } from '@/lib/docs';
+
+try {
+  await docs.renderAll();
+} catch (error) {
+  if (isDocsError(error) && error.code === 'draft-link') {
+    console.warn(error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+`DocsErrorCode` is exported as a union, so a `switch` over it is exhaustive and a typo is a compile error. No error class is exported, deliberately: `instanceof` against a copy of a module resolved twice — two versions in a monorepo, a bundler that duplicates it — silently answers `false`, and a string code with a structural guard has no such failure mode.
+
+### Troubleshooting
+
+| Code | What happened | What to do |
+| --- | --- | --- |
+| `broken-link` | A markdown link resolves to a route no published page owns. | Fix the link, or add an `aliases` entry to the page that moved. |
+| `draft-link` | A link points at a page that exists but is `draft: true`. | Publish the page, or drop the link until it ships. |
+| `alias-link` | A link points at an alias, which is a redirect and not a page. | Link the page the alias redirects to — the error names it. |
+| `invalid-alias` | An `aliases` entry is empty, escapes the content root, or is not URL-safe. | Write it as a root-relative path, e.g. `/docs/old-name`. |
+| `alias-collision` | Two pages claim one alias, or an alias shadows a real route. | Remove one of them; a redirect cannot have two destinations. |
+| `route-collision` | Two files resolve to the same route. | Usually `about.md` beside `about/index.md`. Keep one. |
+| `invalid-frontmatter` | A page has no frontmatter block, or the schema rejected it. | Every page needs at least `title`. The message names the file and the field. |
+| `invalid-meta` | A `meta.json` is malformed, or names a page that is not there. | Check the filename spelling — entries are filenames without the extension. |
+| `invalid-config` | An option passed to this package cannot be used as given. | The message names the option. `siteUrl` must be an absolute origin with no path. |
+| `missing-content-dir` | `contentDir` does not point at a readable directory. | It resolves against `process.cwd()`, which is your project root under `next build`. |
+| `broken-symlink` | A markdown page is reachable only through a broken symbolic link. | Repoint or delete the link; skipping it would silently drop a route. |
+| `invalid-image` | A relative image needs an `imageResolver`, or one returned an unusable shape. | Pass `imageResolver`, or use an absolute `/path` the browser can resolve. |
+| `unknown-theme` | A theme name outside the supported set. | Pass a `highlighter` of your own if you need a theme this package does not load. |
+| `unknown-language` | A fence language outside the loaded set. | Add it to `langs`, or accept the plain-text fallback. |
+| `missing-peer` | `next` is absent, or not the shape this adapter expects. | Install `next`, or build pages from `@waveso/docs/react/*` with your own loader. |
+| `search-index-unavailable` | The dialog could not fetch or parse the index. | Check `indexUrl` — pass `docs.searchIndexUrl`, and prefix it yourself under a Next `basePath`. |
+| `search-index-dynamic` | The search-index route ran at request time instead of prerendering. | Add `export const dynamic = 'force-static'` to the route file. It must be a literal. |
+| `invalid-code-meta` | A fence's `title=` cannot be read. | Quote it: ```` ```ts title="app/page.tsx" ````. |
+| `internal` | A plugin ran without context this package always supplies. | This one is a bug here. Please report it with the stack trace. |
+
 ## Requirements
 
 | | |
 | --- | --- |
-| Node.js | ≥ 20.19.0 |
+| Node.js | ≥ 22.12.0 |
 | React | 19 |
 | Next.js | 16 (optional peer — only `@waveso/docs/next` needs it) |
 | Module format | **ESM only** |
@@ -524,10 +885,64 @@ If you extend the frontmatter schema, use `.exactOptional()` rather than `.optio
 
 > [!NOTE]
 > Under `exactOptionalPropertyTypes: true`, passing `next/link` straight into
-> `DocsSidebar` or `SearchDialog` does not type-check — `next/link` types
-> `prefetch` as `boolean | null | undefined` where `DocsLinkProps` says
-> `boolean | undefined`. `docs.Page` is unaffected, because the adapter wraps
-> `next/link` internally. Without that flag, `Link={Link}` compiles as shown.
+> `DocsSidebar` does not type-check. Next's `LinkProps` re-declares `onClick?`,
+> `onMouseEnter?` and `onTouchStart?` *without* `| undefined`, and React's
+> anchor props include it, so the two declaration files disagree — about props
+> `next/link` accepts perfectly well at runtime. It is true of every
+> `next/link` call site in a project with that flag on, not just this one.
+> Cast at the call site (`Link={Link as DocsLinkComponent}`) until the
+> Next-wired navigation component ships.
+>
+> `docs.Page` and `DocsSearch` are both unaffected — each wraps `next/link`
+> inside the package, which is where that cast belongs. Without the flag,
+> `Link={Link}` compiles exactly as shown above.
+
+## Stability
+
+**This is `0.x`, and `0.x` means breaking changes land in minors.** They will be
+listed, with the migration, in the changelog. What follows is what counts as
+breaking — which is the part most packages leave unsaid until someone is angry.
+
+### What is public API
+
+| | Covered |
+| --- | --- |
+| Every subpath in `exports`, and every runtime name it exports | ✅ enforced by `manifest.test.ts` |
+| Exported types, including `DocsErrorCode`'s members | ✅ enforced by `error-taxonomy.test.ts` |
+| **CSS class names** — `wave-docs-*`, and the shell's element tree | ✅ frozen in [ADR 001](docs/adr/001-shell-contract.md) |
+| **The hast this emits** — element names, and the attributes on them | ✅ the same policy as the types |
+| Layout tokens — the five custom properties above | ✅ |
+| Anything reachable only through `dist/` internals, or a private module | ❌ |
+
+The two in bold are the ones usually omitted, and omitting them is how a
+package ships a "patch" that silently reflows everyone's site. If you can write
+a selector against it or read it out of `RenderedDoc.hast`, this package owes
+you a changelog entry before it moves.
+
+### Four clauses
+
+**Dropping a major of `next`, `react` or `react-dom` is breaking; adding one is
+not.** Widening `peerDependencies` to accept the next major is a minor and
+always safe to take. Narrowing it — dropping React 19 once React 20 has settled
+— is breaking, gets its own release, and will not be bundled with features.
+
+**The Node floor follows LTS, and moving it is breaking.** It rises when a
+version leaves maintenance, not when a shiny builtin appears. Today `22.12.0`.
+
+**A third-party type in this package's signature makes that library's major
+ours.** `unified`'s `PluggableList` is in `remarkPlugins`, `MiniSearch`'s
+`Options` is in `miniSearchOptions`, and hast's `Root` is in `RenderedDoc`. When
+one of those releases a breaking major, so does this — a package that quietly
+re-exports someone else's break is worse than one that names it.
+
+**Zod is a dependency, not a peer, and that is deliberate.** Your Zod is yours.
+When you extend the frontmatter schema, take `z` from
+`@waveso/docs/frontmatter`.
+
+### What is not covered
+
+The rendered *appearance* — colours, spacing, the type scale — is design, and it
+will change without a major. The class names it hangs on will not.
 
 ## Design notes
 
@@ -560,7 +975,7 @@ It also hardcodes `passNode: true` with no opt-out, so any component you map tha
 
 An HTML string is a dead end: you can only render it with `dangerouslySetInnerHTML`, which forfeits component mapping, makes every element unstyleable except through descendant selectors, and puts the burden of trusting the content on you.
 
-A hast tree is data. It survives `JSON.stringify`, crosses the RSC boundary, caches to disk, and renders through `hast-util-to-jsx-runtime` with your components substituted for whichever elements you care about. The cost is a slightly larger payload; positions are stripped before it ships, which removes about 44% of the JSON on a typical page.
+A hast tree is data. It survives `JSON.stringify`, crosses the RSC boundary, caches to disk, and renders through `hast-util-to-jsx-runtime` with your components substituted for whichever elements you care about. The cost is a slightly larger payload; positions are stripped before it ships, which removes roughly a third of the JSON. Measured at 33% on a mixed page — it rises on short pages, where the offsets are a larger share of a smaller tree. Two figures in this repository disagreed about it (38% in a comment, 44% here) until somebody measured.
 
 </details>