@takazudo/zudo-doc 5.5.3 → 5.7.0

package/eject/header/nav-overflow-script.ts

@@ -29,307 +29,29 @@
 // Kept as a separate module (rather than inlined in `header.tsx`) so
 // the JSX file stays focused on markup and so future edits to the
 // script can be reviewed in isolation.
-
-import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
-import {
-  NAV_CHEVRON_ACTIVE,
-  NAV_CHEVRON_INACTIVE,
-  NAV_CHILD_ACTIVE,
-  NAV_CHILD_INACTIVE,
-  NAV_MENU_CHILD_ACTIVE,
-  NAV_MENU_CHILD_INACTIVE,
-  NAV_MENU_PARENT,
-  NAV_MENU_PARENT_ACTIVE_SUFFIX,
-  NAV_MENU_PLAIN,
-  NAV_MENU_PLAIN_ACTIVE_SUFFIX,
-  NAV_TOP_ACTIVE,
-  NAV_TOP_INACTIVE,
-} from "./nav-class-tokens.js";
-
-// The class lists spliced into the script below are the SSR ↔ runtime
-// lockstep: they must match the strings header.tsx renders. Both files import
-// them from ./nav-class-tokens so they cannot drift (zudolab/zudo-doc#3023).
-// The script ships as plain text via dangerouslySetInnerHTML and cannot import
-// the arrays at runtime, so these helpers splice the token lists into the
-// script string at module-eval (build) time instead.
-
-// -> `"bg-fg", "text-bg"` — argument list for a classList.add/remove(...) call.
-const clsArgs = (tokens: readonly string[]): string =>
-  tokens.map((token) => JSON.stringify(token)).join(", ");
-
-// -> `"bg-fg text-bg"` — a single class-string literal for `className = ...`.
-const clsLiteral = (tokens: readonly string[]): string =>
-  JSON.stringify(tokens.join(" "));
-
-// -> `" font-bold text-accent"` — leading-space append for `className += ...`.
-const clsAppend = (tokens: readonly string[]): string =>
-  JSON.stringify(" " + tokens.join(" "));
-
-export const NAV_OVERFLOW_SCRIPT = `(function () {
-  var cleanupNavOverflow = null;
-
-  function trimSlashes(p) {
-    while (p.length > 1 && p.charAt(p.length - 1) === "/") p = p.slice(0, -1);
-    return p || "/";
-  }
-
-  function navPathname(a) {
-    try { return trimSlashes(new URL(a.href, location.href).pathname); }
-    catch (e) { return ""; }
-  }
-
-  function isUnderPath(cur, p) {
-    if (!p) return false;
-    if (cur === p) return true;
-    return p !== "/" && cur.indexOf(p + "/") === 0;
-  }
-
-  // Recompute which header nav item is "active" from the CURRENT URL and
-  // repaint the highlight. SSR sets the active item on first paint, but the
-  // header is persisted across same-locale client-router swaps
-  // (data-zfb-transition-persist), so without this the highlight would stay
-  // frozen on the page where the header was first rendered. Mirrors the
-  // sidebar island's client-side approach (match location.pathname against
-  // each entry's href) and the SSR longest-match + dropdown-parent rules.
-  // URL-based: hrefs and location.pathname both carry the base + locale
-  // prefix, so they compare directly without stripping.
-  function applyActiveNav() {
-    var nav = document.querySelector("[data-header-nav]");
-    if (!nav) return;
-    var topItems = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
-    if (topItems.length === 0) return;
-
-    var cur = trimSlashes(location.pathname);
-
-    // Deepest (longest) nav path the current URL lives under, across both
-    // top-level and dropdown-child paths — matches computeActiveNavPath.
-    var activePath = "";
-    topItems.forEach(function (it) {
-      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
-      var topA = isDropdown ? it.querySelector(":scope > a") : it;
-      if (topA) {
-        var tp = navPathname(topA);
-        if (isUnderPath(cur, tp) && tp.length > activePath.length) activePath = tp;
-      }
-      if (isDropdown) {
-        it.querySelectorAll(":scope > div a").forEach(function (c) {
-          var cp = navPathname(c);
-          if (isUnderPath(cur, cp) && cp.length > activePath.length) activePath = cp;
-        });
-      }
-    });
-
-    function setTopActive(a, active) {
-      if (!a) return;
-      if (active) {
-        a.classList.add(${clsArgs(NAV_TOP_ACTIVE)});
-        a.classList.remove(${clsArgs(NAV_TOP_INACTIVE)});
-        a.setAttribute("aria-current", "page");
-      } else {
-        a.classList.remove(${clsArgs(NAV_TOP_ACTIVE)});
-        a.classList.add(${clsArgs(NAV_TOP_INACTIVE)});
-        a.removeAttribute("aria-current");
-      }
-    }
-
-    topItems.forEach(function (it) {
-      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
-      var topA = isDropdown ? it.querySelector(":scope > a") : it;
-      var topActive = false;
-
-      if (isDropdown) {
-        var parentMatch = !!topA && navPathname(topA) === activePath && activePath !== "";
-        var anyChild = false;
-        it.querySelectorAll(":scope > div a").forEach(function (c) {
-          var childActive = navPathname(c) === activePath && activePath !== "";
-          if (childActive) {
-            anyChild = true;
-            c.setAttribute("data-active", "");
-            c.classList.add(${clsArgs(NAV_CHILD_ACTIVE)});
-            c.classList.remove(${clsArgs(NAV_CHILD_INACTIVE)});
-          } else {
-            c.removeAttribute("data-active");
-            c.classList.remove(${clsArgs(NAV_CHILD_ACTIVE)});
-            c.classList.add(${clsArgs(NAV_CHILD_INACTIVE)});
-          }
-        });
-        topActive = parentMatch || anyChild;
-        var svg = topA ? topA.querySelector("svg") : null;
-        if (svg) {
-          if (topActive) { svg.classList.add(${clsArgs(NAV_CHEVRON_ACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_INACTIVE)}); }
-          else { svg.classList.add(${clsArgs(NAV_CHEVRON_INACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_ACTIVE)}); }
-        }
-      } else {
-        topActive = activePath !== "" && navPathname(topA) === activePath;
-      }
-
-      setTopActive(topA, topActive);
-    });
-  }
-
-  function initNavOverflow() {
-    if (cleanupNavOverflow) cleanupNavOverflow();
-
-    // Repaint the active highlight for the current URL before measuring /
-    // cloning, so the overflow "···" menu mirrors the correct active state.
-    applyActiveNav();
-
-    var nav = document.querySelector("[data-header-nav]");
-    var moreContainer = document.querySelector("[data-nav-more]");
-    var moreMenu = document.querySelector("[data-nav-more-menu]");
-    var moreToggle = document.querySelector("[data-nav-more-toggle]");
-    if (!nav || !moreContainer || !moreMenu || !moreToggle) return;
-
-    var items = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
-    if (items.length === 0) return;
-
-    var controller = new AbortController();
-
-    function update() {
-      items.forEach(function (el) { el.style.display = ""; });
-      moreContainer.style.display = "";
-      moreMenu.innerHTML = "";
-      moreMenu.classList.add("hidden");
-      moreToggle.setAttribute("aria-expanded", "false");
-
-      var itemWidths = items.map(function (el) { return el.offsetWidth; });
-      var moreWidth = moreContainer.offsetWidth;
-      var navGap = parseFloat(getComputedStyle(nav).columnGap) || 0;
-      var available = nav.clientWidth;
-
-      if (available <= 0) {
-        moreContainer.style.display = "none";
-        return;
-      }
-
-      var total = 0;
-      for (var i = 0; i < itemWidths.length; i++) {
-        total += itemWidths[i] + (i > 0 ? navGap : 0);
-      }
-
-      if (total <= available) {
-        moreContainer.style.display = "none";
-        return;
-      }
-
-      var used = 0;
-      var cutoffIndex = 0;
-
-      for (var i2 = 0; i2 < items.length; i2++) {
-        var w = itemWidths[i2] + (i2 > 0 ? navGap : 0);
-        if (used + w > available - moreWidth - navGap) break;
-        used += w;
-        cutoffIndex = i2 + 1;
-      }
-
-      for (var i3 = cutoffIndex; i3 < items.length; i3++) {
-        items[i3].style.display = "none";
-      }
-
-      for (var i4 = cutoffIndex; i4 < items.length; i4++) {
-        var el = items[i4];
-        var isDropdown = el.hasAttribute("data-nav-item-dropdown");
-
-        if (isDropdown) {
-          var parentLink = el.querySelector(":scope > a");
-          var childLinks = el.querySelectorAll(":scope > div a");
-          if (parentLink) {
-            var li = document.createElement("li");
-            var a = document.createElement("a");
-            a.href = parentLink.href;
-            var parentText = parentLink.textContent ? parentLink.textContent.trim().replace(/\\s+/g, " ") : "";
-            a.textContent = parentText;
-            a.className = ${clsLiteral(NAV_MENU_PARENT)};
-            if (parentLink.getAttribute("aria-current") === "page") {
-              a.className += ${clsAppend(NAV_MENU_PARENT_ACTIVE_SUFFIX)};
-            }
-            li.appendChild(a);
-            moreMenu.appendChild(li);
-          }
-          childLinks.forEach(function (child) {
-            var li = document.createElement("li");
-            var a = document.createElement("a");
-            a.href = child.href;
-            a.textContent = child.textContent ? child.textContent.trim() : "";
-            var isChildActive = child.hasAttribute("data-active");
-            a.className = isChildActive
-              ? ${clsLiteral(NAV_MENU_CHILD_ACTIVE)}
-              : ${clsLiteral(NAV_MENU_CHILD_INACTIVE)};
-            li.appendChild(a);
-            moreMenu.appendChild(li);
-          });
-        } else {
-          var anchor = el;
-          var li2 = document.createElement("li");
-          var a2 = document.createElement("a");
-          a2.href = anchor.href;
-          a2.textContent = anchor.textContent ? anchor.textContent.trim() : "";
-          a2.className = ${clsLiteral(NAV_MENU_PLAIN)};
-          if (anchor.getAttribute("aria-current") === "page") {
-            a2.className += ${clsAppend(NAV_MENU_PLAIN_ACTIVE_SUFFIX)};
-          }
-          li2.appendChild(a2);
-          moreMenu.appendChild(li2);
-        }
-      }
-    }
-
-    moreToggle.addEventListener("click", function () {
-      var isOpen = !moreMenu.classList.contains("hidden");
-      moreMenu.classList.toggle("hidden", isOpen);
-      moreToggle.setAttribute("aria-expanded", String(!isOpen));
-    }, { signal: controller.signal });
-
-    document.addEventListener("click", function (e) {
-      if (!moreContainer.contains(e.target)) {
-        moreMenu.classList.add("hidden");
-        moreToggle.setAttribute("aria-expanded", "false");
-      }
-    }, { signal: controller.signal });
-
-    document.addEventListener("keydown", function (e) {
-      if (e.key !== "Escape") return;
-      if (!moreMenu.classList.contains("hidden")) {
-        moreMenu.classList.add("hidden");
-        moreToggle.setAttribute("aria-expanded", "false");
-        moreToggle.focus();
-        return;
-      }
-      var active = document.activeElement;
-      var dropdown = active && active.closest ? active.closest("[data-nav-item-dropdown]") : null;
-      if (dropdown && active && active.blur) {
-        active.blur();
-      }
-    }, { signal: controller.signal });
-
-    var dropdowns = nav.querySelectorAll("[data-nav-item-dropdown]");
-    dropdowns.forEach(function (dd) {
-      var trigger = dd.querySelector(":scope > a");
-      if (!trigger) return;
-      function setExpanded(v) {
-        trigger.setAttribute("aria-expanded", String(v));
-      }
-      dd.addEventListener("mouseenter", function () { setExpanded(true); }, { signal: controller.signal });
-      dd.addEventListener("mouseleave", function () { setExpanded(false); }, { signal: controller.signal });
-      dd.addEventListener("focusin", function () { setExpanded(true); }, { signal: controller.signal });
-      dd.addEventListener("focusout", function (e) {
-        if (!dd.contains(e.relatedTarget)) {
-          setExpanded(false);
-        }
-      }, { signal: controller.signal });
-    });
-
-    var ro = new ResizeObserver(update);
-    ro.observe(nav);
-    controller.signal.addEventListener("abort", function () { ro.disconnect(); });
-
-    document.fonts.ready.then(update);
-
-    update();
-
-    cleanupNavOverflow = function () { controller.abort(); };
-  }
-
-  initNavOverflow();
-  document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, initNavOverflow);
-})();`;
+//
+// FROZEN (zudolab/zudo-doc#3534, epic #3533): the script body used to be
+// assembled here, at module-eval time, from three `Function.prototype.toString()`
+// embeddings (`CURRENT_PATH_SCRIPT_PRELUDE`, `pathMatchesNavPath`,
+// `computeActiveNavPath`) plus splice formatters over the twelve
+// `nav-class-tokens.ts` arrays. That made the emitted bytes depend on the
+// CONSUMING bundler (zudolab/zudo-doc#3502), so no CSP hash could be pinned
+// against a stable value. The assembly logic now lives in
+// `scripts/gen-nav-overflow-script.mjs`, which freezes it ONCE at package
+// build time into the committed `./nav-overflow-generated-script.ts` literal
+// re-exported below. Regenerate via
+// `pnpm --filter @takazudo/zudo-doc gen:nav-overflow-script` after editing
+// any of the four source files it reads from (see the generator's header
+// comment for the list); the vitest guard at
+// `src/header/__tests__/nav-overflow-script.test.ts` proves the committed
+// literal still matches a fresh regeneration.
+//
+// EJECTED COPIES (`zudo-doc eject header`): the generator is NOT shipped, so
+// in an ejected tree the re-exported literal is permanently frozen — editing
+// the ejected `./nav-class-tokens.ts` or `./nav-active.ts` changes the SSR
+// markup (header.tsx imports them live) but NOT this client script, breaking
+// the SSR ↔ runtime class lockstep those files exist to guarantee. To change
+// the client script in an ejected copy, edit the literal in
+// `./nav-overflow-generated-script.ts` directly (it is plain JS in a string)
+// and keep it in step with your token edits by hand.
+export { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-generated-script.js";

package/eject/sidebar-toggle-island/index.tsx

@@ -7,10 +7,22 @@
 import { useState, useEffect } from "preact/hooks";
 // After zudolab/zudo-doc#1335 the host components pull lifecycle event names
 // from the v2 transitions module rather than hard-coding `astro:*` literals.
-import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+// `ensureNestedIslandPropsRefresh` is imported through the barrel (not the
+// deep `./nested-island-props-refresh.js` path) on purpose: eject rewrites
+// EVERY `../transitions/<anything>.js` import to the single specifier
+// `@takazudo/zudo-doc/transitions`, so two distinct relative imports would
+// collapse into duplicate import statements in an ejected copy.
+import { AFTER_NAVIGATE_EVENT, ensureNestedIslandPropsRefresh } from "../transitions/index.js";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
 import type { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink } from "../sidebar/types.js";
 
+// This island lives INSIDE the persisted `<header>`, so a same-locale swap
+// lifts it verbatim and would re-mount it from the previous page's serialized
+// props (zudolab/zudo-doc#3525). The refresh has to outlive the island's own
+// mount/unmount cycle across a swap, so it is installed at document lifetime
+// here rather than from an effect. SSR evaluation is a safe no-op.
+ensureNestedIslandPropsRefresh();
+
 const cx = (...classes: Array<string | false | null | undefined>) =>
   classes.filter(Boolean).join(" ");
 

package/eject/sidebar-tree-island/index.tsx

@@ -18,6 +18,7 @@ import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
+import { CURRENT_PATH_DATASET_KEY, readCurrentPath } from "../current-path/index.js";
 import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
 
 // The persisted aside can transiently tear down and re-mount its SidebarTree
@@ -61,38 +62,54 @@ function saveOpenSet(set: Set<string>) {
 }
 
 /**
- * Derive the active slug from the current document URL. Used as a hydration-
- * time fallback when the parent island does not forward `currentSlug` through
- * its prop boundary, and at every View Transition to keep the highlight in
- * sync.
+ * Derive the active slug from an explicit current-route input. Resolution
+ * order is owned by {@link readCurrentPath}: the `pathname` argument, then the
+ * `data-zd-current-path` override, then `window.location.pathname`. Used as a
+ * hydration-time fallback when the parent island does not forward
+ * `currentSlug` through its prop boundary, and at every View Transition to
+ * keep the highlight in sync.
+ *
+ * Returns `undefined` both when no pathname is resolvable AND when the
+ * resolved pathname matches no route (e.g. the literal "srcdoc") — callers
+ * must treat `undefined` as "no update," preserving whatever active slug is
+ * already set rather than clearing it.
  */
-function deriveActiveSlugFromUrl(nodes: SidebarNavNode[]): string | undefined {
-  if (typeof window === "undefined") return undefined;
-  const pathname = normalizePath(window.location.pathname);
-  return findActiveSlug(nodes, pathname);
+function deriveActiveSlug(nodes: SidebarNavNode[], pathname?: string): string | undefined {
+  // An empty-string `pathname` must fall through to the live sources instead
+  // of silently disabling derivation — SidebarWithDefaults defaults its own
+  // currentPath to "", so "" is the natural absent shape.
+  const resolved = readCurrentPath(CURRENT_PATH_DATASET_KEY, pathname);
+  if (!resolved) return undefined;
+  return findActiveSlug(nodes, normalizePath(resolved));
 }
 
 /**
  * Track the current active slug, updating on View Transition navigations.
  *
  * The initial-state initialiser prefers the SSR-supplied `initial` prop, but
- * falls back to deriving the slug from `window.location.pathname` when the
- * prop is missing.
+ * falls back to `deriveActiveSlug` (explicit `currentPath` input, then the
+ * override/location fallbacks) when the prop is missing.
  */
-function useActiveSlug(nodes: SidebarNavNode[], initial?: string): string | undefined {
+function useActiveSlug(nodes: SidebarNavNode[], initial?: string, currentPath?: string): string | undefined {
   const [slug, setSlug] = useState<string | undefined>(() =>
-    initial !== undefined ? initial : deriveActiveSlugFromUrl(nodes),
+    initial !== undefined ? initial : deriveActiveSlug(nodes, currentPath),
   );
 
   useEffect(() => {
-    const update = () => {
-      const found = deriveActiveSlugFromUrl(nodes);
+    const update = (pathname?: string) => {
+      const found = deriveActiveSlug(nodes, pathname);
       if (found !== undefined) setSlug(found);
     };
-    update();
-    document.addEventListener(AFTER_NAVIGATE_EVENT, update);
-    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, update);
-  }, [nodes]);
+    // The static `currentPath` prop is an SSR-serialized value for the page the
+    // island first hydrated on — valid at hydration time only. Post-navigation
+    // updates must re-read the LIVE sources (dataset override, then
+    // location.pathname); recomputing from the frozen prop would pin the
+    // highlight to the first-loaded page across client-router navigations.
+    const onNavigate = () => update();
+    update(currentPath);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+  }, [nodes, currentPath]);
 
   return slug;
 }
@@ -143,6 +160,13 @@ function RootMenuItemEntry({ item }: { item: SidebarRootMenuItem }) {
 export interface SidebarTreeProps {
   nodes: SidebarNavNode[];
   currentSlug?: string;
+  /**
+   * Explicit current-route override, checked before the
+   * `data-zd-current-path` dataset override and `window.location.pathname`
+   * when deriving the active slug on hydration and at every View Transition.
+   * See `deriveActiveSlug` (zudolab/zudo-doc#3398).
+   */
+  currentPath?: string;
   rootMenuItems?: SidebarRootMenuItem[];
   backToMenuLabel?: string;
   localeLinks?: SidebarLocaleLink[];
@@ -171,8 +195,8 @@ function SidebarFooter({ links, themeDefaultMode }: { links?: SidebarLocaleLink[
   );
 }
 
-export function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps) {
-  const activeSlug = useActiveSlug(nodes, currentSlug);
+export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps) {
+  const activeSlug = useActiveSlug(nodes, currentSlug, currentPath);
   const [query, setQuery] = useState("");
   const [showingRootMenu, setShowingRootMenu] = useState(false);
   const filterRef = useRef<HTMLInputElement>(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.5.3",
+  "version": "5.7.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",
@@ -239,6 +239,10 @@
       "types": "./dist/catalog.d.ts",
       "default": "./dist/catalog.js"
     },
+    "./site-schema": {
+      "types": "./dist/site-schema/index.d.ts",
+      "default": "./dist/site-schema/index.js"
+    },
     "./theme.css": "./dist/theme.css",
     "./safelist.css": "./dist/safelist.css",
     "./content.css": "./dist/content.css",
@@ -553,6 +557,10 @@
       "types": "./dist/sidebar-active-slug/index.d.ts",
       "default": "./dist/sidebar-active-slug/index.js"
     },
+    "./current-path": {
+      "types": "./dist/current-path/index.d.ts",
+      "default": "./dist/current-path/index.js"
+    },
     "./i18n-defaults": {
       "types": "./dist/i18n-defaults/index.d.ts",
       "default": "./dist/i18n-defaults/index.js"
@@ -609,11 +617,11 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@takazudo/zdtp": "^0.4.10",
-    "@takazudo/zfb": "^2.5.2",
-    "@takazudo/zfb-md-wasm": "^2.5.2",
-    "@takazudo/zfb-runtime": "^2.5.2",
-    "@takazudo/zudo-doc-history-server": "^5.5.2",
+    "@takazudo/zdtp": "^0.4.11",
+    "@takazudo/zfb": "^2.7.1",
+    "@takazudo/zfb-md-wasm": "^2.7.1",
+    "@takazudo/zfb-runtime": "^2.7.1",
+    "@takazudo/zudo-doc-history-server": "^5.5.3",
     "diff": "^8.0.0",
     "katex": "^0.16.0",
     "preact": "^10.29.1",
@@ -647,14 +655,15 @@
     "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@takazudo/zfb": "2.5.2",
-    "@takazudo/zfb-md-wasm": "2.5.2",
-    "@takazudo/zfb-runtime": "2.5.2",
+    "@takazudo/zfb": "2.7.1",
+    "@takazudo/zfb-md-wasm": "2.7.1",
+    "@takazudo/zfb-runtime": "2.7.1",
     "@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",
+    "esbuild": ">=0.28.1",
     "happy-dom": "^20.10.6",
     "npm-run-all2": "^7.0.2",
     "preact": "^10.29.1",
@@ -663,15 +672,19 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.5.3"
+    "@takazudo/zudo-doc-history-server": "5.7.0"
   },
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
-    "predev": "node ../../scripts/ensure-workspace-build.mjs",
+    "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",
+    "gen:nav-overflow-script": "node scripts/gen-nav-overflow-script.mjs",
+    "build": "node scripts/gen-search-widget-script.mjs && node scripts/gen-nav-overflow-script.mjs && tsup && tsc -p tsconfig.build.json",
+    "predev": "node ../../scripts/ensure-workspace-build.mjs && node scripts/gen-search-widget-script.mjs && node scripts/gen-nav-overflow-script.mjs",
     "// dev": "Do NOT add `--continue-on-error` here. It stops a fatal watcher exit from cascading, but the dead watcher then fails silently — a dead dev:dts leaves dist/*.d.ts frozen while the JS keeps updating, which typechecks cleanly against stale types instead of failing loudly like #3113's absent declarations did. See the #3129 section in CLAUDE.md.",
     "dev": "run-p dev:js dev:dts",
     "dev:js": "tsup --watch",
     "dev:dts": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "// check:prepack-contract": "check:search-widget-drift and check:nav-overflow-drift run here (not just b4push/CI) because `prepare` regenerates BOTH frozen literals unconditionally — without a prepack gate, packing from a tree where a source changed but a literal was never re-committed would silently publish new script bytes and break every consumer's pinned CSP hash (#3534/#3535 for nav-overflow; #3540 extended the same gate to search-widget, the exact failure class the freezes exist to prevent).",
+    "check:prepack-contract": "pnpm --dir ../.. check:search-widget-drift && pnpm --dir ../.. check:nav-overflow-drift && pnpm --dir ../.. gen:changelog && node scripts/check-theme-css.mjs && node scripts/check-safelist.mjs && node scripts/check-content-css.mjs && node scripts/check-page-loading-css.mjs && node scripts/check-features-css.mjs && node scripts/check-theme-packs.mjs && node scripts/check-catalog.mjs && node scripts/check-site-schema.mjs && node scripts/check-plugins.mjs && node scripts/check-plugin-resolution.mjs && node scripts/check-eject-sources.mjs && node scripts/check-routes-src.mjs && node scripts/check-shim-artifacts.mjs && node scripts/check-virtual-modules.mjs && node bin/gen-component-tokens.mjs --check",
     "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",

package/routes-src/_chrome.tsx

@@ -13,7 +13,7 @@
 import { routeCtx } from "./_context.js";
 import { createChrome } from "@takazudo/zudo-doc/chrome";
 import { DocHistory } from "@takazudo/zudo-doc/doc-history";
-import type { DocNavNode } from "./_docs-helpers.js";
+import type { DocNavNode } from "@takazudo/zudo-doc/site-schema";
 // 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
@@ -27,6 +27,10 @@ import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
 // ("Host-callables channel — chromeBindingsModule"). Not present on disk; the
 // package ships ambient typings for it (`routes/_virtual.d.ts`).
 import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
+// Routes-only configured design-token-panel island (#3396) — the ONLY importer
+// of `virtual:zudo-doc-design-token-panel-config` in the package. Static, for
+// the same island-scanner reason as `DocHistory` above.
+import { ConfiguredDesignTokenPanelBootstrap } from "./_design-token-panel-bootstrap.js";
 
 // Island-scanner contract (load-bearing): the injected doc routes reach the real
 // DocHistory client island ONLY through this static import → `createChrome`
@@ -57,15 +61,23 @@ import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 // 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`.
+// `DesignTokenPanelBootstrap` IS threaded here since #3396, but only to swap
+// the BUILDER — the mount, the settings gate, and the slot default all still
+// belong to `chrome/derive.tsx`'s `deriveBodyEndIslands` (gate-2 fix from the
+// Wave-5 confirm #2659), so the locked-manifest self-contained doc stub (#2653)
+// and every other bare `createChrome` caller keep getting the package-default
+// island with no explicit wiring. On THESE injected routes the configured
+// wrapper wins, which is what carries a host's
+// `settings.designTokenPanelConfigModule` through. Scanner reachability holds
+// through the static chain route → this shim → `_design-token-panel-bootstrap`.
+//
+// It is spread BEFORE `...chromeBindings` (unlike `DocHistory`, which is spread
+// after): a host's own `DesignTokenPanelBootstrap` slot value must still win,
+// exactly as it did when the derive-level default was the only package wiring.
 const chrome = createChrome(routeCtx, {
+  ...defineChromeBindings({
+    DesignTokenPanelBootstrap: ConfiguredDesignTokenPanelBootstrap,
+  }),
   ...chromeBindings,
   ...defineChromeBindings({ DocHistory }),
 });