@waveso/docs 0.1.0 → 0.2.0

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

@@ -1,4 +1,4 @@
-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. */
@@ -16,17 +16,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 +29,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 +49,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-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,48 @@
+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";
+		});
+	};
+};
+//#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 };

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/markdown-components.js

@@ -6,6 +6,62 @@ import { jsx, jsxs } from "react/jsx-runtime";
 const HTTP_SCHEME = /^https?:\/\//i;
 /** Any URL with a scheme, or protocol-relative. */
 const ABSOLUTE_URL = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+/**
+* The schemes a markdown link may carry.
+*
+* GitHub's own allowlist, which is the bar to match: documentation links to
+* `sms:`, `ftp:` and `irc:` are ordinary, and an allowlist of three silently
+* deleted them. The point of the check is to stop `javascript:`, `data:` and
+* `vbscript:` reaching an `href`, not to have an opinion about protocols.
+*
+* A scheme not listed here — `vscode:`, `obsidian:`, `slack:` — is dropped
+* rather than rendered. That is deliberate: an allowlist that grows on request
+* is safe, one that guesses is not. {@link warnDroppedHref} makes it visible.
+*/
+const SAFE_SCHEME = /^(https?|mailto|tel|sms|ftp|ftps|irc|ircs|xmpp|news|nntp|feed|git|matrix):/i;
+/** Hrefs already reported, so a re-render does not repeat the warning. */
+const warnedHrefs = /* @__PURE__ */ new Set();
+/**
+* Say something when a link is dropped.
+*
+* A destination that vanishes with the text left behind is the quietest
+* possible failure — the page looks fine and the link is simply gone. Every
+* other rejection in this package names a file and a fix; this one cannot see
+* the file, so it names the href and stays out of production noise.
+*/
+function warnDroppedHref(href) {
+	if (process.env.NODE_ENV === "production" || warnedHrefs.has(href)) return;
+	warnedHrefs.add(href);
+	console.warn(`@waveso/docs: dropped a link to '${href}' — its URL scheme is not in the allowlist, so the text was kept and the destination removed. Use http, https, mailto, tel, sms, ftp, irc, xmpp or matrix, or render the link yourself with a custom \`a\` component.`);
+}
+/**
+* A copy of `href` as a browser will parse it.
+*
+* ASCII control characters and spaces are stripped before parsing, so
+* ` javascript:` and `java<TAB>script:` both navigate where the raw string
+* matches no scheme at all — which is how a scheme check gets walked around.
+*/
+function normaliseUrl(href) {
+	return [...href].filter((char) => (char.codePointAt(0) ?? 0) > 32).join("");
+}
+/**
+* Would this href navigate somewhere we are willing to send a reader?
+*
+* Nothing upstream filters it: `remarkDocLinks` skips every href with a scheme
+* (`isRelativeLink` is false for it), so `assertLinks` never sees one either,
+* and `remarkRehype` runs with `allowDangerousHtml` off but passes a link's own
+* url through untouched. Verified against React 19: it neutralises
+* `javascript:` in every obfuscated form, silently — but it lets `vbscript:`
+* and `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is
+* ours to keep.
+*
+* Tested against {@link normaliseUrl}, not the raw string.
+*/
+function isSafeHref(href) {
+	const normalised = normaliseUrl(href);
+	if (!ABSOLUTE_URL.test(normalised)) return true;
+	return normalised.startsWith("//") || SAFE_SCHEME.test(normalised);
+}
 function joinClassNames(...values) {
 	const joined = values.filter(Boolean).join(" ");
 	return joined === "" ? void 0 : joined;
@@ -23,6 +79,10 @@ function createAnchor(Link) {
 			...rest,
 			children
 		});
+		if (!isSafeHref(href)) {
+			warnDroppedHref(href);
+			return /* @__PURE__ */ jsx("span", { children });
+		}
 		if (HTTP_SCHEME.test(href) || href.startsWith("//")) return /* @__PURE__ */ jsxs("a", {
 			...rest,
 			href,
@@ -46,28 +106,33 @@ function createAnchor(Link) {
 	};
 }
 function createImage(Image) {
-	return function MarkdownImage({ src, alt, width, height, title, className, ...rest }) {
+	return function MarkdownImage({ src, alt, width, height, title, className, sizes, loading, ...rest }) {
 		const resolvedWidth = toDimension(width);
 		const resolvedHeight = toDimension(height);
+		const resolvedLoading = loading ?? "lazy";
+		const resolvedClassName = joinClassNames("wave-docs-image", className);
 		if (Image !== void 0 && typeof src === "string" && resolvedWidth !== void 0 && resolvedHeight !== void 0) return /* @__PURE__ */ jsx(Image, {
+			...rest,
 			src,
 			alt: alt ?? "",
 			width: resolvedWidth,
 			height: resolvedHeight,
 			title,
-			className: joinClassNames("wave-docs-image", className),
-			loading: "lazy"
+			className: resolvedClassName,
+			sizes,
+			loading: resolvedLoading
 		});
 		return /* @__PURE__ */ jsx("img", {
+			decoding: "async",
 			...rest,
 			src,
 			alt: alt ?? "",
 			width,
 			height,
 			title,
-			className: joinClassNames("wave-docs-image", className),
-			loading: "lazy",
-			decoding: "async"
+			className: resolvedClassName,
+			sizes,
+			loading: resolvedLoading
 		});
 	};
 }

package/dist/react/search-dialog.d.ts

@@ -1,5 +1,7 @@
+import { SearchRecord } from "../types.js";
 import { DocsLinkComponent } from "./markdown-components.js";
 import { ReactNode } from "react";
+import { Options } from "minisearch";
 //#region src/react/search-dialog.d.ts
 interface SearchDialogProps {
   /**
@@ -17,17 +19,31 @@ interface SearchDialogProps {
    * Optional link component for results, e.g. `next/link`, so hovering a hit
    * prefetches the page. Results fall back to a plain anchor.
    */
-  Link?: DocsLinkComponent;
+  Link?: DocsLinkComponent | undefined;
   /** Trigger button label. Defaults to `'Search'`. */
-  triggerLabel?: string;
+  triggerLabel?: string | undefined;
   /** Input placeholder. Defaults to `'Search documentation'`. */
-  placeholder?: string;
+  placeholder?: string | undefined;
   /** Accessible name for the dialog. Defaults to `'Search documentation'`. */
-  dialogLabel?: string;
+  dialogLabel?: string | undefined;
   /** Maximum results rendered. Defaults to 8. */
-  maxResults?: number;
+  maxResults?: number | undefined;
   /** Input debounce in milliseconds. Defaults to 120. */
-  debounceMs?: number;
+  debounceMs?: number | undefined;
+  /** Extra class names for the trigger button, e.g. a navbar's own layout. */
+  className?: string | undefined;
+  /**
+   * Overrides applied through `mergeSearchOptions` when the index is
+   * deserialised — the escape hatch for tokenisation, `processTerm` and the
+   * query defaults (`fuzzy`, `prefix`, `combineWith`, `boost`) without waiting
+   * on a release of this package.
+   *
+   * ⚠️ HAND THE IDENTICAL OVERRIDES TO `buildSearchIndex`. `tokenize` and
+   * `processTerm` decide how terms were written into the index; a client that
+   * splits differently from the build looks up terms that were never written
+   * and finds nothing, silently.
+   */
+  searchOptions?: Partial<Options<SearchRecord>> | undefined;
 }
 /**
  * Search trigger plus its dialog.
@@ -36,6 +52,6 @@ interface SearchDialogProps {
  * portalled to `document.body`, so a navbar's stacking context cannot trap
  * it behind the page.
  */
-declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs, className, searchOptions }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };