@waveso/docs 0.2.0 → 0.4.0

package/dist/react/sidebar.js

@@ -1,6 +1,7 @@
 "use client";
-import { useId, useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { nearestScrollTop } from "./nearest-scroll-top.js";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/sidebar.tsx
 /** Trailing slashes are a routing detail, not a difference in identity. */
 function normalizeHref(href) {
@@ -21,9 +22,44 @@ function containsActive(node, pathname) {
 /**
 * The docs navigation tree.
 *
-* Prefetch is off by default on the injected link. A full-tree sidebar on a
-* few hundred pages otherwise asks Next to prefetch every route in it —
-* ~1.8 KB brotli each, all of it wasted on the routes nobody clicks.
+* ## Prefetch
+*
+* Nearby links prefetch; the rest do not. Nearby means the list that directly
+* contains the current page, plus the heading link of the group the reader is
+* inside — 5 to 15 warm links on a real sidebar rather than 400 or none.
+*
+* ⚠️ THE PREVIOUS NOTE HERE WAS WRONG, AND THE RETRACTION IS THE POINT. It
+* said prefetch was off because a full-tree sidebar otherwise asks Next to
+* prefetch every route in it, ~1.8 KB brotli each. That reasoning is correct
+* for the Pages Router and wrong for the App Router:
+* `next/dist/client/app-dir/link.js` computes
+* `const prefetchEnabled = prefetchProp !== false`, and BOTH the hover path
+* and the touch path bail on it, while the IntersectionObserver is only
+* registered when it is true. So `prefetch={false}` did not trade viewport
+* prefetching for hover prefetching — it turned off both, and made every
+* navigation from the most-clicked control in a docs site a cold RSC
+* round-trip.
+*
+* ## The keyboard model, and why there is no `role="tree"`
+*
+* This is the **APG Disclosure Navigation** pattern: a list of links, with a
+* button per collapsible group. Every link is an ordinary tab stop, Enter
+* follows it, and the browser does all of it. There is no `tabindex`
+* anywhere in here and no roving focus, deliberately.
+*
+* `role="tree"` is the tempting alternative and it is refused. It removes
+* every link from the tab order in favour of a single roving tabstop, so a
+* reader who tabs into the navigation can no longer tab through it; and it
+* makes a screen reader announce "tree item, level 3" for what is, in every
+* way that matters to the person hearing it, a link to a page. A docs sidebar
+* is not a file explorer. `sidebar.test.tsx` asserts the absence of both, so
+* the decision survives someone reaching for the aria pattern that sounds
+* closest to "collapsible tree".
+*
+* ⚠️ AND IT IS UNOBSERVABLE IN `next dev`. The same file guards the hover path
+* with `if (!prefetchEnabled || process.env.NODE_ENV === 'development')`, so
+* nothing prefetches locally whatever this says. Do not "fix" it back because
+* the network tab looks the same.
 */
 function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 	const baseId = useId();
@@ -39,7 +75,23 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 			[key]: isOpen
 		}));
 	};
+	const navRef = useRef(null);
+	useLayoutEffect(() => {
+		const active = navRef.current?.querySelector("[aria-current=\"page\"]");
+		if (!(active instanceof HTMLElement)) return;
+		const port = scrollableAncestor(active);
+		if (port === null) return;
+		const next = nearestScrollTop({
+			itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
+			itemHeight: active.offsetHeight,
+			viewHeight: port.clientHeight,
+			scrollTop: port.scrollTop,
+			scrollHeight: port.scrollHeight
+		});
+		if (next !== void 0) port.scrollTop = next;
+	}, [pathname]);
 	return /* @__PURE__ */ jsx("nav", {
+		ref: navRef,
 		"aria-label": label,
 		className: ["wave-docs-sidebar", className].filter(Boolean).join(" "),
 		children: /* @__PURE__ */ jsx(NavList, {
@@ -53,7 +105,27 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 		})
 	});
 }
+/**
+* The nearest ancestor that actually scrolls, or `null`.
+*
+* ⚠️ THIS EXISTS SO `scrollIntoView` DOES NOT HAVE TO. `scrollIntoView({ block:
+* 'nearest' })` reads as exactly the right call and scrolls **every**
+* scrollable ancestor including the document — so on a docs page it brings the
+* sidebar item into view and jumps the article the reader came to read, on the
+* one navigation where they know precisely what they asked for.
+* `sidebar.test.tsx` spies on it and asserts it is never called.
+*/
+function scrollableAncestor(element) {
+	let current = element.parentElement;
+	while (current !== null) {
+		const overflow = getComputedStyle(current).overflowY;
+		if ((overflow === "auto" || overflow === "scroll") && current.scrollHeight > current.clientHeight) return current;
+		current = current.parentElement;
+	}
+	return null;
+}
 function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, id }) {
+	const holdsActive = nodes.some((node) => (node.type === "page" || node.type === "link" && !node.external) && isActiveHref(pathname, node.href));
 	return /* @__PURE__ */ jsx("ul", {
 		id,
 		className: "wave-docs-sidebar__list",
@@ -74,6 +146,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						href: node.href,
 						isExternal: node.external,
 						isActive: !node.external && isActiveHref(pathname, node.href),
+						isNearby: holdsActive,
 						Link,
 						children: node.title
 					})
@@ -84,6 +157,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						href: node.href,
 						isExternal: false,
 						isActive: isActiveHref(pathname, node.href),
+						isNearby: holdsActive,
 						Link,
 						children: node.title
 					})
@@ -122,10 +196,11 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 					className: "wave-docs-sidebar__group-title",
 					children: node.title
 				}), /* @__PURE__ */ jsx(Chevron, { isOpen })]
-			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(NavLink, {
+			}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(NavLink, {
 				href: node.href,
 				isExternal: false,
 				isActive: isGroupActive,
+				isNearby: hasActive,
 				Link,
 				children: node.title
 			}), /* @__PURE__ */ jsx("button", {
@@ -149,17 +224,34 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 		}) : null]
 	});
 }
-function NavLink({ href, isExternal, isActive, Link, children }) {
+function NavLink({ href, isExternal, isActive, isNearby = false, Link, children }) {
 	const className = "wave-docs-sidebar__link";
 	if (isExternal) return /* @__PURE__ */ jsxs("a", {
 		className,
 		href,
 		target: "_blank",
 		rel: "noopener noreferrer",
-		children: [children, /* @__PURE__ */ jsx("span", {
-			className: "wave-docs-sr-only",
-			children: " (opens in a new tab)"
-		})]
+		children: [
+			children,
+			/* @__PURE__ */ jsx("svg", {
+				className: "wave-docs-sidebar__external",
+				"aria-hidden": "true",
+				focusable: "false",
+				viewBox: "0 0 24 24",
+				width: "12",
+				height: "12",
+				fill: "none",
+				stroke: "currentColor",
+				strokeWidth: "2",
+				strokeLinecap: "round",
+				strokeLinejoin: "round",
+				children: /* @__PURE__ */ jsx("path", { d: "M14 4h6v6M20 4l-8 8M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" })
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "wave-docs-sr-only",
+				children: " (opens in a new tab)"
+			})
+		]
 	});
 	if (Link === void 0) return /* @__PURE__ */ jsx("a", {
 		className,
@@ -170,7 +262,7 @@ function NavLink({ href, isExternal, isActive, Link, children }) {
 	return /* @__PURE__ */ jsx(Link, {
 		className,
 		href,
-		prefetch: false,
+		prefetch: isNearby ? void 0 : false,
 		"aria-current": isActive ? "page" : void 0,
 		children
 	});

package/dist/react/skip-link.d.ts

@@ -1,14 +1,6 @@
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { ReactNode } from "react";
 //#region src/react/skip-link.d.ts
-/**
- * The `id` this link targets, and the one `createDocsRoute` puts on its
- * `<article>`.
- *
- * One constant for both halves: the two files spelled the string independently,
- * and a skip link pointing at an id nothing carries scrolls nowhere and focuses
- * nothing — a failure with no symptom until a keyboard user hits it.
- */
-declare const DOCS_CONTENT_ID = "docs-content";
 interface SkipLinkProps {
   /** Fragment id of the main content region. */
   href?: string | undefined;

package/dist/react/skip-link.js

@@ -1,14 +1,15 @@
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { jsx } from "react/jsx-runtime";
 //#region src/react/skip-link.tsx
 /**
 * The `id` this link targets, and the one `createDocsRoute` puts on its
-* `<article>`.
+* `<main>`. Defined in a private module so the two halves cannot spell it
+* differently; re-exported here because this is the documented import path.
 *
-* One constant for both halves: the two files spelled the string independently,
-* and a skip link pointing at an id nothing carries scrolls nowhere and focuses
-* nothing — a failure with no symptom until a keyboard user hits it.
+* (This comment used to call the file a `'use client'` module. It is not one
+* and never was — `SkipLink` is an anchor with no state, so it is a Server
+* Component like everything else here that does not need a browser.)
 */
-const DOCS_CONTENT_ID = "docs-content";
 /**
 * Skip-to-content link: invisible until focused, first in the tab order.
 *

package/dist/react/toc.d.ts

@@ -16,6 +16,8 @@ interface DocsTocProps {
    * other unit, `rem` included.
    */
   rootMargin?: string | undefined;
+  /** Text for the back-to-top link. */
+  topLabel?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -26,10 +28,16 @@ interface DocsTocProps {
  * out of sync on duplicate headings.
  *
  * Scrolling itself is left to the browser: the links are real anchors, and
- * smooth scrolling is applied in CSS under
- * `@media (prefers-reduced-motion: no-preference)`. Doing it in JavaScript
- * means reimplementing that check, and getting it wrong makes people ill.
+ * nothing here calls `scrollTo`. Doing it in JavaScript means reimplementing
+ * the `prefers-reduced-motion` check, and getting that wrong makes people ill.
+ *
+ * ⚠️ AND THE STYLESHEET SETS NO `scroll-behavior: smooth` EITHER, deliberately
+ * — this comment used to say it did. Next 16 suppresses smooth scrolling
+ * across a route change only when `<html>` carries
+ * `data-scroll-behavior="smooth"`, an attribute only the host can set, so a
+ * package-level rule would smooth-scroll every navigation and no reader could
+ * turn it off. `styles.css` says the same at greater length.
  */
-declare function DocsToc({ entries, label, rootMargin, className }: DocsTocProps): ReactNode;
+declare function DocsToc({ entries, label, rootMargin, className, topLabel }: DocsTocProps): ReactNode;
 //#endregion
 export { DocsToc, DocsTocProps };

package/dist/react/toc.js

@@ -1,4 +1,5 @@
 "use client";
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/toc.tsx
@@ -29,11 +30,17 @@ function flattenTocIds(entries) {
 * out of sync on duplicate headings.
 *
 * Scrolling itself is left to the browser: the links are real anchors, and
-* smooth scrolling is applied in CSS under
-* `@media (prefers-reduced-motion: no-preference)`. Doing it in JavaScript
-* means reimplementing that check, and getting it wrong makes people ill.
+* nothing here calls `scrollTo`. Doing it in JavaScript means reimplementing
+* the `prefers-reduced-motion` check, and getting that wrong makes people ill.
+*
+* ⚠️ AND THE STYLESHEET SETS NO `scroll-behavior: smooth` EITHER, deliberately
+* — this comment used to say it did. Next 16 suppresses smooth scrolling
+* across a route change only when `<html>` carries
+* `data-scroll-behavior="smooth"`, an attribute only the host can set, so a
+* package-level rule would smooth-scroll every navigation and no reader could
+* turn it off. `styles.css` says the same at greater length.
 */
-function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MARGIN, className }) {
+function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MARGIN, className, topLabel = "Back to top" }) {
 	const ids = useMemo(() => flattenTocIds(entries), [entries]);
 	const [activeId, setActiveId] = useState(void 0);
 	const lastIds = useRef(ids);
@@ -76,14 +83,18 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 		};
 	}, [ids, rootMargin]);
 	if (entries.length === 0) return null;
-	return /* @__PURE__ */ jsx("nav", {
+	return /* @__PURE__ */ jsxs("nav", {
 		"aria-label": label,
 		className: ["wave-docs-toc", className].filter(Boolean).join(" "),
-		children: /* @__PURE__ */ jsx(TocList, {
+		children: [/* @__PURE__ */ jsx(TocList, {
 			entries,
 			activeId,
 			onSelect: setActiveId
-		})
+		}), /* @__PURE__ */ jsx("a", {
+			className: "wave-docs-toc__top",
+			href: `#${DOCS_CONTENT_ID}`,
+			children: topLabel
+		})]
 	});
 }
 function TocList({ entries, activeId, onSelect }) {

package/dist/react/youtube.d.ts

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

package/dist/react/youtube.js

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

package/dist/render.d.ts

@@ -1,5 +1,7 @@
 import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+import { resolveMarkdownLink } from "./plugins/remark-doc-links.js";
+import { PluggableList } from "unified";
 //#region src/render.d.ts
 /**
  * The parts of {@link ResolvedDocsConfig} rendering actually depends on.
@@ -31,6 +33,38 @@ interface DocsRendererOptions {
    * is a duplication authors forget to keep in step.
    */
   titleHeading?: boolean | undefined;
+  /**
+   * Extra remark plugins, attached **after `remarkGfm` and before
+   * `remarkDocLinks`**.
+   *
+   * Which is to say: while links are still mdast `url` strings, so anything
+   * you emit is folded, contained and asserted exactly like authored markdown.
+   * A plugin emitting `[x](../other/page.md)` gets the same resolution an
+   * author would; one emitting `![i](./x.png)` throws `invalid-image` without
+   * a resolver, for the same reason.
+   *
+   * ⚠️ ATTACHED ONCE, TO A PROCESSOR SHARED BY EVERY FILE. The pipeline is
+   * built and frozen a single time, so a plugin holding state accumulates it
+   * across the whole build rather than per document. Keep them pure, or key
+   * whatever they hold on the vfile.
+   */
+  remarkPlugins?: PluggableList | undefined;
+  /**
+   * Extra rehype plugins, attached **after `rehypeAutolinkHeadings` and before
+   * the code frame and Shiki**.
+   *
+   * The position is the useful one and it is not negotiable: after slugging
+   * and autolinking, so heading ids exist; before Shiki, so a `<pre>` is still
+   * `<pre><code class="language-ts">` with the author's text inside rather
+   * than several hundred token spans. Fences excluded by `excludeLangs` are
+   * not yet disguised at this point either, so a plugin sees every code block
+   * the same way.
+   *
+   * Code-block internals are Shiki's `transformers`, not this. There is no
+   * after-Shiki slot, because the honest documentation for one would be a list
+   * of things you must not do.
+   */
+  rehypePlugins?: PluggableList | undefined;
   /** Replaces the built-in markdown-link resolution. */
   linkResolver?: LinkResolver | undefined;
   /**
@@ -103,4 +137,4 @@ interface DocsRenderer {
  */
 declare function createDocsRenderer(options: DocsRendererOptions): DocsRenderer;
 //#endregion
-export { DocsRenderer, DocsRendererConfig, DocsRendererOptions, createDocsRenderer };
+export { DocsRenderer, DocsRendererConfig, DocsRendererOptions, createDocsRenderer, resolveMarkdownLink };