nimbus-docs 0.1.8 → 0.1.10

package/dist/index.js

@@ -1,16 +1,18 @@
-import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-B7o0k3TA.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;
@@ -165,6 +167,7 @@ function canonicalEntryUrl(prefix, entryId) {
 //#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;
@@ -251,7 +254,11 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 		const groupsAtLevel = /* @__PURE__ */ new Map();
 		if (directory && parentPath === directory) {
 			const dirIndex = byId.get(directory);
-			if (dirIndex) result.push(createLink(dirIndex, currentPath, hrefPrefix));
+			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;
@@ -562,7 +569,8 @@ function applyDefaultCollapsed(items) {
 * never holds, so this silently returns the input unchanged.
 */
 function applyOverviewLabel(items, label) {
-	for (const item of items) if (item.type === "group") {
+	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;
@@ -1826,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);
@@ -1855,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;
@@ -1935,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)).replace(/=\s*"[^"\n]*"/g, (m) => "=" + " ".repeat(m.length - 1)).replace(/=\s*'[^'\n]*'/g, (m) => "=" + " ".repeat(m.length - 1));
+	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
@@ -1945,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;
 }
 /**
@@ -2115,6 +2127,1275 @@ 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;
+	/**
+	* @param root Absolute path to the cache directory. Callers resolve this —
+	*   by default the incremental layer roots it under Astro's own `cacheDir`
+	*   (`node_modules/.astro/nimbus`) so it travels with the framework cache
+	*   every host already persists between builds (Cloudflare, Vercel,
+	*   Netlify, GitHub Actions). Falls back to `<projectRoot>/.nimbus/cache`.
+	*/
+	constructor(root) {
+		this.root = root;
+	}
+	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, cacheDir, logger, partialResolver) {
+	const cache = new Cache(cacheDir ? resolve(cacheDir, "nimbus") : resolve(projectRoot, ".nimbus/cache"));
+	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
 /**
@@ -2500,6 +3781,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({
@@ -2507,7 +3799,10 @@ function nimbus(rawConfig, options = {}) {
 		collections: options.collections
 	}, IMPLEMENTED_CODES);
 	let projectRootForBuild = "";
+	let cacheDirForBuild = "";
 	let astroBaseForBuild = "";
+	let incrementalCtx = null;
+	const mdxSkipCtx = createMdxSkipContext();
 	return {
 		name: "nimbus-docs",
 		hooks: {
@@ -2535,7 +3830,9 @@ function nimbus(rawConfig, options = {}) {
 				}
 				const projectRoot = fileURLToPath(astroConfig.root);
 				projectRootForBuild = projectRoot;
+				cacheDirForBuild = fileURLToPath(astroConfig.cacheDir);
 				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);
@@ -2582,7 +3879,12 @@ 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 : {};
@@ -2606,18 +3908,19 @@ function nimbus(rawConfig, options = {}) {
 							},
 							defaultColor: false,
 							transformers: defaultCodeTransformers(),
-							langAlias: {
-								curl: "bash",
-								console: "bash",
-								shellsession: "shellscript"
-							}
+							langAlias: SHIKI_LANG_ALIAS,
+							langs: codeBlockLangs
 						}
 					},
 					...versionRedirects.length > 0 ? { redirects: Object.fromEntries(versionRedirects.map(({ from, to }) => [from, to])) } : {},
-					vite: { plugins: [...admonitionVitePlugins, virtualConfigPlugin(config, {
-						indexedCollections,
-						versionAlternates
-					})] }
+					vite: { plugins: [
+						...admonitionVitePlugins,
+						virtualConfigPlugin(config, {
+							indexedCollections,
+							versionAlternates
+						}),
+						...options.incrementalBuilds ? [mdxSkipPlugin(mdxSkipCtx)] : []
+					] }
 				});
 			},
 			"astro:config:done": ({ injectTypes }) => {
@@ -2636,10 +3939,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, cacheDirForBuild || void 0, 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;
 			}
 		}
 	};