nimbus-docs 0.1.10 → 0.1.12

package/dist/index.js

@@ -1,4 +1,4 @@
-import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-DDDvKkyJ.js";
+import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-CzB-afEb.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";
@@ -11,7 +11,7 @@ import { satteri } from "@astrojs/markdown-satteri";
 import sitemap from "@astrojs/sitemap";
 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 { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight } from "@shikijs/transformers";
 import { createHash } from "node:crypto";
 
 //#region src/_internal/runtime-config.ts
@@ -118,28 +118,16 @@ function slug(value, maintainCase) {
 * Mirror of Astro's content-layer slug normalization, used by every
 * framework URL builder that derives a URL from an `entry.id`.
 *
-* Astro's `glob` content loader (used by Nimbus's `docsCollection` /
-* `partialsCollection` factories) runs each path segment through
+* Astro's `glob` content loader runs each path segment through
 * `github-slugger.slug()` and strips a trailing `/index`. That output is
-* what `entry.id` becomes inside `getCollection`, and it's what `params.slug`
-* substitutes into `[...slug].astro` routes. Anything that constructs a
-* URL from the raw filesystem path *must* apply the same normalization or
-* the URL won't match what Astro actually serves.
-*
-* Why mirror instead of asking Astro: framework URL builders run at page
-* render time (sidebar hrefs) and during the integration's
-* `astro:config:setup` (sitemap, llms.txt). At neither point do we have a
-* clean way to read Astro's resolved routes. The honest architectural fix
-* is to refactor those builders to consume the route manifest at
-* `astro:routes:resolved` (sitemap/llms) or via a build-emitted lookup
-* table (sidebar). Until that work lands, this helper keeps the URLs
-* correct.
-*
-* Mirror caveat: this matches `github-slugger.slug()` and the trailing-
-* /index strip — the documented public-library behaviors Astro inherits
-* — not Astro's private routing internals. If a user supplies a custom
-* `generateId` to the content loader, or a `data.slug` override in
-* frontmatter, this helper doesn't see it. Both are uncommon.
+* what `entry.id` becomes and what `params.slug` substitutes into
+* `[...slug].astro` routes, so anything building a URL from the raw
+* filesystem path must apply the same normalization to match what Astro
+* serves.
+*
+* Caveat: this matches `github-slugger.slug()` and the trailing-/index
+* strip, not a custom loader `generateId` or a `data.slug` frontmatter
+* override — neither of which this helper sees.
 */
 /** Canonicalize one entry id the way Astro's content layer does. */
 function canonicalSlug(entryId) {
@@ -431,6 +419,13 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 				badge: item.badge,
 				children
 			};
+			const landing = item.landing;
+			const segment = item.segment;
+			if (segment !== void 0) group.segment = segment;
+			if (landing !== void 0) {
+				group.indexHref = toBrowserHref(landing);
+				group.indexIsCurrent = toRouteKey(currentPath) === toRouteKey(landing) || void 0;
+			}
 			result.push(group);
 		}
 	}
@@ -471,6 +466,70 @@ function scopeToCurrentSection(items, currentPath) {
 	}
 	return items;
 }
+/**
+* Return the ancestor chain from the top of the tree to the node that owns
+* `currentPath` (inclusive). Matches by route key, so a chain can be
+* resolved for any path (e.g. a catalog route's section) regardless of the
+* page the tree was built for. A group that only *contains* the match is
+* included with no href (a non-interactive crumb). Returns `[]` on no match.
+*/
+function findActivePath(items, currentPath) {
+	const key = toRouteKey(currentPath);
+	function search(nodes) {
+		for (const item of nodes) if (item.type === "link") {
+			if (toRouteKey(item.href) === key) return [item];
+		} else if (item.type === "group") {
+			if (item.indexHref && !item.indexIsExternal && toRouteKey(item.indexHref) === key) return [item];
+			const childPath = search(item.children);
+			if (childPath) return [item, ...childPath];
+		}
+		return null;
+	}
+	return search(items) ?? [];
+}
+/**
+* Descend a section-scoped tree to the sub-tree under the current path's
+* boundary. A glob like `"guides/*"` (`*` = one segment) sets the prefix
+* depth; the rail is replaced by the children of the shallowest group
+* fully contained under that prefix. Matching is by descendant href, so it
+* works for index-less section folders. Returns the input unchanged on no
+* match.
+*/
+function isolateToBoundary(items, currentPath, boundaries) {
+	const segs = toRouteKey(currentPath).split("/").filter(Boolean);
+	for (const glob of boundaries) {
+		const globSegs = glob.split("/").filter(Boolean);
+		if (segs.length < globSegs.length || globSegs.length === 0) continue;
+		if (!globSegs.every((g, i) => g === "*" || g === segs[i])) continue;
+		const group = findBoundaryGroup(items, toBrowserHref("/" + segs.slice(0, globSegs.length).join("/")));
+		if (group) return group.children;
+	}
+	return items;
+}
+/** Shallowest group whose every flattened descendant href is under `prefix`. */
+function findBoundaryGroup(items, prefix) {
+	for (const item of items) {
+		if (item.type !== "group") continue;
+		const flat = flattenSidebar([item]);
+		if (flat.length > 0 && flat.every((l) => l.href.startsWith(prefix))) return item;
+		const nested = findBoundaryGroup(item.children, prefix);
+		if (nested) return nested;
+	}
+}
+/**
+* Context for the `getSidebar` transform: `sectionSlug` (seg0), `module`
+* (seg1), and `indexEntryId` — the landing entry id of the first group on
+* the active path, or `undefined` for an index-less section.
+*/
+function deriveTransformCtx(fullTree, currentSlug) {
+	const segs = currentSlug.split("/").filter(Boolean);
+	const sectionGroup = findActivePath(fullTree, currentSlug).find((n) => n.type === "group");
+	return {
+		sectionSlug: segs[0] ?? "",
+		module: segs[1],
+		indexEntryId: sectionGroup?._indexId
+	};
+}
 function hasActivePage(item, currentPath) {
 	if (item.type === "link") return item.isCurrent === true;
 	if (item.type === "external") return false;
@@ -489,12 +548,9 @@ function hasActivePage(item, currentPath) {
 * 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.
+* Sub-directories of the primary collection (`wip/`, `lab/`, etc.) are
+* deliberately excluded — the header rail is for cross-collection
+* navigation; sub-sections belong in the sidebar's own tree.
 *
 * Caller must pass the *un-scoped* tree (the result of
 * `buildSidebarTree`, not `getSidebar`); otherwise only the current
@@ -557,16 +613,13 @@ function applyDefaultCollapsed(items) {
 	}
 }
 /**
-* @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.
+* Relabel a section's landing link to the `overviewLabel` string (default
+* "Overview"). Applies to a `directory:` autogenerate's leading landing
+* link wherever it surfaces (tracked via `directoryIndexLinks`), and to a
+* group whose first child link IS the group's own index (matched via the
+* `sortKeyByItem` WeakMap). Config groups expose their index as the group
+* label itself (`SidebarGroupItem.indexHref`), so those aren't relabelled
+* here — there's no separate child link to rename.
 */
 function applyOverviewLabel(items, label) {
 	for (const item of items) if (item.type === "link" && directoryIndexLinks.has(item)) item.label = label;
@@ -599,7 +652,8 @@ function processHideChildren(items, entries) {
 				continue;
 			}
 			if (item._indexId && item.indexHref) {
-				if (entryById.get(item._indexId)?.data.sidebar?.hideChildren) {
+				const entry = entryById.get(item._indexId);
+				if (entry?.data.sidebar?.hideChildren || entry?.data.hideChildren) {
 					const replacement = item.indexIsExternal ? {
 						type: "external",
 						label: item.label,
@@ -889,7 +943,68 @@ function renderEntryAsMarkdown(entry, options = {}) {
 
 //#endregion
 //#region src/_internal/navigation.ts
-function getBreadcrumbs$1(slug, homeLabel = "Home") {
+/**
+* The in-site href a node links to, or `undefined` for a non-interactive
+* crumb (index-less groups and off-site landings).
+*/
+function nodeHref(node) {
+	if (node.type === "link") return node.href;
+	if (node.type === "external") return void 0;
+	return node.indexIsExternal ? void 0 : node.indexHref;
+}
+/**
+* Build the trail from the root crumb and per-node labels. `labels[i]`
+* pairs with `path[i]`: `null` drops the crumb, `undefined` keeps the
+* node label. Deduplicated by href (first wins); hrefless crumbs are
+* never merged.
+*/
+function assembleBreadcrumbs(root, path, labels) {
+	const crumbs = [{
+		label: root.label,
+		href: root.href
+	}];
+	path.forEach((node, i) => {
+		const override = labels[i];
+		if (override === null) return;
+		const label = override ?? node.label;
+		const href = nodeHref(node);
+		crumbs.push(href ? {
+			label,
+			href
+		} : { label });
+	});
+	const seen = /* @__PURE__ */ new Set();
+	return crumbs.filter((c) => {
+		if (c.href === void 0) return true;
+		if (seen.has(c.href)) return false;
+		seen.add(c.href);
+		return true;
+	});
+}
+/**
+* Append `trail` items to a section's ancestry crumbs (a leaf with no
+* `href` is the current page) and deduplicate by href, so a trail crumb
+* that repeats an ancestry crumb's URL collapses to one (first wins). The
+* pure core of `getRouteNavigation`.
+*/
+function composeRouteBreadcrumbs(sectionCrumbs, trail) {
+	const combined = [...sectionCrumbs, ...trail.map((t) => t.href ? {
+		label: t.label,
+		href: t.href
+	} : { label: t.label })];
+	const seen = /* @__PURE__ */ new Set();
+	return combined.filter((c) => {
+		if (c.href === void 0) return true;
+		if (seen.has(c.href)) return false;
+		seen.add(c.href);
+		return true;
+	});
+}
+/**
+* URL-segment fallback for pages with no node in the tree, so a stray
+* page still gets a root-anchored trail.
+*/
+function breadcrumbsFromUrl(slug, homeLabel = "Home") {
 	const parts = slug.split("/").filter(Boolean);
 	const crumbs = [{
 		label: homeLabel,
@@ -1025,7 +1140,7 @@ async function getLastUpdatedFromGit(filePath) {
 
 //#endregion
 //#region src/_internal/admonition-transform.ts
-/** Built-in MyST / Docusaurus / CF admonition types and their Aside mapping. */
+/** Built-in MyST / Docusaurus admonition types and their Aside mapping. */
 const BUILTIN_TYPES = {
 	note: "note",
 	info: "note",
@@ -1046,30 +1161,48 @@ function transformAdmonitions(source, options = {}) {
 	};
 	const { frontmatter, body, bodyOffset: _ } = splitFrontmatter(source);
 	const { stashed, restore } = stashCodeBlocks(body);
-	return frontmatter + restore(stashed.replace(ADMONITION_PATTERN, (match, rawType, rawTitle, rawContent) => {
+	return frontmatter + restore(stashed.replace(ADMONITION_PATTERN, (match, rawIndent, rawType, rawTitle, rawContent) => {
 		const aside = typeMap[String(rawType).toLowerCase()];
 		if (!aside) return match;
+		const indent = typeof rawIndent === "string" ? rawIndent : "";
 		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`;
+		return `\n\n${indent}<Aside type="${aside}"${title ? ` title=${JSON.stringify(title)}` : ""}>\n\n${reindentBody(String(rawContent), indent)}\n\n${indent}</Aside>\n\n`;
 	}));
 }
 /**
 * Match `:::type[optional title] body :::` with non-greedy body.
 *
 * Components:
+*   - `^([ \t]*)`     leading indentation of the opener line (captured) so the
+*                      emitted `<Aside>` can be re-indented to the same depth —
+*                      load-bearing for directives nested inside indented JSX
+*                      (e.g. `:::note` inside a `<TabItem>`). The `m` flag makes
+*                      `^`/`$` match line boundaries. Line-anchoring also stops
+*                      a stray mid-line `:::` from being treated as an opener.
 *   - `:::`           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
+*   - `\n|[ \t]+`     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
+*   - `\n?[ \t]*:::[ \t]*$`  closer, possibly indented, at end of its line
 *
 * 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;
+const ADMONITION_PATTERN = /^([ \t]*):::([a-zA-Z]+)(?:\[([^\]]*)\])?[ \t]*(?:\n|[ \t]+)([\s\S]*?)\n?[ \t]*:::[ \t]*$/gm;
+/**
+* Dedent the captured admonition body to a common baseline (preserving
+* relative structure like nested lists / JSX), then re-prefix every
+* non-blank line with the directive's own indentation so the emitted
+* `<Aside>…</Aside>` block sits at the same depth as the directive.
+*/
+function reindentBody(content, indent) {
+	const lines = content.replace(/^\n+/, "").replace(/\n+$/, "").split("\n");
+	const widths = lines.filter((l) => l.trim() !== "").map((l) => l.match(/^[ \t]*/)?.[0].length ?? 0);
+	const common = widths.length ? Math.min(...widths) : 0;
+	return lines.map((l) => l.trim() === "" ? "" : indent + l.slice(common)).join("\n");
+}
 function splitFrontmatter(source) {
 	const match = source.match(/^---\n[\s\S]*?\n---\n?/);
 	if (!match) return {
@@ -1729,6 +1862,118 @@ function parseTitle(meta) {
 	return (meta.match(/\btitle="([^"]+)"/) ?? meta.match(/\btitle='([^']+)'/))?.[1];
 }
 /**
+* Expand a (possibly space-padded) line-range spec like `5-16, 21-40` or
+* `1,3-5` into an explicit list of 1-based line numbers. Tolerates spaces
+* anywhere — `{5-16, 21-40}` expands to the same set as `{5-16,21-40}`.
+*/
+function expandRanges(spec) {
+	const out = [];
+	for (const partRaw of spec.split(",")) {
+		const part = partRaw.trim();
+		if (!part) continue;
+		const range = part.match(/^(\d+)\s*-\s*(\d+)$/);
+		if (range) {
+			const a = Number.parseInt(range[1], 10);
+			const b = Number.parseInt(range[2], 10);
+			const lo = Math.min(a, b);
+			const hi = Math.max(a, b);
+			for (let i = lo; i <= hi; i++) out.push(i);
+		} else if (/^\d+$/.test(part)) out.push(Number.parseInt(part, 10));
+	}
+	return out;
+}
+/**
+* Parse an EC-style fence meta string into {@link NimbusMeta}.
+*
+* Order matters — each step consumes (blanks out) what it matched so later,
+* looser patterns can't re-grab it:
+*   1. `frame="…"`            (quoted)
+*   2. `title="…"`            (quoted; value resolved separately)
+*   3. `ins="…"` / `del="…"`  (quoted tokens)
+*   4. `ins={…}` / `del={…}` / `collapse={…}`  (brace ranges)
+*   5. standalone `"…"`/`'…'` (search words — what's left of the quotes)
+*   6. `wrap`                 (bare keyword)
+*   7. bare `{…}`             (plain line-highlight — only what survives)
+*/
+function parseNimbusMeta(raw) {
+	const meta = {
+		highlightLines: /* @__PURE__ */ new Set(),
+		insLines: /* @__PURE__ */ new Set(),
+		delLines: /* @__PURE__ */ new Set(),
+		insTokens: [],
+		delTokens: [],
+		searchWords: [],
+		collapseLines: /* @__PURE__ */ new Set(),
+		wrap: false,
+		frame: void 0
+	};
+	if (!raw) return meta;
+	let s = raw;
+	s = s.replace(/\bframe=(?:"([^"]*)"|'([^']*)')/g, (_m, d, sg) => {
+		const v = d ?? sg;
+		if (v) meta.frame = v;
+		return " ";
+	});
+	s = s.replace(/\btitle=(?:"([^"]*)"|'([^']*)')/g, () => " ");
+	s = s.replace(/\bins=(?:"([^"]*)"|'([^']*)')/g, (_m, d, sg) => {
+		const v = d ?? sg;
+		if (v) meta.insTokens.push(v);
+		return " ";
+	});
+	s = s.replace(/\bdel=(?:"([^"]*)"|'([^']*)')/g, (_m, d, sg) => {
+		const v = d ?? sg;
+		if (v) meta.delTokens.push(v);
+		return " ";
+	});
+	s = s.replace(/\bins=\{([^}]*)\}/g, (_m, spec) => {
+		for (const n of expandRanges(spec)) meta.insLines.add(n);
+		return " ";
+	});
+	s = s.replace(/\bdel=\{([^}]*)\}/g, (_m, spec) => {
+		for (const n of expandRanges(spec)) meta.delLines.add(n);
+		return " ";
+	});
+	s = s.replace(/\bcollapse=\{([^}]*)\}/g, (_m, spec) => {
+		for (const n of expandRanges(spec)) meta.collapseLines.add(n);
+		return " ";
+	});
+	for (const m of s.matchAll(/"([^"]*)"|'([^']*)'/g)) {
+		const v = m[1] ?? m[2];
+		if (v) meta.searchWords.push(v);
+	}
+	s = s.replace(/"[^"]*"|'[^']*'/g, " ");
+	s = s.replace(/\bwrap\b/g, () => {
+		meta.wrap = true;
+		return " ";
+	});
+	s = s.replace(/\{([^}]*)\}/g, (_m, spec) => {
+		for (const n of expandRanges(spec)) meta.highlightLines.add(n);
+		return " ";
+	});
+	return meta;
+}
+/** Collect the plain-text content of a hast line node (concatenates spans). */
+function lineText(node) {
+	if (node.type === "text") return node.value ?? "";
+	let out = "";
+	if ("children" in node && node.children) for (const child of node.children) out += lineText(child);
+	return out;
+}
+/** Find every (non-overlapping) start index of `substr` in `str`. */
+function findAllSubstringIndexes(str, substr) {
+	const out = [];
+	if (!substr) return out;
+	let cursor = 0;
+	for (;;) {
+		const index = str.indexOf(substr, cursor);
+		if (index === -1) break;
+		out.push(index);
+		cursor = index + substr.length;
+	}
+	return out;
+}
+const META_SYMBOL = Symbol("nimbus-meta");
+/**
 * The canonical Shiki transformer chain for Nimbus. Returns a fresh
 * array each call so callers don't accidentally mutate a shared list.
 *
@@ -1745,11 +1990,57 @@ function defaultCodeTransformers() {
 		transformerNotationFocus(),
 		transformerNotationErrorLevel(),
 		transformerNotationWordHighlight(),
-		transformerMetaHighlight(),
-		transformerMetaWordHighlight(),
+		nimbusMetaTransformer(),
 		titleAndLangTransformer()
 	];
 }
+/**
+* Nimbus-owned fence-meta transformer. Owns bare-brace highlight
+* (space-tolerant), `ins=`/`del=` (brace + quoted-string forms),
+* quoted-search word highlight, `wrap`, `collapse` (neutral), and a
+* `frame=` hook. Replaces the stock meta-highlight + meta-word-highlight
+* transformers, which double-fired and hijacked braces.
+*/
+function nimbusMetaTransformer() {
+	function getMeta(ctx) {
+		const carrier = ctx.meta ?? {};
+		if (!carrier[META_SYMBOL]) carrier[META_SYMBOL] = parseNimbusMeta(ctx.options.meta?.__raw);
+		return carrier[META_SYMBOL];
+	}
+	return {
+		name: "nimbus:meta",
+		preprocess(code, options) {
+			if (!this.options.meta?.__raw) return;
+			const meta = getMeta(this);
+			if (meta.searchWords.length === 0) return;
+			options.decorations ||= [];
+			for (const word of meta.searchWords) for (const index of findAllSubstringIndexes(code, word)) options.decorations.push({
+				start: index,
+				end: index + word.length,
+				properties: { class: "highlighted-word" }
+			});
+		},
+		line(node, lineNumber) {
+			if (!this.options.meta?.__raw) return;
+			const meta = getMeta(this);
+			if (meta.highlightLines.has(lineNumber)) this.addClassToHast(node, "highlighted");
+			if (meta.insLines.has(lineNumber)) this.addClassToHast(node, "diff add");
+			if (meta.delLines.has(lineNumber)) this.addClassToHast(node, "diff remove");
+			if (meta.insTokens.length || meta.delTokens.length) {
+				const text = lineText(node);
+				if (meta.insTokens.some((t) => text.includes(t))) this.addClassToHast(node, "diff add");
+				if (meta.delTokens.some((t) => text.includes(t))) this.addClassToHast(node, "diff remove");
+			}
+		},
+		pre(preNode) {
+			if (!this.options.meta?.__raw) return;
+			const meta = getMeta(this);
+			preNode.properties = preNode.properties ?? {};
+			if (meta.wrap) preNode.properties["data-nb-wrap"] = "";
+			if (meta.frame) preNode.properties["data-nb-frame"] = meta.frame;
+		}
+	};
+}
 function titleAndLangTransformer() {
 	return {
 		name: "nimbus:title-and-lang",
@@ -1759,6 +2050,8 @@ function titleAndLangTransformer() {
 			const title = parseTitle(meta);
 			preNode.properties = preNode.properties ?? {};
 			preNode.properties["data-nb-lang"] = lang;
+			const wrap = preNode.properties["data-nb-wrap"] !== void 0;
+			const frame = preNode.properties["data-nb-frame"];
 			const children = [];
 			if (title) children.push({
 				type: "element",
@@ -1783,13 +2076,16 @@ function titleAndLangTransformer() {
 				}]
 			});
 			children.push(preNode);
+			const figureProps = {
+				class: title ? "nb-code-figure nb-code-figure-titled" : "nb-code-figure",
+				"data-nb-lang": lang
+			};
+			if (wrap) figureProps["data-nb-wrap"] = "";
+			if (typeof frame === "string") figureProps["data-nb-frame"] = frame;
 			return {
 				type: "element",
 				tagName: "figure",
-				properties: {
-					class: title ? "nb-code-figure nb-code-figure-titled" : "nb-code-figure",
-					"data-nb-lang": lang
-				},
+				properties: figureProps,
 				children
 			};
 		}
@@ -1856,9 +2152,9 @@ async function validateMdxContent(options) {
 * Format a list of failures into a single multi-line error message
 * suitable for `throw new Error(...)`.
 */
-function formatFailures(failures, globalsCount) {
+function formatFailures(failures) {
 	const lines = failures.map((f) => {
-		const fix = f.hint ? `Did you mean <${f.hint} />?` : globalsCount === 0 ? `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.` : `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.`;
+		const fix = f.hint ? `Did you mean <${f.hint} />?` : `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.`;
 		return `  ${f.filePath}:${f.line}:${f.column}  <${f.tag} />  →  ${fix}`;
 	});
 	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.";
@@ -2086,7 +2382,7 @@ function validateNimbusConfig(input) {
 		const tail = received === null ? "" : `\n      received: ${received}`;
 		return `  - ${display}: ${issue.message}${tail}`;
 	}).join("\n");
-	throw new Error(`Invalid nimbus.config — fix these issues:\n${issues}\n\nSee https://nimbus-docs.dev/config for the full config schema.`);
+	throw new Error(`Invalid nimbus.config — fix these issues:\n${issues}\n\nSee https://nimbus-docs.com/config for the full config schema.`);
 }
 /**
 * Resolve the value at `path` inside the raw input and format it for an
@@ -2134,18 +2430,11 @@ function virtualConfigPlugin(config, extras) {
 * 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.
+* Needed because incremental builds skip cached MDX files: those never
+* enter the markdown pipeline, so a language appearing only in cached
+* files would never trigger Shiki's lazy grammar load, and a non-cached
+* file using it would render without highlighting. Eager loading also
+* keeps highlighting independent of which file is processed first.
 */
 const FENCE_RE = /^[ \t]*```([a-zA-Z][a-zA-Z0-9_+\-]*)/gm;
 async function* walkMdx(dir) {
@@ -2200,10 +2489,10 @@ async function scanCodeBlockLanguages(projectRoot, langAlias = {}) {
 *   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.
+* Atomic per-file writes. A manifest-level `namespace` field provides
+* 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 {
@@ -2272,14 +2561,13 @@ var Cache = class {
 	/**
 	* 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 —
+	* Bounded so the cache doesn't grow forever: Vite emits new bundle
+	* hashes whenever the module graph differs between builds. The caller
+	* passes the 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.
+	* extracted from cached HTML — see `collectReferencedAssets` in index.ts.
 	*/
 	async snapshotAssets(distAstroDir, referencedRelPaths) {
 		const target = resolve(this.root, "assets");
@@ -2448,10 +2736,9 @@ async function writeAtomic(path, data) {
 *   - 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.
+* Current scope deliberately omits data-collection tracking and
+* component-graph tracking. Partial-dependency tracking folds the partial
+* registry into the page hash (see `partial-refs.ts`).
 */
 const TRACKED_DIRS = ["src", "public"];
 const TRACKED_FILES = [
@@ -2514,7 +2801,7 @@ async function walk$1(dir, root) {
 *   - 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
+* Including provenance closes a class of staleness bug: 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.
@@ -2583,7 +2870,7 @@ async function readDepVersion(projectRoot, dep) {
 	}
 }
 /**
-* Phase 3 — per-page hash with transitive partial dependencies folded in.
+* 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
@@ -2667,14 +2954,14 @@ async function resolveCacheNamespace(projectRoot) {
 //#endregion
 //#region src/_internal/incremental/partial-refs.ts
 /**
-* Phase 3 — partial dependency tracking.
+* 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.
+* hash gives us the property we want: edit one partial, exactly the pages
+* that transitively embed it re-render.
 *
 * Scope (v1):
 *   - Only string-literal `file` / `slug` props get captured. Dynamic
@@ -2683,16 +2970,17 @@ async function resolveCacheNamespace(projectRoot) {
 *     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).
+*     `src/content/partials/topic/slug.mdx`. Sites with a multi-prop
+*     convention (e.g. a resolver that prepends a `product` prop) need 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.
+* sibling directories that share its name as a prefix (e.g.
+* `partialsRoot-shared/`).
 */
 function isInside(candidate, rootWithSep) {
 	return candidate.startsWith(rootWithSep) || candidate === rootWithSep.slice(0, -1);
@@ -2715,7 +3003,7 @@ const ATTR_RE = /([a-zA-Z][a-zA-Z0-9_]*)\s*=\s*["']([^"']*)["']/g;
 *     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`.
+* collection base. Default: `src/content/partials`.
 */
 function makeDefaultPartialResolver(projectRoot, partialsBase = "src/content/partials") {
 	const partialsRoot = resolve(projectRoot, partialsBase);
@@ -2884,7 +3172,7 @@ async function partialsDirExists(projectRoot, partialsBase = "src/content/partia
 //#endregion
 //#region src/_internal/incremental/index.ts
 /**
-* Incremental builds — Phase 2 MVP.
+* Incremental builds.
 *
 * 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
@@ -2893,16 +3181,14 @@ async function partialsDirExists(projectRoot, partialsBase = "src/content/partia
 *
 * 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.
+* exactly like fresh renders. This is by design — rather than filtering
+* cached routes out of `getStaticPaths`, which would hide them from
+* downstream hooks.
 *
-* Anti-goals for this MVP (deferred to Phase 3+):
-*   - Partial-dependency tracking. Edit a partial → still full rebuild today.
+* Out of scope for now:
 *   - 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.
+*   - `nimbus build --explain` and structured build reports.
 */
 /**
 * Normalise a request URL to its canonical pathname (no trailing slash,
@@ -2921,7 +3207,7 @@ function canonicalisePathname(input) {
 }
 /**
 * Build a map from pathname → MDX file bytes by walking the docs collection
-* directory. Phase 2 MVP only handles the primary `docs` collection.
+* directory. Only the primary `docs` collection is handled.
 *
 * Pathname derivation: `src/content/docs/<entry.id>.mdx` → `/<entry.id>`,
 * mirroring `getDocsStaticPaths` which uses `entry.id` verbatim as slug.
@@ -3019,9 +3305,9 @@ async function collectDocsPages(projectRoot, docsBase = "src/content/docs") {
 * 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.
+* 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"));
@@ -3081,7 +3367,7 @@ async function setupIncrementalContext(projectRoot, cacheDir, logger, partialRes
 /**
 * Wrap an Astro prerenderer with the cache.
 *
-* Strategy (mvvmm-style — chosen empirically over the "wrap Response" approach
+* Strategy (chosen empirically over the "wrap Response" approach
 * because Astro's per-route work outside `render` is the actual dominant cost,
 * not MDX→HTML conversion):
 *
@@ -3094,12 +3380,12 @@ async function setupIncrementalContext(projectRoot, cacheDir, logger, partialRes
 *     `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
+* Trade-off vs. the "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.
+* Documented as a known limitation.
 */
 function wrapPrerenderer(defaultPrerenderer, ctx) {
 	return {
@@ -3176,7 +3462,7 @@ async function restoreCachedPagesToDist(ctx, outDir) {
 * (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
+* 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
@@ -3193,7 +3479,7 @@ 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).
+* `_astro/`, leaving the warm build with a broken reference.
 */
 function normaliseAssetRef(raw) {
 	if (!raw) return null;
@@ -3213,10 +3499,9 @@ function normaliseAssetRef(raw) {
 *
 * 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.)
+* styles, and individual `srcset` URLs alike. (An earlier regex
+* anchored on a quote/paren prefix and missed 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
@@ -3335,8 +3620,8 @@ function mdxSkipPlugin(ctx) {
 *   - 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
+* Scope: an optional `serialize` hook per URL, but no `lastmod`,
+* `changefreq`, `priority`, and 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\"";
@@ -3487,8 +3772,7 @@ function extractFrontmatter(source) {
 	const rest = source.slice(afterFirstMarker + 1);
 	const closingMatch = rest.match(/(^|\n)---\s*(\n|$)/);
 	if (!closingMatch || closingMatch.index === void 0) return null;
-	const endIndex = closingMatch[1] === "\n" ? closingMatch.index : closingMatch.index;
-	return rest.slice(0, endIndex);
+	return rest.slice(0, closingMatch.index);
 }
 /**
 * Find a top-level boolean field in YAML frontmatter. Returns the
@@ -3519,9 +3803,8 @@ function parseBoolField(yaml, field) {
 *   - `string[]` for either array form
 *   - `undefined` if absent
 *
-* The multiline form is the canonical YAML list syntax; the scanner
-* previously accepted only scalar and inline-array, which silently
-* dropped valid block lists at build time. The schema validates the
+* All three forms are accepted: scalar, inline array, and the multiline
+* block list (canonical YAML list syntax). The schema validates the
 * post-parse shape; the scanner has to match it.
 */
 function parsePreviousSlugField(yaml) {
@@ -3824,7 +4107,7 @@ function nimbus(rawConfig, options = {}) {
 							skip: validateOpts.skip,
 							projectRoot
 						});
-						if (failures.length > 0) throw new Error(formatFailures(failures, globals.length));
+						if (failures.length > 0) throw new Error(formatFailures(failures));
 						logger.info(`MDX validation passed — ${globals.length} global component${globals.length === 1 ? "" : "s"} registered, ${contentDirs.length} content dir${contentDirs.length === 1 ? "" : "s"} scanned.`);
 					}
 				}
@@ -4075,9 +4358,9 @@ function runPagefind(siteDir) {
 /**
 * Main entry for `nimbus-docs`.
 *
-* Exports the Astro integration (default), config helper, and the four
-* data helpers (sidebar, prev/next, breadcrumbs, TOC). Phase 6 will
-* add page composition helpers (`getDocsStaticPaths`, `getDocsPageProps`).
+* Exports the Astro integration (default), config helper, the data helpers
+* (sidebar, prev/next, breadcrumbs, TOC), and the page composition helpers
+* (`getDocsStaticPaths`, `getDocsPageProps`).
 *
 * Helpers read the user's config from `virtual:nimbus/config` (provided
 * by our Vite plugin) and content entries from `astro:content`. Both
@@ -4232,8 +4515,19 @@ async function getIndexedTopLevel() {
 */
 async function getSidebar(currentSlug, options) {
 	const config = await loadNimbusConfig();
-	const tree = await buildFullSidebarTree(currentSlug, options?.collection);
-	return config.sidebar?.scope === "section" ? scopeToCurrentSection(tree, currentSlug) : tree;
+	const fullTree = await buildFullSidebarTree(currentSlug, options?.collection);
+	let tree = config.sidebar?.scope === "section" ? scopeToCurrentSection(fullTree, currentSlug) : fullTree;
+	const boundaries = config.sidebar?.isolate?.boundaries;
+	if (boundaries && boundaries.length > 0) tree = isolateToBoundary(tree, currentSlug, boundaries);
+	if (options?.transform) {
+		const ctx = deriveTransformCtx(fullTree, currentSlug);
+		tree = await options.transform({
+			tree,
+			currentSlug,
+			...ctx
+		});
+	}
+	return tree;
 }
 /**
 * Derive one section per top-level group in the sidebar — used by
@@ -4324,13 +4618,74 @@ async function getPrevNext(currentSlug, options) {
 	return getPrevNext$1(currentSlug, tree, options?.overrides, validInternalLinks);
 }
 /**
-* Build breadcrumb trail from "/" to the current page.
-*
-* Phase 5: simple URL-segment derivation. Later phases may enrich with
-* sidebar-aware labels.
+* Build the breadcrumb trail from the active node's ancestry in the nav
+* tree. Labels come from nav nodes, hrefs from each node's landing — so a
+* section crumb links to its real landing page and segments with no node
+* never appear. Index-less folders render as non-interactive crumbs.
+*
+* - `collection` — the page's Astro collection; pass `entry.collection` so
+*   versioned pages get version-prefixed hrefs.
+* - `root` — the leading crumb (default `{ label: "Home", href: "/" }`).
+* - `resolveLabel` — override a crumb label, or return `null` to drop it.
+*
+* Falls back to URL-segment derivation when the page has no node in the
+* tree, so a stray page still gets a root-anchored trail.
 */
 async function getBreadcrumbs(currentSlug, options) {
-	return getBreadcrumbs$1(currentSlug, options?.homeLabel ?? "Home");
+	const path = findActivePath(await buildFullSidebarTree(currentSlug, options?.collection), currentSlug);
+	if (path.length > 0) return assembleBreadcrumbs(options?.root ?? {
+		label: "Home",
+		href: "/"
+	}, path, await Promise.all(path.map((node) => Promise.resolve(options?.resolveLabel?.({
+		node,
+		slug: currentSlug
+	})))));
+	return breadcrumbsFromUrl(currentSlug, options?.root?.label ?? "Home");
+}
+/**
+* Resolve a section's display title(s) for the current page, decoupled so
+* the rail header and the breadcrumb can differ.
+*
+* Derives `sectionSlug` (seg0) and `module` (seg1) from the slug and passes
+* them to a caller-supplied resolver. The resolver is an argument rather
+* than config because config is JSON-serialized and cannot carry functions.
+* `indexEntryId` is currently always `undefined`.
+*/
+async function getSectionTitle(currentSlug, resolve) {
+	const segs = currentSlug.split("/").filter(Boolean);
+	const sectionSlug = segs[0];
+	if (!sectionSlug) return void 0;
+	return resolve({
+		sectionSlug,
+		module: segs[1],
+		indexEntryId: void 0
+	});
+}
+/**
+* Navigation (breadcrumbs, sidebar active-state, optional prev/next) for a
+* data-driven route with no content entry of its own — e.g. a catalog page
+* under `src/pages/[...].astro`.
+*
+* Builds the breadcrumb trail to `section` (a real nav node) and appends
+* `trail` (the leaf). The sidebar is built with `section` as the active
+* path, so the section node highlights even though the leaf is not in the
+* tree — the leaf is never injected, keeping the tree and prev/next clean.
+*/
+async function getRouteNavigation(options) {
+	const { section, trail = [], prevNext = false, collection, resolveLabel } = options;
+	const sidebar = await getSidebar(section, { collection });
+	const breadcrumbs = composeRouteBreadcrumbs(await getBreadcrumbs(section, {
+		collection,
+		resolveLabel
+	}), trail);
+	let pn;
+	if (prevNext) pn = await getPrevNext(section, { sidebarTree: sidebar });
+	return {
+		breadcrumbs,
+		sidebar,
+		activeHref: section,
+		prevNext: pn
+	};
 }
 /**
 * Build an edit URL for a content entry using `config.editPattern`.
@@ -4682,5 +5037,5 @@ async function getVersionStatus(collectionId) {
 }
 
 //#endregion
-export { nimbus as default, defaultCodeTransformers, defineConfig, getBreadcrumbs, getCanonicalUrl, getCollectionLlmsUrl, getCollectionPageProps, getCollectionStaticPaths, getCurrentVersion, getDocsPageProps, getDocsStaticPaths, getEditUrl, getIndexedEntries, getIndexedTopLevel, getLastUpdated, getPrevNext, getSidebar, getSidebarSections, getTOC, getVersionAlternates, getVersionLandingUrl, getVersionStatus, getVersions, getVisibleEntries, renderEntryAsMarkdown, sidebarHash };
+export { nimbus as default, defaultCodeTransformers, defineConfig, getBreadcrumbs, getCanonicalUrl, getCollectionLlmsUrl, getCollectionPageProps, getCollectionStaticPaths, getCurrentVersion, getDocsPageProps, getDocsStaticPaths, getEditUrl, getIndexedEntries, getIndexedTopLevel, getLastUpdated, getPrevNext, getRouteNavigation, getSectionTitle, getSidebar, getSidebarSections, getTOC, getVersionAlternates, getVersionLandingUrl, getVersionStatus, getVersions, getVisibleEntries, renderEntryAsMarkdown, sidebarHash };
 //# sourceMappingURL=index.js.map