nimbus-docs 0.1.7 → 0.1.9

package/dist/index.js

@@ -1,16 +1,18 @@
-import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-DnAP-j89.js";
-import { t as withStrictKeys } from "./strict-keys-BiXiT3pq.js";
+import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-DDDvKkyJ.js";
+import { i as toRouteKey, n as isAbsoluteUrl, r as toBrowserHref, t as withStrictKeys } from "./strict-keys-fbKKxxKL.js";
+import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs";
-import path from "node:path";
+import path, { dirname, extname, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import mdx from "@astrojs/mdx";
 import { satteri } from "@astrojs/markdown-satteri";
 import sitemap from "@astrojs/sitemap";
-import fs$1 from "node:fs/promises";
+import fs$1, { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { z } from "astro/zod";
 import { transformerMetaHighlight, transformerMetaWordHighlight, transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight } from "@shikijs/transformers";
+import { createHash } from "node:crypto";
 
 //#region src/_internal/runtime-config.ts
 let _cached = null;
@@ -162,115 +164,10 @@ function canonicalEntryUrl(prefix, entryId) {
 	return `${prefix}/${slug}`;
 }
 
-//#endregion
-//#region src/_internal/url.ts
-/**
-* Internal URL helpers — one shape for matching, one shape for rendering.
-*
-* Static hosts that serve `page/index.html` (Astro's default `build.format:
-* "directory"`) canonicalize to a trailing-slash URL. If framework helpers
-* emit slashless hrefs, every sidebar click costs a 307 redirect before
-* Astro's client router can pick up the page. The fix splits href shape
-* into two forms:
-*
-*   - `toRouteKey(href)` — slashless canonical form. Used wherever the
-*     framework compares paths for identity (active sidebar state,
-*     prev/next lookup, validation against the indexed route set).
-*
-*   - `toBrowserHref(href)` — what we emit into `<a href>` / `<link>` for
-*     HTML document routes. Adds a trailing slash so the URL matches the
-*     directory-index page the host serves directly.
-*
-* Asset URLs (`.md`, `.png`, `.txt`, …), external URLs, and anchor-only
-* hrefs are returned unchanged by `toBrowserHref` — they aren't HTML
-* document routes and adding a slash would break them.
-*
-* Keep these out of the public API: starter components consume hrefs the
-* framework already shaped. Authors don't (and shouldn't) call these
-* directly.
-*/
-/**
-* True for hrefs that point off-site — anything with a URI scheme
-* (`https:`, `mailto:`, `data:`, …) or a protocol-relative `//cdn.…`
-* prefix. Bare relative paths like `"cli"` and `"./foo"` are NOT external
-* — they resolve against the current page and the framework shouldn't
-* second-guess them.
-*/
-function isAbsoluteUrl(href) {
-	return /^([a-z][a-z0-9+\-.]*:|\/\/)/i.test(href);
-}
-/**
-* Detect whether the final path segment looks like a file (has an
-* extension). HTML document routes don't carry an extension under
-* `build.format: "directory"`; assets like `/og/card.png`,
-* `/llms.txt`, and `/cli/index.md` do.
-*
-* Conservative: only treats short, ASCII-letter-only extensions as files,
-* so paths with dots inside a segment (`/v1.2/foo`, version slugs) still
-* count as document routes.
-*/
-function hasFileExtension(pathname) {
-	const lastSegment = pathname.slice(pathname.lastIndexOf("/") + 1);
-	const dot = lastSegment.lastIndexOf(".");
-	if (dot <= 0) return false;
-	const ext = lastSegment.slice(dot + 1);
-	return ext.length > 0 && ext.length <= 6 && /^[a-zA-Z0-9]+$/.test(ext);
-}
-/** Split an href into `[pathname, suffix]` where `suffix` is the `?…#…` tail. */
-function splitSuffix(href) {
-	const queryAt = href.indexOf("?");
-	const hashAt = href.indexOf("#");
-	const cutAt = queryAt === -1 ? hashAt : hashAt === -1 ? queryAt : Math.min(queryAt, hashAt);
-	if (cutAt === -1) return [href, ""];
-	return [href.slice(0, cutAt), href.slice(cutAt)];
-}
-/**
-* Slashless canonical form for path comparisons.
-*
-*   /cli           → /cli
-*   /cli/          → /cli
-*   /cli/?x=1#y    → /cli
-*   /              → /
-*   /guides/setup/ → /guides/setup
-*
-* Strips query and hash so callers can compare two hrefs that differ only
-* in their tail. Root stays `"/"` — that's identity, not a trailing-slash
-* artifact.
-*/
-function toRouteKey(href) {
-	const [pathname] = splitSuffix(href);
-	if (pathname.length <= 1) return pathname || "/";
-	return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
-}
-/**
-* Trailing-slash form for browser-facing hrefs to HTML document routes.
-* Preserves query and hash; root, external URLs, anchor-only hrefs, and
-* asset URLs (paths with a file extension) are returned unchanged.
-*
-*   /cli              → /cli/
-*   /cli/             → /cli/
-*   /cli#install      → /cli/#install
-*   /cli?v=1          → /cli/?v=1
-*   /                 → /
-*   /og/card.png      → /og/card.png        (asset, unchanged)
-*   /cli/index.md     → /cli/index.md       (asset, unchanged)
-*   https://x.com/a   → https://x.com/a     (external, unchanged)
-*   #anchor           → #anchor             (anchor-only, unchanged)
-*/
-function toBrowserHref(href) {
-	if (isAbsoluteUrl(href)) return href;
-	if (href.startsWith("#") || href.startsWith("?")) return href;
-	if (!href.startsWith("/")) return href;
-	const [pathname, suffix] = splitSuffix(href);
-	if (pathname === "/") return href;
-	if (hasFileExtension(pathname)) return href;
-	if (pathname.endsWith("/")) return href;
-	return `${pathname}/${suffix}`;
-}
-
 //#endregion
 //#region src/_internal/sidebar.ts
 const sortKeyByItem = /* @__PURE__ */ new WeakMap();
+const directoryIndexLinks = /* @__PURE__ */ new WeakSet();
 function sortSidebarItems(a, b) {
 	const orderDiff = a.order - b.order;
 	if (orderDiff !== 0) return orderDiff;
@@ -307,18 +204,44 @@ function joinHref(hrefPrefix, entryId) {
 	return toBrowserHref(canonicalEntryUrl(hrefPrefix.replace(/\/$/, ""), entryId));
 }
 function createLink(entry, currentPath, hrefPrefix = "") {
-	const href = joinHref(hrefPrefix, entry.id);
+	const internalHref = joinHref(hrefPrefix, entry.id);
 	const badge = entry.data.draft ? entry.data.sidebar?.badge ?? {
 		text: "Draft",
 		variant: "warning"
 	} : entry.data.sidebar?.badge;
+	const label = entry.data.sidebar?.label ?? entry.data.title;
+	const order = entry.data.sidebar?.order ?? Number.MAX_VALUE;
+	const externalLink = entry.data.external_link;
+	if (externalLink) {
+		if (isAbsoluteUrl(externalLink)) {
+			const ext = {
+				type: "external",
+				label,
+				href: externalLink,
+				badge,
+				order
+			};
+			sortKeyByItem.set(ext, entry.id);
+			return ext;
+		}
+		const link = {
+			type: "link",
+			label,
+			href: toBrowserHref(externalLink),
+			isCurrent: false,
+			badge,
+			order
+		};
+		sortKeyByItem.set(link, entry.id);
+		return link;
+	}
 	const link = {
 		type: "link",
-		label: entry.data.sidebar?.label ?? entry.data.title,
-		href,
-		isCurrent: toRouteKey(currentPath) === toRouteKey(href),
+		label,
+		href: internalHref,
+		isCurrent: toRouteKey(currentPath) === toRouteKey(internalHref),
 		badge,
-		order: entry.data.sidebar?.order ?? Number.MAX_VALUE
+		order
 	};
 	sortKeyByItem.set(link, entry.id);
 	return link;
@@ -329,8 +252,17 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 	function buildLevel(parentPath) {
 		const result = [];
 		const groupsAtLevel = /* @__PURE__ */ new Map();
+		if (directory && parentPath === directory) {
+			const dirIndex = byId.get(directory);
+			if (dirIndex) {
+				const indexLink = createLink(dirIndex, currentPath, hrefPrefix);
+				if (indexLink.type === "link" && !dirIndex.data.sidebar?.label) directoryIndexLinks.add(indexLink);
+				result.push(indexLink);
+			}
+		}
 		for (const entry of scoped) {
 			if (entry.id === "index") continue;
+			if (entry.id === directory) continue;
 			const id = entry.id;
 			const relativeTo = directory ?? "";
 			const relativeId = relativeTo ? id === relativeTo ? "" : id.slice(relativeTo.length + 1) : id;
@@ -375,26 +307,40 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 		for (const [groupPath, group] of groupsAtLevel) {
 			const nestedChildren = buildLevel(groupPath);
 			group.children = [...group.children, ...nestedChildren].sort(sortSidebarItems);
-			if (group.children.length > 0) {
-				const minChildOrder = Math.min(...group.children.map((item) => item.order));
-				group.order = Math.min(group.order, minChildOrder);
-			}
+			if (group.order === Number.MAX_VALUE && group.children.length > 0) group.order = Math.min(...group.children.map((item) => item.order));
 		}
 		return result.sort(sortSidebarItems);
 	}
 	function createGroupFromEntry(dirPath, indexEntry, currentPath, _byId) {
 		const dirSegment = dirPath.split("/").pop();
-		const groupLabel = indexEntry?.data.sidebar?.label ?? formatLabel(dirSegment);
+		const groupConfig = indexEntry?.data.sidebar?.group;
+		const groupLabel = groupConfig?.label ?? indexEntry?.data.sidebar?.label ?? indexEntry?.data.title ?? formatLabel(dirSegment);
 		const groupOrder = indexEntry?.data.sidebar?.order ?? Number.MAX_VALUE;
-		const children = [];
-		if (indexEntry) children.push(createLink(indexEntry, currentPath, hrefPrefix));
+		const groupBadge = groupConfig?.badge ?? indexEntry?.data.sidebar?.badge;
+		let indexHref;
+		let indexIsCurrent = false;
+		let indexIsExternal = false;
+		if (indexEntry) {
+			const externalLink = indexEntry.data.external_link;
+			if (externalLink !== void 0) if (isAbsoluteUrl(externalLink)) {
+				indexHref = externalLink;
+				indexIsExternal = true;
+			} else indexHref = toBrowserHref(externalLink);
+			else {
+				indexHref = joinHref(hrefPrefix, indexEntry.id);
+				indexIsCurrent = toRouteKey(currentPath) === toRouteKey(indexHref);
+			}
+		}
 		const group = {
 			type: "group",
 			label: groupLabel,
 			order: groupOrder,
-			badge: indexEntry?.data.sidebar?.badge,
-			children,
-			_indexId: indexEntry?.id
+			badge: groupBadge,
+			children: [],
+			_indexId: indexEntry?.id,
+			indexHref,
+			indexIsCurrent: indexIsCurrent || void 0,
+			indexIsExternal: indexIsExternal || void 0
 		};
 		sortKeyByItem.set(group, dirPath);
 		return group;
@@ -494,45 +440,80 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 * Return only the children of the top-level group containing the current
 * page. Falls back to the full tree if the current page isn't inside any
 * group (e.g. a top-level link, or a path that doesn't resolve).
+*
+* Under structural separation the group's landing page lives on
+* `indexHref` rather than in `children`. When the active group has a
+* landing, we prepend a synthetic link (or external item) for it so
+* the section landing remains reachable from the scoped rail — without
+* this, on `/api/` the rail shows `/api/users`, `/api/orders`, … but
+* the section's own overview page would be missing from the rail.
 */
 function scopeToCurrentSection(items, currentPath) {
 	if (!currentPath.split("/").filter(Boolean)[0]) return items;
 	for (const item of items) if (item.type === "group") {
-		if (hasActivePage(item, currentPath)) return item.children;
+		if (hasActivePage(item, currentPath)) {
+			if (!item.indexHref) return item.children;
+			return [item.indexIsExternal ? {
+				type: "external",
+				label: item.label,
+				href: item.indexHref,
+				badge: item.badge,
+				order: Number.NEGATIVE_INFINITY
+			} : {
+				type: "link",
+				label: item.label,
+				href: item.indexHref,
+				isCurrent: item.indexIsCurrent === true,
+				badge: item.badge,
+				order: Number.NEGATIVE_INFINITY
+			}, ...item.children];
+		}
 	}
 	return items;
 }
 function hasActivePage(item, currentPath) {
 	if (item.type === "link") return item.isCurrent === true;
 	if (item.type === "external") return false;
+	if (item.indexIsCurrent === true) return true;
 	return item.children.some((child) => hasActivePage(child, currentPath));
 }
 /**
-* Derive one section per top-level group in the sidebar tree. Used by
-* `Header.astro` to render the section tab strip. Caller must pass the
-* *un-scoped* tree (the result of `buildSidebarTree`, not `getSidebar`);
-* otherwise only the current section's children are visible and the
-* derivation collapses to a single item.
+* Derive one section per top-level group in the sidebar tree, scoped
+* to *cross-collection* navigation. Used by `Header.astro` to render
+* the section tab strip.
+*
+* Filter rule: only groups whose `_prefix` is set become sections. The
+* `_prefix` field is populated exclusively by `autogenerate: { collection: <non-primary> }`
+* config items (see `resolveConfigItems`). This is the structural
+* signal that the group represents a *separate collection mounted at a
+* URL prefix* — e.g. `Components` mounted at `/components/` —
+* rather than a sub-directory of the primary docs collection.
+*
+* Why this matters: under the previous unconditional behavior, every
+* top-level group in the sidebar (including `wip/`, `lab/`, and other
+* docs-collection subdirectories) was promoted to a header tab. The
+* header rail is meant for "other collections" navigation, not for
+* sub-sections of the default collection — those belong in the
+* sidebar's own collapsible tree.
+*
+* Caller must pass the *un-scoped* tree (the result of
+* `buildSidebarTree`, not `getSidebar`); otherwise only the current
+* section's children are visible and the derivation collapses to a
+* single item.
 */
 function deriveSidebarSections(items) {
 	return items.flatMap((item) => {
 		if (item.type !== "group") return [];
-		const links = flattenLinks(item.children);
+		if (!item._prefix) return [];
+		const links = flattenSidebar(item.children);
 		if (links.length === 0) return [];
 		return [{
 			label: item.label,
-			href: toBrowserHref(item._prefix ?? links[0].href),
+			href: toBrowserHref(item._prefix),
 			isActive: links.some((link) => link.isCurrent === true)
 		}];
 	});
 }
-/** Depth-first walk; collect every internal link descendant. */
-function flattenLinks(items) {
-	const out = [];
-	for (const item of items) if (item.type === "link") out.push(item);
-	else if (item.type === "group") out.push(...flattenLinks(item.children));
-	return out;
-}
 /**
 * Build the un-scoped sidebar tree from config + content entries.
 *
@@ -557,11 +538,55 @@ function buildSidebarTree(entriesByCollection, primaryCollection, currentPath, c
 	else items = buildFilesystemTree(primaryEntries, currentPath, void 0, primaryPrefix);
 	const pooledEntries = Object.values(entriesByCollection).flat();
 	items = processHideChildren(items, pooledEntries);
+	if (config?.overviewLabel) {
+		const label = typeof config.overviewLabel === "string" ? config.overviewLabel : "Overview";
+		items = applyOverviewLabel(items, label);
+	}
+	if (config?.defaultCollapsed) applyDefaultCollapsed(items);
 	return items;
 }
 /**
-* Process hideChildren: replace groups whose index has hideChildren=true
-* with a single link to the index page.
+* Walk every group and stamp `collapsed: true` where no explicit value
+* was set. Used by the `sidebar.defaultCollapsed` opt-in. Recurses into
+* nested children so a deeply-structured tree collapses at every level.
+*/
+function applyDefaultCollapsed(items) {
+	for (const item of items) if (item.type === "group") {
+		if (item.collapsed === void 0) item.collapsed = true;
+		applyDefaultCollapsed(item.children);
+	}
+}
+/**
+* @deprecated Effective no-op under structural separation. Pre-2026
+* Nimbus rendered the group's index as the first child link and used
+* this to rename that link to "Overview". The index is now exposed via
+* `SidebarGroupItem.indexHref` (the group label IS the link), so there's
+* no first-child index to rename. The function is kept so older configs
+* that set `sidebar.overviewLabel` don't blow up; future major can drop it.
+*
+* Renamed only when the first link IS the group's index (matched via the
+* `sortKeyByItem` WeakMap) — under structural separation that condition
+* never holds, so this silently returns the input unchanged.
+*/
+function applyOverviewLabel(items, label) {
+	for (const item of items) if (item.type === "link" && directoryIndexLinks.has(item)) item.label = label;
+	else if (item.type === "group") {
+		if (item._indexId) {
+			const firstLink = item.children.find((child) => child.type === "link");
+			if (firstLink && sortKeyByItem.get(firstLink) === item._indexId) firstLink.label = label;
+		}
+		applyOverviewLabel(item.children, label);
+	}
+	return items;
+}
+/**
+* Process `sidebar.hideChildren: true` on a group's index entry:
+* replace the entire group with a single flat link to the index page.
+*
+* Under structural separation the group already exposes its landing
+* page via `indexHref` and never adds the index as a child, so this
+* function reads `indexHref` directly when collapsing — no need to
+* search through `children` for an index link that isn't there.
 */
 function processHideChildren(items, entries) {
 	const entryById = /* @__PURE__ */ new Map();
@@ -573,18 +598,25 @@ function processHideChildren(items, entries) {
 				result.push(item);
 				continue;
 			}
-			if (item._indexId) {
+			if (item._indexId && item.indexHref) {
 				if (entryById.get(item._indexId)?.data.sidebar?.hideChildren) {
-					const indexKey = toRouteKey(canonicalEntryUrl("", item._indexId));
-					const indexLink = item.children.find((c) => c.type === "link" && toRouteKey(c.href) === indexKey);
-					if (indexLink) {
-						const link = {
-							...indexLink,
-							label: item.label
-						};
-						result.push(link);
-						continue;
-					}
+					const replacement = item.indexIsExternal ? {
+						type: "external",
+						label: item.label,
+						href: item.indexHref,
+						badge: item.badge,
+						order: item.order
+					} : {
+						type: "link",
+						label: item.label,
+						href: item.indexHref,
+						isCurrent: item.indexIsCurrent === true,
+						badge: item.badge,
+						order: item.order
+					};
+					sortKeyByItem.set(replacement, item._indexId);
+					result.push(replacement);
+					continue;
 				}
 			}
 			item.children = process(item.children);
@@ -618,11 +650,33 @@ function collectSidebarCollectionRefs(items) {
 	walk(items);
 	return [...found];
 }
-/** Flatten sidebar tree into a list of links (for pagination) */
+/**
+* Flatten sidebar tree into a list of links (for pagination).
+*
+* Groups with a landing page (`indexHref` set; structural-separation
+* model) contribute a synthetic link at the group's position so that
+* `getPrevNext` includes the directory-index page in the prev/next
+* walk. Without this, navigating *to* or *from* a group's index page
+* skips it entirely (e.g. on `/api/`, "prev" jumps over the section
+* landing to the previous group's last child).
+*
+* External landing pages (`indexIsExternal`) are excluded — they're
+* off-site destinations, not part of the in-site pagination ring.
+*/
 function flattenSidebar(items) {
 	const flat = [];
 	for (const item of items) if (item.type === "link") flat.push(item);
-	else if (item.type === "group") flat.push(...flattenSidebar(item.children));
+	else if (item.type === "group") {
+		if (item.indexHref && !item.indexIsExternal) flat.push({
+			type: "link",
+			label: item.label,
+			href: item.indexHref,
+			isCurrent: item.indexIsCurrent === true,
+			badge: item.badge,
+			order: item.order
+		});
+		flat.push(...flattenSidebar(item.children));
+	}
 	return flat;
 }
 function formatLabel(segment) {
@@ -969,6 +1023,131 @@ async function getLastUpdatedFromGit(filePath) {
 	return result;
 }
 
+//#endregion
+//#region src/_internal/admonition-transform.ts
+/** Built-in MyST / Docusaurus / CF admonition types and their Aside mapping. */
+const BUILTIN_TYPES = {
+	note: "note",
+	info: "note",
+	tip: "tip",
+	caution: "caution",
+	warning: "caution",
+	important: "caution",
+	danger: "danger"
+};
+/**
+* Transform a single MDX source string. Idempotent — running the
+* transform twice produces the same output as running it once.
+*/
+function transformAdmonitions(source, options = {}) {
+	const typeMap = {
+		...BUILTIN_TYPES,
+		...options.typeAliases ?? {}
+	};
+	const { frontmatter, body, bodyOffset: _ } = splitFrontmatter(source);
+	const { stashed, restore } = stashCodeBlocks(body);
+	return frontmatter + restore(stashed.replace(ADMONITION_PATTERN, (match, rawType, rawTitle, rawContent) => {
+		const aside = typeMap[String(rawType).toLowerCase()];
+		if (!aside) return match;
+		const title = typeof rawTitle === "string" ? rawTitle.trim() : "";
+		const content = String(rawContent).trim();
+		return `\n\n<Aside type="${aside}"${title ? ` title=${JSON.stringify(title)}` : ""}>\n\n${content}\n\n</Aside>\n\n`;
+	}));
+}
+/**
+* Match `:::type[optional title] body :::` with non-greedy body.
+*
+* Components:
+*   - `:::`           literal opener
+*   - `([a-zA-Z]+)`   type token (captured, case-insensitive lookup at use site)
+*   - `(?:\[(...)\])?` optional bracketed title; brackets stripped from capture
+*   - `\s+|\n`        at least one whitespace before content (avoids matching
+*                      `:::foo:::` directly)
+*   - `([\s\S]*?)`    non-greedy body, may span newlines
+*   - `\n?\s*:::`     closer, possibly with leading whitespace
+*
+* Non-greedy body + global flag means adjacent admonitions don't merge
+* (the engine finds the *nearest* `:::` closer for each opener).
+*/
+const ADMONITION_PATTERN = /:::([a-zA-Z]+)(?:\[([^\]]*)\])?[ \t]*(?:\n|[ \t]+)([\s\S]*?)\n?[ \t]*:::/g;
+function splitFrontmatter(source) {
+	const match = source.match(/^---\n[\s\S]*?\n---\n?/);
+	if (!match) return {
+		frontmatter: "",
+		body: source,
+		bodyOffset: 0
+	};
+	return {
+		frontmatter: match[0],
+		body: source.slice(match[0].length),
+		bodyOffset: match[0].length
+	};
+}
+/**
+* Replace fenced code blocks with opaque placeholders so the admonition
+* regex doesn't reach `:::` tokens inside code samples. The `restore()`
+* function reinstates the originals after the transform.
+*
+* Order matters: stash the longest fence flavors first (``` and ~~~)
+* so the placeholders themselves don't get re-stashed. Inline backtick
+* code spans are NOT stashed — a `:::` inside a single-line `code` span
+* is rare and would have to be on the same line as both fences anyway.
+*/
+function stashCodeBlocks(body) {
+	const blocks = [];
+	const PLACEHOLDER = "\0NIMBUS_CODEBLOCK_";
+	const PLACEHOLDER_END = "\0";
+	const stashed = body.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~/g, (match) => {
+		const index = blocks.length;
+		blocks.push(match);
+		return `${PLACEHOLDER}${index}${PLACEHOLDER_END}`;
+	});
+	function restore(src) {
+		return src.replace(new RegExp(`${PLACEHOLDER}(\\d+)${PLACEHOLDER_END}`, "g"), (_match, index) => blocks[Number(index)] ?? "");
+	}
+	return {
+		stashed,
+		restore
+	};
+}
+
+//#endregion
+//#region src/_internal/admonition-vite-plugin.ts
+/**
+* Vite plugin: intercept `.mdx` (and `.md`) loads under the project's
+* content directories, rewrite `:::admonition` directives to `<Aside>`
+* components, hand the transformed source to the next loader in the
+* chain. Sits in front of @astrojs/mdx and Sätteri.
+*
+* `enforce: "pre"` is load-bearing — the MDX integration's own transform
+* registers without an `enforce` and runs in the default mid-pipeline
+* slot. Pre-stage runs before that, so by the time MDX parses the file,
+* the directive syntax has already been rewritten to JSX.
+*
+* Scope is restricted to the project's content directories so we don't
+* touch unrelated `.md` files in `node_modules/` or vendored MDX.
+*/
+function admonitionPlugin(options) {
+	const normalizedDirs = options.contentDirs.map((d) => path.resolve(d));
+	return {
+		name: "nimbus-docs:admonitions",
+		enforce: "pre",
+		transform(code, id) {
+			const [pathOnly] = id.split("?", 1);
+			if (!pathOnly) return null;
+			if (!pathOnly.endsWith(".mdx") && !pathOnly.endsWith(".md")) return null;
+			const absolute = path.resolve(pathOnly);
+			if (!normalizedDirs.some((dir) => absolute === dir || absolute.startsWith(dir + path.sep))) return null;
+			if (options.skip?.(absolute)) return null;
+			if (!code.includes(":::")) return null;
+			return {
+				code: transformAdmonitions(code, { typeAliases: options.typeAliases }),
+				map: null
+			};
+		}
+	};
+}
+
 //#endregion
 //#region src/_internal/parse-components-registry.ts
 /**
@@ -1655,7 +1834,7 @@ async function validateMdxContent(options) {
 	const globalsSet = new Set(options.globals);
 	const failures = [];
 	for (const dir of options.contentDirs) {
-		const files = await walkMdx(dir);
+		const files = await walkMdx$1(dir);
 		for (const file of files) {
 			if (options.skip?.(file)) continue;
 			const fileFailures = scanFile(await fs$1.readFile(file, "utf8"), globalsSet);
@@ -1684,7 +1863,7 @@ function formatFailures(failures, globalsCount) {
 	});
 	return `[nimbus-docs] Unknown MDX component ${failures.length === 1 ? "tag" : "tags"}:\n` + lines.join("\n") + "\n\nA PascalCase tag in MDX must either be registered in src/components.ts (the global registry) or imported at the top of the file. Without either, MDX renders the tag as literal text on the page — a silent failure this validator turns into a build error.";
 }
-async function walkMdx(dir) {
+async function walkMdx$1(dir) {
 	const out = [];
 	async function visit(current) {
 		let entries;
@@ -1764,7 +1943,7 @@ function parseImports(body) {
 * inside code samples doesn't trip the validator.
 */
 function stripCodeBlocks(body) {
-	return body.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length)).replace(/~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length)).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length));
+	return body.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length)).replace(/~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length)).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length)).replace(/=\s*"[^"\n]*"/g, (m) => "=" + " ".repeat(m.length - 1)).replace(/=\s*'[^'\n]*'/g, (m) => "=" + " ".repeat(m.length - 1)).replace(/"[^"\n]*"/g, (m) => " ".repeat(m.length)).replace(/'[^'\n]*'/g, (m) => " ".repeat(m.length));
 }
 /**
 * Find PascalCase JSX-like tags. Matches `<Capital...` at the start of
@@ -1774,10 +1953,14 @@ function stripCodeBlocks(body) {
 */
 function findPascalCaseTags(body) {
 	const out = [];
-	for (const match of body.matchAll(/<([A-Z][A-Za-z0-9_]*)\b/g)) out.push({
-		name: match[1],
-		offset: match.index ?? 0
-	});
+	for (const match of body.matchAll(/<([A-Z][A-Za-z0-9_]*)/g)) {
+		const offset = match.index ?? 0;
+		if (body[offset + match[0].length] === "<") continue;
+		out.push({
+			name: match[1],
+			offset
+		});
+	}
 	return out;
 }
 /**
@@ -1811,8 +1994,11 @@ const headElementSchema = z.object({
 		"meta",
 		"link",
 		"script",
-		"style"
-	]),
+		"style",
+		"title",
+		"noscript",
+		"base"
+	], { error: "head element \"tag\" must be one of: meta, link, script, style, title, noscript, base" }),
 	attrs: z.record(z.string(), z.string()).default({}),
 	content: z.string().optional()
 });
@@ -1941,6 +2127,1268 @@ function virtualConfigPlugin(config, extras) {
 	};
 }
 
+//#endregion
+//#region src/_internal/scan-code-langs.ts
+/**
+* Walk `src/content/` and collect every language used in fenced code blocks
+* inside `.md` / `.mdx` files. Output feeds `shikiConfig.langs` so Shiki
+* eager-loads every grammar at startup instead of lazy-loading on first use.
+*
+* Why this matters: Shiki's lazy load assumes every MDX file gets processed
+* during a build. Layer 2 (incremental builds' Vite MDX-skip plugin) breaks
+* that assumption — cached MDX files never enter the markdown pipeline, so
+* languages that only appear in cached files would never trigger a grammar
+* load, and any non-cached file using those languages would silently render
+* without highlighting.
+*
+* Eager loading also gives non-incremental users a small predictability win:
+* the highlighter behaves the same regardless of which file is processed
+* first.
+*
+* Cost: ~1s on a 7k-file bench. Acceptable.
+*/
+const FENCE_RE = /^[ \t]*```([a-zA-Z][a-zA-Z0-9_+\-]*)/gm;
+async function* walkMdx(dir) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		const full = resolve(dir, entry.name);
+		if (entry.isDirectory()) yield* walkMdx(full);
+		else if (entry.isFile() && [".mdx", ".md"].includes(extname(entry.name))) yield full;
+	}
+}
+/**
+* Scan a project's content directories for code-fence languages.
+*
+* `langAlias` maps shorthand fence names (e.g. `curl`, `console`) to the
+* underlying highlighter Shiki actually knows. The mapping is applied
+* before deduping so the returned set is what Shiki should load.
+*/
+async function scanCodeBlockLanguages(projectRoot, langAlias = {}) {
+	const langs = /* @__PURE__ */ new Set();
+	const contentRoot = resolve(projectRoot, "src/content");
+	for await (const file of walkMdx(contentRoot)) {
+		let content;
+		try {
+			content = await readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		FENCE_RE.lastIndex = 0;
+		for (const m of content.matchAll(FENCE_RE)) {
+			const raw = m[1].toLowerCase();
+			const mapped = langAlias[raw] ?? raw;
+			langs.add(mapped);
+		}
+	}
+	return Array.from(langs).sort();
+}
+
+//#endregion
+//#region src/_internal/incremental/cache.ts
+/**
+* Filesystem cache layer.
+*
+* Layout under `.nimbus/cache/`:
+*
+*   manifest.json                 — see Manifest type
+*   pages/<aa>/<full-hash>.html   — cached HTML body for a page, sharded
+*                                   by the first 2 hex chars of the hash
+*
+* Phase 2 MVP — atomic per-file writes. v2 adds a manifest-level
+* `namespace` field for PR-vs-main isolation; resolution lives in
+* `namespace.ts`. Framework/Node version is folded into `globalHash` via
+* `computeGlobalHash` already, so it doesn't need a separate field.
+*/
+const SCHEMA_VERSION = 2;
+var Cache = class {
+	root;
+	constructor(projectRoot) {
+		this.root = resolve(projectRoot, ".nimbus/cache");
+	}
+	pagePath(hash) {
+		return resolve(this.root, "pages", hash.slice(0, 2), `${hash}.html`);
+	}
+	manifestPath() {
+		return resolve(this.root, "manifest.json");
+	}
+	async readManifest() {
+		try {
+			const raw = await readFile(this.manifestPath(), "utf8");
+			const m = JSON.parse(raw);
+			if (m.schemaVersion !== SCHEMA_VERSION) return null;
+			return m;
+		} catch {
+			return null;
+		}
+	}
+	async writeManifest(manifest) {
+		const full = {
+			schemaVersion: SCHEMA_VERSION,
+			recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...manifest
+		};
+		await mkdir(this.root, { recursive: true });
+		await writeAtomic(this.manifestPath(), JSON.stringify(full, null, 2) + "\n");
+	}
+	async readPage(hash) {
+		try {
+			return await readFile(this.pagePath(hash), "utf8");
+		} catch {
+			return null;
+		}
+	}
+	async hasPage(hash) {
+		try {
+			await readFile(this.pagePath(hash));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async writePage(hash, html) {
+		const path = this.pagePath(hash);
+		await mkdir(dirname(path), { recursive: true });
+		await writeAtomic(path, html);
+	}
+	async clear() {
+		await rm(this.root, {
+			recursive: true,
+			force: true
+		});
+	}
+	/**
+	* Snapshot a *bounded subset* of `dist/_astro/` into the cache.
+	*
+	* Naive snapshot was unbounded: every warm build accumulated new
+	* bundle hashes (vite produces different hashes when the module graph
+	* differs between builds) and we kept everything forever. Caller passes
+	* the set of asset rel-paths that some cached HTML actually references —
+	* anything outside that set gets dropped.
+	*
+	* `referencedRelPaths` should be the union of every `/_astro/...` URL
+	* extracted from cached HTML — see `parseReferencedAssets` in index.ts.
+	*/
+	async snapshotAssets(distAstroDir, referencedRelPaths) {
+		const target = resolve(this.root, "assets");
+		await rm(target, {
+			recursive: true,
+			force: true
+		});
+		try {
+			await stat(distAstroDir);
+		} catch {
+			return 0;
+		}
+		if (referencedRelPaths.size === 0) return 0;
+		await mkdir(target, { recursive: true });
+		let count = 0;
+		for (const relPath of referencedRelPaths) {
+			const src = resolve(distAstroDir, relPath);
+			const dst = resolve(target, relPath);
+			try {
+				await stat(src);
+			} catch {
+				continue;
+			}
+			try {
+				await mkdir(dirname(dst), { recursive: true });
+				await cp(src, dst);
+				count++;
+			} catch {}
+		}
+		return count;
+	}
+	/**
+	* Restore cached assets into the build's `_astro/` directory. Only writes
+	* files that don't already exist — fresh assets from the current warm
+	* build win when there's a collision.
+	*
+	* Per-file try/catch: a failed copy logs and continues. Aborting the
+	* whole restore on a single bad file would prevent `astro:build:done`
+	* from reaching the manifest write — that's a worse failure mode than
+	* a few missing assets.
+	*/
+	async restoreAssets(distAstroDir, onError) {
+		const source = resolve(this.root, "assets");
+		try {
+			await stat(source);
+		} catch {
+			return 0;
+		}
+		let restored = 0;
+		await mkdir(distAstroDir, { recursive: true });
+		for await (const relPath of walkRelative(source)) {
+			const src = resolve(source, relPath);
+			const dst = resolve(distAstroDir, relPath);
+			try {
+				await stat(dst);
+				continue;
+			} catch {}
+			try {
+				await mkdir(dirname(dst), { recursive: true });
+				await cp(src, dst);
+				restored++;
+			} catch (err) {
+				onError?.(relPath, err);
+			}
+		}
+		return restored;
+	}
+	/**
+	* Snapshot `dist/pagefind/` into the cache. Called after a Pagefind run
+	* completes so a subsequent zero-miss warm build can restore the prior
+	* index without rerunning Pagefind (which sets a ~10s floor at 7k pages
+	* by reindexing the entire site).
+	*
+	* Idempotent: replaces any prior snapshot. Returns the number of files
+	* copied; 0 if `pagefind/` doesn't exist (e.g. user disabled search).
+	*/
+	async snapshotPagefind(distPagefindDir) {
+		const target = resolve(this.root, "pagefind");
+		await rm(target, {
+			recursive: true,
+			force: true
+		});
+		try {
+			await stat(distPagefindDir);
+		} catch {
+			return 0;
+		}
+		await mkdir(target, { recursive: true });
+		let count = 0;
+		for await (const relPath of walkRelative(distPagefindDir)) {
+			const src = resolve(distPagefindDir, relPath);
+			const dst = resolve(target, relPath);
+			try {
+				await mkdir(dirname(dst), { recursive: true });
+				await cp(src, dst);
+				count++;
+			} catch {}
+		}
+		return count;
+	}
+	/**
+	* Restore the cached `pagefind/` into `dist/`. Used on zero-miss warm
+	* builds in place of rerunning Pagefind. Per-file try/catch — a single
+	* bad copy doesn't abort the restore.
+	*/
+	async restorePagefind(distPagefindDir) {
+		const source = resolve(this.root, "pagefind");
+		try {
+			await stat(source);
+		} catch {
+			return 0;
+		}
+		let restored = 0;
+		await mkdir(distPagefindDir, { recursive: true });
+		for await (const relPath of walkRelative(source)) {
+			const src = resolve(source, relPath);
+			const dst = resolve(distPagefindDir, relPath);
+			try {
+				await mkdir(dirname(dst), { recursive: true });
+				await cp(src, dst);
+				restored++;
+			} catch {}
+		}
+		return restored;
+	}
+	/** Whether a Pagefind snapshot is present on disk. */
+	async hasPagefindSnapshot() {
+		try {
+			await stat(resolve(this.root, "pagefind"));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+async function* walkRelative(root) {
+	async function* walk(dir) {
+		const entries = await readdir(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const full = resolve(dir, entry.name);
+			if (entry.isDirectory()) yield* walk(full);
+			else if (entry.isFile()) yield relative(root, full).split(sep).join("/");
+		}
+	}
+	yield* walk(root);
+}
+/**
+* Write `data` to `path` atomically — write to a sibling temp file, then
+* rename into place. Prevents half-written files when a build is interrupted.
+*/
+async function writeAtomic(path, data) {
+	const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+	await writeFile(tmp, data, "utf8");
+	await rename(tmp, path);
+}
+
+//#endregion
+//#region src/_internal/incremental/hash.ts
+/**
+* Hash primitives for the incremental builds cache.
+*
+* Two hash kinds:
+*   - globalHash:  fingerprint of anything outside src/content/ that could
+*                  change rendered output (config, components, layouts,
+*                  lockfile). Any change here invalidates every page.
+*   - pageHash:    sha256(page bytes + globalHash). Determines whether a
+*                  given page's cached HTML is still valid.
+*
+* Phase 2 MVP — deliberately no partial tracking, no data-collection tracking,
+* no component-graph tracking. Phase 3 wires the partial registry into the
+* page hash; that work depends on `validate-mdx-content.ts` being extended
+* to capture `<Render file="…">` references.
+*/
+const TRACKED_DIRS = ["src", "public"];
+const TRACKED_FILES = [
+	"astro.config.ts",
+	"astro.config.mts",
+	"astro.config.mjs",
+	"astro.config.cts",
+	"astro.config.js",
+	"package.json",
+	"pnpm-lock.yaml",
+	"package-lock.json",
+	"yarn.lock",
+	"bun.lockb",
+	"tsconfig.json"
+];
+const CONTENT_EXCLUDES = ["src/content"];
+function sha256Hex(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/**
+* Walk `dir` recursively, returning relative paths of every file.
+* Skips node_modules, dist, .astro, .nimbus, and hidden dirs.
+*/
+async function walk$1(dir, root) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		if (entry.name === "node_modules") continue;
+		if (entry.name === "dist") continue;
+		const full = resolve(dir, entry.name);
+		const rel = relative(root, full).split(sep).join("/");
+		if (CONTENT_EXCLUDES.some((ex) => rel === ex || rel.startsWith(ex + "/"))) continue;
+		if (entry.isDirectory()) out.push(...await walk$1(full, root));
+		else if (entry.isFile()) out.push(rel);
+	}
+	return out;
+}
+/**
+* Compute the global hash for the project at `projectRoot`.
+*
+* The hash is sha256 over a canonical line-per-file listing followed by
+* provenance lines for framework + runtime versions:
+*
+*   FILE\t<rel-path>\t<sha256(file-bytes)>\n
+*   PROVENANCE\t<key>=<value>\n
+*
+* Sorted by line so the hash is deterministic across filesystems
+* (readdir order is not guaranteed).
+*
+* Provenance covers:
+*   - Cache layout schemaVersion (bumped when the cache format changes)
+*   - Nimbus framework version
+*   - Astro version (resolved from the project's installed copy)
+*   - Node major version (minor diffs occasionally affect bundling)
+*   - Platform + arch (some asset emission is platform-sensitive)
+*
+* Including provenance closes BUG-002 / BUG-003: a framework upgrade
+* (or Node bump, or OS change) silently changed rendered output but the
+* old global hash matched, so warm builds served stale entries from a
+* different version of the world.
+*/
+async function computeGlobalHash(projectRoot) {
+	const files = [];
+	for (const dir of TRACKED_DIRS) {
+		const abs = resolve(projectRoot, dir);
+		files.push(...await walk$1(abs, projectRoot));
+	}
+	for (const file of TRACKED_FILES) {
+		const abs = resolve(projectRoot, file);
+		try {
+			if ((await stat(abs)).isFile()) files.push(file);
+		} catch {}
+	}
+	files.sort();
+	const lines = [];
+	for (const rel of files) {
+		const bytes = await readFile(resolve(projectRoot, rel));
+		lines.push(`FILE\t${rel}\t${sha256Hex(bytes)}`);
+	}
+	const provenance = await readProvenance(projectRoot);
+	for (const [key, value] of Object.entries(provenance).sort(([a], [b]) => a.localeCompare(b))) lines.push(`PROVENANCE\t${key}=${value}`);
+	return sha256Hex(lines.join("\n"));
+}
+/** Cache layout version. Bump when the on-disk cache format changes
+*  incompatibly so old entries never get reused under new framework code. */
+const CACHE_SCHEMA_VERSION = "2";
+/**
+* Read versions from the project's installed deps + the runtime. All
+* lookups are best-effort: a missing package.json just gets recorded as
+* "unknown" so the hash still composes, and is still stable across
+* runs on the same machine.
+*/
+async function readProvenance(projectRoot) {
+	const out = {
+		schemaVersion: CACHE_SCHEMA_VERSION,
+		nodeMajor: process.versions.node.split(".")[0] ?? "unknown",
+		platform: process.platform,
+		arch: process.arch
+	};
+	out.nimbusVersion = await readDepVersion(projectRoot, "nimbus-docs");
+	out.astroVersion = await readDepVersion(projectRoot, "astro");
+	for (const key of TRACKED_ENV_KEYS) out[`env.${key}`] = process.env[key] ?? "";
+	for (const key of Object.keys(process.env).sort()) if (TRACKED_ENV_PREFIXES.some((p) => key.startsWith(p))) out[`env.${key}`] = process.env[key] ?? "";
+	return out;
+}
+const TRACKED_ENV_KEYS = [
+	"NODE_ENV",
+	"MODE",
+	"BASE_URL",
+	"SITE"
+];
+const TRACKED_ENV_PREFIXES = [
+	"PUBLIC_",
+	"VITE_PUBLIC_",
+	"ASTRO_"
+];
+async function readDepVersion(projectRoot, dep) {
+	try {
+		const bytes = await readFile(createRequire(resolve(projectRoot, "package.json")).resolve(`${dep}/package.json`), "utf8");
+		return JSON.parse(bytes).version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+/**
+* Phase 3 — per-page hash with transitive partial dependencies folded in.
+*
+* Same shape as `computePageHash` but additionally absorbs the bytes of
+* every partial the page transitively embeds. Sorted by path so two
+* builds with the same dependency set produce the same hash regardless
+* of discovery order.
+*
+* Paths are made *relative to projectRoot* before hashing — without this,
+* absolute paths like `/runner/work/run-N/...` change between CI runs
+* (ephemeral checkout dirs) and every page hash misses, neutralising the
+* cache. The path-in-hash detects rename-within-the-project; absolute
+* prefix differences across machines don't.
+*/
+function computePageHashWithPartials(pageBytes, globalHash, partialPaths, partialBytesByPath, projectRoot) {
+	const h = createHash("sha256");
+	h.update(globalHash);
+	h.update("\n");
+	h.update(pageBytes);
+	for (const absPath of partialPaths) {
+		const relPath = relative(projectRoot, absPath).split(sep).join("/");
+		const bytes = partialBytesByPath.get(absPath);
+		h.update("\0");
+		h.update(relPath);
+		h.update("\0");
+		if (bytes) h.update(bytes);
+	}
+	return h.digest("hex");
+}
+
+//#endregion
+//#region src/_internal/incremental/namespace.ts
+/**
+* Cache namespace resolution.
+*
+* Why: PR builds and main builds sharing a cache directory cross-contaminate
+* — a PR build can reuse stale entries written by main, and vice versa.
+* Without an explicit namespace, the only mitigation is `nimbus-docs clean`
+* between branches, which authors forget and CI doesn't enforce.
+*
+* Resolution order (first match wins):
+*
+*   1. `NIMBUS_CACHE_NAMESPACE` env var — explicit override for users who
+*      need a custom scheme (e.g. preview-vs-prod, or sharing one cache
+*      across multiple branches deliberately).
+*   2. `GITHUB_REF` — GitHub Actions sets this on every workflow run.
+*      `refs/heads/main`, `refs/pull/123/merge`, etc. Distinguishes PRs
+*      from main without any per-repo setup.
+*   3. Local git branch via `git rev-parse --abbrev-ref HEAD`.
+*   4. `"default"` — fallback for detached HEAD, non-git checkouts, or
+*      anything else the prior steps couldn't resolve.
+*
+* The resolved namespace lands in the manifest and is compared on warm
+* build. A mismatch is treated like a global-hash mismatch: full cold
+* rebuild, no per-page hit attempts.
+*
+* On-disk layout stays single-namespace (`.nimbus/cache/`). Switching
+* branches loses the prior namespace's cache; users running multi-branch
+* workflows can preserve per-branch cache via standard CI cache-key
+* conventions (`actions/cache` keyed on branch name).
+*/
+const execFileP = promisify(execFile);
+async function resolveCacheNamespace(projectRoot) {
+	const env = process.env.NIMBUS_CACHE_NAMESPACE?.trim();
+	if (env) return env;
+	const ghRef = process.env.GITHUB_REF?.trim();
+	if (ghRef) return ghRef;
+	try {
+		const { stdout } = await execFileP("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], {
+			cwd: projectRoot,
+			timeout: 2e3
+		});
+		const branch = stdout.trim();
+		if (branch && branch !== "HEAD") return branch;
+	} catch {}
+	return "default";
+}
+
+//#endregion
+//#region src/_internal/incremental/partial-refs.ts
+/**
+* Phase 3 — partial dependency tracking.
+*
+* Walks MDX content to find `<Render file="…" />` and `<Render slug="…" />`
+* references, then builds a per-page transitive closure: "pathname X
+* embeds partials A, B, C — where A in turn embeds D, and B in turn
+* embeds E and F." Folding all of those partials' bytes into the page's
+* hash gives us the property the spec promises: edit one partial, exactly
+* the pages that transitively embed it re-render.
+*
+* Scope (v1):
+*   - Only string-literal `file` / `slug` props get captured. Dynamic
+*     `file={var}` references aren't extractable from regex; partials
+*     reached that way will silently miss invalidation. Documented as a
+*     v1 limitation; the `partialResolver` hook (deferred) gives sites
+*     an escape valve.
+*   - Default resolver: `<Render file="topic/slug" />` resolves to
+*     `src/content/partials/topic/slug.mdx`. Matches the bench, apps/www,
+*     and mvvmm's PR shape for cloudflare-docs (their resolver also
+*     prepends a `product` prop — that needs a custom resolver).
+*   - Cycles in the partial graph are handled (visited set).
+*/
+/**
+* Check `candidate` is a normalised path under `rootWithSep`. Cheap
+* defense against `../` traversal escaping the partials root. We use a
+* trailing-sep marker on root to avoid false-matching `partialsRoot` with
+* `partialsRoot-evil/` style siblings.
+*/
+function isInside(candidate, rootWithSep) {
+	return candidate.startsWith(rootWithSep) || candidate === rootWithSep.slice(0, -1);
+}
+const COMPONENT_OPEN_RE = /<([A-Z][A-Za-z0-9_]*)\s+([^>]*?)\/?\s*>/g;
+const ATTR_RE = /([a-zA-Z][a-zA-Z0-9_]*)\s*=\s*["']([^"']*)["']/g;
+/**
+* Default partial resolver: `<Render file="topic/slug" />` (or `slug=`)
+* → `<projectRoot>/<partialsBase>/topic/slug.{mdx,md}`. Sites using a
+* different convention (multi-prop, parent product, etc.) pass their own
+* resolver via `nimbus(config, { partialResolver: ... })`.
+*
+* Extension handling:
+*   - The incoming `file`/`slug` value gets its `.mdx` or `.md` extension
+*     stripped so authors can write `<Render file="x.mdx" />` without
+*     producing `x.mdx.mdx`.
+*   - The resolver returns `.mdx` by default. The registry builder calls
+*     `resolvePartialPath` below to try `.mdx` first and fall back to
+*     `.md` if the `.mdx` file doesn't exist — handles sites that mix
+*     extensions or use plain Markdown for partials.
+*
+* `partialsBase` lets callers point the resolver at a non-default partials
+* collection base (closes BUG-040). Default: `src/content/partials`.
+*/
+function makeDefaultPartialResolver(projectRoot, partialsBase = "src/content/partials") {
+	const partialsRoot = resolve(projectRoot, partialsBase);
+	return (name, props) => {
+		if (name !== "Render") return null;
+		const id = props.file ?? props.slug;
+		if (!id) return null;
+		return resolve(partialsRoot, `${id.replace(/^\/+/, "").replace(/\.(mdx|md)$/, "")}.mdx`);
+	};
+}
+/**
+* Try a resolved partial path as `.mdx`, then fall back to `.md`. Returns
+* the path that actually exists on disk, or null. Used by the registry
+* builder so `.md` partials work even though the default resolver returns
+* `.mdx` for ergonomics.
+*/
+async function resolvePartialPath(candidatePath) {
+	try {
+		await stat(candidatePath);
+		return candidatePath;
+	} catch {
+		if (candidatePath.endsWith(".mdx")) {
+			const mdPath = candidatePath.slice(0, -4) + ".md";
+			try {
+				await stat(mdPath);
+				return mdPath;
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	}
+}
+/**
+* Extract every PascalCase component opening tag from MDX content along
+* with its string-literal props. Dynamic-value attributes (`file={var}`)
+* aren't extracted by design — they can't be statically analysed without
+* a full MDX AST pass.
+*/
+function extractComponentRefs(mdxContent) {
+	const refs = [];
+	for (const m of mdxContent.matchAll(COMPONENT_OPEN_RE)) {
+		const name = m[1];
+		const propsBlob = m[2] ?? "";
+		const props = {};
+		for (const am of propsBlob.matchAll(ATTR_RE)) props[am[1]] = am[2];
+		refs.push({
+			name,
+			props
+		});
+	}
+	return refs;
+}
+async function* walkPartials(partialsRoot) {
+	let entries;
+	try {
+		entries = await readdir(partialsRoot, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		const full = resolve(partialsRoot, entry.name);
+		if (entry.isDirectory()) yield* walkPartials(full);
+		else if (entry.isFile() && [".mdx", ".md"].includes(extname(entry.name))) yield full;
+	}
+}
+/**
+* Build the per-page transitive partial registry.
+*
+* Algorithm:
+*   1. Walk `src/content/partials/`, hash each file's bytes, record direct
+*      partial → partial references from its content.
+*   2. Topologically expand the partial → partial graph into a per-partial
+*      transitive-set map (with cycle protection).
+*   3. For each page, extract its direct partial refs, then union their
+*      transitive sets into the page's full transitive partial set.
+*/
+async function buildPartialRegistry(projectRoot, pageBytesByPathname, resolver, partialsBase = "src/content/partials") {
+	const partialsRoot = resolve(projectRoot, partialsBase);
+	const partialsRootWithSep = partialsRoot + sep;
+	const partialBytes = /* @__PURE__ */ new Map();
+	const partialDirectRefs = /* @__PURE__ */ new Map();
+	async function resolveWithFallback(name, props) {
+		const candidate = resolver(name, props);
+		if (!candidate) return null;
+		if (!isInside(candidate, partialsRootWithSep)) return null;
+		return resolvePartialPath(candidate);
+	}
+	for await (const filePath of walkPartials(partialsRoot)) {
+		const bytes = await readFile(filePath);
+		partialBytes.set(filePath, bytes);
+		const refs = extractComponentRefs(bytes.toString("utf8"));
+		const resolved = [];
+		for (const ref of refs) {
+			const r = await resolveWithFallback(ref.name, ref.props);
+			if (r) resolved.push(r);
+		}
+		partialDirectRefs.set(filePath, resolved);
+	}
+	const transitiveForPartial = /* @__PURE__ */ new Map();
+	function computeTransitive(start) {
+		const cached = transitiveForPartial.get(start);
+		if (cached) return cached;
+		const visited = /* @__PURE__ */ new Set();
+		const stack = [start];
+		while (stack.length > 0) {
+			const node = stack.pop();
+			if (visited.has(node)) continue;
+			visited.add(node);
+			const direct = partialDirectRefs.get(node) ?? [];
+			for (const d of direct) if (!visited.has(d)) stack.push(d);
+		}
+		transitiveForPartial.set(start, visited);
+		return visited;
+	}
+	for (const p of partialBytes.keys()) computeTransitive(p);
+	const transitiveByPathname = /* @__PURE__ */ new Map();
+	let pagesWithPartials = 0;
+	let totalTransitiveRefs = 0;
+	for (const [pathname, bytes] of pageBytesByPathname) {
+		const directRefs = extractComponentRefs(bytes.toString("utf8"));
+		if (directRefs.length === 0) {
+			transitiveByPathname.set(pathname, []);
+			continue;
+		}
+		const allTransitive = /* @__PURE__ */ new Set();
+		for (const ref of directRefs) {
+			const candidate = resolver(ref.name, ref.props);
+			if (!candidate) continue;
+			if (!isInside(candidate, partialsRootWithSep)) continue;
+			const resolved = await resolvePartialPath(candidate) ?? candidate;
+			const trans = transitiveForPartial.get(resolved);
+			if (trans) for (const t of trans) allTransitive.add(t);
+			else allTransitive.add(resolved);
+		}
+		const sorted = Array.from(allTransitive).sort();
+		transitiveByPathname.set(pathname, sorted);
+		if (sorted.length > 0) {
+			pagesWithPartials++;
+			totalTransitiveRefs += sorted.length;
+		}
+	}
+	return {
+		transitiveByPathname,
+		partialBytes,
+		stats: {
+			partialCount: partialBytes.size,
+			pagesWithPartials,
+			totalTransitiveRefs
+		}
+	};
+}
+/**
+* Best-effort: just confirms the partials directory is present. Used for
+* skipping the registry build when a site has no partials at all.
+*/
+async function partialsDirExists(projectRoot, partialsBase = "src/content/partials") {
+	try {
+		return (await stat(resolve(projectRoot, partialsBase))).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/_internal/incremental/index.ts
+/**
+* Incremental builds — Phase 2 MVP.
+*
+* Wires the cache layer into Astro's prerenderer. On warm build, pages whose
+* source bytes (and the global hash) haven't changed since the last build
+* return cached HTML directly from `prerenderer.render`; pages that did
+* change render normally and persist their output to the cache.
+*
+* Astro sees every route in `getStaticPaths` either way — cache hits flow
+* through `astro:build:generated`, adapter writers, route-headers accounting
+* exactly like fresh renders. This is the spec's design, *not* mvvmm's
+* `getStaticPaths`-filtering approach, because the latter hides cached
+* routes from downstream hooks.
+*
+* Anti-goals for this MVP (deferred to Phase 3+):
+*   - Partial-dependency tracking. Edit a partial → still full rebuild today.
+*   - Data-collection scoping.
+*   - Component-graph tracking. Any tracked-file change → full rebuild.
+*   - Provenance / namespacing / trust boundary. Hardening track.
+*   - `nimbus build --explain` and structured build reports. Console log only.
+*/
+/**
+* Normalise a request URL to its canonical pathname (no trailing slash,
+* except "/"). Astro builds use trailing-slash format by default; cache
+* keys are stripped so both shapes match.
+*/
+function canonicalisePathname(input) {
+	let p = input;
+	const q = p.indexOf("?");
+	if (q >= 0) p = p.slice(0, q);
+	const h = p.indexOf("#");
+	if (h >= 0) p = p.slice(0, h);
+	if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+	if (p.length === 0) p = "/";
+	return p;
+}
+/**
+* Build a map from pathname → MDX file bytes by walking the docs collection
+* directory. Phase 2 MVP only handles the primary `docs` collection.
+*
+* Pathname derivation: `src/content/docs/<entry.id>.mdx` → `/<entry.id>`,
+* mirroring `getDocsStaticPaths` which uses `entry.id` verbatim as slug.
+*/
+/**
+* Normalise whatever `parseCollectionBases` returned for a collection
+* into a projectRoot-relative folder spec. Handles three shapes the
+* user might write:
+*
+*   base: "shared"                  → src/content/shared
+*   base: "./src/content/shared"    → src/content/shared
+*   base: "/abs/path/to/partials"   → preserved (absolute)
+*
+* Falls back to `src/content/<defaultFolder>` if the input is empty.
+*/
+function resolveCollectionBase(projectRoot, raw, defaultFolder) {
+	if (!raw) return `src/content/${defaultFolder}`;
+	if (raw.startsWith("/")) return raw;
+	if (raw.includes("/")) return raw.replace(/^\.\/+/, "");
+	return `src/content/${raw}`;
+}
+/**
+* Pick between the derived collection base and a safe fallback by
+* checking which actually has matching `.mdx` / `.md` files on disk.
+* Protects against `parseCollectionBases` mis-attributing across
+* collections when users hand-roll `defineCollection({ loader:
+* glob({ base: "…" }) })` — the regex parser can't always tell which
+* `base:` belongs to which entry.
+*
+* Preference order:
+*   1. If derived === fallback, return either.
+*   2. If only one of (derived, fallback) has content, return that.
+*   3. If both have content, prefer fallback — the conventional path is
+*      more trustworthy than a regex-derived guess that could be wrong.
+*      Sites with intentionally non-default bases get matched in (2)
+*      because their default path doesn't exist.
+*   4. Neither has content: return derived (caller treats as absent).
+*/
+async function pickCollectionBase(projectRoot, derived, fallback) {
+	if (derived === fallback) return derived;
+	const derivedAbs = resolve(projectRoot, derived);
+	const fallbackAbs = resolve(projectRoot, fallback);
+	const derivedHas = await hasContent(derivedAbs);
+	const fallbackHas = await hasContent(fallbackAbs);
+	if (derivedHas && !fallbackHas) return derived;
+	if (!derivedHas && fallbackHas) return fallback;
+	if (derivedHas && fallbackHas) return fallback;
+	return derived;
+}
+async function hasContent(dir) {
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		for (const e of entries) {
+			if (e.isFile() && [".mdx", ".md"].includes(extname(e.name))) return true;
+			if (e.isDirectory()) {
+				if (await hasContent(resolve(dir, e.name))) return true;
+			}
+		}
+	} catch {
+		return false;
+	}
+	return false;
+}
+async function collectDocsPages(projectRoot, docsBase = "src/content/docs") {
+	const docsRoot = resolve(projectRoot, docsBase);
+	const bytesByPathname = /* @__PURE__ */ new Map();
+	const filePathByPathname = /* @__PURE__ */ new Map();
+	async function walk(dir) {
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const full = resolve(dir, entry.name);
+			if (entry.isDirectory()) await walk(full);
+			else if (entry.isFile() && [".mdx", ".md"].includes(extname(entry.name))) {
+				const bytes = await readFile(full);
+				const entryId = relative(docsRoot, full).split(sep).join("/").replace(/\.(mdx|md)$/, "");
+				const pathname = entryId === "index" ? "/index" : canonicalisePathname(canonicalEntryUrl("", entryId));
+				bytesByPathname.set(pathname, bytes);
+				filePathByPathname.set(pathname, full);
+			}
+		}
+	}
+	await walk(docsRoot);
+	return {
+		bytesByPathname,
+		filePathByPathname
+	};
+}
+/**
+* Set up the cache context for this build. Called at astro:build:start.
+* Computes per-page hashes, reads prior manifest, determines which pages
+* are cache-hits.
+*
+* Phase 3 — the page hash includes the bytes of every partial the page
+* transitively embeds, so editing a partial invalidates exactly the pages
+* that reference it (directly or transitively) and nothing else.
+*/
+async function setupIncrementalContext(projectRoot, logger, partialResolver) {
+	const cache = new Cache(projectRoot);
+	const globalHash = await computeGlobalHash(projectRoot);
+	const namespace = await resolveCacheNamespace(projectRoot);
+	const priorManifest = await cache.readManifest();
+	const bases = await parseCollectionBases(resolve(projectRoot, "src/content.config.ts"));
+	const { bytesByPathname, filePathByPathname } = await collectDocsPages(projectRoot, await pickCollectionBase(projectRoot, resolveCollectionBase(projectRoot, bases?.get("docs") ?? "docs", "docs"), "src/content/docs"));
+	const partialsBase = await pickCollectionBase(projectRoot, resolveCollectionBase(projectRoot, bases?.get("partials") ?? "partials", "partials"), "src/content/partials");
+	const resolver = partialResolver ?? makeDefaultPartialResolver(projectRoot, partialsBase);
+	const registry = await partialsDirExists(projectRoot, partialsBase) ? await buildPartialRegistry(projectRoot, bytesByPathname, resolver, partialsBase) : {
+		transitiveByPathname: /* @__PURE__ */ new Map(),
+		partialBytes: /* @__PURE__ */ new Map(),
+		stats: {
+			partialCount: 0,
+			pagesWithPartials: 0,
+			totalTransitiveRefs: 0
+		}
+	};
+	if (registry.stats.partialCount > 0) logger.info(`[incremental] partial registry: ${registry.stats.partialCount} partials, ${registry.stats.pagesWithPartials} pages reference at least one`);
+	const pageHashByPathname = /* @__PURE__ */ new Map();
+	for (const [pathname, bytes] of bytesByPathname) {
+		const transitive = registry.transitiveByPathname.get(pathname) ?? [];
+		pageHashByPathname.set(pathname, computePageHashWithPartials(bytes, globalHash, transitive, registry.partialBytes, projectRoot));
+	}
+	const cacheableHits = /* @__PURE__ */ new Set();
+	const namespaceChanged = priorManifest != null && priorManifest.namespace !== namespace;
+	const globalChanged = !priorManifest || priorManifest.globalHash !== globalHash;
+	if (!globalChanged && !namespaceChanged && priorManifest != null) {
+		for (const [pathname, hash] of pageHashByPathname) if (priorManifest.pages[pathname] === hash && await cache.hasPage(hash)) cacheableHits.add(pathname);
+	}
+	logger.info(`[incremental] cache namespace: ${namespace}`);
+	if (namespaceChanged) logger.info(`[incremental] namespace changed (${priorManifest.namespace} → ${namespace}) — full rebuild`);
+	else if (globalChanged) logger.info(priorManifest ? "[incremental] global hash changed — full rebuild" : "[incremental] no prior cache — full cold build");
+	else logger.info(`[incremental] ${cacheableHits.size} cache hits / ${pageHashByPathname.size} pages`);
+	const persistedHashes = /* @__PURE__ */ new Set();
+	for (const pathname of cacheableHits) {
+		const h = pageHashByPathname.get(pathname);
+		if (h) persistedHashes.add(h);
+	}
+	return {
+		namespace,
+		globalHash,
+		pageHashByPathname,
+		cacheableHits,
+		cache,
+		persistedHashes,
+		stats: {
+			hits: 0,
+			misses: 0,
+			persisted: 0
+		},
+		logger,
+		filePathByPathname
+	};
+}
+/**
+* Wrap an Astro prerenderer with the cache.
+*
+* Strategy (mvvmm-style — chosen empirically over the "wrap Response" approach
+* because Astro's per-route work outside `render` is the actual dominant cost,
+* not MDX→HTML conversion):
+*
+*   - `getStaticPaths` is filtered to dirty routes (cache misses) only.
+*     Cached routes never enter Astro's render pipeline — Astro skips their
+*     Vite bundling, their per-route emission overhead, everything.
+*   - `render` only sees dirty routes. It renders normally and persists the
+*     output to cache.
+*   - After the build, `restoreCachedPagesToDist` copies cached HTML into
+*     `dist/<pathname>/index.html` for the filtered cached routes — Astro
+*     never wrote them, so we do.
+*
+* Trade-off vs. the spec's "wrap Response in render" design: downstream
+* Astro hooks (`astro:build:generated`, adapter writers, route accounting)
+* don't see cached routes. For Cloudflare adapter sites or anything that
+* depends on every route being visible to those hooks, this matters.
+* For static SSG sites where the rendered HTML *is* the output, it's fine.
+* Documented as a limitation in Phase 5 user-facing notes.
+*/
+function wrapPrerenderer(defaultPrerenderer, ctx) {
+	return {
+		...defaultPrerenderer,
+		name: `${defaultPrerenderer.name}+nimbus-incremental`,
+		async getStaticPaths() {
+			const all = await defaultPrerenderer.getStaticPaths();
+			const dirty = all.filter((p) => !ctx.cacheableHits.has(canonicalisePathname(p.pathname)));
+			ctx.logger.info(`[incremental] filtered ${all.length - dirty.length} cached routes from render; ${dirty.length} to build`);
+			return dirty;
+		},
+		async render(request, opts) {
+			const pathname = canonicalisePathname(new URL(request.url).pathname);
+			const hash = ctx.pageHashByPathname.get(pathname);
+			ctx.stats.misses++;
+			const response = await defaultPrerenderer.render(request, opts);
+			if (hash && response.ok) try {
+				const text = await response.clone().text();
+				await ctx.cache.writePage(hash, text);
+				ctx.persistedHashes.add(hash);
+				ctx.stats.persisted++;
+			} catch (err) {
+				ctx.logger.warn(`[incremental] failed to persist ${pathname}: ${err.message}`);
+			}
+			return response;
+		}
+	};
+}
+/**
+* Copy cached HTML for filtered routes into `dist/`. Run at astro:build:done.
+*
+* Pathname → file mapping assumes `directory` build format (Astro default):
+*   `/foo/bar` → `dist/foo/bar/index.html`
+*   `/`       → `dist/index.html`
+*/
+async function restoreCachedPagesToDist(ctx, outDir) {
+	const astroDir = resolve(outDir, "_astro");
+	const restoredAssets = await ctx.cache.restoreAssets(astroDir, (path, err) => {
+		ctx.logger.warn(`[incremental] failed to restore asset ${path}: ${err.message}`);
+	});
+	if (restoredAssets > 0) ctx.logger.info(`[incremental] restored ${restoredAssets} cached asset files`);
+	const failedRestores = /* @__PURE__ */ new Set();
+	for (const pathname of ctx.cacheableHits) {
+		const hash = ctx.pageHashByPathname.get(pathname);
+		if (!hash) {
+			failedRestores.add(pathname);
+			continue;
+		}
+		const html = await ctx.cache.readPage(hash);
+		if (html === null) {
+			ctx.logger.warn(`[incremental] cached file missing for ${pathname} (hash ${hash.slice(0, 8)}) — dropping from output`);
+			failedRestores.add(pathname);
+			ctx.persistedHashes.delete(hash);
+			continue;
+		}
+		const target = resolve(outDir, pathname === "/" ? "index.html" : `${pathname.slice(1)}/index.html`);
+		try {
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, html, "utf8");
+			ctx.stats.hits++;
+		} catch (err) {
+			ctx.logger.warn(`[incremental] failed to restore ${pathname}: ${err.message}`);
+			failedRestores.add(pathname);
+			ctx.persistedHashes.delete(hash);
+		}
+	}
+	for (const failed of failedRestores) ctx.cacheableHits.delete(failed);
+}
+/**
+* Snapshot the just-built `dist/_astro/` into the cache so future warm
+* builds can restore asset bundles that this build's HTML references.
+*
+* Called at astro:build:done, AFTER any restored bundles have been placed
+* (so the snapshot is the union of fresh + previously-cached assets the
+* cached HTML still references).
+*
+* BUG-007 fix: bounded to assets actually referenced by cached HTML. We
+* walk every cached page's bytes, regex-extract `/_astro/...` URLs,
+* dedupe — and only persist those. Without this the snapshot grew
+* unboundedly because vite produces new bundle hashes on every warm
+* build (different module graph → different chunks).
+*/
+async function snapshotAssetsToCache(ctx, outDir) {
+	const astroDir = resolve(outDir, "_astro");
+	const referencedRelPaths = await collectReferencedAssets(ctx, outDir);
+	const n = await ctx.cache.snapshotAssets(astroDir, referencedRelPaths);
+	if (n > 0) ctx.logger.info(`[incremental] snapshotted ${n} referenced asset files to cache`);
+}
+const ASSET_REF_RE = /\/_astro\/([^"')\s>]+)/g;
+/**
+* Strip query string and hash from an extracted asset path. Without
+* this, `/_astro/foo.js?v=1` would record `foo.js?v=1` as the file
+* name — the snapshot would skip it because no such file exists in
+* `_astro/`, leaving the warm build with a broken reference (BUG-108).
+*/
+function normaliseAssetRef(raw) {
+	if (!raw) return null;
+	const q = raw.indexOf("?");
+	const h = raw.indexOf("#");
+	let end = raw.length;
+	if (q >= 0 && q < end) end = q;
+	if (h >= 0 && h < end) end = h;
+	const path = raw.slice(0, end);
+	return path.length > 0 ? path : null;
+}
+/**
+* Scan every cached HTML page on disk for `/_astro/...` references.
+* Returns the set of rel-paths (e.g. `BaseLayout.C1SNDqdc.css`) every
+* cache hit will need restored on future warm builds. Used to bound the
+* asset snapshot.
+*
+* The single regex matches `/_astro/...` anywhere in the HTML —
+* straightforward for `href="..."`, `src="..."`, `url(...)` in inline
+* styles, and individual `srcset` URLs alike. (BUG-107 was about the
+* earlier regex anchoring on a quote/paren prefix and missing the
+* second+nth URL inside a `srcset` value; the unanchored form here
+* catches them all.)
+*
+* We scan the dist output rather than the in-memory cache because dist
+* is the source of truth for what's currently referenced — after the
+* cached pages have been restored and fresh pages emitted, dist's HTML
+* collectively references every asset any warm build will need.
+*/
+async function collectReferencedAssets(ctx, outDir) {
+	const refs = /* @__PURE__ */ new Set();
+	for (const [pathname, hash] of ctx.pageHashByPathname) {
+		if (!ctx.persistedHashes.has(hash)) continue;
+		const target = resolve(outDir, pathname === "/" ? "index.html" : `${pathname.slice(1)}/index.html`);
+		let content;
+		try {
+			content = await readFile(target, "utf8");
+		} catch {
+			continue;
+		}
+		for (const m of content.matchAll(ASSET_REF_RE)) {
+			const path = normaliseAssetRef(m[1] ?? "");
+			if (path) refs.add(path);
+		}
+	}
+	return refs;
+}
+/**
+* Write the updated manifest. Called at astro:build:done.
+*/
+async function finaliseIncrementalContext(ctx) {
+	const pages = {};
+	for (const [pathname, hash] of ctx.pageHashByPathname) if (ctx.persistedHashes.has(hash)) pages[pathname] = hash;
+	await ctx.cache.writeManifest({
+		namespace: ctx.namespace,
+		globalHash: ctx.globalHash,
+		pages
+	});
+	ctx.logger.info(`[incremental] ${ctx.stats.hits} hits, ${ctx.stats.misses} misses, ${ctx.stats.persisted} persisted`);
+}
+
+//#endregion
+//#region src/_internal/incremental/mdx-skip-plugin.ts
+const VIRTUAL_PREFIX = "\0nimbus-stub:";
+const STUB_MODULE = `// nimbus-incremental: cached entry stub. Layer 3 ensures this is dead code.
+export const frontmatter = {};
+export const headings = [];
+export const file = "";
+export const url = undefined;
+export const rawContent = () => "";
+export const compiledContent = () => "";
+export function Content() { return null; }
+export default Content;
+`;
+function createMdxSkipContext() {
+	return {
+		cachedAbsolutePaths: /* @__PURE__ */ new Set(),
+		enabled: false
+	};
+}
+function mdxSkipPlugin(ctx) {
+	return {
+		name: "nimbus-incremental-mdx-skip",
+		enforce: "pre",
+		async resolveId(source, importer, options) {
+			if (!ctx.enabled) return null;
+			if (!source.endsWith(".mdx")) return null;
+			const resolved = await this.resolve(source, importer, {
+				...options,
+				skipSelf: true
+			});
+			if (!resolved || resolved.external) return resolved;
+			const absPath = resolved.id.split("?")[0];
+			if (ctx.cachedAbsolutePaths.has(absPath)) return `${VIRTUAL_PREFIX}${absPath.replace(/\.mdx$/, ".cached.js")}`;
+			return resolved;
+		},
+		load(id) {
+			if (id.startsWith(VIRTUAL_PREFIX)) return STUB_MODULE;
+			return null;
+		}
+	};
+}
+
+//#endregion
+//#region src/_internal/incremental/sitemap.ts
+/**
+* Layer 4 — sitemap emission.
+*
+* When incremental builds are on, the cache layer filters cached routes
+* from Astro's render pipeline. Downstream integrations that hook
+* `astro:build:done` (including `@astrojs/sitemap`) only see the dirty
+* subset in their `pages` argument. The sitemap they emit is missing all
+* cached routes — broken on every warm build.
+*
+* Fix: don't register `@astrojs/sitemap` at all when incremental is on.
+* Instead, this module emits the sitemap directly from the union of
+* (Astro's `pages` arg) and (incrementalCtx's cached pathnames).
+*
+* Output is **structurally compatible** with `@astrojs/sitemap`'s default
+* output — same xmlns set, same element shape, same sorted-URL invariant
+* — but isn't bit-identical to the upstream emitter. Specifically:
+*
+*   - XML entity escaping uses `&apos;` for single quotes where upstream
+*     uses `&#39;`. Functionally identical; lexically different.
+*   - `@astrojs/sitemap` adds an XML declaration newline upstream's
+*     serializer happens to insert; we don't.
+*
+* The shape that DOES hold across cold and warm builds of *this*
+* emitter is byte-identical (same URL set, same sort, same escape
+* table). Cold-vs-warm parity is the property the cache layer needs;
+* upstream-byte-parity is only relevant for sites comparing against
+* a non-incremental build of `@astrojs/sitemap`.
+*
+* Format details:
+*   - One line, no whitespace between elements
+*   - URLs sorted alphabetically by absolute URL
+*   - Directory-format trailing slash (`/foo/` not `/foo`)
+*   - xmlns declarations matching @astrojs/sitemap's set
+*   - sitemap-0.xml carries all entries (we don't split until >45k urls)
+*   - sitemap-index.xml lists sitemap-0.xml only
+*
+* v1 scope — no custom `serialize` yet (deferred; cloudflare-docs case),
+* no `lastmod`, `changefreq`, `priority`, no image/video sitemaps. Matches
+* `@astrojs/sitemap` *default* output for sites that don't override.
+*/
+const URLSET_XMLNS = "xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:news=\"http://www.google.com/schemas/sitemap-news/0.9\" xmlns:xhtml=\"http://www.w3.org/1999/xhtml\" xmlns:image=\"http://www.google.com/schemas/sitemap-image/1.1\" xmlns:video=\"http://www.google.com/schemas/sitemap-video/1.1\"";
+function trimTrailingSlash(s) {
+	return s.endsWith("/") && s.length > 1 ? s.slice(0, -1) : s;
+}
+function ensureTrailingSlash(s) {
+	return s.endsWith("/") ? s : s + "/";
+}
+function xmlEscape(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
+* Build the canonical URL set. Astro's `pages` arg gives us pathnames as
+* `foo/bar/` style (already trailing-slash for directory format). The
+* cached pathnames from the incremental context are canonical-form
+* (no trailing slash). Normalise both, dedupe, sort.
+*/
+function buildUrlSet(opts) {
+	const siteRoot = trimTrailingSlash(opts.siteUrl);
+	const base = opts.base ? trimTrailingSlash(opts.base) : "";
+	const pathnames = /* @__PURE__ */ new Set();
+	for (const page of opts.builtPages) {
+		const path = ensureTrailingSlash("/" + page.pathname.replace(/^\/+/, ""));
+		pathnames.add(`${siteRoot}${base}${path}`);
+	}
+	for (const cached of opts.cachedPathnames) {
+		const withSlash = cached === "/" ? "/" : ensureTrailingSlash(cached);
+		pathnames.add(`${siteRoot}${base}${withSlash}`);
+	}
+	return Array.from(pathnames).sort();
+}
+function renderItem(item) {
+	let inner = `<loc>${xmlEscape(item.url)}</loc>`;
+	if (item.lastmod !== void 0) inner += `<lastmod>${xmlEscape(item.lastmod)}</lastmod>`;
+	if (item.changefreq !== void 0) inner += `<changefreq>${xmlEscape(item.changefreq)}</changefreq>`;
+	if (item.priority !== void 0) inner += `<priority>${item.priority}</priority>`;
+	if (item.links && item.links.length > 0) for (const link of item.links) inner += `<xhtml:link rel="alternate" hreflang="${xmlEscape(link.lang)}" href="${xmlEscape(link.url)}"/>`;
+	return `<url>${inner}</url>`;
+}
+async function emitIncrementalSitemap(opts) {
+	const urls = buildUrlSet(opts);
+	if (opts.customPages) for (const extra of opts.customPages) urls.push(extra);
+	if (urls.length === 0) return { urlCount: 0 };
+	urls.sort();
+	const items = [];
+	for (const url of urls) {
+		let item = { url };
+		if (opts.serialize) item = await opts.serialize(item);
+		if (item) items.push(item);
+	}
+	const sitemap0 = `<?xml version="1.0" encoding="UTF-8"?><urlset ${URLSET_XMLNS}>${items.map(renderItem).join("")}</urlset>`;
+	const sitemapIndex = `<?xml version="1.0" encoding="UTF-8"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><sitemap><loc>${xmlEscape(`${trimTrailingSlash(opts.siteUrl)}${opts.base ? trimTrailingSlash(opts.base) : ""}/sitemap-0.xml`)}</loc></sitemap></sitemapindex>`;
+	await mkdir(opts.distDir, { recursive: true });
+	await writeFile(resolve(opts.distDir, "sitemap-0.xml"), sitemap0, "utf8");
+	await writeFile(resolve(opts.distDir, "sitemap-index.xml"), sitemapIndex, "utf8");
+	return { urlCount: items.length };
+}
+
 //#endregion
 //#region src/_internal/scan-version-frontmatter.ts
 /**
@@ -2326,6 +3774,17 @@ function pageUrl(versions, version, slug) {
 * Planned (not shipped):
 *   - `/llms.txt` and `/robots.txt` route injection.
 */
+/**
+* Common shorthand fences that Shiki doesn't recognise out of the box.
+* Hoisted to module scope so the code-block-language scanner can apply
+* the same mapping before passing the result to `shikiConfig.langs`.
+* Users can extend via Astro's shallow merge of `markdown.shikiConfig`.
+*/
+const SHIKI_LANG_ALIAS = {
+	curl: "bash",
+	console: "bash",
+	shellsession: "shellscript"
+};
 function nimbus(rawConfig, options = {}) {
 	const config = validateNimbusConfig(rawConfig);
 	const lintOptions = validateLintOptions({
@@ -2334,6 +3793,8 @@ function nimbus(rawConfig, options = {}) {
 	}, IMPLEMENTED_CODES);
 	let projectRootForBuild = "";
 	let astroBaseForBuild = "";
+	let incrementalCtx = null;
+	const mdxSkipCtx = createMdxSkipContext();
 	return {
 		name: "nimbus-docs",
 		hooks: {
@@ -2362,6 +3823,7 @@ function nimbus(rawConfig, options = {}) {
 				const projectRoot = fileURLToPath(astroConfig.root);
 				projectRootForBuild = projectRoot;
 				astroBaseForBuild = astroConfig.base ?? "";
+				const codeBlockLangs = await scanCodeBlockLanguages(projectRoot, SHIKI_LANG_ALIAS);
 				const contentConfigPath = path.join(projectRoot, "src/content.config.ts");
 				const rawCollections = await parseContentCollections(contentConfigPath);
 				const collectionBases = await parseCollectionBases(contentConfigPath);
@@ -2408,26 +3870,48 @@ function nimbus(rawConfig, options = {}) {
 					versionRedirects = computeMissingPageRedirects(resolved, versionAlternates, versionEntries);
 				}
 				integrationsToAdd.push(mdx(options.mdx ?? {}));
-				if (options.sitemap !== false && Boolean(config.site)) integrationsToAdd.push(sitemap());
+				const wantSitemap = options.sitemap !== false && Boolean(config.site);
+				const sitemapOpts = typeof options.sitemap === "object" ? options.sitemap : void 0;
+				if (wantSitemap && !options.incrementalBuilds) integrationsToAdd.push(sitemap({
+					...sitemapOpts?.serialize && { serialize: sitemapOpts.serialize },
+					...sitemapOpts?.customPages && { customPages: sitemapOpts.customPages }
+				}));
+				const admonitionVitePlugins = [];
+				if (options.admonitions !== false) {
+					const admoOpts = typeof options.admonitions === "object" ? options.admonitions : {};
+					const projectRoot = fileURLToPath(astroConfig.root);
+					const contentDirs = (admoOpts.contentDirs ?? ["src/content"]).map((d) => path.isAbsolute(d) ? d : path.join(projectRoot, d));
+					admonitionVitePlugins.push(admonitionPlugin({
+						contentDirs,
+						typeAliases: admoOpts.typeAliases,
+						skip: admoOpts.skip
+					}));
+				}
 				updateConfig({
 					...config.site ? { site: config.site } : {},
 					integrations: integrationsToAdd,
 					markdown: {
-						processor: satteri(),
+						processor: options.markdown?.processor ?? satteri(),
 						shikiConfig: {
 							themes: {
 								light: "github-light",
 								dark: "github-dark"
 							},
 							defaultColor: false,
-							transformers: defaultCodeTransformers()
+							transformers: defaultCodeTransformers(),
+							langAlias: SHIKI_LANG_ALIAS,
+							langs: codeBlockLangs
 						}
 					},
 					...versionRedirects.length > 0 ? { redirects: Object.fromEntries(versionRedirects.map(({ from, to }) => [from, to])) } : {},
-					vite: { plugins: [virtualConfigPlugin(config, {
-						indexedCollections,
-						versionAlternates
-					})] }
+					vite: { plugins: [
+						...admonitionVitePlugins,
+						virtualConfigPlugin(config, {
+							indexedCollections,
+							versionAlternates
+						}),
+						...options.incrementalBuilds ? [mdxSkipPlugin(mdxSkipCtx)] : []
+					] }
 				});
 			},
 			"astro:config:done": ({ injectTypes }) => {
@@ -2446,10 +3930,61 @@ function nimbus(rawConfig, options = {}) {
 					].join("\n")
 				});
 			},
+			"astro:build:start": async ({ setPrerenderer, logger }) => {
+				if (!options.incrementalBuilds) return;
+				if (!projectRootForBuild) {
+					logger.warn("[incremental] project root unknown at build:start; cache disabled this run");
+					return;
+				}
+				incrementalCtx = await setupIncrementalContext(projectRootForBuild, logger, options.partialResolver);
+				mdxSkipCtx.cachedAbsolutePaths.clear();
+				for (const pathname of incrementalCtx.cacheableHits) {
+					const filePath = incrementalCtx.filePathByPathname.get(pathname);
+					if (filePath) mdxSkipCtx.cachedAbsolutePaths.add(filePath);
+				}
+				mdxSkipCtx.enabled = true;
+				logger.info(`[incremental] mdx-skip plugin armed for ${mdxSkipCtx.cachedAbsolutePaths.size} cached MDX files`);
+				setPrerenderer((defaultPrerenderer) => wrapPrerenderer(defaultPrerenderer, incrementalCtx));
+			},
 			"astro:build:done": async ({ dir, pages, logger }) => {
-				materializeRouteTruthFromPages(projectRootForBuild, astroBaseForBuild, pages, logger);
-				if (config.search === false || config.search?.provider === "custom") return;
-				await runPagefind(fileURLToPath(dir));
+				if (incrementalCtx) {
+					const distDir = fileURLToPath(dir);
+					await restoreCachedPagesToDist(incrementalCtx, distDir);
+					const fullPagesForTruth = [...pages, ...[...incrementalCtx.cacheableHits].filter((p) => !pages.some((q) => "/" + q.pathname === (p === "/" ? "/" : p + "/"))).map((p) => ({ pathname: p === "/" ? "" : p.slice(1) + "/" }))];
+					materializeRouteTruthFromPages(projectRootForBuild, astroBaseForBuild, fullPagesForTruth, logger);
+					if (options.sitemap !== false && config.site) {
+						const sitemapOptsResolved = typeof options.sitemap === "object" ? options.sitemap : void 0;
+						const result = await emitIncrementalSitemap({
+							siteUrl: config.site,
+							builtPages: pages,
+							cachedPathnames: incrementalCtx.cacheableHits,
+							distDir,
+							base: astroBaseForBuild,
+							serialize: sitemapOptsResolved?.serialize,
+							customPages: sitemapOptsResolved?.customPages
+						});
+						logger.info(`[incremental] sitemap emitted (${result.urlCount} urls)`);
+					}
+					await snapshotAssetsToCache(incrementalCtx, distDir);
+					await finaliseIncrementalContext(incrementalCtx);
+				} else materializeRouteTruthFromPages(projectRootForBuild, astroBaseForBuild, pages, logger);
+				if (config.search === false || config.search?.provider === "custom") {
+					incrementalCtx = null;
+					return;
+				}
+				const distDir = fileURLToPath(dir);
+				const pagefindDistDir = path.join(distDir, "pagefind");
+				if (incrementalCtx !== null && incrementalCtx.stats.misses === 0 && await incrementalCtx.cache.hasPagefindSnapshot()) {
+					const restored = await incrementalCtx.cache.restorePagefind(pagefindDistDir);
+					logger.info(`[incremental] Pagefind skipped — restored ${restored} cached index file(s)`);
+				} else {
+					await runPagefind(distDir);
+					if (incrementalCtx) {
+						const snapped = await incrementalCtx.cache.snapshotPagefind(pagefindDistDir);
+						if (snapped > 0) logger.info(`[incremental] snapshotted ${snapped} Pagefind index file(s) to cache`);
+					}
+				}
+				incrementalCtx = null;
 			}
 		}
 	};