@waveso/docs 0.1.0 → 0.3.0

package/dist/react/youtube.d.ts

@@ -11,13 +11,39 @@ interface YouTubeProps {
   className?: string | undefined;
 }
 /**
- * Click-to-load YouTube embed.
+ * Click-to-load YouTube embed, with **no client JavaScript at all**.
  *
  * An eager `<iframe>` costs ~137 KB of embed document plus ~580 KB gzipped of
- * player JavaScript, on every page view, whether or not anyone presses play.
- * A facade costs one ~15 KB JPEG and loads the rest on demand. On a docs page
- * with three videos that is the difference between a good Lighthouse score and
- * a bad one.
+ * player JavaScript on every page view, whether or not anyone presses play. A
+ * facade costs one ~15 KB JPEG and loads the rest on demand.
+ *
+ * ## Why `<details>` and not `useState`
+ *
+ * This was a `'use client'` component, and that made it the one thing in
+ * `defaultMarkdownComponents` that crossed the client boundary — so every page
+ * carried a reference to it whether or not it embedded a video. Measured on
+ * the smoke build over a corpus containing no YouTube URL anywhere: its code
+ * was in a client chunk **referenced from the prerendered HTML and the flight
+ * payload of every page**, and afterwards it is in no chunk at all.
+ *
+ * Be precise about the size, because the tempting number is the wrong one:
+ * that chunk was 41 KB raw / 12.70 KB brotli, but it was a *shared* chunk and
+ * most of it was not this component. Total client JavaScript went 610.8 KB to
+ * 609.2 KB raw. The win here is a client boundary removed from the path every
+ * consumer renders — one fewer hydration root, and a default map that is now
+ * provably server-only — not a large byte saving.
+ *
+ * `<details>` does the same job in markup. Measured in Chromium: an
+ * `<iframe loading="lazy">` inside a **closed** `<details>` issues no request
+ * at all, and issues one the moment it opens — so the facade still defers the
+ * player, without a state hook, a hydration root or a client reference. Native
+ * also brings the keyboard handling and the disclosure semantics the button
+ * version had to spell out.
+ *
+ * The summary stays in the DOM once open, visually hidden rather than removed:
+ * removing the element under the reader's focus is what the old version needed
+ * a `useEffect` to paper over, and a hidden-but-focusable control keeps focus
+ * where the reader put it *and* leaves them a way to collapse it again.
  *
  * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
  * exist for uploads below 1280×720 and 404s to a broken image with no fallback.

package/dist/react/youtube.js

@@ -1,74 +1,98 @@
-"use client";
-import { useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/youtube.tsx
 const DEFAULT_TITLE = "YouTube video player";
 /**
-* Click-to-load YouTube embed.
+* Click-to-load YouTube embed, with **no client JavaScript at all**.
 *
 * An eager `<iframe>` costs ~137 KB of embed document plus ~580 KB gzipped of
-* player JavaScript, on every page view, whether or not anyone presses play.
-* A facade costs one ~15 KB JPEG and loads the rest on demand. On a docs page
-* with three videos that is the difference between a good Lighthouse score and
-* a bad one.
+* player JavaScript on every page view, whether or not anyone presses play. A
+* facade costs one ~15 KB JPEG and loads the rest on demand.
+*
+* ## Why `<details>` and not `useState`
+*
+* This was a `'use client'` component, and that made it the one thing in
+* `defaultMarkdownComponents` that crossed the client boundary — so every page
+* carried a reference to it whether or not it embedded a video. Measured on
+* the smoke build over a corpus containing no YouTube URL anywhere: its code
+* was in a client chunk **referenced from the prerendered HTML and the flight
+* payload of every page**, and afterwards it is in no chunk at all.
+*
+* Be precise about the size, because the tempting number is the wrong one:
+* that chunk was 41 KB raw / 12.70 KB brotli, but it was a *shared* chunk and
+* most of it was not this component. Total client JavaScript went 610.8 KB to
+* 609.2 KB raw. The win here is a client boundary removed from the path every
+* consumer renders — one fewer hydration root, and a default map that is now
+* provably server-only — not a large byte saving.
+*
+* `<details>` does the same job in markup. Measured in Chromium: an
+* `<iframe loading="lazy">` inside a **closed** `<details>` issues no request
+* at all, and issues one the moment it opens — so the facade still defers the
+* player, without a state hook, a hydration root or a client reference. Native
+* also brings the keyboard handling and the disclosure semantics the button
+* version had to spell out.
+*
+* The summary stays in the DOM once open, visually hidden rather than removed:
+* removing the element under the reader's focus is what the old version needed
+* a `useEffect` to paper over, and a hidden-but-focusable control keeps focus
+* where the reader put it *and* leaves them a way to collapse it again.
 *
 * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
 * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
 */
 function YouTube({ id, title, className }) {
-	const [isPlaying, setIsPlaying] = useState(false);
 	if (!id) return null;
 	const safeId = encodeURIComponent(id);
 	const label = title?.trim() || DEFAULT_TITLE;
 	const rootClassName = ["wave-docs-youtube", className].filter(Boolean).join(" ");
-	if (isPlaying) return /* @__PURE__ */ jsx("div", {
+	return /* @__PURE__ */ jsxs("details", {
 		className: rootClassName,
-		children: /* @__PURE__ */ jsx("iframe", {
-			className: "wave-docs-youtube__frame",
-			src: `https://www.youtube-nocookie.com/embed/${safeId}?autoplay=1&rel=0`,
-			title: label,
-			loading: "lazy",
-			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
-			allowFullScreen: true,
-			ref: (node) => {
-				node?.focus();
-			}
-		})
-	});
-	return /* @__PURE__ */ jsx("div", {
-		className: rootClassName,
-		children: /* @__PURE__ */ jsxs("button", {
-			type: "button",
+		children: [/* @__PURE__ */ jsxs("summary", {
 			className: "wave-docs-youtube__facade",
-			onClick: () => setIsPlaying(true),
-			"aria-label": `Play video: ${label}`,
-			children: [/* @__PURE__ */ jsx("img", {
-				className: "wave-docs-youtube__thumbnail",
-				src: `https://i.ytimg.com/vi/${safeId}/hqdefault.jpg`,
-				alt: "",
-				width: 480,
-				height: 360,
-				loading: "lazy",
-				decoding: "async"
-			}), /* @__PURE__ */ jsx("span", {
-				className: "wave-docs-youtube__play",
-				"aria-hidden": "true",
-				children: /* @__PURE__ */ jsxs("svg", {
-					viewBox: "0 0 68 48",
-					width: "68",
-					height: "48",
+			children: [
+				/* @__PURE__ */ jsx("img", {
+					className: "wave-docs-youtube__thumbnail",
+					src: `https://i.ytimg.com/vi/${safeId}/hqdefault.jpg`,
+					alt: "",
+					width: 480,
+					height: 360,
+					loading: "lazy",
+					decoding: "async"
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-youtube__play",
 					"aria-hidden": "true",
-					focusable: "false",
-					children: [/* @__PURE__ */ jsx("path", {
-						className: "wave-docs-youtube__play-bg",
-						d: "M66.52 7.74a8 8 0 0 0-5.65-5.66C56.1.99 34 .99 34 .99s-22.1 0-26.87 1.09a8 8 0 0 0-5.65 5.66C.39 12.51.39 24 .39 24s0 11.49 1.09 16.26a8 8 0 0 0 5.65 5.66C11.9 47 34 47 34 47s22.1 0 26.87-1.08a8 8 0 0 0 5.65-5.66C67.61 35.49 67.61 24 67.61 24s0-11.49-1.09-16.26"
-					}), /* @__PURE__ */ jsx("path", {
-						className: "wave-docs-youtube__play-arrow",
-						d: "M27 34V14l17 10z"
-					})]
+					children: /* @__PURE__ */ jsxs("svg", {
+						viewBox: "0 0 68 48",
+						width: "68",
+						height: "48",
+						"aria-hidden": "true",
+						focusable: "false",
+						children: [/* @__PURE__ */ jsx("path", {
+							className: "wave-docs-youtube__play-bg",
+							d: "M66.52 7.74a8 8 0 0 0-5.65-5.66C56.1.99 34 .99 34 .99s-22.1 0-26.87 1.09a8 8 0 0 0-5.65 5.66C.39 12.51.39 24 .39 24s0 11.49 1.09 16.26a8 8 0 0 0 5.65 5.66C11.9 47 34 47 34 47s22.1 0 26.87-1.08a8 8 0 0 0 5.65-5.66C67.61 35.49 67.61 24 67.61 24s0-11.49-1.09-16.26"
+						}), /* @__PURE__ */ jsx("path", {
+							className: "wave-docs-youtube__play-arrow",
+							d: "M27 34V14l17 10z"
+						})]
+					})
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-sr-only wave-docs-youtube__label-play",
+					children: `Play video: ${label}`
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-youtube__label-hide",
+					children: `Hide video: ${label}`
 				})
-			})]
-		})
+			]
+		}), /* @__PURE__ */ jsx("iframe", {
+			className: "wave-docs-youtube__frame",
+			loading: "lazy",
+			src: `https://www.youtube-nocookie.com/embed/${safeId}?rel=0&autoplay=1`,
+			title: label,
+			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
+			allowFullScreen: true
+		})]
 	});
 }
 //#endregion

package/dist/render.d.ts

@@ -1,5 +1,7 @@
 import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+import { resolveMarkdownLink } from "./plugins/remark-doc-links.js";
+import { PluggableList } from "unified";
 //#region src/render.d.ts
 /**
  * The parts of {@link ResolvedDocsConfig} rendering actually depends on.
@@ -16,11 +18,11 @@ interface DocsRendererOptions {
    * Reuse an existing highlighter — the escape hatch for grammars and themes
    * outside the curated set. Defaults to {@link createDocsHighlighter}.
    */
-  highlighter?: DocsHighlighter | Promise<DocsHighlighter>;
+  highlighter?: DocsHighlighter | Promise<DocsHighlighter> | undefined;
   /** Grammars to load, when building the default highlighter. */
-  langs?: readonly DocsLang[];
+  langs?: readonly DocsLang[] | undefined;
   /** Theme pair. Defaults to {@link DEFAULT_DOCS_THEMES}. */
-  themes?: DocsThemes;
+  themes?: DocsThemes | undefined;
   /**
    * Prepend an `<h1>` built from `frontmatter.title` when the markdown body
    * has none. Defaults to `true`.
@@ -30,15 +32,52 @@ interface DocsRendererOptions {
    * starting at `h2`, and markdown that repeats the frontmatter title as `# `
    * is a duplication authors forget to keep in step.
    */
-  titleHeading?: boolean;
+  titleHeading?: boolean | undefined;
+  /**
+   * Extra remark plugins, attached **after `remarkGfm` and before
+   * `remarkDocLinks`**.
+   *
+   * Which is to say: while links are still mdast `url` strings, so anything
+   * you emit is folded, contained and asserted exactly like authored markdown.
+   * A plugin emitting `[x](../other/page.md)` gets the same resolution an
+   * author would; one emitting `![i](./x.png)` throws `invalid-image` without
+   * a resolver, for the same reason.
+   *
+   * ⚠️ ATTACHED ONCE, TO A PROCESSOR SHARED BY EVERY FILE. The pipeline is
+   * built and frozen a single time, so a plugin holding state accumulates it
+   * across the whole build rather than per document. Keep them pure, or key
+   * whatever they hold on the vfile.
+   */
+  remarkPlugins?: PluggableList | undefined;
+  /**
+   * Extra rehype plugins, attached **after `rehypeAutolinkHeadings` and before
+   * the code frame and Shiki**.
+   *
+   * The position is the useful one and it is not negotiable: after slugging
+   * and autolinking, so heading ids exist; before Shiki, so a `<pre>` is still
+   * `<pre><code class="language-ts">` with the author's text inside rather
+   * than several hundred token spans. Fences excluded by `excludeLangs` are
+   * not yet disguised at this point either, so a plugin sees every code block
+   * the same way.
+   *
+   * Code-block internals are Shiki's `transformers`, not this. There is no
+   * after-Shiki slot, because the honest documentation for one would be a list
+   * of things you must not do.
+   */
+  rehypePlugins?: PluggableList | undefined;
   /** Replaces the built-in markdown-link resolution. */
-  linkResolver?: LinkResolver;
+  linkResolver?: LinkResolver | undefined;
   /**
    * Resolves image `src` to a public URL and intrinsic dimensions, so
-   * `next/image` can render without `fill`. Images are left untouched when
-   * omitted, or when the resolver returns `undefined`.
+   * `next/image` can render without `fill`.
+   *
+   * Required as soon as any page writes a relative `![](./diagram.png)`: there
+   * is no correct output for one without it, so it throws rather than shipping
+   * a src the browser resolves against the route. Absolute (`/logo.png`) and
+   * external sources need no resolver, and a resolver returning `undefined`
+   * keeps the folded — not the authored — src.
    */
-  imageResolver?: ImageResolver;
+  imageResolver?: ImageResolver | undefined;
   /**
    * Every route the site publishes, used by `assertLinks`. Read at render
    * time, so a host may pass a set it populates during the source walk.
@@ -46,7 +85,36 @@ interface DocsRendererOptions {
    * Without it only unresolvable links can be caught; with it, links to pages
    * that simply do not exist are caught too.
    */
-  knownRoutes?: ReadonlySet<string>;
+  knownRoutes?: ReadonlySet<string> | undefined;
+  /**
+   * Routes of pages excluded from {@link DocsRendererOptions.knownRoutes}
+   * because they are `draft: true`.
+   *
+   * Purely diagnostic, and it earns its place: a link to a draft is a link to a
+   * file plainly sitting on disk, and the generic "no such page exists — add an
+   * `aliases` entry" is advice that cannot be followed. Failing the build is
+   * still right; naming the reason is what makes it fixable.
+   */
+  draftRoutes?: ReadonlySet<string> | undefined;
+  /**
+   * Alias route → the canonical `href` it redirects to.
+   *
+   * Deliberately not folded into {@link DocsRendererOptions.knownRoutes}. An
+   * alias is only a live URL once `createDocsRedirects` is wired into
+   * `next.config.ts`, which the quick start does not do — so treating one as
+   * publishable produced a green build and a hard 404 for every reader who
+   * clicked, which is the exact failure `assertLinks` exists to prevent.
+   * Knowing the target lets the error name the page to link instead.
+   */
+  aliasRoutes?: ReadonlyMap<string, string> | undefined;
+  /**
+   * Fence languages Shiki must not touch, e.g. `['mermaid']`.
+   *
+   * The `<pre><code class="language-mermaid">` reaches your `pre`/`code`
+   * component untouched, which is what lets a consumer render a diagram rather
+   * than a monochrome block of DSL.
+   */
+  excludeLangs?: readonly string[] | undefined;
 }
 /**
  * Renders {@link DocFile}s. Build one per process and reuse it.
@@ -69,4 +137,4 @@ interface DocsRenderer {
  */
 declare function createDocsRenderer(options: DocsRendererOptions): DocsRenderer;
 //#endregion
-export { DocsRenderer, DocsRendererConfig, DocsRendererOptions, createDocsRenderer };
+export { DocsRenderer, DocsRendererConfig, DocsRendererOptions, createDocsRenderer, resolveMarkdownLink };

package/dist/render.js

@@ -1,6 +1,11 @@
+import { docsError } from "./docs-error.js";
 import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
 import { rehypeCaptureToc } from "./plugins/rehype-capture-toc.js";
-import { foldSegments, remarkDocLinks } from "./plugins/remark-doc-links.js";
+import { rehypeCodeFrame } from "./plugins/rehype-code-frame.js";
+import { rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode } from "./plugins/rehype-code-language.js";
+import { rehypeFallbackHeadingIds } from "./plugins/rehype-fallback-heading-ids.js";
+import { rehypeFlattenRoots } from "./plugins/rehype-flatten-roots.js";
+import { foldSegments, remarkDocLinks, resolveMarkdownLink } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
 import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
@@ -11,7 +16,7 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
-import { CONTINUE, EXIT, visit } from "unist-util-visit";
+import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
 //#region src/render.ts
 /**
@@ -54,6 +59,34 @@ function toDirSegments(relativePath) {
 /** `scheme:` — `https:`, `data:`, anything that is not ours to resolve. */
 const IMAGE_HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 /**
+* Is this src already a URL a browser can fetch from any page?
+*
+* `/logo.png`, `//cdn/…` and `https://…` are; everything else is relative to
+* the markdown file and means nothing once the file has become a route.
+*/
+function isPublicImageSrc(src) {
+	return src.startsWith("/") || IMAGE_HAS_SCHEME.test(src);
+}
+/**
+* Check what the resolver actually returned.
+*
+* `ImageResolver` is a type, and a type stops at the JavaScript boundary: a
+* host reading dimensions from a manifest hands back `{ src, width: '1200' }`
+* or a bare string, and the only symptom is `width="undefined"` in the HTML —
+* on one page, at build time, with nothing naming the image or the document.
+*/
+function assertResolvedImage(value, src, relativePath) {
+	const blame = `for image "${src}" in ${relativePath}`;
+	if (typeof value !== "object" || value === null) throw docsError("invalid-image", `@waveso/docs: the imageResolver returned ${typeof value} ${blame}. Return \`{ src, width?, height? }\`, or \`undefined\` to leave the src alone.`);
+	const resolved = value;
+	if (typeof resolved.src !== "string" || resolved.src === "") throw docsError("invalid-image", `@waveso/docs: the imageResolver returned no \`src\` ${blame}. Return \`{ src, width?, height? }\`, or \`undefined\` to leave the src alone.`);
+	for (const key of ["width", "height"]) {
+		const dimension = resolved[key];
+		if (dimension === void 0) continue;
+		if (typeof dimension !== "number" || !Number.isFinite(dimension)) throw docsError("invalid-image", `@waveso/docs: the imageResolver returned a non-numeric \`${key}\` ${blame}. \`next/image\` needs intrinsic pixel dimensions; parse the value before returning it.`);
+	}
+}
+/**
 * An image `src` folded against the page's directory, or `undefined` if it
 * climbs out of the content root.
 *
@@ -63,7 +96,7 @@ const IMAGE_HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 * author means by `![](./diagram.png)` and what the link path has always done.
 */
 function foldImageSrc(src, dirSegments) {
-	if (src.startsWith("/") || IMAGE_HAS_SCHEME.test(src)) return src;
+	if (isPublicImageSrc(src)) return src;
 	const segments = foldSegments(dirSegments, src);
 	return segments === void 0 ? void 0 : segments.join("/");
 }
@@ -76,15 +109,17 @@ function describeLink(file, ref) {
 	const at = ref.line === void 0 ? "" : `:${ref.line}`;
 	return `${file.relativePath}${at}`;
 }
-/** Does the document already open on a page title? */
+/**
+* Does the document already open on a page title?
+*
+* ⚠️ TOP-LEVEL CHILDREN ONLY, DELIBERATELY. A whole-tree walk counted an `h1`
+* anywhere — including `> [!NOTE]\n> # Callout title` — and suppressed the
+* frontmatter heading, so the page title appeared nowhere in the body and the
+* document's only `h1` was buried inside a callout. That is precisely the
+* `page-has-heading-one` failure this option's docstring says it prevents.
+*/
 function hasHeadingOne(tree) {
-	let found = false;
-	visit(tree, "element", (node) => {
-		if (node.tagName !== "h1") return CONTINUE;
-		found = true;
-		return EXIT;
-	});
-	return found;
+	return tree.children.some((child) => child.type === "element" && child.tagName === "h1");
 }
 /**
 * The `<h1>` a page gets when its markdown does not declare one.
@@ -111,7 +146,7 @@ function titleHeadingNode(title) {
 *
 * The tree is the payload: it crosses the RSC boundary, so every byte is
 * shipped to every reader.
-* Positions are 38% of that JSON on a typical page — line and column offsets
+* Positions are roughly a third of that JSON — line and column offsets
 * into a markdown file the browser does not have and cannot fetch. Nothing
 * downstream reads them: link errors are reported from positions captured
 * during the mdast phase, and the TOC works off ids.
@@ -151,27 +186,51 @@ function stripPositions(tree) {
 *                             `remark-gfm` does not implement alerts at all.
 *                             Runs before slugging so a heading inside a
 *                             callout is slugged in its final position.
-*  8. `rehypeSlug`          — assigns heading ids.
-*  9. `rehypeCaptureToc`    — reads those ids. Before autolinking, so heading
-*                             text is captured without the appended `#`.
+*  8. `rehypeFallbackHeadingIds` — before slugging, so an emoji-only heading
+*                             never seeds the collision counter with `''`.
+*  9. `rehypeSlug`          — assigns heading ids.
 * 10. `rehypeAutolinkHeadings` — appends the permalink.
-* 11. `rehypeShikiFromHighlighter` — last: it replaces `<pre><code>` wholesale,
-*                             and anything walking code blocks afterwards
-*                             would be walking Shiki's token spans instead.
+* 11. `rehypePlugins`      — the consumer's, after slugging and autolinking so
+*                             heading ids exist, and before the code steps so
+*                             a `<pre>` is still the author's text.
+* 12. `rehypeNormalizeCodeLanguage` — immediately before Shiki, which is the
+*                             last moment `class="language-JSON"` exists.
+* 13. `rehypeCodeFrame`    — the one step wide window: after 12, which folds
+*                             the language and disguises excluded fences, and
+*                             before Shiki, which destroys `code.data.meta`
+*                             and with it the fence's `title="…"`.
+* 14. `rehypeShikiFromHighlighter` — near-last: it replaces `<pre><code>`
+*                             wholesale, and anything walking code blocks
+*                             afterwards would be walking Shiki's token spans.
+* 15. `rehypeRestoreExcludedCode` — the other side of step 12's disguise.
+* 16. `rehypeFlattenRoots` — because Shiki is what splices a `root` into
+*                             `root.children` and the published
+*                             `RenderedDoc.hast` type says that cannot happen.
+*                             Step 13 is the first thing to put a `root`
+*                             inside an *element* rather than at the top, so
+*                             this recursing into element children is now
+*                             load-bearing rather than defensive.
+* 17. `rehypeCaptureToc`    — DEAD LAST, and that is the design rather than an
+*                             ordering detail. The TOC is then read off the
+*                             identical tree `extractSearchRecords` walks, so
+*                             a consumer plugin cannot put the two out of step
+*                             — and no validation pass or error has to exist
+*                             to notice when it does. Measured both drifts
+*                             before the move: a plugin deleting a heading id
+*                             left `toc` pointing at an id no longer in the
+*                             DOM while search silently dropped the section;
+*                             one adding an `<h2>` produced a search record
+*                             with no TOC entry. Both silent.
 */
-async function buildProcessor(options) {
-	const themes = options.themes ?? DEFAULT_DOCS_THEMES;
-	const highlighter = await (options.highlighter ?? createDocsHighlighter({
-		themes,
-		...options.langs === void 0 ? {} : { langs: options.langs }
-	}));
-	return unified().use(remarkParse).use(remarkGfm).use(remarkDocLinks, {
+async function buildProcessor(options, themes, highlighterPromise) {
+	const highlighter = await highlighterPromise;
+	return unified().use(remarkParse).use(remarkGfm).use(options.remarkPlugins ?? []).use(remarkDocLinks, {
 		basePath: options.config.basePath,
 		...options.linkResolver === void 0 ? {} : { resolve: options.linkResolver }
 	}).use(remarkUnwrapImages).use(remarkYouTube).use(remarkRehype, {
 		allowDangerousHtml: false,
 		footnoteLabelProperties: { className: ["wave-docs-sr-only"] }
-	}).use(rehypeGithubAlerts, { build: buildCallout }).use(rehypeSlug).use(rehypeCaptureToc).use(rehypeAutolinkHeadings, {
+	}).use(rehypeGithubAlerts, { build: buildCallout }).use(rehypeFallbackHeadingIds).use(rehypeSlug).use(rehypeAutolinkHeadings, {
 		behavior: "append",
 		content: HEADING_ANCHOR_CONTENT,
 		properties: {
@@ -179,11 +238,13 @@ async function buildProcessor(options) {
 			ariaHidden: "true",
 			tabIndex: -1
 		}
-	}).use(rehypeShikiFromHighlighter, highlighter, {
+	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame).use(rehypeShikiFromHighlighter, highlighter, {
 		themes,
+		defaultColor: false,
 		fallbackLanguage: "text",
-		defaultLanguage: "text"
-	}).freeze();
+		defaultLanguage: "text",
+		addLanguageClass: true
+	}).use(rehypeRestoreExcludedCode).use(rehypeFlattenRoots).use(rehypeCaptureToc).freeze();
 }
 /**
 * Create a renderer.
@@ -193,33 +254,38 @@ async function buildProcessor(options) {
 * a docs build that takes a second and one that takes a minute.
 */
 function createDocsRenderer(options) {
-	const processorPromise = buildProcessor(options);
-	const { config, imageResolver, knownRoutes } = options;
+	const themes = options.themes ?? DEFAULT_DOCS_THEMES;
+	const processorPromise = buildProcessor(options, themes, options.highlighter ?? createDocsHighlighter({
+		themes,
+		...options.langs === void 0 ? {} : { langs: options.langs }
+	}));
+	processorPromise.catch(() => void 0);
+	const { config, imageResolver, knownRoutes, draftRoutes, aliasRoutes } = options;
 	const titleHeading = options.titleHeading ?? true;
 	/**
-	* Hand every `<img>` to the resolver, FOLDED AND CONTAINED.
-	*
-	* ⚠️ IMAGES USED TO SKIP FOLDING ENTIRELY. `remarkDocLinks` visits `link` and
-	* `definition` and never `image`, so an image `src` reached the resolver
-	* exactly as authored — `../../../../.env` included — while every LINK on the
-	* same page went through `foldSegments`, which refuses a chain that climbs
-	* out of the content root. Two paths into the same kind of consumer code,
-	* one of them guarded.
+	* Fold every `<img src>`, then hand it to the resolver if there is one.
 	*
-	* That is a containment hole rather than a formatting bug: the resolver's
-	* documented job is to turn a src into a public URL, and a reasonable
-	* implementation joins it onto a directory. So the fold happens HERE, before
-	* the call, and an escape throws with the file named — the same treatment
-	* `assertLinks` gives a link that climbs out.
+	* ⚠️ THIS RUNS FOR EVERY DOCUMENT, RESOLVER OR NOT, AND THAT IS THE POINT.
+	* It used to be gated on `imageResolver`, which is the option nobody sets
+	* first — so under the quickstart config `![d](./diagram.png)` shipped
+	* byte-for-byte as authored and the BROWSER resolved it, against the route:
+	* `/docs/guide` asked for `/docs/diagram.png` and `/docs/guide/setup` asked
+	* for `/docs/guide/diagram.png`, from identical markdown. `assertLinks` could
+	* not see it either — `remarkDocLinks` visits `link` and `definition`, never
+	* `image` — so the build stayed green and the containment throw below was
+	* dead code in the only configuration most sites run.
 	*
-	* Absolute and external srcs are passed through untouched: `/logo.png` is
-	* already a public URL and `https://…` belongs to someone else.
+	* A relative src has no correct output without a resolver, so it throws.
+	* Absolute (`/logo.png`) and schemed srcs are already public URLs and are
+	* passed through untouched — but still offered to the resolver, so a host can
+	* rewrite them onto a CDN.
 	*/
 	async function resolveImages(tree, file, resolve) {
 		const images = [];
 		visit(tree, "element", (node) => {
 			if (node.tagName === "img") images.push(node);
 		});
+		if (images.length === 0) return;
 		const context = {
 			segments: file.segments,
 			dirSegments: toDirSegments(file.relativePath),
@@ -229,9 +295,22 @@ function createDocsRenderer(options) {
 			const src = node.properties.src;
 			if (typeof src !== "string" || src === "") return;
 			const folded = foldImageSrc(src, context.dirSegments);
-			if (folded === void 0) throw new Error(`@waveso/docs: image "${src}" in ${file.relativePath} climbs above the content root.`);
-			const resolved = await resolve(folded, context);
-			if (resolved === void 0) return;
+			if (folded === void 0) throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} climbs above the content root.`);
+			if (resolve === void 0) {
+				if (isPublicImageSrc(src)) return;
+				throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} is relative to the markdown file, and nothing can serve it: the browser would resolve it against the page route, so the same markdown would request a different file from every page. Pass an \`imageResolver\`, or move the image under \`public/\` and write an absolute src such as "/diagram.png".`);
+			}
+			let resolved;
+			try {
+				resolved = await resolve(folded, context);
+			} catch (error) {
+				throw docsError("invalid-image", `@waveso/docs: the imageResolver threw on image "${src}" in ${file.relativePath}.`, { cause: error });
+			}
+			if (resolved === void 0) {
+				node.properties.src = folded;
+				return;
+			}
+			assertResolvedImage(resolved, src, file.relativePath);
 			node.properties.src = resolved.src;
 			if (resolved.width !== void 0) node.properties.width = resolved.width;
 			if (resolved.height !== void 0) node.properties.height = resolved.height;
@@ -245,10 +324,14 @@ function createDocsRenderer(options) {
 	*/
 	function assertLinks(file, refs) {
 		for (const ref of refs) {
-			if (ref.href === void 0) throw new Error(`@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
-			if (knownRoutes === void 0) continue;
+			if (ref.href === void 0) throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
+			if (knownRoutes === void 0 || ref.asset) continue;
 			const route = toRouteKey(ref.href);
-			if (!knownRoutes.has(route)) throw new Error(`@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists. Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
+			if (knownRoutes.has(route)) continue;
+			if (draftRoutes?.has(route)) throw docsError("draft-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — a page marked \`draft: true\`, so it is not published and the link would 404. Publish the page, remove the link, or build with \`includeDrafts\`.`);
+			const aliasTarget = aliasRoutes?.get(route);
+			if (aliasTarget !== void 0) throw docsError("alias-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — an alias that redirects to '${aliasTarget}'. An alias is not a page: it 404s unless \`createDocsRedirects\` is wired into \`next.config.ts\`, and it is never prerendered. Link to '${aliasTarget}' directly.`);
+			throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists. Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
 		}
 	}
 	return { async render(file) {
@@ -264,7 +347,7 @@ function createDocsRenderer(options) {
 		};
 		const hast = await processor.run(processor.parse(vfile), vfile);
 		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
-		if (imageResolver !== void 0) await resolveImages(hast, file, imageResolver);
+		await resolveImages(hast, file, imageResolver);
 		if (config.assertLinks) assertLinks(file, vfile.data.docLinks ?? []);
 		return {
 			frontmatter: file.frontmatter,
@@ -276,4 +359,4 @@ function createDocsRenderer(options) {
 	} };
 }
 //#endregion
-export { createDocsRenderer };
+export { createDocsRenderer, resolveMarkdownLink };