@waveso/docs 0.1.0 → 0.2.0

package/dist/react/search-dialog.js

@@ -1,5 +1,6 @@
 "use client";
-import { SEARCH_INDEX_OPTIONS } from "../search-options.js";
+import { docsError } from "../docs-error.js";
+import { mergeSearchOptions } from "../search-options.js";
 import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
@@ -25,7 +26,7 @@ const FOCUSABLE_SELECTOR = [
 * portalled to `document.body`, so a navbar's stacking context cannot trap
 * it behind the page.
 */
-function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", maxResults = 8, debounceMs = 120 }) {
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", maxResults = 8, debounceMs = 120, className, searchOptions }) {
 	const [isOpen, setIsOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [hits, setHits] = useState([]);
@@ -37,29 +38,34 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	const inputRef = useRef(null);
 	const listRef = useRef(null);
 	const returnFocusRef = useRef(null);
-	const indexRef = useRef(null);
+	const indexCacheRef = useRef(/* @__PURE__ */ new Map());
+	const searchOptionsRef = useRef(searchOptions);
 	/** Whether the dialog has ever been open. See the focus effect below. */
 	const hasOpenedRef = useRef(false);
 	const baseId = useId();
 	const listId = `${baseId}-results`;
 	const optionId = (index) => `${baseId}-option-${index}`;
-	/** Load the index at most once; a failure clears the cache so a retry can. */
+	useEffect(() => {
+		searchOptionsRef.current = searchOptions;
+	}, [searchOptions]);
+	/** Load each URL at most once; a failure evicts that key so a retry can. */
 	const ensureIndex = useCallback(() => {
-		let pending = indexRef.current;
-		if (pending === null) {
-			pending = loadIndex(indexUrl).catch((error) => {
-				indexRef.current = null;
+		const cache = indexCacheRef.current;
+		let pending = cache.get(indexUrl);
+		if (pending === void 0) {
+			pending = loadIndex(indexUrl, searchOptionsRef.current).catch((error) => {
+				cache.delete(indexUrl);
 				throw error;
 			});
-			indexRef.current = pending;
+			cache.set(indexUrl, pending);
 		}
 		return pending;
 	}, [indexUrl]);
 	const warmIndex = useCallback(() => {
-		if (indexRef.current !== null) return;
+		if (indexCacheRef.current.has(indexUrl)) return;
 		setStatus("loading");
 		ensureIndex().then(() => setStatus("ready"), () => setStatus("error"));
-	}, [ensureIndex]);
+	}, [ensureIndex, indexUrl]);
 	const openDialog = useCallback(() => {
 		returnFocusRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
 		setIsOpen(true);
@@ -83,6 +89,20 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		openDialog,
 		closeDialog
 	]);
+	useEffect(() => {
+		if (!isOpen) return;
+		function handleKeyDown(event) {
+			if (event.key === "Escape") {
+				event.preventDefault();
+				event.stopPropagation();
+				closeDialog();
+				return;
+			}
+			if (event.key === "Tab") trapFocus(dialogRef.current, event);
+		}
+		document.addEventListener("keydown", handleKeyDown, true);
+		return () => document.removeEventListener("keydown", handleKeyDown, true);
+	}, [isOpen, closeDialog]);
 	useEffect(() => {
 		const isApple = /mac|iphone|ipad|ipod/i.test(navigator.userAgent);
 		setShortcutHint(isApple ? "⌘K" : "Ctrl K");
@@ -153,17 +173,8 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		closeDialog();
 		navigate(hit.href);
 	}, [closeDialog, navigate]);
-	function handleDialogKeyDown(event) {
-		if (event.key === "Escape") {
-			event.preventDefault();
-			event.stopPropagation();
-			closeDialog();
-			return;
-		}
-		if (event.key === "Tab") {
-			trapFocus(dialogRef.current, event);
-			return;
-		}
+	function handleInputKeyDown(event) {
+		if (event.nativeEvent.isComposing || event.keyCode === 229) return;
 		if (event.key === "ArrowDown" || event.key === "ArrowUp") {
 			if (hits.length === 0) return;
 			event.preventDefault();
@@ -182,7 +193,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
 		type: "button",
 		ref: triggerRef,
-		className: "wave-docs-search-trigger",
+		className: ["wave-docs-search-trigger", className].filter(Boolean).join(" "),
 		"aria-label": triggerLabel,
 		"aria-keyshortcuts": "Meta+K Control+K",
 		onClick: openDialog,
@@ -206,7 +217,6 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			role: "dialog",
 			"aria-modal": "true",
 			"aria-label": dialogLabel,
-			onKeyDown: handleDialogKeyDown,
 			children: [
 				/* @__PURE__ */ jsxs("div", {
 					className: "wave-docs-search-input-row",
@@ -223,6 +233,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 						placeholder,
 						value: query,
 						onChange: (event) => setQuery(event.target.value),
+						onKeyDown: handleInputKeyDown,
 						autoComplete: "off",
 						autoCorrect: "off",
 						spellCheck: false
@@ -335,10 +346,10 @@ function SearchStatus({ status, query, hitCount }) {
 * `loadJSONAsync` yields between chunks so deserialising a large index does
 * not freeze the frame the dialog just opened in.
 */
-async function loadIndex(url) {
+async function loadIndex(url, overrides) {
 	const [{ default: MiniSearchClass }, response] = await Promise.all([import("minisearch"), fetch(url)]);
-	if (!response.ok) throw new Error(`Failed to load the search index from ${url} (HTTP ${response.status}).`);
-	return MiniSearchClass.loadJSONAsync(await response.text(), SEARCH_INDEX_OPTIONS);
+	if (!response.ok) throw docsError("search-index-unavailable", `Failed to load the search index from ${url} (HTTP ${response.status}).`);
+	return MiniSearchClass.loadJSONAsync(await response.text(), mergeSearchOptions(overrides));
 }
 /**
 * Narrow one MiniSearch result. Its stored fields are untyped by design, and
@@ -392,10 +403,16 @@ function trapFocus(root, event) {
 		event.preventDefault();
 		return;
 	}
-	if (event.shiftKey && document.activeElement === first) {
+	const active = document.activeElement;
+	if (!(active instanceof HTMLElement) || !root.contains(active)) {
+		event.preventDefault();
+		(event.shiftKey ? last : first).focus();
+		return;
+	}
+	if (event.shiftKey && active === first) {
 		event.preventDefault();
 		last.focus();
-	} else if (!event.shiftKey && document.activeElement === last) {
+	} else if (!event.shiftKey && active === last) {
 		event.preventDefault();
 		first.focus();
 	}

package/dist/react/toc.js

@@ -3,6 +3,13 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/toc.tsx
 const DEFAULT_ROOT_MARGIN = "-80px 0px -60% 0px";
+/**
+* How many frames to keep looking for headings that are not in the document
+* yet. ~1s at 60Hz, which covers a `<Suspense>` boundary resolving or a
+* tabs/accordion wrapper revealing its panel. Bounded because the loop must
+* also terminate on a page whose headings genuinely never arrive.
+*/
+const MAX_ATTACH_FRAMES = 60;
 function flattenTocIds(entries) {
 	const ids = [];
 	const walk = (list) => {
@@ -46,11 +53,27 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 			rootMargin,
 			threshold: 0
 		});
-		for (const id of ids) {
-			const element = document.getElementById(id);
-			if (element !== null) observer.observe(element);
-		}
-		return () => observer.disconnect();
+		let frame;
+		let framesLeft = MAX_ATTACH_FRAMES;
+		const attach = () => {
+			let attached = 0;
+			for (const id of ids) {
+				const element = document.getElementById(id);
+				if (element !== null) {
+					observer.observe(element);
+					attached += 1;
+				}
+			}
+			if (attached === 0 && framesLeft > 0 && typeof requestAnimationFrame === "function") {
+				framesLeft -= 1;
+				frame = requestAnimationFrame(attach);
+			}
+		};
+		attach();
+		return () => {
+			if (frame !== void 0) cancelAnimationFrame(frame);
+			observer.disconnect();
+		};
 	}, [ids, rootMargin]);
 	if (entries.length === 0) return null;
 	return /* @__PURE__ */ jsx("nav", {

package/dist/react/youtube.js

@@ -1,5 +1,5 @@
 "use client";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/youtube.tsx
 const DEFAULT_TITLE = "YouTube video player";
@@ -17,6 +17,10 @@ const DEFAULT_TITLE = "YouTube video player";
 */
 function YouTube({ id, title, className }) {
 	const [isPlaying, setIsPlaying] = useState(false);
+	const frameRef = useRef(null);
+	useEffect(() => {
+		if (isPlaying) frameRef.current?.focus();
+	}, [isPlaying]);
 	if (!id) return null;
 	const safeId = encodeURIComponent(id);
 	const label = title?.trim() || DEFAULT_TITLE;
@@ -30,9 +34,7 @@ function YouTube({ id, title, className }) {
 			loading: "lazy",
 			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
 			allowFullScreen: true,
-			ref: (node) => {
-				node?.focus();
-			}
+			ref: frameRef
 		})
 	});
 	return /* @__PURE__ */ jsx("div", {

package/dist/render.d.ts

@@ -16,11 +16,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 +30,20 @@ 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;
   /** 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 +51,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.

package/dist/render.js

@@ -1,5 +1,9 @@
+import { docsError } from "./docs-error.js";
 import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
 import { rehypeCaptureToc } from "./plugins/rehype-capture-toc.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 } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
@@ -11,7 +15,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 +58,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 +95,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 +108,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.
@@ -151,27 +185,31 @@ 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
+*  8. `rehypeFallbackHeadingIds` — before slugging, so an emoji-only heading
+*                             never seeds the collision counter with `''`.
+*  9. `rehypeSlug`          — assigns heading ids.
+* 10. `rehypeCaptureToc`    — reads those ids. Before autolinking, so heading
 *                             text is captured without the appended `#`.
-* 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. `rehypeAutolinkHeadings` — appends the permalink.
+* 12. `rehypeNormalizeCodeLanguage` — immediately before Shiki, which is the
+*                             last moment `class="language-JSON"` exists.
+* 13. `rehypeShikiFromHighlighter` — near-last: it replaces `<pre><code>`
+*                             wholesale, and anything walking code blocks
+*                             afterwards would be walking Shiki's token spans.
+* 14. `rehypeRestoreExcludedCode` — the other side of step 12's disguise.
+* 15. `rehypeFlattenRoots` — last of all, because Shiki is what splices a
+*                             `root` into `root.children` and the published
+*                             `RenderedDoc.hast` type says that cannot happen.
 */
-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 }
-	}));
+async function buildProcessor(options, themes, highlighterPromise) {
+	const highlighter = await highlighterPromise;
 	return unified().use(remarkParse).use(remarkGfm).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(rehypeCaptureToc).use(rehypeAutolinkHeadings, {
 		behavior: "append",
 		content: HEADING_ANCHOR_CONTENT,
 		properties: {
@@ -179,11 +217,13 @@ async function buildProcessor(options) {
 			ariaHidden: "true",
 			tabIndex: -1
 		}
-	}).use(rehypeShikiFromHighlighter, highlighter, {
+	}).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeShikiFromHighlighter, highlighter, {
 		themes,
+		defaultColor: false,
 		fallbackLanguage: "text",
-		defaultLanguage: "text"
-	}).freeze();
+		defaultLanguage: "text",
+		addLanguageClass: true
+	}).use(rehypeRestoreExcludedCode).use(rehypeFlattenRoots).freeze();
 }
 /**
 * Create a renderer.
@@ -193,33 +233,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 +274,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 +303,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 +326,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,

package/dist/search-index.d.ts

@@ -1,14 +1,6 @@
 import { RenderedDoc, SearchRecord } from "./types.js";
+import { Options } from "minisearch";
 //#region src/search-index.d.ts
-/** Options for {@link extractSearchRecords}. */
-interface ExtractSearchRecordsOptions {
-  /**
-   * Maximum length of {@link SearchRecord.text}, in characters. Defaults to
-   * 300 — long enough to carry a section's vocabulary into the index, short
-   * enough that a 300-page corpus stays under a megabyte.
-   */
-  excerptLength?: number;
-}
 /**
  * Split a rendered document into section-scoped {@link SearchRecord}s.
  *
@@ -26,26 +18,52 @@ interface ExtractSearchRecordsOptions {
  * does with the same heading — the two must not disagree about which sections
  * exist.
  *
+ * `text` is the section's PROSE IN FULL. It used to be cut to 300 characters
+ * before indexing, which on a normal corpus (200 pages × 6 sections, ~1,686
+ * characters of prose each) dropped 82% of the words from the index — and
+ * `combineWith: 'AND'` compounds it, since every term of a query then has to
+ * land inside the surviving prefix of the same section. The cap bought nothing
+ * back: `storeFields` does not carry `text`, so not one character of the kept
+ * prefix was ever rendered. Truncate for display, in the layer that displays.
+ *
  * Not generic over the frontmatter type, deliberately: `frontmatter.title` is
  * the only field read, and a `RenderedDoc` carrying a project's own fields is
  * assignable to this signature already. A type parameter here would appear in
  * every call site and constrain nothing.
  */
-declare function extractSearchRecords(doc: RenderedDoc, options?: ExtractSearchRecordsOptions): SearchRecord[];
+declare function extractSearchRecords(doc: RenderedDoc): SearchRecord[];
 /**
  * Build a serialised MiniSearch index from extracted records.
  *
  * The return value is JSON, ready for `MiniSearch.loadJSON` on the client or
- * for {@link writeSearchIndex} to put on disk.
+ * for {@link writeSearchIndex} to put on disk. The output is byte-stable for a
+ * given record list, so an index committed to the repository does not dirty
+ * the diff on every build.
+ *
+ * ⚠️ `options` MUST ALSO REACH THE DIALOG — pass the identical object to
+ * `SearchDialog`'s `searchOptions`. Both sides feed it through
+ * `mergeSearchOptions`, and a `tokenize` or `processTerm` applied to the
+ * documents but not to the query produces an index whose terms no query can
+ * spell: zero results, no error, nothing in the console.
  */
-declare function buildSearchIndex(records: SearchRecord[]): string;
+declare function buildSearchIndex(records: SearchRecord[], options?: Partial<Options<SearchRecord>>): string;
 /**
  * Write the serialised index to `outFile`, creating parent directories.
  *
  * Returns the byte size written, so a build step can log it or assert a
  * budget — a docs index that quietly crosses a megabyte is a regression
  * nobody notices until the dialog takes a second to open.
+ *
+ * ⚠️ WRITTEN BESIDE THE TARGET AND RENAMED OVER IT, NEVER INTO IT. The target
+ * is normally `public/search-index.json`, a live static asset: writing in
+ * place truncates it to zero and grows it back in 1 MiB chunks, and a fetch
+ * landing in that window gets a 200 with a half-written body. `response.ok`
+ * passes, the parse throws, and the dialog is stuck in its error state —
+ * *"Try reloading the page"* — for every visitor, reloading forever, until
+ * someone redeploys content that did not change. `rename` is atomic within a
+ * filesystem, so a reader sees either the whole old file or the whole new one;
+ * it also makes two concurrent builds safe.
  */
-declare function writeSearchIndex(records: SearchRecord[], outFile: string): Promise<number>;
+declare function writeSearchIndex(records: SearchRecord[], outFile: string, options?: Partial<Options<SearchRecord>>): Promise<number>;
 //#endregion
-export { ExtractSearchRecordsOptions, buildSearchIndex, extractSearchRecords, writeSearchIndex };
+export { buildSearchIndex, extractSearchRecords, writeSearchIndex };