@takazudo/zudo-doc 5.5.3 → 5.6.0

package/dist/theme/theme-pack-provider.js

@@ -11,6 +11,9 @@ import {
   THEME_PACK_STORAGE_KEY,
   buildPackCssUrl
 } from "../theme-pack-switcher/theme-pack-sync.js";
+const THEME_PACK_LOADING_ATTR = "data-zd-theme-pack-loading";
+const THEME_PACK_LOAD_WATCHDOG_MS = 2e3;
+const THEME_PACK_LATCH_CSS = `html[${THEME_PACK_LOADING_ATTR}] body{visibility:hidden}`;
 function themePackVersionMap(registry) {
   const map = {};
   for (const entry of registry) {
@@ -33,6 +36,8 @@ function buildThemePackBootstrap(configuredSlug, enabled, base) {
   const runtimeGlobal = JSON.stringify(THEME_PACK_RUNTIME_GLOBAL);
   const afterNav = JSON.stringify(AFTER_NAVIGATE_EVENT);
   const beforeSwap = JSON.stringify(BEFORE_SWAP_EVENT);
+  const loadingAttr = JSON.stringify(THEME_PACK_LOADING_ATTR);
+  const watchdog = JSON.stringify(THEME_PACK_LOAD_WATCHDOG_MS);
   return `(function(){
 var configured=${configured};
 var packs=${packs};
@@ -40,12 +45,31 @@ var base=${b};
 var KEY=${key};
 var ATTR=${attr};
 var LINK_ATTR=${linkAttr};
+var LOADING_ATTR=${loadingAttr};
+var WATCHDOG=${watchdog};
 var DEFAULT_SLUG=${defaultSlug};
 function resolveSlug(){var stored=null;try{stored=localStorage.getItem(KEY);}catch(e){}if(stored&&Object.prototype.hasOwnProperty.call(packs,stored))return stored;var live=document.documentElement.getAttribute(ATTR);if(live&&Object.prototype.hasOwnProperty.call(packs,live))return live;return configured;}
 function packHref(slug){return base+"theme-packs/"+slug+"/pack.css?v="+packs[slug];}
+function hasPackLink(href){var ls=document.querySelectorAll("link["+LINK_ATTR+"]");for(var i=0;i<ls.length;i++){if(ls[i].getAttribute("href")===href)return true;}return false;}
 var slug=resolveSlug();
-document.documentElement.setAttribute(ATTR,slug);
-if(slug!==DEFAULT_SLUG){document.write('<link rel="stylesheet" '+LINK_ATTR+' href="'+packHref(slug)+'">');}
+var root=document.documentElement;
+root.setAttribute(ATTR,slug);
+if(slug!==DEFAULT_SLUG){
+var href=packHref(slug);
+if(!hasPackLink(href)){
+var shouldLatch=document.readyState==="loading";
+if(shouldLatch){root.setAttribute(LOADING_ATTR,"");}
+var release=function(){root.removeAttribute(LOADING_ATTR);};
+var link=document.createElement("link");
+link.setAttribute("rel","stylesheet");
+link.setAttribute(LINK_ATTR,"");
+link.setAttribute("href",href);
+link.onload=release;
+link.onerror=release;
+document.head.appendChild(link);
+if(shouldLatch){setTimeout(release,WATCHDOG);}
+}
+}
 window[${runtimeGlobal}]={base:base,packs:packs,configured:configured};
 document.addEventListener(${beforeSwap},function(e){
 var s=resolveSlug();
@@ -81,11 +105,15 @@ function ThemePackProvider({
   const configuredVersion = enabled[configuredSlug];
   const noscriptHref = configuredSlug !== DEFAULT_THEME_PACK_SLUG && configuredVersion !== void 0 ? buildPackCssUrl(base, configuredSlug, configuredVersion) : null;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: THEME_PACK_LATCH_CSS } }),
     /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: bootstrap } }),
     noscriptHref !== null && /* @__PURE__ */ jsx("noscript", { children: /* @__PURE__ */ jsx("link", { rel: "stylesheet", href: noscriptHref }) })
   ] });
 }
 export {
+  THEME_PACK_LATCH_CSS,
+  THEME_PACK_LOADING_ATTR,
+  THEME_PACK_LOAD_WATCHDOG_MS,
   buildThemePackBootstrap,
   ThemePackProvider as default,
   resolveThemePackSsrSlug,

package/eject/header/nav-active.ts

@@ -53,13 +53,25 @@ export function pathForMatch(
 /**
  * Segment-aware prefix test: nav path `/docs/guides` matches `/docs/guides`
  * and `/docs/guides/...` but NOT `/docs/guideship`.
+ *
+ * Exported (not just module-private) so `nav-overflow-script.ts` can embed it
+ * verbatim via `.toString()` alongside `computeActiveNavPath` — that function
+ * closes over this one, so a bare `computeActiveNavPath.toString()` embed
+ * would reference an undefined `pathMatchesNavPath` in the browser (see the
+ * caution note on `computeActiveNavPath` below). Kept self-contained (no
+ * outer references) for the same reason.
  */
-function pathMatchesNavPath(currentPath: string, navPath: string): boolean {
+export function pathMatchesNavPath(currentPath: string, navPath: string): boolean {
   if (currentPath === navPath) return true;
   const prefix = navPath.endsWith("/") ? navPath : `${navPath}/`;
   return currentPath.startsWith(prefix);
 }
 
+/**
+ * CAUTION (zudolab/zudo-doc#3398): this closes over `pathMatchesNavPath`
+ * above. `nav-overflow-script.ts` embeds both via `.toString()` (never this
+ * one alone) so the generated browser script is self-contained.
+ */
 export function computeActiveNavPath(
   navItems: readonly NavItemLike[],
   pathForMatchValue: string,

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

@@ -31,6 +31,8 @@
 // script can be reviewed in isolation.
 
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import { CURRENT_PATH_SCRIPT_PRELUDE } from "../current-path/index.js";
+import { computeActiveNavPath, pathMatchesNavPath } from "./nav-active.js";
 import {
   NAV_CHEVRON_ACTIVE,
   NAV_CHEVRON_INACTIVE,
@@ -78,20 +80,26 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
     catch (e) { return ""; }
   }
 
-  function isUnderPath(cur, p) {
-    if (!p) return false;
-    if (cur === p) return true;
-    return p !== "/" && cur.indexOf(p + "/") === 0;
-  }
+  // Explicit current-route override, embedded from current-path/index.ts so
+  // this script cannot drift from the three other read sites
+  // (zudolab/zudo-doc#3398, #3408).
+  ${CURRENT_PATH_SCRIPT_PRELUDE}
+
+  // Shared matching core (zudolab/zudo-doc#3398): embedded verbatim from
+  // nav-active.ts so this script's longest-match walk cannot drift from the
+  // SSR header's own computeActiveNavPath call (header.tsx). computeActiveNavPath
+  // closes over pathMatchesNavPath, so both are embedded together.
+  var pathMatchesNavPath = ${pathMatchesNavPath.toString()};
+  var computeActiveNavPath = ${computeActiveNavPath.toString()};
 
   // 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
+  // sidebar island's client-side approach (match the current path against
   // each entry's href) and the SSR longest-match + dropdown-parent rules.
-  // URL-based: hrefs and location.pathname both carry the base + locale
+  // URL-based: hrefs and the current path both carry the base + locale
   // prefix, so they compare directly without stripping.
   function applyActiveNav() {
     var nav = document.querySelector("[data-header-nav]");
@@ -99,26 +107,31 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
     var topItems = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
     if (topItems.length === 0) return;
 
-    var cur = trimSlashes(location.pathname);
+    var cur = trimSlashes(readCurrentPath(CURRENT_PATH_DATASET_KEY));
 
-    // Deepest (longest) nav path the current URL lives under, across both
-    // top-level and dropdown-child paths — matches computeActiveNavPath.
-    var activePath = "";
+    // Build NavItemLike-shaped entries from the live DOM so the shared
+    // computeActiveNavPath can do the deepest-match walk — the same call
+    // shape the SSR header uses (matches computeActiveNavPath). A dropdown
+    // missing its own top-level anchor is skipped entirely (path "" would
+    // otherwise match every current path — pathMatchesNavPath treats "" as
+    // the root "/"), mirroring the parentLink guard used below for the same
+    // malformed-markup case.
+    var navItems = [];
     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 (!topA) return;
+      var children = [];
       if (isDropdown) {
         it.querySelectorAll(":scope > div a").forEach(function (c) {
-          var cp = navPathname(c);
-          if (isUnderPath(cur, cp) && cp.length > activePath.length) activePath = cp;
+          children.push({ path: navPathname(c) });
         });
       }
+      navItems.push({ path: navPathname(topA), children: children });
     });
 
+    var activePath = computeActiveNavPath(navItems, cur) || "";
+
     function setTopActive(a, active) {
       if (!a) return;
       if (active) {

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.6.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,11 +672,12 @@
     "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.6.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",
+    "build": "node scripts/gen-search-widget-script.mjs && tsup && tsc -p tsconfig.build.json",
+    "predev": "node ../../scripts/ensure-workspace-build.mjs && node scripts/gen-search-widget-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",

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 }),
 });

package/routes-src/_design-token-panel-bootstrap.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// routes/_design-token-panel-bootstrap — the ROUTES-ONLY configured
+// design-token-panel island (#3396, epic #3394).
+//
+// WHY THIS FILE EXISTS: `virtual:zudo-doc-design-token-panel-config` is
+// registered by the routes plugin, so any module that imports it statically
+// drags the plugin along as a hard requirement. Until #3396 that importer was
+// `../design-token-panel-bootstrap.tsx`, which `chrome/derive.tsx` imports —
+// meaning `@takazudo/zudo-doc/chrome` could not be bundled outside a zfb build
+// (or by a `packageOwnedRoutes: false` host) without aliasing the specifier.
+// Moving the import HERE confines it to the routes graph, which zfb always
+// bundles with the plugin active.
+//
+// WHY A COMPONENT AND NOT A SETTER: the route/SSR module graph and the
+// hydrated island bundle are SEPARATE graphs. A `setPanelConfigBuilder(...)`
+// called while `_chrome.tsx` evaluates would configure only the server-side
+// copy of the bootstrap module; the client bundle re-evaluates that module
+// independently and would keep the package default. Passing the builder as an
+// argument from a component that lives INSIDE the island bundle is the only
+// shape that survives the boundary.
+//
+// ISLAND-SCANNER CONTRACT (#2480 lesson): `_chrome.tsx` imports this module
+// STATICALLY and threads the component into `hostBindings`, so the scanner
+// walks route → _chrome → here. The exported binding identifier and the
+// `displayName` must stay IDENTICAL — zfb registers islands by the
+// scanner-visible export name, and a marker whose name has no registry entry
+// silently never hydrates. The name must also stay DISTINCT from
+// `DesignTokenPanelBootstrap`: `chrome/derive.tsx` still statically imports
+// that package default (it is the slot default for bare `createChrome`
+// callers), so both components are in the scanned graph and a shared name
+// would trip zfb's "island marker name collision" warning and drop one of them.
+
+import type { JSX } from "preact";
+import { runDesignTokenPanelBootstrapOnce } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
+// Host-callables channel, third virtual module (#2658, mirrors #2501's
+// chromeBindingsModule): absent `settings.designTokenPanelConfigModule` →
+// re-exports the package default (`@takazudo/zudo-doc/design-token-panel-config`);
+// present → re-exports the host's module. Registered unconditionally by the
+// routes plugin (`../plugins/routes.ts`) whenever `packageOwnedRoutes` is on.
+// Not present on disk; the package ships ambient typings for it
+// (`./_virtual.d.ts`).
+import { buildDesignTokenPanelConfig } from "virtual:zudo-doc-design-token-panel-config";
+
+/**
+ * The design-token-panel island injected routes mount instead of the package
+ * default: identical behavior, except the mode-scoped `PanelConfig` builder is
+ * the one the routes plugin resolved — the host's
+ * `settings.designTokenPanelConfigModule` when set, the package default
+ * otherwise.
+ *
+ * Renders `null` on both SSR and client (the panel self-mounts as a side
+ * effect of `bootstrapDesignTokenPanel`), matching the package default's
+ * non-`ssrFallback` `Island({ when: "load" })` shape.
+ */
+export function ConfiguredDesignTokenPanelBootstrap(): JSX.Element | null {
+  runDesignTokenPanelBootstrapOnce(buildDesignTokenPanelConfig, "configured");
+  return null;
+}
+ConfiguredDesignTokenPanelBootstrap.displayName = "ConfiguredDesignTokenPanelBootstrap";