@takazudo/zudo-doc 3.3.0 → 4.0.0

package/eject/footer/footer.tsx

@@ -87,6 +87,7 @@ export function Footer(props: FooterProps): VNode {
   return (
     <footer
       class="border-t border-muted bg-surface"
+      data-footer
       // Strategy B: locale-keyed persist (zudolab/zudo-doc#1546).
       // The footer's locale-aware bits (link labels, copyright) are SSR'd
       // per locale; a locale-keyed persist key (`footer-en`, `footer-ja`)

package/eject/header/header.tsx

@@ -49,6 +49,8 @@ import { LANGUAGE_SWITCHER_INIT_SCRIPT } from "../i18n-version/language-switcher
 import { VERSION_SWITCHER_REWIRE_SCRIPT } from "../i18n-version/version-switcher.js";
 import type {
   HeaderNavItem,
+  HeaderRightComponentProps,
+  HeaderRightComponentRegistry,
   HeaderRightItem,
   Locale,
 } from "./types.js";
@@ -137,10 +139,9 @@ export interface HeaderProps {
   search?: ComponentChildren;
 
   /**
-   * When provided, emits `data-zfb-transition-persist={persistKey}` on the
+   * Emits `data-zfb-transition-persist={persistKey}` on the
    * `<header>` element so zfb's client-router preserves DOM-node identity
-   * across same-locale View Transition swaps. Omit to disable persist
-   * (back-compat default — the header is re-rendered on every swap).
+   * across same-locale View Transition swaps.
    *
    * **Locale keying**: callers MUST key by locale (e.g. `"header-en"`,
    * `"header-ja"`). Cross-locale swaps must NOT share the same key; a
@@ -156,7 +157,7 @@ export interface HeaderProps {
    * for consistency, matching the Astro reference implementation
    * (zudolab/zudo-doc#1546).
    */
-  persistKey?: string;
+  persistKey: string;
 
   /** Site-name string shown in the logo anchor (host `settings.siteName`). */
   siteName: string;
@@ -175,6 +176,13 @@ export interface HeaderProps {
    */
   headerRightItems: HeaderRightItem[];
 
+  /**
+   * Host-callable renderers for project-owned component names. The registry is
+   * carried through `chromeBindingsModule`; it is never part of the serialized
+   * settings payload. Package built-in names are reserved.
+   */
+  headerRightComponents?: HeaderRightComponentRegistry;
+
   /**
    * Whether the host has a `colorMode` config. Required because the
    * `theme-toggle` right-item is two-gated: the filter drops it when
@@ -253,6 +261,7 @@ export function Header(props: HeaderProps): JSX.Element {
     siteName,
     headerNav,
     headerRightItems,
+    headerRightComponents,
     colorModeEnabled,
     hasLocales,
     hasVersions,
@@ -267,14 +276,15 @@ export function Header(props: HeaderProps): JSX.Element {
   const matchPath = pathForMatch(pathWithoutBase, lang, i18n.defaultLocale);
 
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
+  const rightItemDispatch = createRightItemDispatch(headerRightComponents);
 
   return (
     <header
       class="sticky top-0 z-toolbar flex h-[3.5rem] items-center border-b border-muted bg-surface px-hsp-lg"
       data-header
       // Strategy B persist (zudolab/zudo-doc#1546): the header now carries
-      // data-zfb-transition-persist when a locale-keyed persistKey is
-      // supplied (e.g. "header-en" / "header-ja"). Cross-locale swaps use
+      // data-zfb-transition-persist with a locale-keyed persistKey
+      // (e.g. "header-en" / "header-ja"). Cross-locale swaps use
       // different keys, so the router replaces the header element entirely,
       // re-rendering the locale toggle anchors and all locale-specific SSR
       // content with fresh markup. Same-locale swaps share the key and
@@ -303,7 +313,6 @@ export function Header(props: HeaderProps): JSX.Element {
       //     LANGUAGE_SWITCHER_INIT_SCRIPT recomputes each anchor's href from
       //     window.location on AFTER_NAVIGATE_EVENT, same as the controls above
       //     (zudolab/zudo-doc#2551).
-      // Omit persistKey to fall back to the old repaint-on-every-swap path.
       data-zfb-transition-persist={persistKey}
     >
       {sidebarToggle ?? (
@@ -371,6 +380,7 @@ export function Header(props: HeaderProps): JSX.Element {
             colorModeEnabled,
             hasLocales,
           },
+          rightItemDispatch,
         ))}
       </div>
 
@@ -513,17 +523,7 @@ function renderNavItem(
   );
 }
 
-interface RightItemContext {
-  lang: Locale | undefined;
-  githubRepoUrl: string | null;
-  githubLabel: string;
-  themeToggle: ComponentChildren;
-  languageSwitcher: ComponentChildren;
-  versionSwitcher: ComponentChildren;
-  search: ComponentChildren;
-  colorModeEnabled: boolean;
-  hasLocales: boolean;
-}
+type RightItemContext = Omit<HeaderRightComponentProps, "item" | "index">;
 
 /**
  * Shared trigger-button shell for header-right items that dispatch a
@@ -591,7 +591,15 @@ type RightItemHandler = (
 
 // Dispatch table keyed by `${type}:${trigger|component}`, or just `type`
 // for link/html items that carry no sub-type discriminant.
-const RIGHT_ITEM_DISPATCH: Record<string, RightItemHandler> = {
+const BUILTIN_COMPONENT_NAMES = [
+  "theme-toggle",
+  "language-switcher",
+  "version-switcher",
+  "github-link",
+  "search",
+] as const;
+
+const BASE_RIGHT_ITEM_DISPATCH: Readonly<Record<string, RightItemHandler>> = {
   "trigger:design-token-panel": (_item, index) => (
     <TriggerButton
       index={index}
@@ -737,10 +745,55 @@ const RIGHT_ITEM_DISPATCH: Record<string, RightItemHandler> = {
   },
 };
 
+/**
+ * Compose the immutable package dispatch table with host-callable component
+ * entries. Built-ins are reserved: a host collision is almost certainly a
+ * typo or an attempted override, so reject it rather than silently changing
+ * package markup. Runtime callable checks keep JavaScript/untyped consumers on
+ * the same contract as TypeScript callers.
+ */
+function createRightItemDispatch(
+  hostRegistry: HeaderRightComponentRegistry | undefined,
+): ReadonlyMap<string, RightItemHandler> {
+  const dispatch = new Map<string, RightItemHandler>(
+    Object.entries(BASE_RIGHT_ITEM_DISPATCH),
+  );
+  if (hostRegistry === undefined) return dispatch;
+
+  for (const [name, component] of Object.entries(hostRegistry)) {
+    if (BUILTIN_COMPONENT_NAMES.includes(name as typeof BUILTIN_COMPONENT_NAMES[number])) {
+      throw new Error(
+        `[zudo-doc] Duplicate header-right component name "${name}" at ` +
+          `chromeBindings.headerRightComponents[${JSON.stringify(name)}]: built-in names are reserved and ` +
+          `cannot be shadowed. Remove this registry entry or choose a project-owned name.`,
+      );
+    }
+    if (typeof component !== "function") {
+      throw new TypeError(
+        `[zudo-doc] Invalid header-right component "${name}" at ` +
+          `chromeBindings.headerRightComponents[${JSON.stringify(name)}]: expected a callable renderer.`,
+      );
+    }
+
+    dispatch.set(`component:${name}`, (item, index, ctx) => {
+      if (item.type !== "component") return null;
+      const CustomComponent = component;
+      return (
+        <SlotWrapper index={index}>
+          <CustomComponent item={item} index={index} {...ctx} />
+        </SlotWrapper>
+      );
+    });
+  }
+
+  return dispatch;
+}
+
 function renderRightItem(
   item: HeaderRightItem,
   index: number,
   ctx: RightItemContext,
+  dispatch: ReadonlyMap<string, RightItemHandler>,
 ): VNode | null {
   const key =
     item.type === "trigger"
@@ -748,6 +801,18 @@ function renderRightItem(
       : item.type === "component"
         ? `component:${item.component}`
         : item.type;
-  const handler = RIGHT_ITEM_DISPATCH[key];
-  return handler ? handler(item, index, ctx) : null;
+  const handler = dispatch.get(key);
+  if (handler) return handler(item, index, ctx);
+
+  if (item.type === "component") {
+    throw new Error(
+      `[zudo-doc] Unknown header-right component "${item.component}" at ` +
+        `Header.headerRightItems[${index}].component. Register a callable renderer as ` +
+        `chromeBindings.headerRightComponents["${item.component}"] through ` +
+        `settings.chromeBindingsModule, or use a built-in name: ` +
+        `${BUILTIN_COMPONENT_NAMES.join(", ")}.`,
+    );
+  }
+
+  return null;
 }

package/eject/header/index.ts

@@ -14,8 +14,11 @@ export type {
   Locale,
   HeaderNavChildItem,
   HeaderNavItem,
+  HeaderRightBuiltinComponentName,
   HeaderRightComponentItem,
   HeaderRightComponentName,
+  HeaderRightComponentProps,
+  HeaderRightComponentRegistry,
   HeaderRightHtmlItem,
   HeaderRightItem,
   HeaderRightLinkItem,

package/eject/header/types.ts

@@ -11,6 +11,8 @@
 // downstream consumers may continue to use the v2 types until the v2
 // package itself widens them. Changes here are v2 breaking changes.
 
+import type { ComponentChildren } from "preact";
+
 /**
  * Locale code as seen by the header. Widened from the host's literal
  * union (`"en" | "ja" | …`) to plain `string` at the v2 boundary so the
@@ -30,13 +32,22 @@ export interface HeaderNavItem extends HeaderNavChildItem {
   children?: HeaderNavChildItem[];
 }
 
-export type HeaderRightComponentName =
+export type HeaderRightBuiltinComponentName =
   | "theme-toggle"
   | "language-switcher"
   | "version-switcher"
   | "github-link"
   | "search";
 
+/**
+ * A serializable name resolved against the package built-ins plus the host's
+ * `headerRightComponents` chrome-binding registry. The intersection preserves
+ * built-in autocomplete while allowing project-owned names.
+ */
+export type HeaderRightComponentName =
+  | HeaderRightBuiltinComponentName
+  | (string & {});
+
 export type HeaderRightTriggerName = "design-token-panel" | "ai-chat";
 
 export interface HeaderRightComponentItem {
@@ -44,6 +55,33 @@ export interface HeaderRightComponentItem {
   component: HeaderRightComponentName;
 }
 
+/**
+ * Exact props passed to a host `headerRightComponents` renderer. They mirror
+ * the existing header-right dispatch context; no callable enters the
+ * serialized {@link HeaderRightComponentItem}.
+ */
+export interface HeaderRightComponentProps {
+  /** The serialized item that selected this renderer. */
+  item: HeaderRightComponentItem;
+  /** Zero-based position in the rendered `headerRightItems` array. */
+  index: number;
+  lang: Locale | undefined;
+  githubRepoUrl: string | null;
+  githubLabel: string;
+  themeToggle: ComponentChildren;
+  languageSwitcher: ComponentChildren;
+  versionSwitcher: ComponentChildren;
+  search: ComponentChildren;
+  colorModeEnabled: boolean;
+  hasLocales: boolean;
+}
+
+/** A callable-only host registry keyed by serialized component name. */
+export type HeaderRightComponentRegistry = Record<
+  string,
+  (props: HeaderRightComponentProps) => ComponentChildren
+>;
+
 export interface HeaderRightTriggerItem {
   type: "trigger";
   trigger: HeaderRightTriggerName;

package/eject/site-tree-nav-island/index.tsx

@@ -8,6 +8,7 @@ import { useState } from "preact/hooks";
 import type { SidebarNavNode } from "../sidebar/types.js";
 import { INDENT, connectorLeft, ConnectorLines, CategoryLinkIcon } from "../tree-nav-shared/index.js";
 import { ChevronRight } from "../icons/index.js";
+import { initialCategoryOpenState, toggleCategoryOpenState } from "./state.js";
 
 // site-tree-nav uses wider padding than the narrow sidebar
 const SITE_BASE_PAD = "clamp(0.5rem, 0.8vw, 1rem)";
@@ -39,6 +40,8 @@ export interface SiteTreeNavProps {
   ariaLabel?: string;
   categoryOrder?: string[];
   categoryIgnore?: string[];
+  /** Root-category slugs that should start collapsed. */
+  initiallyCollapsedCategorySlugs?: string[];
 }
 
 export function SiteTreeNav({
@@ -46,6 +49,7 @@ export function SiteTreeNav({
   ariaLabel = "Site index",
   categoryOrder,
   categoryIgnore,
+  initiallyCollapsedCategorySlugs,
 }: SiteTreeNavProps) {
   let processedTree = tree;
   if (categoryIgnore) {
@@ -55,6 +59,7 @@ export function SiteTreeNav({
   if (categoryOrder) {
     processedTree = reorderTree(processedTree, categoryOrder);
   }
+  const initiallyCollapsed = new Set(initiallyCollapsedCategorySlugs);
   return (
     <nav
       aria-label={ariaLabel}
@@ -67,7 +72,12 @@ export function SiteTreeNav({
       {processedTree.map((node) => (
         <div key={node.slug} className="min-w-0 border border-muted pl-hsp-sm py-vsp-2xs">
           {node.children.length > 0 ? (
-            <CategoryNode node={node} depth={0} isLast={true} />
+            <CategoryNode
+              node={node}
+              depth={0}
+              isLast={true}
+              initiallyCollapsed={initiallyCollapsed.has(node.slug)}
+            />
           ) : (
             <LeafNode node={node} depth={0} isLast={true} />
           )}
@@ -107,13 +117,15 @@ function CategoryNode({
   node,
   depth,
   isLast,
+  initiallyCollapsed = false,
 }: {
   node: SidebarNavNode;
   depth: number;
   isLast: boolean;
+  initiallyCollapsed?: boolean;
 }) {
-  const [open, setOpen] = useState(true);
-  const toggle = () => setOpen((prev) => !prev);
+  const [open, setOpen] = useState(() => initialCategoryOpenState(initiallyCollapsed));
+  const toggle = () => setOpen(toggleCategoryOpenState);
   const paddingLeft = padLeft(depth);
 
   return (

package/eject/site-tree-nav-island/state.ts

@@ -0,0 +1,9 @@
+/** Derive the one-time open state used when a category mounts. */
+export function initialCategoryOpenState(initiallyCollapsed: boolean): boolean {
+  return !initiallyCollapsed;
+}
+
+/** Toggle a mounted category without coupling later state to its initial input. */
+export function toggleCategoryOpenState(open: boolean): boolean {
+  return !open;
+}

package/eject/theme-toggle/color-scheme-sync.ts

@@ -41,10 +41,8 @@ export function readColorSchemeFromDom(
  * `color-scheme-changed` window event.
  *
  * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
- * panel owns its own storage lifecycle: it persists the unified tweak envelope
- * under `zudo-doc-tweak-state-v4` (auto-migrating the legacy
- * `zudo-doc-tweak-state-v3` / `-v2` / `zudo-doc-tweak-state` (v1) keys into
- * it), and its own `color-scheme-changed` listener clears applied inline
+ * panel owns its own storage lifecycle and current persisted-state contract;
+ * its own `color-scheme-changed` listener clears applied inline
  * styles and re-seeds the color slice from the newly active scheme. An
  * earlier version of this function deleted `zudo-doc-tweak-state` + `-v2` on
  * every toggle, which (a) targeted stale keys after zdtp moved to v3 — so it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -107,26 +107,10 @@
       "types": "./dist/transitions/index.d.ts",
       "default": "./dist/transitions/index.js"
     },
-    "./integrations/doc-history": {
-      "types": "./dist/integrations/doc-history/index.d.ts",
-      "default": "./dist/integrations/doc-history/index.js"
-    },
-    "./integrations/llms-txt": {
-      "types": "./dist/integrations/llms-txt/index.d.ts",
-      "default": "./dist/integrations/llms-txt/index.js"
-    },
     "./integrations/changelog": {
       "types": "./dist/integrations/changelog/index.d.ts",
       "default": "./dist/integrations/changelog/index.js"
     },
-    "./integrations/search-index": {
-      "types": "./dist/integrations/search-index/index.d.ts",
-      "default": "./dist/integrations/search-index/index.js"
-    },
-    "./integrations/claude-resources": {
-      "types": "./dist/integrations/claude-resources/index.d.ts",
-      "default": "./dist/integrations/claude-resources/index.js"
-    },
     "./content": {
       "types": "./dist/content/index.d.ts",
       "default": "./dist/content/index.js"
@@ -195,6 +179,10 @@
       "types": "./dist/plugins/routes.d.ts",
       "default": "./dist/plugins/routes.js"
     },
+    "./plugins/theme-packs": {
+      "types": "./dist/plugins/theme-packs.d.ts",
+      "default": "./dist/plugins/theme-packs.js"
+    },
     "./content-admonition": {
       "types": "./dist/content-admonition/index.d.ts",
       "default": "./dist/content-admonition/index.js"
@@ -237,10 +225,10 @@
     },
     "./theme.css": "./dist/theme.css",
     "./safelist.css": "./dist/safelist.css",
-    "./safelist": "./dist/safelist.css",
     "./content.css": "./dist/content.css",
     "./page-loading.css": "./dist/page-loading.css",
     "./features.css": "./dist/features.css",
+    "./theme-packs/*": "./dist/theme-packs/*",
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./zfb-config-shim.d.ts": "./zfb-config-shim.d.ts",
     "./virtual-modules.d.ts": "./virtual-modules.d.ts",
@@ -575,12 +563,17 @@
     "./config": {
       "types": "./dist/config.d.ts",
       "default": "./dist/config.js"
+    },
+    "./theme-cli": {
+      "types": "./dist/theme-cli/index.d.ts",
+      "default": "./dist/theme-cli/index.js"
     }
   },
   "bin": {
     "gen-component-tokens": "./bin/gen-component-tokens.mjs",
     "gen-z-index": "./bin/gen-z-index.mjs",
     "tags-audit": "./bin/tags-audit.mjs",
+    "tags-suggest": "./bin/tags-suggest.mjs",
     "zudo-doc": "./bin/zudo-doc.mjs"
   },
   "files": [
@@ -595,15 +588,16 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
+    "@takazudo/zdtp": "^0.4.9",
+    "@takazudo/zfb": "^0.1.0-next.87",
+    "@takazudo/zfb-md-wasm": "^0.1.0-next.87",
+    "@takazudo/zfb-runtime": "^0.1.0-next.87",
+    "@takazudo/zudo-doc-history-server": "^4.0.0",
+    "diff": "^8.0.0",
+    "katex": "^0.16.0",
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.78",
-    "@takazudo/zfb-runtime": "^0.1.0-next.78",
-    "@takazudo/zudo-doc-history-server": "^3.1.0",
-    "@takazudo/zdtp": "^0.4.6",
     "shiki": "^4.0.2",
-    "zod": "^4.3.6",
-    "katex": "^0.16.0",
-    "diff": "^8.0.0"
+    "zod": "^4.3.6"
   },
   "peerDependenciesMeta": {
     "@takazudo/zudo-doc-history-server": {
@@ -612,6 +606,9 @@
     "@takazudo/zdtp": {
       "optional": true
     },
+    "@takazudo/zfb-md-wasm": {
+      "optional": true
+    },
     "shiki": {
       "optional": true
     },
@@ -623,16 +620,26 @@
     }
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
     "fs-extra": "^11.3.0",
     "gray-matter": "^4.0.3",
     "minimist": "^1.2.8",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "pluralize": "^8.0.0",
+    "string-similarity": "^4.0.4",
+    "tsx": "^4.21.0"
   },
   "devDependencies": {
+    "@takazudo/zfb": "0.1.0-next.87",
+    "@takazudo/zfb-md-wasm": "0.1.0-next.87",
+    "@takazudo/zfb-runtime": "0.1.0-next.87",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
+    "@types/pluralize": "^0.0.33",
+    "@types/string-similarity": "^4.0.2",
     "cross-env": "^7.0.3",
+    "happy-dom": "^20.10.6",
     "preact": "^10.29.1",
     "preact-render-to-string": "^6.6.6",
     "shiki": "^4.0.2",
@@ -640,13 +647,12 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zfb": "0.1.0-next.78",
-    "@takazudo/zfb-runtime": "0.1.0-next.78",
-    "@takazudo/zudo-doc-history-server": "3.3.0"
+    "@takazudo/zudo-doc-history-server": "4.0.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",
     "dev": "tsup --watch",
+    "test:plugin-resolution": "node scripts/check-plugin-resolution.mjs",
     "test": "vitest run --config vitest.config.ts",
     "test:slow": "vitest run --config vitest.slow.config.ts",
     "typecheck": "tsc --noEmit"

package/routes-src/404.tsx

@@ -5,7 +5,8 @@
 
 import type { JSX } from "preact";
 import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { settings, defaultLocale, withBase } from "./_context.js";
+import { resolveThemePackSsrSlug } from "@takazudo/zudo-doc/theme";
+import { settings, defaultLocale, withBase, themePackRegistry } from "./_context.js";
 import {
   HeadWithDefaults,
   HeaderWithDefaults,
@@ -25,6 +26,8 @@ export default function NotFoundPage(): JSX.Element {
       title={composeMetaTitle(title)}
       head={<HeadWithDefaults title={title} />}
       lang={locale}
+      // SSR `data-theme-pack` html attribute (ADR theme-packs.md D3, #2822).
+      dataThemePack={resolveThemePackSsrSlug(themePackRegistry, settings)}
       noindex={true}
       hideSidebar={true}
       hideToc={true}

package/routes-src/_chrome.tsx

@@ -44,10 +44,11 @@ import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 // prop contract before performing the widening, restoring the #2674
 // drift-detection check a bare cast would erase.)
 //
-// `...chromeBindings` is spread AFTER the `defineChromeBindings({ DocHistory })`
-// result so a host that configured `chromeBindingsModule` can override ANY
-// slot — including DocHistory itself — while a host that didn't still gets
-// the #2480 fix for free. `chromeBindings` (the virtual re-export) is already
+// The statically imported DocHistory is spread AFTER `...chromeBindings` so
+// scanner-safe hydration wins consistently with generated self-contained
+// routes. Hosts can override every other slot; DocHistory customization uses
+// the package island's supported owner path rather than a virtual callable
+// that the scanner cannot register. `chromeBindings` (the virtual re-export) is already
 // erased to the structural `ChromeHostBindings` at its own source, so it is
 // spread as-is rather than run back through `defineChromeBindings` (which
 // cannot recover types `defineChromeBindings` never checked in the first
@@ -65,8 +66,8 @@ import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 // static chain route → this shim → `createChrome` → `chrome/derive` →
 // `design-token-panel-bootstrap`.
 const chrome = createChrome(routeCtx, {
-  ...defineChromeBindings({ DocHistory }),
   ...chromeBindings,
+  ...defineChromeBindings({ DocHistory }),
 });
 
 export const {

package/routes-src/_context.ts

@@ -22,6 +22,7 @@ import { routeContext } from "virtual:zudo-doc-route-context";
 
 import type { Settings } from "@takazudo/zudo-doc/settings";
 import type { ColorScheme } from "@takazudo/zudo-doc/color-scheme-utils";
+import type { ThemePackRegistry } from "@takazudo/zudo-doc/theme-packs-registry";
 import {
   createRouteContext,
   type RouteContextPayload,
@@ -42,6 +43,9 @@ export const settings: Settings = routeCtx.settings;
 /** Host color-scheme palette map. `null` when not supplied — `_chrome.tsx`
  *  falls back to `DEFAULT_SCHEME` in that case. */
 export const colorSchemes: Record<string, ColorScheme> | null = routeCtx.colorSchemes;
+/** Resolved, enabled, ordered theme-pack registry. `null` when the routes
+ *  plugin did not thread one (ADR `docs/adr/theme-packs.md`, Decision 2). */
+export const themePackRegistry: ThemePackRegistry | null = routeCtx.themePackRegistry;
 
 export const {
   i18n,

package/routes-src/_docs-helpers.ts

@@ -22,7 +22,6 @@
 import {
   getCollection,
   getContentSnapshot,
-  type CollectionEntry,
 } from "@takazudo/zfb/content";
 import {
   buildSidebarTree,
@@ -44,29 +43,10 @@ function snapshotAnchor(name: string): readonly unknown[] | undefined {
   return getContentSnapshot()?.collections[name];
 }
 
-const bridgedByAnchor = new WeakMap<object, DocPageEntry[]>();
+const docsByAnchor = new WeakMap<object, DocPageEntry[]>();
 
-/** Bridge a raw zfb collection entry onto the `DocPageEntry` shape the factories
- *  expect (Astro-compat `id`/`collection`, with `index` suffix stripped via the
- *  canonical root-slug rule). */
-function bridgeEntry(
-  e: CollectionEntry<DocPageFrontmatter>,
-  collectionName: string,
-): DocPageEntry {
-  return {
-    slug: e.slug,
-    id: toRouteSlug(e.slug),
-    collection: collectionName,
-    data: e.data,
-    body: e.body,
-    module_specifier: e.module_specifier,
-    Content: e.Content,
-  };
-}
-
-function buildBridged(collectionName: string): DocPageEntry[] {
-  const raw = getCollection<DocPageFrontmatter>(collectionName);
-  return raw.map((e) => bridgeEntry(e, collectionName)).filter((d) => !d.data.draft);
+function buildDocs(collectionName: string): DocPageEntry[] {
+  return getCollection<DocPageFrontmatter>(collectionName).filter((entry) => !entry.data.draft);
 }
 
 /**
@@ -77,11 +57,11 @@ function buildBridged(collectionName: string): DocPageEntry[] {
  */
 export function stableDocs(collectionName: string): DocPageEntry[] {
   const anchor = snapshotAnchor(collectionName);
-  if (anchor === undefined) return buildBridged(collectionName);
-  const cached = bridgedByAnchor.get(anchor);
+  if (anchor === undefined) return buildDocs(collectionName);
+  const cached = docsByAnchor.get(anchor);
   if (cached) return cached;
-  const built = buildBridged(collectionName);
-  bridgedByAnchor.set(anchor, built);
+  const built = buildDocs(collectionName);
+  docsByAnchor.set(anchor, built);
   return built;
 }
 
@@ -119,7 +99,7 @@ function toNavNode(node: SidebarNode): DocNavNode {
 function findRootIndexDoc(docs: DocPageEntry[]): DocPageEntry | undefined {
   let found: DocPageEntry | undefined;
   for (const d of docs) {
-    const slug = d.data.slug ?? d.id.replace(/\/index$/, "");
+    const slug = d.data.slug ?? toRouteSlug(d.slug);
     if (slug === "") found = d;
   }
   return found;
@@ -169,7 +149,7 @@ export function buildNavTree(
 ): DocNavNode[] {
   const href: BuildHref = options?.buildHref ?? buildHref;
   const sidebarTree = buildSidebarTree(
-    docs.map((d) => ({ id: d.id, data: d.data })),
+    docs,
     locale,
     {
       categoryMeta,