@waveso/docs 0.1.0 → 0.3.0

package/dist/next.js

@@ -1,10 +1,17 @@
+import { docsError } from "./docs-error.js";
+import { DOCS_CONTENT_ID } from "./docs-content-id.js";
+import { mapPooled } from "./map-pooled.js";
 import { createMarkdownComponents } from "./react/markdown-components.js";
 import { DocContent } from "./react/doc-content.js";
-import "./react/skip-link.js";
+import { DocsToc } from "./react/toc.js";
+import { wrapNextLink } from "./react/next-link.js";
 import { createDocsRenderer } from "./render.js";
-import { createDocsSource, resolveDocsConfig, toAliasRoute } from "./source.js";
+import { toAliasRoute } from "./route-path.js";
+import { createDocsSource, resolveDocsConfig } from "./source.js";
+import { sitemapLimitWarning } from "./sitemap-limit.js";
 import { stat } from "node:fs/promises";
-import { createElement } from "react";
+import { createHash } from "node:crypto";
+import { Fragment, cache, createElement } from "react";
 //#region src/next.ts
 /**
 * The Next.js App Router adapter.
@@ -38,16 +45,39 @@ import { createElement } from "react";
 * export const generateMetadata = docs.generateMetadata;
 * ```
 *
-* `next` is an *optional* peer dependency, so its modules are imported lazily
-* and only from the code paths that render. That is what lets
+* `next` is an *optional* peer dependency, so **Next's own modules** are
+* imported lazily and only from the code paths that render. That is what lets
 * {@link createDocsSitemap} and {@link createDocsRedirects} be called from
 * `next.config.ts` — which Node loads outside the Next runtime — without
-* dragging React and Next's client runtime into the config load.
+* dragging Next's client runtime into the config load.
+*
+* React itself is *not* excluded: this module statically imports `react` and
+* the package's own React layer, so importing it from `next.config.ts` costs
+* around 210 ms and ~870 modules (measured against 24 ms for an empty config).
+* That is a startup cost, not a correctness problem, and it is stated here
+* rather than claimed away — an earlier version of this note said React stayed
+* out of the config load, which was never true.
 */
+/**
+* Pages rendered at once by {@link DocsRoute.renderAll}.
+*
+* High enough that the pipeline — CPU-bound and effectively synchronous — never
+* idles, low enough that an async `imageResolver` cannot put an entire site's
+* worth of trees and network calls in flight simultaneously.
+*/
+const RENDER_CONCURRENCY = 16;
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
 /**
+* A React component type: a function, or an object tagged with `$$typeof`
+* (`forwardRef`, `memo`, lazy…). Anything else that reaches `createElement`
+* throws four frames inside React.
+*/
+function isComponentLike(value) {
+	return typeof value === "function" || isRecord(value) && "$$typeof" in value;
+}
+/**
 * Pull the default export out of a lazily-imported module.
 *
 * This is the one place a cast is unavoidable — the import crosses a boundary
@@ -56,8 +86,9 @@ function isRecord(value) {
 * than as `undefined is not a function` four frames inside React.
 */
 function readDefaultExport(mod, specifier) {
-	const value = isRecord(mod) && "default" in mod ? mod.default : mod;
-	if (typeof value !== "function" && !isRecord(value)) throw new Error(`@waveso/docs: '${specifier}' has no usable default export. The \`@waveso/docs/next\` entry point requires Next.js 16 — install \`next\`, or build your pages from \`@waveso/docs/react/*\` instead.`);
+	let value = isRecord(mod) && "default" in mod ? mod.default : mod;
+	if (!isComponentLike(value) && isRecord(value) && "default" in value) value = value.default;
+	if (typeof value !== "function" && !isRecord(value)) throw docsError("missing-peer", `@waveso/docs: '${specifier}' has no usable default export. The \`@waveso/docs/next\` entry point requires Next.js 16 — install \`next\`, or build your pages from \`@waveso/docs/react/*\` instead.`);
 	return value;
 }
 /**
@@ -72,33 +103,16 @@ async function importNext(load, specifier) {
 	try {
 		return await load();
 	} catch (error) {
-		throw new Error(`@waveso/docs: could not load '${specifier}'. The \`@waveso/docs/next\` entry point needs Next.js 16, which is an optional peer dependency — install \`next\`. Outside Next, build your pages from \`@waveso/docs/react/*\` and load content yourself with \`@waveso/docs/source\` and \`@waveso/docs/render\`.`, { cause: error });
+		throw docsError("missing-peer", `@waveso/docs: could not load '${specifier}'. The \`@waveso/docs/next\` entry point needs Next.js 16, which is an optional peer dependency — install \`next\`. Outside Next, build your pages from \`@waveso/docs/react/*\` and load content yourself with \`@waveso/docs/source\` and \`@waveso/docs/render\`.`, { cause: error });
 	}
 }
 async function loadNotFound() {
 	const mod = await importNext(() => import("next/navigation"), "next/navigation");
 	const value = isRecord(mod) ? mod.notFound : void 0;
-	if (typeof value !== "function") throw new Error("@waveso/docs: 'next/navigation' has no `notFound` export. The `@waveso/docs/next` entry point requires Next.js 16.");
+	if (typeof value !== "function") throw docsError("missing-peer", "@waveso/docs: 'next/navigation' has no `notFound` export. The `@waveso/docs/next` entry point requires Next.js 16.");
 	return value;
 }
 /**
-* Adapt `next/link` to {@link DocsLinkProps}.
-*
-* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
-* `boolean | null`; the React layer promises neither, because it must also run
-* with a plain `<a>`. One wrapper keeps that mismatch in a single
-* place instead of at every call site.
-*/
-function wrapNextLink(NextLink) {
-	return function DocsNextLink({ href, prefetch, children, ...rest }) {
-		return createElement(NextLink, {
-			...rest,
-			href,
-			...prefetch === void 0 ? {} : { prefetch }
-		}, children);
-	};
-}
-/**
 * Adapt `next/image` to {@link DocsImageProps}.
 *
 * Every prop is named rather than spread. `next/image` types `width`/`height`
@@ -155,13 +169,26 @@ function createDocsRoute(options) {
 	const config = resolveDocsConfig(options);
 	const source = createDocsSource(options);
 	const siteUrl = normalizeSiteUrl(options.siteUrl);
-	const contentId = options.contentId ?? "docs-content";
-	const rescanPerRequest = options.rescanPerRequest ?? process.env.NODE_ENV !== "production";
+	const rescanPerRequest = process.env.NODE_ENV !== "production";
 	let renderer = null;
 	const knownRoutes = /* @__PURE__ */ new Set();
+	const draftRoutes = /* @__PURE__ */ new Set();
+	const aliasRoutes = /* @__PURE__ */ new Map();
 	let routesLoaded = null;
 	/**
-	* Drop the cached scan so the next query reads the disk again.
+	* Drop the cached scan so the next query reads the disk again — at most once
+	* per request.
+	*
+	* `React.cache` is doing real work here, not memoising for speed. Next runs
+	* `generateMetadata` and `Page` concurrently, and a layout calling
+	* `source.nav()` is a third caller; each used to invalidate independently,
+	* so each discarded the others' in-flight scan. Measured on a 401-file tree:
+	* 22 readdir + 824 readFile per request, against 11 + 412 for a single scan,
+	* at 39 ms — which is also why the old docstring's "single-digit
+	* milliseconds" was wrong. Inside a request the first caller invalidates and
+	* the rest see the memo; outside one (a sitemap built from `next.config.ts`,
+	* a script) `cache` does not memoise at all, so those callers keep the old
+	* invalidate-every-time behaviour, which is what they want.
 	*
 	* `knownRoutes` is added to, never cleared: it is shared with the renderer,
 	* and emptying it while a concurrent render is asserting links would fail
@@ -169,26 +196,76 @@ function createDocsRoute(options) {
 	* deleted page only makes dev *more* permissive than the production build,
 	* which is the right direction to be wrong in.
 	*/
-	const invalidate = () => {
+	const invalidate = cache(() => {
 		source.invalidate();
 		routesLoaded = null;
-	};
-	const loadRoutes = () => routesLoaded ??= source.all().then((files) => {
+	});
+	/**
+	* Record each page's own route in `into`, and each of its aliases in
+	* `aliasRoutes`.
+	*
+	* The two are kept apart on purpose. An alias used to be added to
+	* `knownRoutes` on the reasoning that a permanent redirect resolves — but it
+	* only resolves once `createDocsRedirects` is wired into `next.config.ts`,
+	* which the quick start never does, and `generateStaticParams` does not emit
+	* it either. So a page linking a sibling's alias built green and 404'd for
+	* every reader, with `dynamicParams = false` making it a hard 404. The
+	* renderer now names the alias's target instead, which is better advice than
+	* the acceptance ever was: the author gets told where the page actually is.
+	*/
+	const collectRoutes = (into, files) => {
 		for (const file of files) {
-			knownRoutes.add(file.href);
-			for (const alias of file.frontmatter.aliases ?? []) knownRoutes.add(toAliasRoute(alias, config.basePath, file.relativePath));
+			into.add(file.href);
+			for (const alias of file.frontmatter.aliases ?? []) aliasRoutes.set(toAliasRoute(alias, config.basePath, file.relativePath), file.href);
 		}
+	};
+	const loadRoutes = () => routesLoaded ??= Promise.all([source.all(), source.drafts()]).then(([published, drafts]) => {
+		collectRoutes(knownRoutes, published);
+		collectRoutes(draftRoutes, drafts);
 	});
 	const loadRenderer = () => renderer ??= createDocsRenderer({
 		config,
 		knownRoutes,
+		draftRoutes,
+		aliasRoutes,
 		...options.highlighter === void 0 ? {} : { highlighter: options.highlighter },
 		...options.langs === void 0 ? {} : { langs: options.langs },
 		...options.themes === void 0 ? {} : { themes: options.themes },
+		...options.excludeLangs === void 0 ? {} : { excludeLangs: options.excludeLangs },
 		...options.titleHeading === void 0 ? {} : { titleHeading: options.titleHeading },
+		...options.remarkPlugins === void 0 ? {} : { remarkPlugins: options.remarkPlugins },
+		...options.rehypePlugins === void 0 ? {} : { rehypePlugins: options.rehypePlugins },
 		...options.linkResolver === void 0 ? {} : { linkResolver: options.linkResolver },
 		...options.imageResolver === void 0 ? {} : { imageResolver: options.imageResolver }
 	});
+	/** Re-read the disk on the route's schedule before delegating. */
+	const rescanned = (read) => {
+		return (...args) => {
+			if (rescanPerRequest) invalidate();
+			return read(...args);
+		};
+	};
+	/**
+	* The source handed to layouts.
+	*
+	* `docs.source.nav()` is the documented way to feed `DocsSidebar`, and it was
+	* the one reader that never invalidated — so in dev, the request after adding
+	* or renaming a page rendered the *new* body beside the *old* sidebar, and
+	* only the request after that agreed with itself. Everything else on the
+	* route already rescanned; this closes the last hole.
+	*/
+	const requestScopedSource = {
+		config: source.config,
+		all: rescanned(() => source.all()),
+		drafts: rescanned(() => source.drafts()),
+		find: rescanned((segments) => source.find(segments)),
+		nav: rescanned(() => source.nav()),
+		slugs: rescanned(() => source.slugs()),
+		invalidate: () => {
+			source.invalidate();
+			routesLoaded = null;
+		}
+	};
 	/**
 	* `find` returns drafts regardless of config so a preview route can opt in;
 	* a public route must not.
@@ -211,30 +288,58 @@ function createDocsRoute(options) {
 		const files = await source.all();
 		await loadRoutes();
 		const renderer = loadRenderer();
-		return Promise.all(files.map((file) => renderer.render(file)));
+		return mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
+	};
+	const searchIndexUrl = `${config.basePath}/search-index.json`;
+	/**
+	* Fail loudly when the search-index route was not frozen at build time.
+	*
+	* The signal is `NEXT_PHASE`, which Next sets to `phase-production-build`
+	* while prerendering — verified in both output modes, and `undefined` under
+	* `next start`. It is internal and undocumented, which is why the CI smoke
+	* build asserts the prerendered body exists: if this ever changes meaning it
+	* fails there, in this repository, rather than in a consumer's deploy.
+	*
+	* The alternative was a `console.error`, and it is not one. A warning in a
+	* serverless log is unread, and the observable symptom — a search dialog
+	* stuck on "could not load the index" — arrives days later with nothing
+	* connecting it to a missing line in a route file.
+	*/
+	const assertPrerendered = () => {
+		if (process.env.NODE_ENV === "production" && process.env.NEXT_PHASE !== "phase-production-build") throw docsError("search-index-dynamic", `the search index was requested at runtime instead of being built into your deployment. Add \`export const dynamic = 'force-static'\` to app${searchIndexUrl}/route.ts — it has to be a literal, like \`dynamicParams\`. Without it Next re-renders every page of your corpus per request, from markdown that is not in the deployment bundle. (Building the index somewhere else on purpose? Use \`docs.renderAll()\` with \`extractSearchRecords\` and \`buildSearchIndex\` from \`@waveso/docs/search-index\` instead of calling this handler.)`);
+	};
+	const searchIndex = async () => {
+		assertPrerendered();
+		const { buildSearchIndex, extractSearchRecords } = await import("./search-index.js");
+		const json = buildSearchIndex((await renderAll()).flatMap((doc) => extractSearchRecords(doc)), options.miniSearchOptions ?? {});
+		return new Response(json, { headers: {
+			"content-type": "application/json",
+			"cache-control": "public, max-age=0, must-revalidate",
+			etag: `"${createHash("sha1").update(json).digest("hex")}"`
+		} });
 	};
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
 		const components = await loadNextComponents();
-		return createElement("article", {
-			className: "wave-docs-prose",
-			...contentId === false ? {} : {
-				id: contentId,
-				tabIndex: -1
-			}
+		return createElement(Fragment, null, createElement("main", {
+			className: "wave-docs-layout__main",
+			id: DOCS_CONTENT_ID,
+			tabIndex: -1
 		}, createElement(DocContent, {
 			hast: doc.hast,
 			components: {
 				...components,
 				...options.components
 			}
-		}));
+		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, { entries: doc.toc })));
 	}
 	return {
-		source,
+		source: requestScopedSource,
 		getPage,
 		renderAll,
+		searchIndex,
+		searchIndexUrl,
 		dynamicParams: false,
 		async Page({ params }) {
 			const { slug } = await params;
@@ -243,6 +348,22 @@ function createDocsRoute(options) {
 		async IndexPage() {
 			return renderRoute([]);
 		},
+		async Layout({ children, title, actions, search, labels }) {
+			const { DocsLayoutShell } = await import("./react/layout.js");
+			const searchProps = search === false ? false : {
+				...options.miniSearchOptions === void 0 ? {} : { miniSearchOptions: options.miniSearchOptions },
+				...search === true || search === void 0 ? {} : search
+			};
+			return createElement(DocsLayoutShell, {
+				children,
+				nav: await requestScopedSource.nav(),
+				searchIndexUrl,
+				search: searchProps,
+				...title === void 0 ? {} : { title },
+				...actions === void 0 ? {} : { actions },
+				...labels === void 0 ? {} : { labels }
+			});
+		},
 		async generateStaticParams() {
 			if (rescanPerRequest) invalidate();
 			return (await source.slugs()).filter((segments) => segments.length > 0).map((segments) => ({ slug: segments }));
@@ -287,7 +408,11 @@ function createDocsRoute(options) {
 */
 async function createDocsSitemap(options) {
 	const siteUrl = requireSiteUrl(options.siteUrl);
-	const files = await createDocsSource(options).all();
+	const source = createDocsSource(options);
+	if (process.env.NODE_ENV !== "production") source.invalidate();
+	const files = await source.all();
+	const oversized = sitemapLimitWarning(files.length);
+	if (oversized !== void 0) console.warn(oversized);
 	const readDate = options.lastModified ?? readMtime;
 	return Promise.all(files.map(async (file) => {
 		const lastModified = await readDate(file);
@@ -338,9 +463,9 @@ async function createDocsRedirects(config) {
 	for (const file of files) for (const alias of file.frontmatter.aliases ?? []) {
 		const route = toAliasRoute(alias, resolved.basePath, file.relativePath);
 		const page = routes.get(route);
-		if (page !== void 0) throw new Error(`@waveso/docs: the alias '${alias}' in ${file.relativePath} redirects '${route}', which is already the route of ${page.relativePath}. Remove the alias, or rename the page it collides with.`);
+		if (page !== void 0) throw docsError("alias-collision", `@waveso/docs: the alias '${alias}' in ${file.relativePath} redirects '${route}', which is already the route of ${page.relativePath}. Remove the alias, or rename the page it collides with.`);
 		const other = claimed.get(route);
-		if (other !== void 0) throw new Error(`@waveso/docs: '${route}' is claimed as an alias by both ${other.relativePath} and ${file.relativePath}. An alias can only redirect to one page.`);
+		if (other !== void 0) throw docsError("alias-collision", `@waveso/docs: '${route}' is claimed as an alias by both ${other.relativePath} and ${file.relativePath}. An alias can only redirect to one page.`);
 		claimed.set(route, file);
 		redirects.push({
 			source: route,
@@ -355,11 +480,14 @@ function normalizeSiteUrl(siteUrl) {
 }
 /** Fail at config time, not with a malformed `<link rel="canonical">`. */
 function requireSiteUrl(siteUrl) {
+	let parsed;
 	try {
-		return new URL(siteUrl).toString();
+		parsed = new URL(siteUrl);
 	} catch {
-		throw new Error(`@waveso/docs: '${siteUrl}' is not an absolute URL. Pass an origin such as 'https://example.com'.`);
+		throw docsError("invalid-config", `@waveso/docs: '${siteUrl}' is not an absolute URL. Pass an origin such as 'https://example.com'.`);
 	}
+	if (parsed.pathname !== "/") throw docsError("invalid-config", `@waveso/docs: '${siteUrl}' has a path ('${parsed.pathname}'), and a site URL must be a bare origin — canonical and sitemap URLs are resolved against it, which discards the path. Pass '${parsed.origin}' and move '${parsed.pathname}' into \`basePath\`, which does accept multiple segments.`);
+	return parsed.toString();
 }
 //#endregion
 export { createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/plugins/rehype-capture-toc.js

@@ -1,14 +1,35 @@
-import { SKIP, visit } from "unist-util-visit";
+import { isFootnotes, isTransparentContainer } from "../section-boundary.js";
 import { toString } from "hast-util-to-string";
 //#region src/plugins/rehype-capture-toc.ts
-/** `h2`–`h6`. `h1` is the page title and never appears in a TOC. */
-const HEADING = /^h([2-6])$/;
+/**
+* `h2` and `h3`. `h1` is the page title, and h4–h6 are too deep to navigate.
+*
+* Measured on a synthetic API page — 8 methods, 3 overloads each, 3
+* subsections apiece — capturing h2–h6 gave **104 entries and 6,797 bytes** of
+* flight payload against **32 entries and 2,321 bytes** capped at h3. A rail
+* with a hundred entries is not a table of contents; it is the page again, in
+* a narrower column.
+*
+* Stripe, Linear, Mintlify, Fumadocs and Docusaurus all cap at h2+h3 —
+* Docusaurus's defaults are literally 2 and 3.
+*
+* Nothing becomes unreachable by cutting here. `rehype-slug` and
+* `rehype-autolink-headings` still give every h4–h6 an id and a permalink, so
+* they are still linkable and still land in the search index, which opens
+* sections on its own walk. There is deliberately no `maxDepth` option: the
+* escape hatch is `rehypePlugins`, where a plugin writing its own
+* `file.data.toc` is about forty lines.
+*/
+const HEADING = /^h([23])$/;
 /**
 * Drop the permalink anchor `rehype-autolink-headings` appends.
 *
-* This plugin is ordered before that one, so in practice there is nothing to
-* drop — but the check costs nothing and the alternative, if the order ever
-* changes, is every TOC entry silently gaining a trailing `#`.
+* ⚠️ LOAD-BEARING NOW. This used to run *before* autolinking, so there was
+* nothing to drop and this was insurance against an order that might change.
+* The order changed: the capture is dead last, after Shiki and after the
+* consumer's own plugins, so every heading really does carry an appended
+* anchor by the time this walks it. Delete this and every TOC entry gains a
+* trailing `#`.
 */
 function isPermalink(child) {
 	if (child.type !== "element" || child.tagName !== "a") return false;
@@ -16,17 +37,6 @@ function isPermalink(child) {
 	const ariaHidden = child.properties.ariaHidden;
 	return ariaHidden === true || ariaHidden === "true" || Array.isArray(className) && className.includes("heading-anchor");
 }
-/**
-* The GFM footnote block `mdast-util-to-hast` appends.
-*
-* It carries a generated `<h2 id="footnote-label">Footnotes</h2>` that is
-* machinery rather than a section of the page — and is visually hidden, so a
-* TOC entry for it points the reader at nothing they can see. `search-index.ts`
-* skips the same subtree; the two must agree about which sections exist.
-*/
-function isFootnotes(node) {
-	return node.properties.dataFootnotes !== void 0;
-}
 function headingText(node) {
 	return node.children.filter((child) => !isPermalink(child)).map((child) => toString(child)).join("").trim();
 }
@@ -40,8 +50,7 @@ const rehypeCaptureToc = () => {
 		const toc = [];
 		/** Open ancestors, outermost first. */
 		const stack = [];
-		visit(tree, "element", (node) => {
-			if (isFootnotes(node)) return SKIP;
+		const capture = (node) => {
 			const level = HEADING.exec(node.tagName)?.[1];
 			if (level === void 0) return;
 			const id = node.properties.id;
@@ -61,7 +70,30 @@ const rehypeCaptureToc = () => {
 			if (parent === void 0) toc.push(entry);
 			else parent.children.push(entry);
 			stack.push(entry);
-		});
+		};
+		/**
+		* Block-level nodes in document order, stepping into wrappers a section may
+		* legitimately sit inside — and no further.
+		*
+		* ⚠️ THE BOUND IS THE POINT, AND IT IS SHARED WITH THE SEARCH INDEX. A
+		* whole-tree walk gave a TOC entry to any heading with an id however deeply
+		* wrapped, while `extractSearchRecords` opens a section only inside an
+		* {@link isTransparentContainer} — so a `## ` written inside a list item or
+		* a table cell got a TOC entry with no searchable section behind it, and its
+		* prose was folded into the section above under the wrong breadcrumb. One
+		* exported predicate is what stops the two drifting apart again.
+		*/
+		const walk = (nodes) => {
+			for (const node of nodes) {
+				if (node.type !== "element" || isFootnotes(node)) continue;
+				if (isTransparentContainer(node)) {
+					walk(node.children);
+					continue;
+				}
+				capture(node);
+			}
+		};
+		walk(tree.children);
 		file.data.toc = toc;
 	};
 };

package/dist/plugins/rehype-code-frame.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-code-frame.d.ts
+interface RehypeCodeFrameOptions {
+  /** Accessible name when a fence has no title. */
+  copyLabel?: string | undefined;
+}
+declare const rehypeCodeFrame: Plugin<[RehypeCodeFrameOptions?], Root>;
+//#endregion
+export { RehypeCodeFrameOptions, rehypeCodeFrame };

package/dist/plugins/rehype-code-frame.js

@@ -0,0 +1,88 @@
+import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE } from "../code-frame.js";
+import { parseCodeMeta } from "../code-meta.js";
+import { CONTINUE, SKIP, visit } from "unist-util-visit";
+//#region src/plugins/rehype-code-frame.ts
+/** `language-ts` on the `<code>`, already folded to lower case by step 12. */
+const LANGUAGE_CLASS = /^language-(.+)$/;
+const rehypeCodeFrame = (options = {}) => {
+	const copyLabel = options.copyLabel ?? "Copy code";
+	return (tree, file) => {
+		const path = file.data.docLinkContext?.relativePath ?? file.path ?? "a document";
+		visit(tree, "element", (node, index, parent) => {
+			if (node.tagName !== "pre") return CONTINUE;
+			if (parent === void 0 || index === void 0) return CONTINUE;
+			const code = node.children[0];
+			if (code === void 0 || code.type !== "element") return CONTINUE;
+			if (code.tagName !== "code") return CONTINUE;
+			const meta = readMeta(code);
+			const { title } = parseCodeMeta(meta, path);
+			const language = readLanguage(code);
+			const children = [];
+			if (title !== void 0) children.push({
+				type: "element",
+				tagName: "figcaption",
+				properties: { className: ["wave-docs-code__title"] },
+				children: [{
+					type: "text",
+					value: title
+				}]
+			});
+			children.push(copyButton(title === void 0 ? copyLabel : `${copyLabel} from ${title}`), node);
+			parent.children[index] = {
+				type: "element",
+				tagName: "figure",
+				properties: {
+					className: ["wave-docs-code"],
+					[CODE_FRAME_ATTRIBUTE]: "",
+					...language === void 0 ? {} : { "data-lang": language }
+				},
+				children
+			};
+			return SKIP;
+		});
+	};
+};
+/**
+* A real `<button type="button">`, so Enter and Space work with no key
+* handling of ours and the control is announced as a button.
+*
+* It sits before the `<pre>`, which is what makes the tab order read "copy
+* this block" → "the scrollable code region" rather than the reverse.
+*/
+function copyButton(label) {
+	return {
+		type: "element",
+		tagName: "button",
+		properties: {
+			type: "button",
+			className: ["wave-docs-code__copy"],
+			[CODE_COPY_ATTRIBUTE]: "",
+			"aria-label": label
+		},
+		children: [{
+			type: "element",
+			tagName: "span",
+			properties: { "aria-hidden": "true" },
+			children: [{
+				type: "text",
+				value: "⧉"
+			}]
+		}]
+	};
+}
+/** `code.data.meta` — read, never written. */
+function readMeta(code) {
+	const meta = code.data?.meta;
+	return typeof meta === "string" ? meta : void 0;
+}
+function readLanguage(code) {
+	const classNames = code.properties.className;
+	if (!Array.isArray(classNames)) return void 0;
+	for (const name of classNames) {
+		if (typeof name !== "string") continue;
+		const found = LANGUAGE_CLASS.exec(name)?.[1];
+		if (found !== void 0) return found;
+	}
+}
+//#endregion
+export { rehypeCodeFrame };

package/dist/plugins/rehype-code-language.d.ts

@@ -0,0 +1,24 @@
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-code-language.d.ts
+/**
+ * The tag an excluded `<pre>` wears while Shiki walks the tree.
+ *
+ * Exported so a test can prove it never reaches the output: a leaked sentinel
+ * is an unstyled block with an invented tag name, which React renders happily
+ * and nobody notices.
+ */
+declare const EXCLUDED_PRE_TAG = "wave-docs-excluded-pre";
+interface RehypeCodeLanguageOptions {
+  /** Lower-cased fence languages Shiki must leave alone, e.g. `['mermaid']`. */
+  exclude?: readonly string[];
+}
+declare const rehypeNormalizeCodeLanguage: Plugin<[RehypeCodeLanguageOptions?], Root>;
+/**
+ * Undo the disguise. Must run after `rehypeShikiFromHighlighter`, and it is a
+ * separate plugin rather than a flag on the first one because unified gives a
+ * plugin one position in the pipeline and this needs the other side of Shiki.
+ */
+declare const rehypeRestoreExcludedCode: Plugin<[], Root>;
+//#endregion
+export { EXCLUDED_PRE_TAG, RehypeCodeLanguageOptions, rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode };

package/dist/plugins/rehype-code-language.js

@@ -0,0 +1,54 @@
+import { CONTINUE, SKIP, visit } from "unist-util-visit";
+//#region src/plugins/rehype-code-language.ts
+/** `language-ts` on a `<code>` — how a fence's language survives to hast. */
+const LANGUAGE_CLASS = /^language-(.+)$/;
+/**
+* The tag an excluded `<pre>` wears while Shiki walks the tree.
+*
+* Exported so a test can prove it never reaches the output: a leaked sentinel
+* is an unstyled block with an invented tag name, which React renders happily
+* and nobody notices.
+*/
+const EXCLUDED_PRE_TAG = "wave-docs-excluded-pre";
+const rehypeNormalizeCodeLanguage = (options = {}) => {
+	const excluded = new Set((options.exclude ?? []).map((lang) => lang.toLowerCase()));
+	return (tree) => {
+		visit(tree, "element", (node) => {
+			if (node.tagName !== "pre") return CONTINUE;
+			const code = node.children[0];
+			if (code === void 0 || code.type !== "element") return CONTINUE;
+			const classNames = code.properties.className;
+			if (!Array.isArray(classNames)) return SKIP;
+			let language;
+			code.properties.className = classNames.map((name) => {
+				if (typeof name !== "string") return name;
+				const found = LANGUAGE_CLASS.exec(name)?.[1];
+				if (found === void 0) return name;
+				language = found.toLowerCase();
+				return `language-${language}`;
+			});
+			if (language !== void 0 && excluded.has(language)) node.tagName = EXCLUDED_PRE_TAG;
+			return SKIP;
+		});
+	};
+};
+/**
+* Undo the disguise. Must run after `rehypeShikiFromHighlighter`, and it is a
+* separate plugin rather than a flag on the first one because unified gives a
+* plugin one position in the pipeline and this needs the other side of Shiki.
+*/
+const rehypeRestoreExcludedCode = () => {
+	return (tree) => {
+		visit(tree, "element", (node) => {
+			if (node.tagName === "wave-docs-excluded-pre") {
+				node.tagName = "pre";
+				node.properties = {
+					...node.properties,
+					tabIndex: 0
+				};
+			}
+		});
+	};
+};
+//#endregion
+export { EXCLUDED_PRE_TAG, rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode };

package/dist/plugins/rehype-fallback-heading-ids.d.ts

@@ -0,0 +1,6 @@
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-fallback-heading-ids.d.ts
+declare const rehypeFallbackHeadingIds: Plugin<[], Root>;
+//#endregion
+export { rehypeFallbackHeadingIds };