@waveso/docs 0.1.0 → 0.2.0

package/dist/map-pooled.d.ts

@@ -0,0 +1,26 @@
+//#region src/map-pooled.d.ts
+/**
+ * Bounded-concurrency `Promise.all`.
+ *
+ * Private — deliberately not an entry point in `package.json`.
+ */
+/**
+ * Like `Promise.all(items.map(fn))`, but with at most `limit` calls in flight.
+ *
+ * Results keep input order, and the first rejection rejects the whole call,
+ * exactly as `Promise.all` does. Workers also stop pulling new items once one
+ * has thrown: a build that is going to fail on page 3 should not render the
+ * other 1,997 first. In-flight calls are not cancelled — there is nothing to
+ * cancel them with — so up to `limit - 1` may still settle after the rejection.
+ *
+ * `Promise.all` over a whole documentation set is fine only while the mapped
+ * function is effectively synchronous — which is true of the markdown pipeline
+ * today, and stops being true the moment a consumer wires the async
+ * `imageResolver` the docs recommend. At that point every page's tree is live
+ * at once, and a 2,000-page site holds 2,000 hast trees plus 2,000 in-flight
+ * resolver calls in memory to produce output that was always going to be
+ * written in order.
+ */
+declare function mapPooled<TItem, TResult>(items: readonly TItem[], limit: number, fn: (item: TItem, index: number) => Promise<TResult>): Promise<TResult[]>;
+//#endregion
+export { mapPooled };

package/dist/map-pooled.js

@@ -0,0 +1,45 @@
+//#region src/map-pooled.ts
+/**
+* Bounded-concurrency `Promise.all`.
+*
+* Private — deliberately not an entry point in `package.json`.
+*/
+/**
+* Like `Promise.all(items.map(fn))`, but with at most `limit` calls in flight.
+*
+* Results keep input order, and the first rejection rejects the whole call,
+* exactly as `Promise.all` does. Workers also stop pulling new items once one
+* has thrown: a build that is going to fail on page 3 should not render the
+* other 1,997 first. In-flight calls are not cancelled — there is nothing to
+* cancel them with — so up to `limit - 1` may still settle after the rejection.
+*
+* `Promise.all` over a whole documentation set is fine only while the mapped
+* function is effectively synchronous — which is true of the markdown pipeline
+* today, and stops being true the moment a consumer wires the async
+* `imageResolver` the docs recommend. At that point every page's tree is live
+* at once, and a 2,000-page site holds 2,000 hast trees plus 2,000 in-flight
+* resolver calls in memory to produce output that was always going to be
+* written in order.
+*/
+async function mapPooled(items, limit, fn) {
+	if (items.length <= limit) return Promise.all(items.map((item, index) => fn(item, index)));
+	const results = new Array(items.length);
+	let next = 0;
+	let failed = false;
+	const worker = async () => {
+		while (next < items.length && !failed) {
+			const index = next++;
+			try {
+				results[index] = await fn(items[index], index);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		}
+	};
+	const workers = Math.max(1, Math.min(limit, items.length));
+	await Promise.all(Array.from({ length: workers }, () => worker()));
+	return results;
+}
+//#endregion
+export { mapPooled };

package/dist/meta.d.ts

@@ -67,9 +67,13 @@ declare function readDocsMeta(dirPath: string): Promise<DocsMeta | undefined>;
  * @param entries - The directory's children.
  * @param meta - Its validated `meta.json`, if any.
  * @param metaPath - Path to that `meta.json`, used in error messages.
- * @throws When `pages` names a child that does not exist — always a typo, and
- *   catching it here is the entire reason `meta.json` is validated at build.
+ * @param depth - How far this directory sits below the content root, which
+ *   decides whether its own `index.md` is listed by default. See
+ *   {@link isListedByDefault}.
+ * @throws When `pages` names a child that does not exist, or names one twice —
+ *   always a typo, and catching it here is the entire reason `meta.json` is
+ *   validated at build.
  */
-declare function orderNavEntries(entries: readonly MetaDirEntry[], meta: DocsMeta | undefined, metaPath: string): DocNavNode[];
+declare function orderNavEntries(entries: readonly MetaDirEntry[], meta: DocsMeta | undefined, metaPath: string, depth: number): DocNavNode[];
 //#endregion
 export { MetaDirEntry, docsMetaSchema, orderNavEntries, parseDocsMeta, readDocsMeta };

package/dist/meta.js

@@ -1,3 +1,4 @@
+import { docsError } from "./docs-error.js";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -40,7 +41,7 @@ function parseDocsMeta(raw, filePath) {
 	const result = docsMetaSchema.safeParse(raw);
 	if (result.success) return result.data;
 	const details = result.error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
-	throw new Error(`Invalid meta.json at ${filePath}:\n${details}`);
+	throw docsError("invalid-meta", `Invalid meta.json at ${filePath}:\n${details}`);
 }
 /**
 * Read and validate `<dirPath>/meta.json`. Resolves to `undefined` when the
@@ -60,7 +61,7 @@ async function readDocsMeta(dirPath) {
 		parsed = JSON.parse(raw);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
-		throw new Error(`Could not parse ${filePath} as JSON: ${reason}`);
+		throw docsError("invalid-meta", `Could not parse ${filePath} as JSON: ${reason}`, { cause: err });
 	}
 	return parseDocsMeta(parsed, filePath);
 }
@@ -75,12 +76,16 @@ async function readDocsMeta(dirPath) {
 * @param entries - The directory's children.
 * @param meta - Its validated `meta.json`, if any.
 * @param metaPath - Path to that `meta.json`, used in error messages.
-* @throws When `pages` names a child that does not exist — always a typo, and
-*   catching it here is the entire reason `meta.json` is validated at build.
+* @param depth - How far this directory sits below the content root, which
+*   decides whether its own `index.md` is listed by default. See
+*   {@link isListedByDefault}.
+* @throws When `pages` names a child that does not exist, or names one twice —
+*   always a typo, and catching it here is the entire reason `meta.json` is
+*   validated at build.
 */
-function orderNavEntries(entries, meta, metaPath) {
+function orderNavEntries(entries, meta, metaPath, depth) {
 	const pages = meta?.pages;
-	if (pages === void 0) return dropEmptyGroups(sortEntries(entries.filter((entry) => isListedByDefault(entry))).map((entry) => entry.node));
+	if (pages === void 0) return dropEmptyGroups(sortEntries(entries.filter((entry) => isListedByDefault(entry, depth))).map((entry) => entry.node));
 	const byName = indexByName(entries, metaPath);
 	const used = /* @__PURE__ */ new Set();
 	const nodes = [];
@@ -104,29 +109,42 @@ function orderNavEntries(entries, meta, metaPath) {
 			continue;
 		}
 		if (page === REST) {
-			if (restAt !== -1) throw new Error(`${metaPath} has more than one "..." entry. A directory has a single set of unnamed pages, so only one wildcard can be honoured — remove the extra.`);
+			if (restAt !== -1) throw docsError("invalid-meta", `${metaPath} has more than one "..." entry. A directory has a single set of unnamed pages, so only one wildcard can be honoured — remove the extra.`);
 			restAt = nodes.length;
 			continue;
 		}
 		if (page.startsWith(REST)) {
 			const name = page.slice(3);
 			const target = byName.get(name);
-			if (!target?.inlineChildren) throw new Error(`${metaPath} entry "${page}" expands a directory named "${name}", which is not a subdirectory here. ${describeAvailable(entries, true)}`);
+			if (!target?.inlineChildren) throw docsError("invalid-meta", `${metaPath} entry "${page}" expands a directory named "${name}", which is not a subdirectory here. ${describeAvailable(entries, true)}`);
+			assertUnused(used, name, page, metaPath);
 			used.add(name);
 			if (target.indexNode !== void 0) nodes.push(target.indexNode);
 			nodes.push(...target.inlineChildren);
 			continue;
 		}
 		const target = byName.get(page);
-		if (!target) throw new Error(`${metaPath} lists "${page}", which does not exist. ${describeAvailable(entries, false)}`);
+		if (!target) throw docsError("invalid-meta", `${metaPath} lists "${page}", which does not exist. ${describeAvailable(entries, false)}`);
+		assertUnused(used, page, page, metaPath);
 		used.add(page);
 		if (!target.hidden) nodes.push(target.node);
 	}
 	if (restAt !== -1) {
-		const rest = sortEntries(entries.filter((entry) => isListedByDefault(entry) && !used.has(entry.name))).map((entry) => entry.node);
+		const rest = sortEntries(entries.filter((entry) => isListedByDefault(entry, depth) && !used.has(entry.name))).map((entry) => entry.node);
 		nodes.splice(restAt, 0, ...rest);
 	}
-	return dropEmptyGroups(nodes);
+	return dropDanglingSeparators(dropEmptyGroups(nodes));
+}
+/**
+* A child named twice is a typo, not an instruction.
+*
+* It renders the page twice, both copies highlighted on the page they link to,
+* and the sidebar keys its items positionally — so there is no duplicate-key
+* warning either. Every other ambiguity in this file is a build error; this
+* one only looked deliberate because nothing checked for it.
+*/
+function assertUnused(used, name, written, metaPath) {
+	if (used.has(name)) throw docsError("invalid-meta", `${metaPath} lists "${written}" more than once. It would appear twice in the sidebar, both copies marked as the current page. Remove the duplicate.`);
 }
 /**
 * Index the directory's children by the name `pages` addresses them with.
@@ -141,7 +159,7 @@ function indexByName(entries, metaPath) {
 	const byName = /* @__PURE__ */ new Map();
 	for (const entry of entries) {
 		const clash = byName.get(entry.name);
-		if (clash !== void 0) throw new Error(`${metaPath} cannot address "${entry.name}": ${describeEntry(clash)} and ${describeEntry(entry)} both claim that name. Rename one.`);
+		if (clash !== void 0) throw docsError("invalid-meta", `${metaPath} cannot address "${entry.name}": ${describeEntry(clash)} and ${describeEntry(entry)} both claim that name. Rename one.`);
 		byName.set(entry.name, entry);
 	}
 	return byName;
@@ -157,9 +175,37 @@ function describeEntry(entry) {
 function dropEmptyGroups(nodes) {
 	return nodes.filter((node) => node.type !== "group" || node.children.length > 0 || node.href !== void 0);
 }
-/** An entry appears without being named: not the index, not a draft. */
-function isListedByDefault(entry) {
-	return entry.isIndex !== true && entry.hidden !== true;
+/**
+* A separator labels whatever follows it. When that turned out to be nothing —
+* every page in the next group a draft, or two separators in a row after one
+* of them emptied — the heading is left standing over nothing.
+*
+* Runs after {@link dropEmptyGroups}, which is what empties them, and cannot be
+* left to the author to notice: `includeDrafts` is how a docs site is
+* previewed, and it is exactly the mode where the group is not empty.
+*/
+function dropDanglingSeparators(nodes) {
+	const kept = [];
+	for (const node of [...nodes].reverse()) {
+		const next = kept.at(-1);
+		if (node.type === "separator" && (next === void 0 || next.type === "separator")) continue;
+		kept.push(node);
+	}
+	return kept.reverse();
+}
+/**
+* An entry appears without being named: not a draft, and not the directory's
+* own `index.md` — which is the group heading's link, and would be a second
+* entry for a page the sidebar already shows.
+*
+* The content root is the exception, and the case the rule never considered:
+* nothing encloses it, so its `index.md` is the one page that has no heading
+* to carry its href. Without this, the site's landing page is missing from its
+* own sidebar — a reader who follows any link cannot get back — and every
+* install writes a `meta.json` whose only purpose is to undo the default.
+*/
+function isListedByDefault(entry, depth) {
+	return entry.hidden !== true && (entry.isIndex !== true || depth === 0);
 }
 function sortEntries(entries) {
 	return [...entries].sort(compareEntries);

package/dist/next.d.ts

@@ -6,24 +6,32 @@ import { ReactNode } from "react";
 //#region src/next.d.ts
 interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter> extends DocsConfig<TFrontmatter> {
   /** Overrides merged over the Next-flavoured defaults (`next/link` + `next/image`). */
-  components?: MarkdownComponents;
+  components?: MarkdownComponents | undefined;
   /** Reuse an existing Shiki highlighter. */
-  highlighter?: DocsHighlighter | Promise<DocsHighlighter>;
+  highlighter?: DocsHighlighter | Promise<DocsHighlighter> | undefined;
   /** Grammars to load, when building the default highlighter. */
-  langs?: readonly DocsLang[];
+  langs?: readonly DocsLang[] | undefined;
   /** Theme pair. */
-  themes?: DocsThemes;
+  themes?: DocsThemes | undefined;
+  /**
+   * Fence languages Shiki must not touch, e.g. `['mermaid']`.
+   *
+   * The `<pre><code class="language-mermaid">` then reaches your `pre`/`code`
+   * component untouched, which is what lets you render a diagram instead of a
+   * monochrome block of DSL.
+   */
+  excludeLangs?: readonly string[] | undefined;
   /**
    * Prepend an `<h1>` from `frontmatter.title` when the markdown has none.
    * Defaults to `true`; turn it off if your layout renders the title itself.
    */
-  titleHeading?: boolean;
+  titleHeading?: boolean | undefined;
   /**
    * `id` of the rendered `<article>`, which is also what
    * `@waveso/docs/react/skip-link` targets by default. Defaults to
    * `'docs-content'`. Pass `false` to render no id at all.
    */
-  contentId?: string | false;
+  contentId?: string | false | undefined;
   /**
    * Re-read the content directory on every request.
    *
@@ -34,15 +42,15 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
    * found. A rescan of a few hundred small files costs single-digit
    * milliseconds; a production build reads the tree once, as it should.
    */
-  rescanPerRequest?: boolean;
+  rescanPerRequest?: boolean | undefined;
   /** Replaces the built-in markdown-link resolution. */
-  linkResolver?: LinkResolver;
+  linkResolver?: LinkResolver | undefined;
   /**
    * Resolves image `src` to a public URL and intrinsic dimensions. Without one,
    * markdown images render as a plain `<img>`: `next/image` refuses to render
    * without dimensions, and markdown carries none.
    */
-  imageResolver?: ImageResolver;
+  imageResolver?: ImageResolver | undefined;
   /**
    * Absolute site origin, e.g. `'https://example.com'`.
    *
@@ -50,7 +58,7 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
    * root-relative path, which Next resolves against `metadataBase` — so if you
    * set neither, you ship pages with no usable canonical.
    */
-  siteUrl?: string;
+  siteUrl?: string | undefined;
 }
 /** Props Next hands a page in the App Router. */
 interface DocsPageProps {
@@ -142,13 +150,17 @@ interface DocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    * is documented in one place and typed as `false`, not so it can be
    * forwarded.
    *
-   * Declaring it is not optional. Next defaults `dynamicParams` to `true`,
-   * which means a URL that `generateStaticParams` never listed is still
-   * rendered on demand — so `/docs/typo` reaches the source layer,
-   * `fs.readFile` throws `ENOENT`, and Next answers **HTTP 500**. Google
-   * treats a 5xx as a crawl failure and retries it; it treats a 404 as an
-   * answer. With the full page set known at build time there is nothing to
-   * render on demand anyway.
+   * Declaring it is not optional. Next defaults `dynamicParams` to `true`, so
+   * a URL `generateStaticParams` never listed is still invoked on demand: the
+   * route runs on a server at request time to produce a 404 that was already
+   * knowable at build time. `output: 'export'` refuses to build without it at
+   * all. With the full page set known ahead of time there is nothing to render
+   * on demand anyway, and a prerendered 404 is both faster and cacheable.
+   *
+   * (An earlier version of this note claimed an unlisted URL reached
+   * `fs.readFile` and returned HTTP 500. It does not: `find()` is a lookup in
+   * the map built by the directory walk, so a miss is just `undefined`. The
+   * export is still required, for the reasons above.)
    */
   dynamicParams: false;
   /**
@@ -191,9 +203,9 @@ interface DocsSitemapOptions<TFrontmatter extends DocFrontmatter = DocFrontmatte
    */
   siteUrl: string;
   /** Applied to every entry. Omitted by default — Google ignores it anyway. */
-  changeFrequency?: DocsSitemapEntry['changeFrequency'];
+  changeFrequency?: DocsSitemapEntry['changeFrequency'] | undefined;
   /** Applied to every entry. Omitted by default. */
-  priority?: number;
+  priority?: number | undefined;
   /**
    * Override the last-modified date per page.
    *
@@ -202,6 +214,16 @@ interface DocsSitemapOptions<TFrontmatter extends DocFrontmatter = DocFrontmatte
    * noise. Wire this to your git history if the dates are load-bearing.
    */
   lastModified?: (file: DocFile<TFrontmatter>) => Date | undefined | Promise<Date | undefined>;
+  /**
+   * Re-read the content directory before building the sitemap.
+   *
+   * Defaults to `true` outside `NODE_ENV=production`, matching
+   * {@link DocsRouteOptions.rescanPerRequest}. `createDocsSource` memoises by
+   * config, so without this the first scan of the process is the only one —
+   * and `app/sitemap.ts` in `next dev` would keep serving the page set as it
+   * stood when the server booted.
+   */
+  rescanPerRequest?: boolean | undefined;
 }
 /**
  * Sitemap entries for every published page, for `app/sitemap.ts`.

package/dist/next.js

@@ -1,10 +1,12 @@
+import { docsError } from "./docs-error.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 { createDocsRenderer } from "./render.js";
 import { createDocsSource, resolveDocsConfig, toAliasRoute } from "./source.js";
 import { stat } from "node:fs/promises";
-import { createElement } from "react";
+import { cache, createElement } from "react";
 //#region src/next.ts
 /**
 * The Next.js App Router adapter.
@@ -38,16 +40,41 @@ 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;
+/** Google's per-sitemap URL cap. */
+const SITEMAP_URL_LIMIT = 5e4;
 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 +83,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,13 +100,13 @@ 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;
 }
 /**
@@ -159,9 +187,23 @@ function createDocsRoute(options) {
 	const rescanPerRequest = options.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 +211,74 @@ 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.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,7 +301,7 @@ 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));
 	};
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
@@ -232,7 +322,7 @@ function createDocsRoute(options) {
 		}));
 	}
 	return {
-		source,
+		source: requestScopedSource,
 		getPage,
 		renderAll,
 		dynamicParams: false,
@@ -287,7 +377,10 @@ function createDocsRoute(options) {
 */
 async function createDocsSitemap(options) {
 	const siteUrl = requireSiteUrl(options.siteUrl);
-	const files = await createDocsSource(options).all();
+	const source = createDocsSource(options);
+	if (options.rescanPerRequest ?? process.env.NODE_ENV !== "production") source.invalidate();
+	const files = await source.all();
+	if (files.length > SITEMAP_URL_LIMIT) console.warn(`@waveso/docs: this sitemap has ${files.length} URLs, above Google's limit of ${SITEMAP_URL_LIMIT}. Split it with Next's \`generateSitemaps\` and slice the array this returns.`);
 	const readDate = options.lastModified ?? readMtime;
 	return Promise.all(files.map(async (file) => {
 		const lastModified = await readDate(file);
@@ -338,9 +431,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 +448,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 };