@takazudo/zudo-doc 3.2.0 → 4.0.0

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.2.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"
@@ -227,15 +215,23 @@
       "types": "./dist/chrome/index.d.ts",
       "default": "./dist/chrome/index.js"
     },
+    "./chrome-bindings": {
+      "types": "./dist/chrome-bindings.d.ts",
+      "default": "./dist/chrome-bindings.js"
+    },
     "./home-page": {
       "types": "./dist/home-page/index.d.ts",
       "default": "./dist/home-page/index.js"
     },
+    "./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",
     "./tags-audit": {
       "types": "./dist/tags-audit.d.ts",
       "default": "./dist/tags-audit.js"
@@ -248,6 +244,10 @@
       "types": "./dist/design-token-panel-bootstrap.d.ts",
       "default": "./dist/design-token-panel-bootstrap.js"
     },
+    "./design-token-panel-config": {
+      "types": "./dist/design-token-panel-config/index.d.ts",
+      "default": "./dist/design-token-panel-config/index.js"
+    },
     "./render-markdown": {
       "types": "./dist/render-markdown/index.d.ts",
       "default": "./dist/render-markdown/index.js"
@@ -316,6 +316,10 @@
       "types": "./dist/ai-chat-modal/index.d.ts",
       "default": "./dist/ai-chat-modal/index.js"
     },
+    "./find-in-page": {
+      "types": "./dist/find-in-page/index.d.ts",
+      "default": "./dist/find-in-page/index.js"
+    },
     "./doc-history": {
       "types": "./dist/doc-history/index.d.ts",
       "default": "./dist/doc-history/index.js"
@@ -531,12 +535,45 @@
     "./sidebar-active-slug": {
       "types": "./dist/sidebar-active-slug/index.d.ts",
       "default": "./dist/sidebar-active-slug/index.js"
+    },
+    "./i18n-defaults": {
+      "types": "./dist/i18n-defaults/index.d.ts",
+      "default": "./dist/i18n-defaults/index.js"
+    },
+    "./color-schemes-defaults": {
+      "types": "./dist/color-schemes-defaults/index.d.ts",
+      "default": "./dist/color-schemes-defaults/index.js"
+    },
+    "./docs-schema": {
+      "types": "./dist/docs-schema/index.d.ts",
+      "default": "./dist/docs-schema/index.js"
+    },
+    "./z-index-defaults": {
+      "types": "./dist/z-index-defaults/index.d.ts",
+      "default": "./dist/z-index-defaults/index.js"
+    },
+    "./frontmatter-preview-defaults": {
+      "types": "./dist/frontmatter-preview-defaults/index.d.ts",
+      "default": "./dist/frontmatter-preview-defaults/index.js"
+    },
+    "./directive-vocabulary-defaults": {
+      "types": "./dist/directive-vocabulary-defaults/index.d.ts",
+      "default": "./dist/directive-vocabulary-defaults/index.js"
+    },
+    "./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": [
@@ -544,19 +581,23 @@
     "bin",
     "eject",
     "routes-src",
+    "tsconfig.base.json",
+    "zfb-config-shim.d.ts",
+    "virtual-modules.d.ts",
     "README.md",
     "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.5",
     "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": {
@@ -565,6 +606,9 @@
     "@takazudo/zdtp": {
       "optional": true
     },
+    "@takazudo/zfb-md-wasm": {
+      "optional": true
+    },
     "shiki": {
       "optional": true
     },
@@ -576,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",
@@ -593,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.2.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

@@ -13,8 +13,14 @@
 import { routeCtx } from "./_context.js";
 import { createChrome } from "@takazudo/zudo-doc/chrome";
 import { DocHistory } from "@takazudo/zudo-doc/doc-history";
-import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";
 import type { DocNavNode } from "./_docs-helpers.js";
+// Imported via the BARE published subpath rather than a relative
+// `../chrome-bindings.js`. This file is copied into consumer projects by the
+// routes-src mechanism (`scripts/copy-routes-src.mjs`), which rewrites relative
+// `../` imports to `@takazudo/zudo-doc/*` specifiers so the copy resolves
+// against this package's `dist/`. Writing the bare specifier here directly
+// keeps the source identical to that rewritten output.
+import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
 // Host-callables channel (#2501): re-exports `settings.chromeBindingsModule`
 // when the host configured one, else `{}` — see
 // `plugins/routes.ts` and `docs/adr/route-injection-seam.md`
@@ -31,20 +37,37 @@ import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 // The import MUST stay static — a dynamic/type-only import stops zfb's island
 // scanner from walking it. SSR output is unchanged: `DocHistoryArea` gates on
 // `settings.docHistory` and the island is skip-SSR, so binding the real component
-// vs the stub is byte-identical. Mirrors the host's `pages/lib/_chrome.ts`.
+// vs the stub is byte-identical. Mirrors the host's `src/chrome-bindings.tsx`.
 // (The narrow real-island props signature isn't assignable to the structural
-// `FactoryComponent`, so cast — same as the host.)
+// `FactoryComponent`, so it's widened through `defineChromeBindings` — same
+// helper the host uses — which checks `DocHistory` against its real call-side
+// prop contract before performing the widening, restoring the #2674
+// drift-detection check a bare cast would erase.)
 //
-// `...chromeBindings` is spread AFTER the `DocHistory` default 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. Note the SSR-presentational-only limitation: a client island defined
+// 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
+// place). Note the SSR-presentational-only limitation: a client island defined
 // INSIDE the bindings module is not guaranteed to register on injected routes
 // the way the static `DocHistory` import above is (the virtual re-export sits
 // outside zfb's static-import scanner reachability graph) — see the ADR.
+//
+// `DesignTokenPanelBootstrap` (#2658) is NOT threaded here: unlike DocHistory
+// (whose derive-level default is a no-op stub), the package-default island IS
+// the derive-level default (`chrome/derive.tsx`'s `deriveBodyEndIslands`,
+// gate-2 fix from the Wave-5 confirm #2659) — so this shim, the locked-manifest
+// self-contained doc stub (#2653), and every other bare `createChrome` caller
+// all get it without explicit wiring. Scanner reachability holds through the
+// static chain route → this shim → `createChrome` → `chrome/derive` →
+// `design-token-panel-bootstrap`.
 const chrome = createChrome(routeCtx, {
-  DocHistory: DocHistory as unknown as ChromeHostBindings["DocHistory"],
   ...chromeBindings,
+  ...defineChromeBindings({ DocHistory }),
 });
 
 export const {