@waveso/docs 0.1.0 → 0.3.0

package/dist/plugins/rehype-fallback-heading-ids.js

@@ -0,0 +1,51 @@
+import rehypeSlug from "rehype-slug";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+//#region src/plugins/rehype-fallback-heading-ids.ts
+const HEADING = /^h[1-6]$/;
+/** `-1`, `-2` … — what `github-slugger` returns for a repeated empty slug. */
+const EMPTY_SLUG_COLLISION = /^-\d+$/;
+/**
+* `rehype-slug` itself, run over a throwaway tree, is how we learn what it will
+* assign. Reimplementing `github-slugger`'s removal table would put a second,
+* drifting opinion about slugs in the pipeline — the exact failure
+* `rehypeCaptureToc` reads ids off the tree to avoid.
+*/
+const slugProbe = unified().use(rehypeSlug).freeze();
+function readId(node) {
+	const id = node.properties.id;
+	return typeof id === "string" ? id : "";
+}
+const rehypeFallbackHeadingIds = () => {
+	return (tree) => {
+		const headings = [];
+		visit(tree, "element", (node) => {
+			if (HEADING.test(node.tagName)) headings.push(node);
+		});
+		if (headings.length === 0) return;
+		const probe = {
+			type: "root",
+			children: headings.map((heading) => ({
+				...heading,
+				properties: { ...heading.properties }
+			}))
+		};
+		slugProbe.runSync(probe);
+		const willBe = probe.children.map((child) => child.type === "element" ? readId(child) : "");
+		const taken = new Set(willBe);
+		let counter = 0;
+		headings.forEach((heading, index) => {
+			const id = willBe[index] ?? "";
+			if (id !== "" && !EMPTY_SLUG_COLLISION.test(id)) return;
+			let fallback;
+			do {
+				counter += 1;
+				fallback = `section-${counter}`;
+			} while (taken.has(fallback));
+			heading.properties.id = fallback;
+			taken.add(fallback);
+		});
+	};
+};
+//#endregion
+export { rehypeFallbackHeadingIds };

package/dist/plugins/rehype-flatten-roots.d.ts

@@ -0,0 +1,7 @@
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-flatten-roots.d.ts
+/** rehype plugin. Must run after every plugin that can splice in a subtree. */
+declare const rehypeFlattenRoots: Plugin<[], Root>;
+//#endregion
+export { rehypeFlattenRoots };

package/dist/plugins/rehype-flatten-roots.js

@@ -0,0 +1,39 @@
+//#region src/plugins/rehype-flatten-roots.ts
+/**
+* Takes the open {@link AnyNode} on purpose: `RootContent` has no `root`
+* member, so `child.type === 'root'` on a typed child is a compile error
+* ("no overlap"). The declared type is the thing being repaired here.
+*/
+function isNestedRoot(node) {
+	return node.type === "root";
+}
+/** `RootContent` minus `doctype`, which is the only member an element rejects. */
+function isElementContent(node) {
+	return node.type !== "doctype";
+}
+function flatten(parent) {
+	const children = [];
+	let nested = false;
+	for (const child of parent.children) {
+		const node = child;
+		if (isNestedRoot(node)) {
+			nested = true;
+			children.push(...node.children);
+			continue;
+		}
+		children.push(child);
+	}
+	if (nested) {
+		if (parent.type === "root") parent.children = children;
+		else parent.children = children.filter(isElementContent);
+	}
+	for (const child of parent.children) if (child.type === "element") flatten(child);
+}
+/** rehype plugin. Must run after every plugin that can splice in a subtree. */
+const rehypeFlattenRoots = () => {
+	return (tree) => {
+		flatten(tree);
+	};
+};
+//#endregion
+export { rehypeFlattenRoots };

package/dist/plugins/remark-doc-links.d.ts

@@ -17,6 +17,15 @@ interface DocLinkRef {
   href: string | undefined;
   /** 1-based line in the source markdown, when the parser recorded one. */
   line?: number;
+  /**
+   * The target is a file served beside the docs (`./schema.json`), not a page.
+   *
+   * It is still folded and still recorded, because a `../` chain that climbs
+   * out of the content root is an authoring error whatever it points at — but
+   * it must not be checked against the set of published ROUTES, which it will
+   * never be a member of.
+   */
+  asset?: true;
 }
 declare module 'vfile' {
   interface DataMap {
@@ -50,7 +59,9 @@ declare function foldSegments(from: readonly string[], path: string): string[] |
 /**
  * The built-in {@link LinkResolver}: markdown file path in, route out.
  *
- * Exported for reuse by hosts that want to wrap rather than replace it.
+ * Exported for reuse by hosts that want to wrap rather than replace it. Throws
+ * a {@link URIError} on a malformed percent-escape; every other failure is
+ * reported as `undefined`.
  */
 declare function resolveMarkdownLink(href: string, fromDir: readonly string[], basePath: string): string | undefined;
 /**

package/dist/plugins/remark-doc-links.js

@@ -1,3 +1,4 @@
+import { docsError } from "../docs-error.js";
 import { visit } from "unist-util-visit";
 //#region src/plugins/remark-doc-links.ts
 /** `scheme:` — matches `https:`, `mailto:`, `tel:`, `data:`. */
@@ -20,6 +21,24 @@ function isRelativeLink(href) {
 	return href !== "" && !href.startsWith("#") && !href.startsWith("?") && !href.startsWith("/") && !HAS_SCHEME.test(href);
 }
 /**
+* Is this already-absolute href one of OUR routes?
+*
+* `/docs/api/auht` needs no rewriting and used to need no thought either — so
+* it was never recorded, never asserted, and shipped a 404 with a green build.
+* A typo in a hand-written absolute link is exactly as likely as one in a
+* relative link; only the rewriting differs.
+*
+* Requires a non-empty base path. Docs mounted at the site root cannot be told
+* apart from the rest of the site, and asserting `/login` against the set of
+* documentation routes would fail builds over links that are perfectly good.
+*/
+function isInternalAbsoluteLink(href, basePath) {
+	const base = basePath.replace(/\/+$/, "");
+	if (base === "" || href.startsWith("//")) return false;
+	const path = HREF_PARTS.exec(href)?.[1] ?? "";
+	return path === base || path.startsWith(`${base}/`);
+}
+/**
 * Fold `.` and `..` against a starting directory.
 *
 * Hand-rolled rather than `path.resolve` because these are URL paths, not
@@ -46,17 +65,58 @@ function foldSegments(from, path) {
 	}
 	return out;
 }
-/** Join route segments onto the base path, e.g. `('/docs', ['api'])`. */
+/**
+* Join route segments onto the base path, e.g. `('/docs', ['api'])`.
+*
+* ⚠️ ENCODES EACH SEGMENT, which is the half of the percent-encoding contract
+* that lives here: `source.ts` builds every published `href` as
+* `basePath + '/' + segments.map(encodeURIComponent).join('/')` and keeps
+* `segments` raw, so a route computed from a link has to be spelled the same
+* way or `assertLinks` compares an encoded route against a decoded one and
+* fails the build on a page that exists.
+*/
 function toRoute(basePath, segments) {
 	const base = basePath.replace(/\/+$/, "");
-	const path = segments.join("/");
+	const path = segments.map((segment) => encodeURIComponent(segment)).join("/");
 	if (path === "") return base === "" ? "/" : base;
 	return `${base}/${path}`;
 }
 /**
+* Percent-decode one authored path segment, and normalise it.
+*
+* GitHub's own UI writes `[gs](./getting%20started.md)` when you drag a file
+* with a space in its name into an issue, and that is the form that ends up in
+* a repository's markdown. Without decoding, the segment stays `getting%20started`,
+* matches no file, and hard-fails the build on a link GitHub renders correctly.
+*
+* NFC because macOS hands back decomposed filenames and `source.ts` normalises
+* at the `readdir` boundary; two spellings of `é` are one page.
+*
+* Throws rather than returning the input on failure: `decodeURIComponent`
+* rejects `100%-faster`, and a silent pass-through would turn a malformed link
+* into a mystery 404 instead of a message the author can act on.
+*/
+function decodeSegment(segment, href) {
+	try {
+		return decodeURIComponent(segment).normalize("NFC");
+	} catch (error) {
+		throw new URIError(`@waveso/docs: link '${href}' is not valid percent-encoding — '${segment}' cannot be decoded. Write '%25' for a literal percent sign, or link to the file by its real name.`, { cause: error });
+	}
+}
+/**
+* Decode BEFORE folding, never after: `%2E%2E%2F` is `../` in disguise, and
+* `foldSegments` is the only thing that refuses a chain climbing out of the
+* content root.
+*/
+function decodePath(path, href) {
+	return path.split("/").map((segment) => decodeSegment(segment, href)).join("/");
+}
+/**
 * The built-in {@link LinkResolver}: markdown file path in, route out.
 *
-* Exported for reuse by hosts that want to wrap rather than replace it.
+* Exported for reuse by hosts that want to wrap rather than replace it. Throws
+* a {@link URIError} on a malformed percent-escape; every other failure is
+* reported as `undefined`.
 */
 function resolveMarkdownLink(href, fromDir, basePath) {
 	const parts = HREF_PARTS.exec(href);
@@ -64,7 +124,7 @@ function resolveMarkdownLink(href, fromDir, basePath) {
 	const query = parts?.[2] ?? "";
 	const hash = parts?.[3] ?? "";
 	if (path === "") return;
-	const segments = foldSegments(fromDir, path);
+	const segments = foldSegments(fromDir, decodePath(path, href));
 	if (segments === void 0) return;
 	const last = segments.at(-1);
 	if (last !== void 0) {
@@ -75,6 +135,30 @@ function resolveMarkdownLink(href, fromDir, basePath) {
 	return `${toRoute(basePath, segments)}${query}${hash}`;
 }
 /**
+* Respell an already-absolute internal link the way route keys are spelled.
+*
+* An absolute link is not rewritten — it is already a route — but it still has
+* to be *compared* against one, and `source.ts` spells every published href
+* with `encodeURIComponent` per segment. Recording the author's raw text made
+* that comparison spelling-sensitive: `/docs/café` and `/docs/caf%C3%A9` are the
+* same page, and only the second matched, so the human-readable form every
+* editor produces failed the build with "no such page exists" for a page that
+* plainly exists. Decoding and re-encoding puts both on the canonical spelling.
+*
+* `.`/`..` are folded for the same reason: `/docs/api/../guide` is a route a
+* browser resolves happily and `knownRoutes` has never heard of.
+*/
+function normalizeInternalRoute(href, basePath) {
+	const parts = HREF_PARTS.exec(href);
+	const path = parts?.[1] ?? "";
+	const query = parts?.[2] ?? "";
+	const hash = parts?.[3] ?? "";
+	const base = basePath.replace(/\/+$/, "");
+	const segments = foldSegments([], decodePath(path.slice(base.length), href));
+	if (segments === void 0) return;
+	return `${toRoute(basePath, segments)}${query}${hash}`;
+}
+/**
 * Is this relative href pointing at an asset rather than a page?
 *
 * A link to `./diagram.svg` or `./schema.sql` is a download, not a route, and
@@ -88,6 +172,26 @@ function isAssetLink(href) {
 	return FILE_EXTENSION.test(last) && !MARKDOWN_EXTENSION.test(last);
 }
 /**
+* An asset href, folded against the page's directory.
+*
+* ⚠️ ASSETS USED TO BE RETURNED UNTOUCHED, which made `./schema.json` mean two
+* different files: the browser resolves a relative href against the ROUTE, so
+* `guide/index.md` requested `/docs/guide/schema.json` and `guide/setup.md`
+* requested `/docs/guide/setup/schema.json` — from byte-identical markdown that
+* previews correctly in both places. Folding to a route-absolute path is what
+* every link in this file already does, and there is no reason a download is
+* the exception.
+*/
+function resolveAssetLink(href, fromDir, basePath) {
+	const parts = HREF_PARTS.exec(href);
+	const path = parts?.[1] ?? "";
+	const query = parts?.[2] ?? "";
+	const hash = parts?.[3] ?? "";
+	const segments = foldSegments(fromDir, decodePath(path, href));
+	if (segments === void 0) return;
+	return `${toRoute(basePath, segments)}${query}${hash}`;
+}
+/**
 * remark plugin. Requires `file.data.docLinkContext` to be set; without it the
 * containing document is unknown and every relative link would resolve against
 * the content root, which is worse than leaving them alone.
@@ -96,26 +200,49 @@ const remarkDocLinks = (options) => {
 	const { basePath, resolve } = options;
 	return (tree, file) => {
 		const context = file.data.docLinkContext;
-		if (context === void 0) throw new Error(`@waveso/docs: remarkDocLinks ran without file.data.docLinkContext${file.path === void 0 ? "" : ` (file: ${file.path})`}. Set it before running the processor.`);
+		if (context === void 0) throw docsError("internal", `@waveso/docs: remarkDocLinks ran without file.data.docLinkContext${file.path === void 0 ? "" : ` (file: ${file.path})`}. Set it before running the processor.`);
 		const refs = file.data.docLinks ?? [];
 		file.data.docLinks = refs;
-		visit(tree, ["link", "definition"], (node) => {
-			if (node.type !== "link" && node.type !== "definition") return;
+		const imageIdentifiers = /* @__PURE__ */ new Set();
+		const targets = [];
+		visit(tree, (node) => {
+			if (node.type === "imageReference") imageIdentifiers.add(node.identifier);
+			else if (node.type === "link" || node.type === "definition") targets.push(node);
+		});
+		for (const node of targets) {
 			const raw = node.url;
-			if (!isRelativeLink(raw)) return;
-			if (resolve === void 0 && isAssetLink(raw)) return;
-			const href = resolve ? resolve(raw, context) : resolveMarkdownLink(raw, context.dirSegments, basePath);
+			if (node.type === "definition" && imageIdentifiers.has(node.identifier)) continue;
 			const line = node.position?.start.line;
-			refs.push(line === void 0 ? {
-				raw,
-				href
-			} : {
-				raw,
-				href,
-				line
-			});
-			if (href !== void 0) node.url = href;
-		});
+			const record = (href, asset) => {
+				const ref = {
+					raw,
+					href
+				};
+				if (line !== void 0) ref.line = line;
+				if (asset !== void 0) ref.asset = asset;
+				refs.push(ref);
+				if (href !== void 0) node.url = href;
+			};
+			try {
+				if (!isRelativeLink(raw)) {
+					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath));
+					continue;
+				}
+				if (resolve === void 0 && isAssetLink(raw)) {
+					record(resolveAssetLink(raw, context.dirSegments, basePath), true);
+					continue;
+				}
+				if (resolve) {
+					record(resolve(raw, context));
+					continue;
+				}
+				record(resolveMarkdownLink(raw, context.dirSegments, basePath));
+			} catch (error) {
+				if (!(error instanceof URIError)) throw error;
+				const at = line === void 0 ? "" : `:${line}`;
+				throw docsError("broken-link", `@waveso/docs: ${context.relativePath}${at} links to '${raw}', whose percent-encoding is malformed. Write %25 for a literal percent sign, or link to the file by its real name.`, { cause: error });
+			}
+		}
 	};
 };
 //#endregion

package/dist/react/code-runtime.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from "react";
+//#region src/react/code-runtime.d.ts
+/**
+ * Mount the copy runtime. Renders nothing.
+ *
+ * Every hook of state lives in the DOM rather than in React: the button's
+ * copied state is a `data-copied` attribute the stylesheet reads, and the
+ * announcement is a live region. React owns none of these nodes, so nothing
+ * re-renders and there is no state to get out of step with a page that was
+ * server-rendered.
+ */
+declare function DocsCodeRuntime(): ReactNode;
+//#endregion
+export { DocsCodeRuntime };

package/dist/react/code-runtime.js

@@ -0,0 +1,161 @@
+"use client";
+import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE } from "../code-frame.js";
+import { useEffect } from "react";
+//#region src/react/code-runtime.tsx
+/**
+* The nine hundred bytes that make every copy button on the page work.
+*
+* Private. `DocContent` mounts it, and only when the tree it was handed
+* actually contains a code frame — so a page with no fences ships none of
+* this rather than a component that mounts and finds nothing to do.
+*
+* ## One listener, not one component per block
+*
+* The buttons are plain server-rendered HTML with no React identity at all.
+* This attaches a single delegated `click` listener to `document` and one live
+* region to `<body>`, both behind a module-level ref count: the first instance
+* installs them, later instances increment and return, and the last one out
+* removes them. Two `DocContent`s on one page therefore copy once and announce
+* once — a bug nothing else would catch, because the second announcement is
+* only audible to a screen-reader user.
+*
+* The alternative every comparable package ships — mapping `pre` to a
+* `'use client'` component — puts one client reference and one hydration root
+* in the flight stream per fence, and drags the highlighted subtree across the
+* client boundary as children.
+*/
+/** How long the button shows its copied state. */
+const COPIED_MS = 2e3;
+/**
+* Line classes whose text is not part of what the reader wanted.
+*
+* Empty today, and deliberately an array rather than an inline condition:
+* `@shikijs/transformers` lands at 0.3, and `'remove'` — the class it puts on
+* a deleted diff line — goes here. Copying deleted lines into somebody's
+* editor is the kind of failure that is discovered at run time, in their
+* project, days later.
+*/
+const SKIP_LINE_CLASSES = [];
+/** Marker classes whose lines carry trailing whitespace worth trimming. */
+const TRIMMED_LINE_CLASSES = [];
+let refCount = 0;
+let detach;
+/**
+* Mount the copy runtime. Renders nothing.
+*
+* Every hook of state lives in the DOM rather than in React: the button's
+* copied state is a `data-copied` attribute the stylesheet reads, and the
+* announcement is a live region. React owns none of these nodes, so nothing
+* re-renders and there is no state to get out of step with a page that was
+* server-rendered.
+*/
+function DocsCodeRuntime() {
+	useEffect(() => {
+		refCount += 1;
+		if (refCount === 1) detach = install();
+		return () => {
+			refCount -= 1;
+			if (refCount === 0) {
+				detach?.();
+				detach = void 0;
+			}
+		};
+	}, []);
+	return null;
+}
+function install() {
+	const status = document.createElement("div");
+	status.setAttribute("role", "status");
+	status.setAttribute("aria-live", "polite");
+	status.className = "wave-docs-code__status";
+	document.body.append(status);
+	const onClick = (event) => {
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		const button = target.closest(`[${CODE_COPY_ATTRIBUTE}]`);
+		if (!(button instanceof HTMLElement)) return;
+		const pre = button.closest(`[${CODE_FRAME_ATTRIBUTE}]`)?.querySelector("pre");
+		if (pre === null || pre === void 0) return;
+		copy(readCode(pre), button, status);
+	};
+	document.addEventListener("click", onClick);
+	document.documentElement.setAttribute(CODE_READY_ATTRIBUTE, "");
+	return () => {
+		document.removeEventListener("click", onClick);
+		document.documentElement.removeAttribute(CODE_READY_ATTRIBUTE);
+		status.remove();
+	};
+}
+/**
+* The text of a code block, as the author wrote it.
+*
+* ⚠️ NOT `pre.textContent`. Shiki emits one `<span class="line">` per line with
+* a literal `"\n"` text node between them, so `textContent` happens to be
+* right *today* — and stops being right the moment a transformer adds a line
+* that should not be copied, or a gutter of line numbers that should not be
+* either. Walking the lines is the same amount of code and survives both.
+*/
+function readCode(pre) {
+	const lines = pre.querySelectorAll(".line");
+	if (lines.length === 0) return pre.textContent ?? "";
+	const out = [];
+	for (const line of lines) {
+		const classes = line.className.split(/\s+/);
+		if (classes.some((name) => SKIP_LINE_CLASSES.includes(name))) continue;
+		const text = line.textContent ?? "";
+		out.push(classes.some((name) => TRIMMED_LINE_CLASSES.includes(name)) ? text.replace(/\s+$/, "") : text);
+	}
+	return out.join("\n");
+}
+async function copy(text, button, status) {
+	const copied = await writeClipboard(text) ? "true" : "false";
+	button.dataset.copied = copied;
+	status.textContent = copied === "true" ? "Copied to the clipboard." : "Copy failed. Select the code and press Control or Command + C.";
+	const existing = timers.get(button);
+	if (existing !== void 0) window.clearTimeout(existing);
+	timers.set(button, window.setTimeout(() => {
+		timers.delete(button);
+		button.removeAttribute("data-copied");
+	}, COPIED_MS));
+}
+/**
+* The pending "clear the indicator" timer per button.
+*
+* A `WeakMap`, so a button removed by a client-side navigation takes its entry
+* with it — this module is a page-lifetime singleton and a `Map` here would
+* hold every code block the reader ever copied from.
+*/
+const timers = /* @__PURE__ */ new WeakMap();
+async function writeClipboard(text) {
+	if (window.isSecureContext && navigator.clipboard !== void 0) try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {}
+	return legacyCopy(text);
+}
+/**
+* `execCommand('copy')`, which is deprecated and still the only thing that
+* works over plain HTTP.
+*
+* When it finally goes, this returns `false` and the reader gets the
+* instruction — which is why that message is written as an instruction rather
+* than as an apology.
+*/
+function legacyCopy(text) {
+	const area = document.createElement("textarea");
+	area.value = text;
+	area.setAttribute("readonly", "");
+	area.setAttribute("aria-hidden", "true");
+	area.style.cssText = "position:fixed;top:-9999px;opacity:0;";
+	document.body.append(area);
+	try {
+		area.select();
+		return document.execCommand("copy");
+	} catch {
+		return false;
+	} finally {
+		area.remove();
+	}
+}
+//#endregion
+export { DocsCodeRuntime };

package/dist/react/doc-content.d.ts

@@ -10,20 +10,57 @@ interface DocContentProps {
   hast: Root;
   /** Overrides, merged over {@link defaultMarkdownComponents}. */
   components?: MarkdownComponents | undefined;
+  /**
+   * Appended to `wave-docs-prose`, never substituted for it.
+   *
+   * Substitution is the failure this whole wrapper exists to prevent, so it is
+   * not offered: almost every rule in the stylesheet is scoped under
+   * `.wave-docs-prose`, and dropping it leaves a page whose code blocks still
+   * carry correct syntax colours and nothing else — which reads as a design
+   * choice rather than as a mistake.
+   */
+  className?: string | undefined;
 }
 /**
- * Render a hast tree as React elements.
+ * Render a hast tree as React elements, inside the prose wrapper.
  *
  * Not a client component, and it must stay that way: the markdown parser and
  * Shiki ran in Node at build time, and this component only walks the resulting
  * tree. Nothing here pulls unified, remark or a highlighter into the browser.
  *
+ * ## Why the wrapper is here and not on your `<article>`
+ *
+ * `.wave-docs-prose` is the scope for nearly every rule in `styles.css` —
+ * including `.wave-docs-prose .shiki`, which is deliberately scoped so the
+ * package never styles a code block it did not render. `createDocsRoute.Page`
+ * always put the class on for you, but the documented hand-rolled path made
+ * the consumer type it, and forgetting it silently unstyled every code block
+ * on the site while leaving the syntax colours intact. One component owning
+ * the class removes the way to get that wrong.
+ *
+ * The rules that care about tree shape are `.wave-docs-prose > * + *` and
+ * `.wave-docs-prose > :is(h2…h6)`, and the tree's own children are this
+ * element's direct children, so nothing moves.
+ *
+ * ## The copy runtime is mounted here
+ *
+ * Because this is the component no consumer can avoid: `createDocsRoute.Page`
+ * renders it, and the documented hand-rolled route renders it directly. Wiring
+ * the listener from `docs.Layout` instead would ship dead buttons to everyone
+ * composing their own shell, and "what about someone not using the layout?"
+ * would be a caveat rather than a non-question.
+ *
+ * It renders only when the tree actually contains a code frame. The server has
+ * the tree in hand, the check is one pass, and the result is that a page
+ * without fences ships zero extra bytes rather than a runtime with nothing to
+ * do.
+ *
  * `passNode` is left off (the default). `react-markdown` hardcodes it *on* with
  * no opt-out, so any mapped component that spreads its props renders
  * `node="[object Object]"` into production HTML — with no type error to warn
  * you, because `node` is a legal prop on the component and an unknown attribute
  * on the element.
  */
-declare function DocContent({ hast, components }: DocContentProps): ReactNode;
+declare function DocContent({ hast, components, className }: DocContentProps): ReactNode;
 //#endregion
 export { DocContent, DocContentProps };

package/dist/react/doc-content.js

@@ -1,29 +1,61 @@
+import { hasCodeFrame } from "../code-frame.js";
+import { DocsCodeRuntime } from "./code-runtime.js";
 import { defaultMarkdownComponents } from "./markdown-components.js";
 import { toJsxRuntime } from "hast-util-to-jsx-runtime";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/doc-content.tsx
 /**
-* Render a hast tree as React elements.
+* Render a hast tree as React elements, inside the prose wrapper.
 *
 * Not a client component, and it must stay that way: the markdown parser and
 * Shiki ran in Node at build time, and this component only walks the resulting
 * tree. Nothing here pulls unified, remark or a highlighter into the browser.
 *
+* ## Why the wrapper is here and not on your `<article>`
+*
+* `.wave-docs-prose` is the scope for nearly every rule in `styles.css` —
+* including `.wave-docs-prose .shiki`, which is deliberately scoped so the
+* package never styles a code block it did not render. `createDocsRoute.Page`
+* always put the class on for you, but the documented hand-rolled path made
+* the consumer type it, and forgetting it silently unstyled every code block
+* on the site while leaving the syntax colours intact. One component owning
+* the class removes the way to get that wrong.
+*
+* The rules that care about tree shape are `.wave-docs-prose > * + *` and
+* `.wave-docs-prose > :is(h2…h6)`, and the tree's own children are this
+* element's direct children, so nothing moves.
+*
+* ## The copy runtime is mounted here
+*
+* Because this is the component no consumer can avoid: `createDocsRoute.Page`
+* renders it, and the documented hand-rolled route renders it directly. Wiring
+* the listener from `docs.Layout` instead would ship dead buttons to everyone
+* composing their own shell, and "what about someone not using the layout?"
+* would be a caveat rather than a non-question.
+*
+* It renders only when the tree actually contains a code frame. The server has
+* the tree in hand, the check is one pass, and the result is that a page
+* without fences ships zero extra bytes rather than a runtime with nothing to
+* do.
+*
 * `passNode` is left off (the default). `react-markdown` hardcodes it *on* with
 * no opt-out, so any mapped component that spreads its props renders
 * `node="[object Object]"` into production HTML — with no type error to warn
 * you, because `node` is a legal prop on the component and an unknown attribute
 * on the element.
 */
-function DocContent({ hast, components }) {
-	return toJsxRuntime(hast, {
-		Fragment,
-		jsx,
-		jsxs,
-		components: {
-			...defaultMarkdownComponents,
-			...components
-		}
+function DocContent({ hast, components, className }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: className === void 0 || className === "" ? "wave-docs-prose" : `wave-docs-prose ${className}`,
+		children: [hasCodeFrame(hast) ? /* @__PURE__ */ jsx(DocsCodeRuntime, {}) : null, toJsxRuntime(hast, {
+			Fragment,
+			jsx,
+			jsxs,
+			components: {
+				...defaultMarkdownComponents,
+				...components
+			}
+		})]
 	});
 }
 //#endregion