@waveso/docs 0.4.0 → 0.6.0

package/README.md

@@ -13,32 +13,11 @@
 
 <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>
+<p align="center">
+  <strong><a href="https://docs.wave.so">docs.wave.so</a></strong> — the documentation for this package, built with this package.
+</p>
+
+<p align="center"><em>Every page you see there is markdown in <code>site/content/</code>, rendered by <code>docs.Layout</code> with no layout CSS of its own. It is the acceptance harness and the showcase, and it is the same build CI runs on every commit — so it cannot drift from what this README claims.</em></p>
 
 ---
 
@@ -90,16 +69,16 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | 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 |
+| Everything the quick start ships, gzipped | 13.5 KB |
+| Search dialog and router wiring | 9.3 KB |
+| Navigation: sidebar and mobile drawer | 2.4 KB |
 | Table of contents | 0.9 KB |
-| Copy-button runtime | 0.9 KB |
+| Copy-button runtime | 1.1 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 first row is the honest total: a reader who lands on a page of your documentation downloads under 13.5 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.
 
@@ -211,20 +190,25 @@ Every subpath is enumerated in `exports` — there is no wildcard. A name that i
 
 ## 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. `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`.
+Every component takes data as props, and two modules in `src/react/` import from `next/*` — `next-nav` for `usePathname` and `next-search` for `useRouter`, each named so the exception is visible in the file list. Everything else has `next/link` and `next/image` injected. 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, inside `.wave-docs-prose`. Server Component |
 | `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
-| `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver` |
+| `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
+| `DocsLink` | `react/next-link` | `next/link`, adapted — pass it as `Link` when composing by hand |
 | `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 |
+| `YouTube` | `react/youtube` | Click-to-load facade. `title`, `playLabel`, `hideLabel` — `{title}` interpolates the first |
 | `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 |
 
+`DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end.
+
+The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` carries `src`, `alt`, `width` and `height` — the four `next/image` refuses to render without — and adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to it; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
+
 ### Layout
 
 `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.
@@ -255,35 +239,13 @@ export default function DocsLayout({ children }: { children: ReactNode }) {
 | `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 |
+| `labels` | `DocsLabels` | the route's | Overrides `createDocsRoute`'s labels, key by key |
 
 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.
+`labels` belongs on `createDocsRoute` — see [Translating the chrome](#translating-the-chrome) — and this prop overrides it key by key, for a site with two shells or a section in another language.
 
 #### The mobile drawer
 
@@ -653,6 +615,35 @@ The response carries `cache-control: public, max-age=0, must-revalidate` and a s
 
 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()`.
 
+### The dialog's props
+
+`DocsSearch` takes everything `SearchDialog` does except `navigate` and `Link`, which the Next adapter wires. `docs.Layout`'s `search={{ … }}` takes all of it except `indexUrl`, which it derives.
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `indexUrl` | `string` | — | Where the index is served. Pass `docs.searchIndexUrl` |
+| `pageSize` | `number` | `20` | Results rendered at a time. **Not a cap** — another page loads as the reader nears the end |
+| `minQueryLength` | `number` | `2` | Shortest query that runs |
+| `debounceMs` | `number` | `120` | Input debounce |
+| `className` | `string` | — | Extra classes for the trigger button |
+| `triggerLabel` | `string` | `'Search'` | The trigger's text |
+| `placeholder` | `string` | `'Search documentation'` | The input's placeholder |
+| `dialogLabel` | `string` | `'Search documentation'` | The dialog's accessible name |
+| `hintLabel` | `string` | `'Start typing to search the documentation.'` | Before anything is typed |
+| `shortQueryLabel` | `string` | `'Keep typing — {min} characters or more.'` | Below `minQueryLength`. `{min}` is that number |
+| `loadingLabel` | `string` | `'Loading the search index…'` | While the index is fetched |
+| `errorLabel` | `string` | `'Search is unavailable right now. Try reloading the page.'` | When it cannot be |
+| `emptyLabel` | `string` | `'No results for “{query}”.'` | No matches. `{query}` is what was typed |
+| `resultCountLabels` | `Partial<Record<Intl.LDMLPluralRule, string>>` | `{ one: '{count} result', other: '{count} results' }` | The live region, by plural category |
+| `locale` | `string` | `<html lang>`, then `'en'` | Language tag for those plural rules |
+| `miniSearchOptions` | `Partial<Options<SearchRecord>>` | — | See [Tuning](#tuning) |
+
+**`pageSize` replaced `maxResults` in 0.4.0**, and the meaning changed with the name: `maxResults` was a hard ceiling of 8 that made results unreachable on a six-page site, and the live region announced the slice as though it were the total. `pageSize` is a window — every match is reachable by scrolling, and the count announced is the real one.
+
+`resultCountLabels` is keyed by plural category rather than being a singular and a plural, because most languages are not English: Polish takes four forms and Arabic six. `Intl.PluralRules` picks, and a category you do not list falls back to `other`.
+
+There is no `hotkey` prop. The shortcut is ⌘K on Apple platforms and Ctrl-K elsewhere, and it is not configurable.
+
 ### 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.
@@ -692,6 +683,60 @@ export function Search() {
 
 `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.
 
+### Functions need a client boundary
+
+`tokenize` and `processTerm` are functions, and `docs.Layout` cannot hand a function to the dialog. The layout is a Server Component and the dialog is a Client Component, so props crossing between them are serialised — React refuses a function outright and `next build` fails while prerendering, with *"Functions cannot be passed directly to Client Components"*.
+
+So `docs.Layout` forwards the serialisable half of `miniSearchOptions` — `fields`, `storeFields`, `boost`, and everything under `searchOptions` that is not a callback — and refuses the rest by name. It does not quietly drop them: an index built with a `processTerm` the query does not share matches nothing at all and says nothing, which is the exact failure the forwarding exists to prevent.
+
+Function tuning means taking the boundary yourself, so the function is a module import on both sides rather than a prop between them:
+
+```ts
+// lib/search-terms.ts — one function, imported by both halves
+export function stripDashes(term: string): string {
+  return term.replace(/-/g, '');
+}
+```
+
+```tsx
+// components/docs-search.tsx
+'use client';
+
+import { DocsSearch } from '@waveso/docs/react/next-search';
+import { stripDashes } from '@/lib/search-terms';
+
+export function DocsSearchTrigger({ indexUrl }: { indexUrl: string }) {
+  return (
+    <DocsSearch
+      indexUrl={indexUrl}
+      miniSearchOptions={{ processTerm: stripDashes }}
+    />
+  );
+}
+```
+
+Add the same function to your `createDocsRoute` call — `miniSearchOptions: { processTerm: stripDashes }` — so the index is built with it. Then turn the built-in trigger off and render yours in `actions`, in `app/docs/layout.tsx`:
+
+```tsx
+import '@waveso/docs/styles.css';
+import type { ReactNode } from 'react';
+import { DocsSearchTrigger } from '@/components/docs-search';
+import { docs } from '@/lib/docs';
+
+export default function DocsLayout({ children }: { children: ReactNode }) {
+  return (
+    <docs.Layout
+      search={false}
+      actions={<DocsSearchTrigger indexUrl={docs.searchIndexUrl} />}
+    >
+      {children}
+    </docs.Layout>
+  );
+}
+```
+
+`search={false}` omits the built-in trigger so yours is the only one, and it is also why the refusal is scoped to the forward: the route keeps the function for the index it builds on the server, and nothing crosses to the client but a string.
+
 ### 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:
@@ -746,26 +791,110 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
   contentDir: string;        // relative paths resolve against process.cwd()
   basePath?: string;         // default '/docs'; '/' normalises to ''
   includeDrafts?: boolean;   // default false
-  assertLinks?: boolean;     // default true
+  onBrokenLinks?: DocsLinkSeverity;    // default 'throw'
+  onBrokenAnchors?: DocsLinkSeverity;  // default 'throw'
+  externalRoutes?: readonly string[];  // routes your app owns, not the docs
   frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
 }
+
+type DocsLinkSeverity = 'throw' | 'warn' | 'ignore';
 ```
 
-`createDocsRoute` additionally accepts:
+### Broken links
 
-| Option | Default | Purpose |
-| --- | --- | --- |
-| `langs` | 18 grammars | Typed `readonly DocsLang[]`, so a typo is a compile error |
-| `themes` | `github-light` / `github-dark` | Shiki theme pair |
-| `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 |
-| `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 |
+**`onBrokenLinks` defaults to `'throw'`, and should stay there.** A link that 404s was valid in your editor and on GitHub, so it is the kind of mistake nobody finds by reading — and a warning in a build log is a warning nobody reads. `'warn'` exists for a migration running knowingly against an incomplete corpus.
+
+The error names the file, the line and the closest published route when the link looks like a typo of one:
+
+```
+@waveso/docs: guide.md:12 links to './instalation.md', which resolves to
+'/docs/instalation' — no such page exists. Did you mean '/docs/installation'?
+Fix the link, or add an `aliases` entry to the page it used to point at.
+```
+
+A suggestion is offered only for a genuine near-miss. `/docs/instructions` is five edits from `/docs/installation` — a different word, not a typo — and gets none, because a wrong suggestion sends you to rename a link that was correct.
+
+### Broken anchors
+
+**`onBrokenAnchors` defaults to `'throw'`.** A route used to be verified and its fragment thrown away, so `[setup](./install.md#setup)` built green with no `#setup` anywhere on the page. It is the more common of the two failures: headings get renamed constantly, and nothing renames the links into them.
+
+```
+@waveso/docs: guide.md:12 links to '#instalation', and this page has no
+'#instalation'. Did you mean 'installation'? Heading ids come from the heading
+text, so renaming a heading renames its anchor.
+```
+
+Checked against every `id` in the rendered page rather than against the table of contents — which captures `h2`–`h3` only, so a link to an `h4` is fine, and so is a link to an id one of your `rehypePlugins` added. Lower it to `'warn'` if a plugin of yours adds ids this package cannot see at render time.
+
+Same-page anchors are checked as each page renders, so those errors carry the file and the line. Cross-page anchors need the target page's ids, which exist only once everything has been rendered — `docs.renderAll()` does that pass, and it runs in every build that serves search, because the index route is `force-static`.
+
+### Routes your application owns
+
+**`externalRoutes` only matters at a root mount.** Under `basePath: '/docs'` an absolute link either carries the prefix — so it is documentation and is checked — or it does not, and this package leaves it alone. Under `basePath: '/'` there is no prefix: `/setup` and `/login` look identical, and both are checked against the published pages.
+
+That is the right default, because a root mount is what you choose when the origin serves documentation and nothing else. If yours serves something else too, name what is yours:
+
+```ts
+// lib/docs-root.ts
+import { createDocsRoute } from '@waveso/docs/next';
+
+export const docs = createDocsRoute({
+  contentDir: 'content/docs',
+  basePath: '/',
+  externalRoutes: ['/login', '/dashboard', '/api/'],
+});
+```
+
+A link is skipped when it equals one of these or begins with one followed by `/` — so `/api` covers `/api/keys` and not `/apiary`. It is a statement about your application, so nothing here infers it.
+
+### Translating the chrome
+
+Twenty-two strings, and every one of them is yours to set. They go on `createDocsRoute` rather than on `docs.Layout`, because they are not all rendered in the same place: four are the shell's, two the table of contents', nine come from the markdown component map, two are baked into the HTML by a rehype plugin at build time, and two are announced by a client-side runtime after a copy. A layout prop is upstream of the first four and nothing else.
+
+```ts
+// lib/docs-pt.ts
+import { createDocsRoute } from '@waveso/docs/next';
 
-`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.
+export const docs = createDocsRoute({
+  contentDir: 'content/docs',
+  labels: {
+    // The shell
+    nav: 'Documentação',
+    openNav: 'Abrir navegação',
+    closeNav: 'Fechar navegação',
+    skipToContent: 'Ir para o conteúdo',
+    // The navigation tree — `{title}` is the group's own name
+    expandGroup: 'Abrir {title}',
+    collapseGroup: 'Fechar {title}',
+    externalLink: '(abre num novo separador)',
+    // The table of contents
+    toc: 'Nesta página',
+    backToTop: 'Voltar ao topo',
+    // Your content
+    table: 'Tabela',
+    calloutNote: 'Nota',
+    calloutTip: 'Dica',
+    calloutImportant: 'Importante',
+    calloutWarning: 'Aviso',
+    calloutCaution: 'Atenção',
+    youtubeTitle: 'Vídeo do YouTube',
+    youtubePlay: 'Reproduzir: {title}',
+    youtubeHide: 'Esconder: {title}',
+    // Code frames
+    copyCode: 'Copiar código',
+    copyCodeFrom: 'Copiar código de {title}',
+    copied: 'Copiado para a área de transferência.',
+    copyFailed: 'Falhou. Selecione o código e prima Control ou Command + C.',
+  },
+});
+```
+
+Each key falls back on its own, so a partial map is not a half-translated site. `{title}` is a placeholder rather than a function, because three of these cross from a Server Component to a Client one — and because a translator has to be able to move the name within the sentence, which concatenation forbids.
 
-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.
+The search dialog's own strings are separate, and reachable through `search={{ … }}` — see [Search](#search).
+
+> [!NOTE]
+> These were hardcoded English until 0.5.0, under a `labels` prop on `docs.Layout` that documented itself as the whole of a site's translatable chrome and reached four strings of the twenty-two. A site built the documented way shipped `aria-label="On this page"`, a visible `Back to top`, `aria-label="Tip"` on every callout and `Copy code` on every fence, in English, whatever language it was written in.
 
 ### Redirects and sitemap
 
@@ -852,6 +981,7 @@ try {
 | `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. |
+| `broken-anchor` | A `#fragment` that no heading on the target page owns. | Fix the link, or restore the heading. Heading ids come from the heading text, so renaming one renames its anchor. |
 | `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. |
@@ -860,6 +990,7 @@ try {
 | `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. |
+| `descriptor-limit` | The process ran out of file descriptors while scanning the content directory. | Raise the limit — `ulimit -n`, or `LimitNOFILE` under systemd. The scan holds at most 64 open at once, so something else in the process has them. |
 | `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. |
@@ -884,14 +1015,25 @@ ESM-only is forced rather than chosen: `unified` and the entire `remark-*` / `re
 If you extend the frontmatter schema, use `.exactOptional()` rather than `.optional()` for optional fields: the latter infers `{ description?: string | undefined }`, which is not assignable to `DocFrontmatter`.
 
 > [!NOTE]
-> Under `exactOptionalPropertyTypes: true`, passing `next/link` straight into
-> `DocsSidebar` does not type-check. Next's `LinkProps` re-declares `onClick?`,
-> `onMouseEnter?` and `onTouchStart?` *without* `| undefined`, and React's
+> Passing `next/link` **straight** into `DocsSidebar` does not type-check under
+> `exactOptionalPropertyTypes: true`. Next's `LinkProps` re-declares `onClick?`,
+> `onMouseEnter?` and `onTouchStart?` *without* `| undefined` while 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.
+> `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.
+>
+> Import `DocsLink` instead of casting:
+>
+> ```tsx
+> 'use client';
+> import { DocsLink } from '@waveso/docs/react/next-link';
+> import { DocsSidebar } from '@waveso/docs/react/sidebar';
+>
+> <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />
+> ```
+>
+> `docs.Layout` and `DocsSearch` have always used the same adapter internally,
+> so this only ever came up when composing a shell by hand.
 >
 > `docs.Page` and `DocsSearch` are both unaffected — each wraps `next/link`
 > inside the package, which is where that cast belongs. Without the flag,
@@ -1005,7 +1147,7 @@ src/
   next.ts             # The App Router adapter
   meta.ts             # meta.json ordering
   plugins/            # remark/rehype plugins
-  react/              # Components. Import nothing from next/*
+  react/              # Components. Only next-nav and next-search touch next/*
   styles.css          # Theme tokens + prose styles
 ```
 

package/dist/anchors.d.ts

@@ -0,0 +1,44 @@
+import { RenderedDoc } from "./types.js";
+import { Root } from "hast";
+//#region src/anchors.d.ts
+/**
+ * Every `id` in a tree, which is the set an anchor may target.
+ *
+ * Not the table of contents: that captures `h2`–`h3` only, so checking against
+ * it would reject a perfectly good link to an `h4` — and would miss an id a
+ * `rehypePlugins` entry put on something that is not a heading at all.
+ */
+declare function collectAnchorIds(tree: Root): Set<string>;
+/** An internal link carrying a fragment, as found in a rendered tree. */
+interface AnchorLink {
+  /** The href exactly as it stands in the tree, e.g. `/docs/install#setup`. */
+  href: string;
+  /** Route without the fragment. */
+  route: string;
+  /** Fragment without the `#`, percent-decoded. */
+  fragment: string;
+}
+/**
+ * `#fragment` split off an internal href, or `undefined`.
+ *
+ * Skips anything with a scheme and anything protocol-relative: an anchor on
+ * somebody else's page is theirs to get wrong, and a fragment there is a
+ * routine way to link into a spec.
+ */
+declare function splitAnchor(href: string): AnchorLink | undefined;
+/** Every internal anchor link in a tree, in document order. */
+declare function collectAnchorLinks(tree: Root): AnchorLink[];
+/**
+ * Cross-page anchors, once every page has been rendered.
+ *
+ * `report` is passed in rather than imported so this module stays free of the
+ * error factory and the severity plumbing — it answers "which anchors are
+ * wrong", and the caller owns what that costs.
+ *
+ * A link to a route nothing rendered is a *broken link*, not a broken anchor,
+ * and `assertLinks` has already reported it at its own severity. Skipped here
+ * so one mistake is not two failures.
+ */
+declare function assertAnchors(docs: ReadonlyArray<RenderedDoc<never>> | ReadonlyArray<RenderedDoc>, report: (from: string, link: AnchorLink, known: Set<string>) => void): void;
+//#endregion
+export { AnchorLink, assertAnchors, collectAnchorIds, collectAnchorLinks, splitAnchor };

package/dist/anchors.js

@@ -0,0 +1,76 @@
+import { visit } from "unist-util-visit";
+//#region src/anchors.ts
+/**
+* Every `id` in a tree, which is the set an anchor may target.
+*
+* Not the table of contents: that captures `h2`–`h3` only, so checking against
+* it would reject a perfectly good link to an `h4` — and would miss an id a
+* `rehypePlugins` entry put on something that is not a heading at all.
+*/
+function collectAnchorIds(tree) {
+	const ids = /* @__PURE__ */ new Set();
+	visit(tree, "element", (node) => {
+		const id = node.properties.id;
+		if (typeof id === "string" && id !== "") ids.add(id);
+	});
+	return ids;
+}
+/**
+* `#fragment` split off an internal href, or `undefined`.
+*
+* Skips anything with a scheme and anything protocol-relative: an anchor on
+* somebody else's page is theirs to get wrong, and a fragment there is a
+* routine way to link into a spec.
+*/
+function splitAnchor(href) {
+	if (href === "" || /^([a-z][a-z0-9+.-]*:|\/\/)/i.test(href)) return void 0;
+	const hash = href.indexOf("#");
+	if (hash === -1 || hash === href.length - 1) return void 0;
+	const raw = href.slice(hash + 1);
+	let fragment;
+	try {
+		fragment = decodeURIComponent(raw);
+	} catch {
+		return;
+	}
+	return {
+		href,
+		route: href.slice(0, hash),
+		fragment
+	};
+}
+/** Every internal anchor link in a tree, in document order. */
+function collectAnchorLinks(tree) {
+	const links = [];
+	visit(tree, "element", (node) => {
+		if (node.tagName !== "a") return;
+		const href = node.properties.href;
+		if (typeof href !== "string") return;
+		const anchor = splitAnchor(href);
+		if (anchor !== void 0) links.push(anchor);
+	});
+	return links;
+}
+/**
+* Cross-page anchors, once every page has been rendered.
+*
+* `report` is passed in rather than imported so this module stays free of the
+* error factory and the severity plumbing — it answers "which anchors are
+* wrong", and the caller owns what that costs.
+*
+* A link to a route nothing rendered is a *broken link*, not a broken anchor,
+* and `assertLinks` has already reported it at its own severity. Skipped here
+* so one mistake is not two failures.
+*/
+function assertAnchors(docs, report) {
+	const idsByRoute = /* @__PURE__ */ new Map();
+	for (const doc of docs) idsByRoute.set(doc.href, collectAnchorIds(doc.hast));
+	for (const doc of docs) for (const link of collectAnchorLinks(doc.hast)) {
+		if (link.route === "") continue;
+		const known = idsByRoute.get(link.route);
+		if (known === void 0 || known.has(link.fragment)) continue;
+		report(doc.href, link, known);
+	}
+}
+//#endregion
+export { assertAnchors, collectAnchorIds, collectAnchorLinks, splitAnchor };

package/dist/errors.d.ts

@@ -47,6 +47,8 @@ type DocsErrorCode =
 'draft-link' |
 /** A link resolves to an alias, which is a redirect and not a page. */
 'alias-link' |
+/** A `#fragment` that no heading on the target page owns. */
+'broken-anchor' |
 /** An `aliases` entry is empty, escapes the root, or is not URL-safe. */
 'invalid-alias' |
 /** Two pages claim one alias, or an alias shadows a real route. */
@@ -63,6 +65,8 @@ type DocsErrorCode =
 'missing-content-dir' |
 /** A markdown page is reachable only through a broken symbolic link. */
 'broken-symlink' |
+/** The process ran out of file descriptors while scanning the content. */
+'descriptor-limit' |
 /** An `imageResolver` returned an unusable shape, threw, or was needed. */
 'invalid-image' |
 /** A theme name outside the supported set. */

package/dist/highlighter.js

@@ -165,7 +165,8 @@ function createDocsHighlighter(options = {}) {
 	}
 	const key = JSON.stringify({
 		langs,
-		themes
+		light: themes.light,
+		dark: themes.dark
 	});
 	const cached = highlighters.get(key);
 	if (cached) return cached;

package/dist/link-suggestion.d.ts

@@ -0,0 +1,31 @@
+//#region src/link-suggestion.d.ts
+/**
+ * "Did you mean …?" for a link that matched no page.
+ *
+ * Private — deliberately not an entry point.
+ *
+ * A broken link is almost always a typo, and a typo is a near-miss by
+ * construction: `/instalation` is one edit from `/installation`, while `/login`
+ * is six from anything in a docs tree. That gap is what makes a suggestion
+ * safe to offer and safe to withhold — the same reason `git`, `tsc`, `cargo`
+ * and Python 3.12 all do it, and the reason none of them offers one for a word
+ * that is nowhere near a real name.
+ *
+ * ⚠️ A SUGGESTION ONLY, NEVER A DECISION. Nothing here decides whether a link
+ * is an error; `render.ts` has already decided that by the time it asks. Using
+ * an edit distance to pick between failing and staying silent would be a
+ * heuristic holding a build hostage, which is not a thing to do to somebody
+ * whose page happens to be called `/setting`.
+ */
+/**
+ * The closest route to `target`, or `undefined` if nothing is close enough.
+ *
+ * Ties break on the shortest candidate and then alphabetically, so the message
+ * is the same on every machine — a suggestion that changes between runs reads
+ * as a flaky build.
+ */
+declare function suggestRoute(target: string, routes: Iterable<string>): string | undefined;
+/** ` Did you mean '/installation'?`, or `''` when nothing is close. */
+declare function describeSuggestion(target: string, routes: Iterable<string> | undefined): string;
+//#endregion
+export { describeSuggestion, suggestRoute };