@takazudo/zudo-doc 3.3.0 → 4.1.0

package/dist/design-token-panel-bootstrap.d.ts

@@ -6,25 +6,17 @@
  *
  * `bootstrapDesignTokenPanel` is a callable that configures zdtp's panel and
  * wires its lifecycle hooks to zfb's navigation events via
- * `setLifecycleAdapter()`. Projects import it with their own PanelConfig
- * DATA — which stays project-side (or, since #2658, the PACKAGE-DEFAULT data
- * from `@takazudo/zudo-doc/design-token-panel-config`).
+ * `setLifecycleAdapter()`. It receives a mode-scoped PanelConfig builder —
+ * either a project override or the package default from
+ * `@takazudo/zudo-doc/design-token-panel-config`.
  *
- * Two calling shapes (both supported):
+ * The current call shape is a mode-scoped builder. It rebuilds the panel per
+ * light/dark mode on every `color-scheme-changed` toggle:
  *
- *   // Mode-scoped builder — rebuilds the panel per light/dark mode on every
- *   // `color-scheme-changed` toggle:
  *   import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
  *   import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
  *   bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
  *
- *   // Plain config (back-compat — generated projects on the old shape):
- *   import { designTokenPanelConfig } from "@/config/design-token-panel-config";
- *   bootstrapDesignTokenPanel(designTokenPanelConfig);
- *
- * A plain-config caller gets NO toggle listener (a static config has nothing to
- * rebuild), so existing generated projects keep working with zero changes.
- *
  * `DesignTokenPanelBootstrap` (below) is the PACKAGE-OWNED island component
  * that wires the mode-scoped builder for package-owned routes with no host
  * config file — the #2658 "Approach (a)" package default. It resolves its
@@ -32,27 +24,25 @@
  * module the routes plugin registers (`../plugins/routes.ts`): absent a host
  * `designTokenPanelConfigModule` override, that resolves to
  * `@takazudo/zudo-doc/design-token-panel-config`'s `buildDesignTokenPanelConfig`.
- * `packages/zudo-doc/src/routes/_chrome.tsx` statically imports it so zfb's
- * island scanner walks route → `_chrome` → here (mirrors the DocHistory
- * #2480 static-import chain). A host that ejects entirely (its own
- * `src/lib/*` + `src/components/*`, like the pre-#2658 showcase) never
- * reaches this component — it only calls `bootstrapDesignTokenPanel` itself,
- * same as always.
+ * `packages/zudo-doc/src/chrome/derive.tsx` statically imports it so zfb's
+ * island scanner walks route → chrome → derive → here (mirrors the DocHistory
+ * #2480 static-import contract). A host that ejects entirely can call
+ * `bootstrapDesignTokenPanel` with its own builder, but current package-owned
+ * routes use this component directly.
  *
  * KNOWN COUPLING: `DesignTokenPanelBootstrap`'s top-level import of
  * `virtual:zudo-doc-design-token-panel-config` requires the routes plugin
  * (`settings.packageOwnedRoutes`, default `true`) to be active in the
  * consuming project, since that plugin is what registers the virtual module.
  * A project that explicitly sets `packageOwnedRoutes: false` AND wants to
- * reuse the bare `bootstrapDesignTokenPanel` export for its own hand-wired
- * component (as every current consumer's `src/lib/design-token-panel-bootstrap.ts`
- * does) is unaffected — that import graph never reaches `DesignTokenPanelBootstrap`
- * — but a `packageOwnedRoutes: false` project must not import
- * `DesignTokenPanelBootstrap` itself.
+ * reuse the bare `bootstrapDesignTokenPanel` export for its own component is
+ * unaffected — that import graph never reaches `DesignTokenPanelBootstrap` —
+ * but a `packageOwnedRoutes: false` project must not import the package island
+ * component itself.
  *
- * Moved from the host's `src/lib/design-token-panel-bootstrap.ts` as part of
- * the package-first migration (S9a zudolab/zudo-doc#2333); mode-scoped rebuild
- * wiring added in zudolab/zudo-doc#2610; package-default island added in #2658.
+ * Package-first wiring landed in S9a zudolab/zudo-doc#2333; mode-scoped rebuild
+ * wiring was added in zudolab/zudo-doc#2610 and the package-default island in
+ * #2658.
  *
  * CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in the project's
  * `src/styles/global.css` so the panel chrome lands in the main page CSS
@@ -65,28 +55,43 @@ import { type PanelConfig } from "@takazudo/zdtp";
 /** Active color-scheme mode, read from `<html data-theme>`. */
 type ColorSchemeMode = "light" | "dark";
 /**
- * A per-mode PanelConfig factory. Supplied by hosts that want the panel's
- * defaults to follow the live light/dark mode (see `buildDesignTokenPanelConfig`
- * in the host's `design-token-panel-config.ts`).
+ * A per-mode PanelConfig factory. The package default and host overrides use
+ * this same shape so panel defaults follow the live light/dark mode.
  */
 export type PanelConfigBuilder = (mode: ColorSchemeMode) => PanelConfig;
+/**
+ * Theme-pack storage-prefix rule (ADR theme-packs.md Decision 4), enforced
+ * CENTRALLY here — never per-builder, so host builders supplied via
+ * `designTokenPanelConfigModule` cannot cross-contaminate namespaces even if
+ * unaware of packs:
+ *
+ * - active pack `default` → the builder's `storagePrefix` stays BYTE-UNCHANGED
+ *   (the existing-user carry-over guarantee: `zudo-doc-tweak` keys keep
+ *   working on the stock look).
+ * - any other pack → `${storagePrefix}--<slug>` (double hyphen avoids
+ *   colliding with zdtp's own `-open`/version suffixes). zdtp derives every
+ *   key — including the `${prefix}-open` open-state mirror — from the prefix,
+ *   so tweaks saved under pack A are invisible under pack B and restored
+ *   verbatim on switch-back.
+ *
+ * The `PanelConfigBuilder` signature stays `(mode) => PanelConfig` — this is a
+ * post-process of the RETURNED config, not a builder-contract change.
+ */
+export declare function withPackScopedStoragePrefix(config: PanelConfig, activePack: string): PanelConfig;
 /**
  * Bootstrap zdtp for a project. Configures the panel, drains any pre-hydration
  * click queue, and wires the zdtp lifecycle adapter to zfb's navigation events
  * so persisted token overrides re-apply on every soft navigation.
  *
- * When passed a `PanelConfigBuilder`, also wires a `color-scheme-changed`
- * listener that rebuilds the panel per light/dark mode (see the toggle sequence
- * below). When passed a plain `PanelConfig`, no toggle listener is registered.
- *
- * Call this once, as a side-effect import from the project's island wrapper
- * (`src/components/design-token-panel-bootstrap.tsx`).
+ * Wires a `color-scheme-changed` listener that rebuilds the panel per
+ * light/dark mode (see the toggle sequence below), and a parallel
+ * `theme-pack-changed` listener that rebuilds it per theme pack with a
+ * pack-scoped storage prefix (ADR theme-packs.md Decision 4, #2822).
  *
- * @param configOrBuilder - The project's `PanelConfig`, or a `(mode) =>
- *   PanelConfig` builder for mode-scoped rebuilds. DATA stays project-side in
- *   `src/config/design-token-panel-config.ts`.
+ * @param buildConfig - The project's `(mode) => PanelConfig` builder for
+ *   mode-scoped rebuilds.
  */
-export declare function bootstrapDesignTokenPanel(configOrBuilder: PanelConfig | PanelConfigBuilder): void;
+export declare function bootstrapDesignTokenPanel(buildConfig: PanelConfigBuilder): void;
 /**
  * The package-default `<DesignTokenPanelBootstrap/>` island: mounted (via
  * `Island({ when: "load" })`, no `ssrFallback` — it renders nothing on either

package/dist/design-token-panel-bootstrap.js

@@ -1,6 +1,7 @@
 "use client";
 import {
   configurePanel,
+  reapplyPersistedOverrides,
   setLifecycleAdapter,
   showDesignTokenPanel
 } from "@takazudo/zdtp";
@@ -8,37 +9,112 @@ import {
   BEFORE_NAVIGATE_EVENT,
   AFTER_NAVIGATE_EVENT
 } from "./transitions/page-events.js";
+import {
+  DEFAULT_THEME_PACK_SLUG,
+  THEME_PACK_CHANGED_EVENT,
+  readThemePackFromDom
+} from "./theme-pack-switcher/theme-pack-sync.js";
 import { buildDesignTokenPanelConfig } from "virtual:zudo-doc-design-token-panel-config";
 const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
 function openStateKey(instancePrefix) {
   return `${instancePrefix}-open`;
 }
+function readOpenState(instancePrefix) {
+  try {
+    return localStorage.getItem(openStateKey(instancePrefix)) === "1";
+  } catch {
+    return false;
+  }
+}
 function readMode() {
   return document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light";
 }
-function bootstrapDesignTokenPanel(configOrBuilder) {
-  if (typeof window === "undefined" || typeof document === "undefined") {
+function withPackScopedStoragePrefix(config, activePack) {
+  if (activePack === DEFAULT_THEME_PACK_SLUG) return config;
+  return { ...config, storagePrefix: `${config.storagePrefix}--${activePack}` };
+}
+function collectDeclaredTokenNames(config) {
+  const names = [];
+  for (const tab of config.tabs ?? []) {
+    for (const tier of tab.tiers ?? []) {
+      for (const item of tier.items ?? []) {
+        names.push(item.cssVar);
+      }
+    }
+    const baseRoles = tab.colorExtras?.baseRoles;
+    if (baseRoles) {
+      for (const cssVar of Object.values(baseRoles)) {
+        if (typeof cssVar === "string" && cssVar.length > 0) {
+          names.push(cssVar);
+        }
+      }
+    }
+  }
+  return names;
+}
+function clearAppliedTokenOverrides(config) {
+  const names = collectDeclaredTokenNames(config);
+  if (config.applySink) {
+    try {
+      config.applySink.clear(names);
+    } catch (err) {
+      console.warn(
+        "[zudo-doc] applySink.clear threw during theme-pack switch; outgoing overrides may linger.",
+        err
+      );
+    }
     return;
   }
-  const isBuilder = typeof configOrBuilder === "function";
-  const builder = isBuilder ? configOrBuilder : () => configOrBuilder;
-  let handle = configurePanel(builder(readMode()));
-  if (isBuilder) {
-    let pendingMode = readMode();
-    let timer = null;
-    window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, () => {
-      pendingMode = readMode();
-      if (timer !== null) return;
-      timer = setTimeout(() => {
-        timer = null;
-        const mode = pendingMode;
-        const wasOpen = localStorage.getItem(openStateKey(handle.instanceId)) === "1";
-        handle.destroy();
-        handle = configurePanel(builder(mode));
-        if (wasOpen) showDesignTokenPanel();
-      }, 0);
-    });
+  const style = document.documentElement.style;
+  for (const name of names) {
+    style.removeProperty(name);
+  }
+}
+function bootstrapDesignTokenPanel(buildConfig) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
   }
+  let currentConfig = withPackScopedStoragePrefix(
+    buildConfig(readMode()),
+    readThemePackFromDom()
+  );
+  let handle = configurePanel(currentConfig);
+  let pendingMode = readMode();
+  let timer = null;
+  window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, () => {
+    pendingMode = readMode();
+    if (timer !== null) return;
+    timer = setTimeout(() => {
+      timer = null;
+      const mode = pendingMode;
+      const wasOpen = readOpenState(handle.instanceId);
+      handle.destroy();
+      currentConfig = withPackScopedStoragePrefix(
+        buildConfig(mode),
+        readThemePackFromDom()
+      );
+      handle = configurePanel(currentConfig);
+      if (wasOpen) showDesignTokenPanel();
+    }, 0);
+  });
+  let pendingPack = readThemePackFromDom();
+  let packTimer = null;
+  window.addEventListener(THEME_PACK_CHANGED_EVENT, () => {
+    pendingPack = readThemePackFromDom();
+    if (packTimer !== null) return;
+    packTimer = setTimeout(() => {
+      packTimer = null;
+      const pack = pendingPack;
+      const wasOpen = readOpenState(handle.instanceId);
+      const outgoingConfig = currentConfig;
+      handle.destroy();
+      clearAppliedTokenOverrides(outgoingConfig);
+      currentConfig = withPackScopedStoragePrefix(buildConfig(readMode()), pack);
+      handle = configurePanel(currentConfig);
+      reapplyPersistedOverrides();
+      if (wasOpen) showDesignTokenPanel();
+    }, 0);
+  });
   window.__zdtpReadyClicks?.();
   const adapter = {
     onBeforeSwap(cb) {
@@ -65,5 +141,6 @@ function DesignTokenPanelBootstrap() {
 DesignTokenPanelBootstrap.displayName = "DesignTokenPanelBootstrap";
 export {
   DesignTokenPanelBootstrap,
-  bootstrapDesignTokenPanel
+  bootstrapDesignTokenPanel,
+  withPackScopedStoragePrefix
 };

package/dist/design-token-panel-config/index.js

@@ -200,10 +200,7 @@ function buildDesignTokenPanelConfig(mode) {
     // `SCHEMA_V3` constants (#498/#505), which are unrelated to this field.
     // It is thus a purely descriptive config value with no runtime effect;
     // set to v3 (a literal, not one of those constants) to match what real
-    // exports carry. Distinct from the host serde's `DESIGN_TOKEN_SCHEMA`
-    // (`zudo-doc-design-tokens/v3` — bumped from v2 in #2599 so a stale
-    // pre-5/3-minimize export resets instead of crashing on import), which
-    // governs a separate round-trip.
+    // exports carry.
     schemaId: "zudo-design-tokens/v3",
     exportFilenameBase: "zudo-doc-design-tokens",
     tabs: [buildPaletteTab(mode), buildColorTab(mode), buildFontTab(), buildSpacingTab(), buildSizeTab()]

package/dist/doc-body-end-islands/design-token-panel-island.d.ts

@@ -0,0 +1,15 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import type { FactoryComponent } from "../factory-context/index.js";
+export interface DesignTokenPanelIslandDeps {
+    designTokenPanel: boolean;
+    DesignTokenPanelBootstrap?: FactoryComponent;
+}
+/**
+ * Bind the current settings gate to the package-owned bootstrap island.
+ * Kept separate from the rest of the package body-end islands so a host
+ * BodyEndIslands override can be composed with this package-owned marker
+ * without duplicating the other package defaults.
+ */
+export declare function createDesignTokenPanelIsland(deps: DesignTokenPanelIslandDeps): () => JSX.Element | null;

package/dist/doc-body-end-islands/design-token-panel-island.js

@@ -0,0 +1,31 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { Island } from "@takazudo/zfb";
+const ZDTP_TOGGLE_SHIM_SRC = `(function(){
+if(window.__zdtpToggleShimInstalled)return;
+window.__zdtpToggleShimInstalled=true;
+var pending=false;
+function shim(){pending=true;}
+window.addEventListener('toggle-design-token-panel',shim);
+window.__zdtpReadyClicks=function(){
+window.removeEventListener('toggle-design-token-panel',shim);
+delete window.__zdtpReadyClicks;
+if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
+};
+})();`;
+function createDesignTokenPanelIsland(deps) {
+  const DesignTokenPanelBootstrap = deps.DesignTokenPanelBootstrap;
+  function DesignTokenPanelIsland() {
+    if (!deps.designTokenPanel || !DesignTokenPanelBootstrap) return null;
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: ZDTP_TOGGLE_SHIM_SRC } }),
+      Island({
+        when: "load",
+        children: /* @__PURE__ */ jsx(DesignTokenPanelBootstrap, {})
+      })
+    ] });
+  }
+  return DesignTokenPanelIsland;
+}
+export {
+  createDesignTokenPanelIsland
+};

package/dist/doc-body-end-islands/index.d.ts

@@ -2,34 +2,36 @@
 /** @jsxImportSource preact */
 import type { JSX } from "preact";
 import type { FactoryComponent } from "../factory-context/index.js";
-/** The `settings` subset this factory reads — the four package-island flags.
+import type { ThemePackSwitcherProps } from "../theme-pack-switcher/index.js";
+/** The `settings` subset this factory reads — the package feature flags.
  *  A structural subset so the host can pass its full `Settings` object. */
 export interface BodyEndIslandsSettings {
     aiAssistant: boolean;
     imageEnlarge: boolean;
     mermaid: boolean;
     /** Gates the pure-SSR `<PageLoadingOverlay/>` mount (zudolab/zudo-doc#2482),
-     *  mirroring the host gate and `enableClientRouter`'s on package-owned routes.
-     *  Optional so adding it is NOT a breaking change for external callers that
-     *  construct this documented subset — this is an exported package subpath API.
-     *  `undefined` is treated as `false` (no overlay) at the mount site, preserving
-     *  pre-#2482 behavior; internal callers always pass the full `Settings`. */
-    dynamicPageTransition?: boolean;
-    /** Gates the `DesignTokenPanelBootstrap` island mount (#2658). Optional for
-     *  the same external-caller-compat reason as `dynamicPageTransition` above.
-     *  `undefined` is treated as `false` (no panel island). Even when `true`,
-     *  nothing mounts unless `deps.DesignTokenPanelBootstrap` was also supplied
-     *  — see {@link BodyEndIslandsDeps}. */
-    designTokenPanel?: boolean;
+     *  mirroring the host gate and `enableClientRouter` on package-owned routes. */
+    dynamicPageTransition: boolean;
+    /** Gates the `DesignTokenPanelBootstrap` island mount (#2658). Even when
+     *  `true`, nothing mounts unless `deps.DesignTokenPanelBootstrap` was also
+     *  supplied — see {@link BodyEndIslandsDeps}. */
+    designTokenPanel: boolean;
     /**
-     * Gates the `FindInPageInit` island mount (zudolab/zudo-doc#2689). Optional
-     * for the same external-caller-compat reason as `dynamicPageTransition`/
-     * `designTokenPanel` above. `undefined` is treated as `false` (no island).
+     * Gates the `FindInPageInit` island mount (zudolab/zudo-doc#2689).
      * Controls the PACKAGE-DEFAULT `BodyEndIslands` slot only — a host that
      * overrides the `BodyEndIslands` chrome binding must mount `FindInPageInit`
      * itself.
      */
-    findInPage?: boolean;
+    findInPage: boolean;
+    /**
+     * Gates the `ThemePackSwitcher` flyout island mount (ADR
+     * `docs/adr/theme-packs.md` Decision 7; #2821). Optional — the field is
+     * optional on the host `Settings` census too (default `false`). Even when
+     * `true`, nothing mounts unless `deps.themePackSwitcherProps` AND
+     * `deps.ThemePackSwitcher` were also supplied — see
+     * {@link BodyEndIslandsDeps}.
+     */
+    themePackSwitcher?: boolean;
 }
 /** Dependencies injected by `_chrome.tsx` (carries the virtual-module settings). */
 export interface BodyEndIslandsDeps {
@@ -47,6 +49,20 @@ export interface BodyEndIslandsDeps {
      * not a crash.
      */
     DesignTokenPanelBootstrap?: FactoryComponent;
+    /**
+     * SSR props for the theme-pack switcher flyout (#2821) — derived from
+     * `ctx.themePackRegistry` by `chrome/derive.tsx` (only the chrome-derive
+     * path knows the registry). `null`/omitted renders the feature inert even
+     * when `settings.themePackSwitcher` is `true`.
+     */
+    themePackSwitcherProps?: ThemePackSwitcherProps | null;
+    /**
+     * The real `ThemePackSwitcher` island component (#2821), injected by
+     * `chrome/derive.tsx` (which statically imports it — the island-scanner
+     * reachability chain, mirroring `DesignTokenPanelBootstrap` above).
+     * Omitted means no switcher island mounts — a safe no-op, not a crash.
+     */
+    ThemePackSwitcher?: FactoryComponent;
 }
 /** Props for the produced `BodyEndIslands` component. */
 export interface BodyEndIslandsProps {
@@ -59,4 +75,10 @@ export interface BodyEndIslandsProps {
      */
     aiChatBodyLabel?: string;
 }
+/**
+ * Build the package-default `BodyEndIslands` component bound to the host's
+ * serializable `settings` flags. The produced component matches the
+ * `createDocBodyEnd` `BodyEndIslands` slot contract
+ * (`(props: { basePath: string }) => JSX.Element`).
+ */
 export declare function createBodyEndIslands(deps: BodyEndIslandsDeps): (props: BodyEndIslandsProps) => JSX.Element;

package/dist/doc-body-end-islands/index.js

@@ -5,22 +5,20 @@ import { ImageEnlarge, ImageEnlargeSsrFallback } from "../image-enlarge/index.js
 import { MermaidEnlarge, MermaidEnlargeSsrFallback } from "../mermaid-enlarge/index.js";
 import { FindInPageInit } from "../find-in-page/index.js";
 import { PageLoadingOverlay } from "../page-loading/index.js";
+import { createDesignTokenPanelIsland } from "./design-token-panel-island.js";
+import { createThemePackSwitcherIsland } from "./theme-pack-switcher-island.js";
 const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
-const ZDTP_TOGGLE_SHIM_SRC = `(function(){
-if(window.__zdtpToggleShimInstalled)return;
-window.__zdtpToggleShimInstalled=true;
-var pending=false;
-function shim(){pending=true;}
-window.addEventListener('toggle-design-token-panel',shim);
-window.__zdtpReadyClicks=function(){
-window.removeEventListener('toggle-design-token-panel',shim);
-delete window.__zdtpReadyClicks;
-if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
-};
-})();`;
 function createBodyEndIslands(deps) {
   const { settings } = deps;
-  const DesignTokenPanelBootstrap = deps.DesignTokenPanelBootstrap;
+  const DesignTokenPanelIsland = createDesignTokenPanelIsland({
+    designTokenPanel: settings.designTokenPanel,
+    DesignTokenPanelBootstrap: deps.DesignTokenPanelBootstrap
+  });
+  const ThemePackSwitcherIsland = createThemePackSwitcherIsland({
+    themePackSwitcher: settings.themePackSwitcher === true,
+    themePackSwitcherProps: deps.themePackSwitcherProps ?? null,
+    ThemePackSwitcher: deps.ThemePackSwitcher
+  });
   function BodyEndIslands({
     basePath,
     aiChatBodyLabel = DEFAULT_AI_CHAT_BODY_LABEL
@@ -42,20 +40,14 @@ function createBodyEndIslands(deps) {
       ssrFallback: /* @__PURE__ */ jsx(MermaidEnlargeSsrFallback, {}),
       children: /* @__PURE__ */ jsx(MermaidEnlarge, {})
     }) : null;
-    const designTokenPanelBootstrap = settings.designTokenPanel && DesignTokenPanelBootstrap ? /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: ZDTP_TOGGLE_SHIM_SRC } }),
-      Island({
-        when: "load",
-        children: /* @__PURE__ */ jsx(DesignTokenPanelBootstrap, {})
-      })
-    ] }) : null;
     const findInPageInit = settings.findInPage ? Island({
       when: "load",
       children: /* @__PURE__ */ jsx(FindInPageInit, {})
     }) : null;
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       settings.dynamicPageTransition ? /* @__PURE__ */ jsx(PageLoadingOverlay, {}) : null,
-      designTokenPanelBootstrap,
+      /* @__PURE__ */ jsx(DesignTokenPanelIsland, {}),
+      /* @__PURE__ */ jsx(ThemePackSwitcherIsland, {}),
       findInPageInit,
       aiAssistant,
       imageEnlarge,

package/dist/doc-body-end-islands/theme-pack-switcher-island.d.ts

@@ -0,0 +1,37 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import type { FactoryComponent } from "../factory-context/index.js";
+import type { ThemePackSwitcherProps } from "../theme-pack-switcher/index.js";
+export interface ThemePackSwitcherIslandDeps {
+    /** The `settings.themePackSwitcher` gate (default `false`). */
+    themePackSwitcher: boolean;
+    /**
+     * SSR props derived from `ctx.themePackRegistry` by
+     * `chrome/derive.tsx` (ADR theme-packs.md Decision 7 "Switcher data
+     * flow"). `null` means the registry was not threaded
+     * (`themePackRegistry: null`) — the whole feature renders inert even when
+     * the settings gate is on.
+     */
+    themePackSwitcherProps: ThemePackSwitcherProps | null;
+    /**
+     * The real `ThemePackSwitcher` island component. Injected (not imported
+     * here) mirroring `design-token-panel-island.tsx`'s shape: the props above
+     * only exist on the chrome-derive path, so `chrome/derive.tsx` supplies the
+     * statically imported package component as the default for every
+     * `createChrome` consumer (route → chrome → derive → component is the
+     * island-scanner reachability chain — the #2480 lesson). Omitted means no
+     * island mounts even when the gate is on — a safe no-op, not a crash.
+     */
+    ThemePackSwitcher?: FactoryComponent;
+}
+/**
+ * Bind the settings gate + the SSR-derived props to the theme-pack switcher
+ * flyout island mount (`Island({ when: "load" })` — the island SSRs its
+ * launcher markup and hydrates at load; its serializable props ride the
+ * marker's `data-props` JSON). Kept separate from the rest of the package
+ * body-end islands so a host BodyEndIslands override can be composed with
+ * this package-owned mount without duplicating the other package defaults
+ * (the `design-token-panel-island.tsx` pattern).
+ */
+export declare function createThemePackSwitcherIsland(deps: ThemePackSwitcherIslandDeps): () => JSX.Element | null;

package/dist/doc-body-end-islands/theme-pack-switcher-island.js

@@ -0,0 +1,18 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
+import { Island } from "@takazudo/zfb";
+function createThemePackSwitcherIsland(deps) {
+  const ThemePackSwitcher = deps.ThemePackSwitcher;
+  function ThemePackSwitcherIsland() {
+    if (!deps.themePackSwitcher || deps.themePackSwitcherProps === null || !ThemePackSwitcher) {
+      return null;
+    }
+    return /* @__PURE__ */ jsx(Fragment, { children: Island({
+      when: "load",
+      children: /* @__PURE__ */ jsx(ThemePackSwitcher, { ...deps.themePackSwitcherProps })
+    }) });
+  }
+  return ThemePackSwitcherIsland;
+}
+export {
+  createThemePackSwitcherIsland
+};

package/dist/doc-content-header/index.js

@@ -37,7 +37,7 @@ function createDocContentHeader(ctx) {
           children: t("doc.fallbackNotice", locale)
         }
       ),
-      entry.data.description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", children: entry.data.description }),
+      entry.data.description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", "data-doc-description": true, children: entry.data.description }),
       /* @__PURE__ */ jsx(
         FrontmatterPreview,
         {

package/dist/doc-history-area/index.d.ts

@@ -8,8 +8,8 @@ export interface DocHistoryMetaEntry {
     author: string;
     createdDate: string;
     updatedDate: string;
-    /** Source file extension (".mdx" | ".md") — optional in older manifests. */
-    ext?: string;
+    /** Source file extension recorded by the current build-time manifest. */
+    ext: ".mdx" | ".md";
 }
 /** Settings subset read by the DocHistoryArea factory. */
 export interface DocHistoryAreaSettings {
@@ -36,12 +36,18 @@ export interface DocHistoryAreaProps {
     /**
      * Raw zfb entry slug (relative path without extension), e.g.
      * "getting-started/intro" or "getting-started/index". Appended with
-     * the source extension from the build-time manifest (".mdx" fallback)
-     * to form the file path passed to buildGitHubSourceUrl.
+     * the source extension from the build-time manifest to form the file path
+     * passed to buildGitHubSourceUrl.
      * Omit for auto-index pages (no underlying MDX file) — sourceUrl
      * will be suppressed automatically.
      */
     entrySlug?: string;
+    /**
+     * Source extension from the current content entry. Used only when the file
+     * has no manifest metadata yet (for example, an untracked file or a build
+     * with `SKIP_DOC_HISTORY=1`). A present manifest owns its required `ext`.
+     */
+    sourceFileExt?: ".mdx" | ".md";
     /**
      * Content directory for the active locale, e.g. "src/content/docs"
      * or "src/content/docs-ja". Combined with entrySlug to build the

package/dist/doc-history-area/index.js

@@ -22,6 +22,7 @@ function createDocHistoryArea(ctx) {
     slug,
     locale,
     entrySlug,
+    sourceFileExt,
     contentDir,
     isFallback
   }) {
@@ -62,8 +63,8 @@ function createDocHistoryArea(ctx) {
       )
     });
     const utilSettings = settings.bodyFootUtilArea;
-    const sourceExt = meta?.ext ?? ".mdx";
-    const sourceUrl = utilSettings && utilSettings.viewSourceLink && entrySlug && contentDir ? buildGitHubSourceUrl(contentDir, entrySlug + sourceExt) : null;
+    const sourceExt = meta ? meta.ext : sourceFileExt;
+    const sourceUrl = utilSettings && utilSettings.viewSourceLink && entrySlug && sourceExt && contentDir ? buildGitHubSourceUrl(contentDir, entrySlug + sourceExt) : null;
     const viewSourceLabel = t("doc.viewSource", locale);
     void historyLabel;
     return /* @__PURE__ */ jsx(

package/dist/doc-metainfo-area/index.d.ts

@@ -8,6 +8,7 @@ export interface DocHistoryMetaEntry {
     author: string;
     createdDate: string;
     updatedDate: string;
+    ext: ".mdx" | ".md";
 }
 /** Settings subset read by the DocMetainfoArea factory. */
 export interface DocMetainfoAreaSettings {