@takazudo/zudo-doc 3.2.0 → 4.0.0

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

@@ -0,0 +1,105 @@
+const FONT_WEIGHT_OPTIONS = [
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900"
+];
+const SPACING_TOKENS = [
+  // --- Horizontal spacing ---
+  { id: "hsp-2xs", cssVar: "--spacing-hsp-2xs", label: "hsp-2xs", group: "hsp", default: "0.125rem", step: 0.025, unit: "rem" },
+  { id: "hsp-xs", cssVar: "--spacing-hsp-xs", label: "hsp-xs", group: "hsp", default: "0.375rem", step: 0.025, unit: "rem" },
+  { id: "hsp-sm", cssVar: "--spacing-hsp-sm", label: "hsp-sm", group: "hsp", default: "0.5rem", step: 0.025, unit: "rem" },
+  { id: "hsp-md", cssVar: "--spacing-hsp-md", label: "hsp-md", group: "hsp", default: "0.75rem", step: 0.025, unit: "rem" },
+  { id: "hsp-lg", cssVar: "--spacing-hsp-lg", label: "hsp-lg", group: "hsp", default: "1rem", step: 0.025, unit: "rem" },
+  { id: "hsp-xl", cssVar: "--spacing-hsp-xl", label: "hsp-xl", group: "hsp", default: "1.5rem", step: 0.025, unit: "rem" },
+  { id: "hsp-2xl", cssVar: "--spacing-hsp-2xl", label: "hsp-2xl", group: "hsp", default: "2rem", step: 0.025, unit: "rem" },
+  // --- Vertical spacing ---
+  { id: "vsp-3xs", cssVar: "--spacing-vsp-3xs", label: "vsp-3xs", group: "vsp", default: "0.25rem", step: 0.025, unit: "rem" },
+  { id: "vsp-2xs", cssVar: "--spacing-vsp-2xs", label: "vsp-2xs", group: "vsp", default: "0.4375rem", step: 0.025, unit: "rem" },
+  { id: "vsp-xs", cssVar: "--spacing-vsp-xs", label: "vsp-xs", group: "vsp", default: "0.875rem", step: 0.025, unit: "rem" },
+  { id: "vsp-sm", cssVar: "--spacing-vsp-sm", label: "vsp-sm", group: "vsp", default: "1.25rem", step: 0.025, unit: "rem" },
+  { id: "vsp-md", cssVar: "--spacing-vsp-md", label: "vsp-md", group: "vsp", default: "1.5rem", step: 0.025, unit: "rem" },
+  { id: "vsp-lg", cssVar: "--spacing-vsp-lg", label: "vsp-lg", group: "vsp", default: "1.75rem", step: 0.025, unit: "rem" },
+  { id: "vsp-xl", cssVar: "--spacing-vsp-xl", label: "vsp-xl", group: "vsp", default: "2.5rem", step: 0.025, unit: "rem" },
+  { id: "vsp-2xl", cssVar: "--spacing-vsp-2xl", label: "vsp-2xl", group: "vsp", default: "3.5rem", step: 0.025, unit: "rem" },
+  // --- Icons ---
+  { id: "icon-xs", cssVar: "--spacing-icon-xs", label: "icon-xs", group: "icon", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "icon-sm", cssVar: "--spacing-icon-sm", label: "icon-sm", group: "icon", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "icon-md", cssVar: "--spacing-icon-md", label: "icon-md", group: "icon", default: "1.25rem", step: 0.05, unit: "rem" },
+  { id: "icon-lg", cssVar: "--spacing-icon-lg", label: "icon-lg", group: "icon", default: "1.5rem", step: 0.05, unit: "rem" },
+  // --- Layout ---
+  { id: "image-overlay-inset", cssVar: "--spacing-image-overlay-inset", label: "image-overlay-inset", group: "layout", default: "0.5rem", step: 0.05, unit: "rem" },
+  // Structural zero — surfaced as read-only so designers see it exists, but
+  // editing it would break every utility that relies on "0 is 0".
+  { id: "spacing-0", cssVar: "--spacing-0", label: "spacing-0", group: "layout", default: "0", step: 1, unit: "", readonly: true },
+  // 1px hairline — also read-only by design.
+  { id: "spacing-px", cssVar: "--spacing-px", label: "spacing-px", group: "layout", default: "1px", step: 1, unit: "px", readonly: true },
+  // Responsive clamp() expression — can't be expressed on a single slider.
+  { id: "sidebar-w", cssVar: "--zd-sidebar-w", label: "sidebar-w", group: "layout", default: "clamp(14rem, 20vw, 22rem)", step: 1, unit: "", readonly: true }
+];
+const FONT_TOKENS = [
+  // --- Font sizes (Tier 2 semantic) ---
+  { id: "text-micro", cssVar: "--text-micro", label: "text-micro", group: "font-size", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "text-caption", cssVar: "--text-caption", label: "text-caption", group: "font-size", default: "0.875rem", step: 0.05, unit: "rem" },
+  { id: "text-small", cssVar: "--text-small", label: "text-small", group: "font-size", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "text-body", cssVar: "--text-body", label: "text-body", group: "font-size", default: "1.2rem", step: 0.05, unit: "rem" },
+  { id: "text-title", cssVar: "--text-title", label: "text-title", group: "font-size", default: "1.4rem", step: 0.05, unit: "rem" },
+  { id: "text-heading", cssVar: "--text-heading", label: "text-heading", group: "font-size", default: "3rem", step: 0.05, unit: "rem" },
+  { id: "text-display", cssVar: "--text-display", label: "text-display", group: "font-size", default: "3.75rem", step: 0.05, unit: "rem" },
+  // --- Line heights (unitless) ---
+  { id: "leading-tight", cssVar: "--leading-tight", label: "leading-tight", group: "line-height", default: "1.25", step: 0.05, unit: "" },
+  { id: "leading-snug", cssVar: "--leading-snug", label: "leading-snug", group: "line-height", default: "1.375", step: 0.05, unit: "" },
+  { id: "leading-normal", cssVar: "--leading-normal", label: "leading-normal", group: "line-height", default: "1.5", step: 0.05, unit: "" },
+  { id: "leading-relaxed", cssVar: "--leading-relaxed", label: "leading-relaxed", group: "line-height", default: "1.625", step: 0.05, unit: "" },
+  // --- Font weights (select) ---
+  { id: "font-weight-normal", cssVar: "--font-weight-normal", label: "font-weight-normal", group: "font-weight", default: "400", step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-medium", cssVar: "--font-weight-medium", label: "font-weight-medium", group: "font-weight", default: "500", step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-semibold", cssVar: "--font-weight-semibold", label: "font-weight-semibold", group: "font-weight", default: "600", step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-bold", cssVar: "--font-weight-bold", label: "font-weight-bold", group: "font-weight", default: "700", step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  // --- Font families (text input) ---
+  { id: "font-sans", cssVar: "--font-sans", label: "font-sans", group: "font-family", default: "system-ui, sans-serif", step: 1, unit: "", control: "text" },
+  { id: "font-mono", cssVar: "--font-mono", label: "font-mono", group: "font-family", default: "ui-monospace, monospace", step: 1, unit: "", control: "text" },
+  // --- Tier 1 abstract scale ---
+  { id: "text-scale-2xs", cssVar: "--text-scale-2xs", label: "text-scale-2xs", group: "font-scale", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-xs", cssVar: "--text-scale-xs", label: "text-scale-xs", group: "font-scale", default: "0.875rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-sm", cssVar: "--text-scale-sm", label: "text-scale-sm", group: "font-scale", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-md", cssVar: "--text-scale-md", label: "text-scale-md", group: "font-scale", default: "1.2rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-lg", cssVar: "--text-scale-lg", label: "text-scale-lg", group: "font-scale", default: "1.4rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-xl", cssVar: "--text-scale-xl", label: "text-scale-xl", group: "font-scale", default: "3rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-2xl", cssVar: "--text-scale-2xl", label: "text-scale-2xl", group: "font-scale", default: "3.75rem", step: 0.05, unit: "rem" }
+];
+const SIZE_TOKENS = [
+  // --- Radius ---
+  { id: "radius-DEFAULT", cssVar: "--radius-DEFAULT", label: "radius-DEFAULT", group: "radius", default: "4px", step: 1, unit: "px" },
+  { id: "radius-lg", cssVar: "--radius-lg", label: "radius-lg", group: "radius", default: "8px", step: 1, unit: "px" },
+  {
+    id: "radius-full",
+    cssVar: "--radius-full",
+    label: "radius-full",
+    group: "radius",
+    default: "9999px",
+    step: 1,
+    unit: "px",
+    pill: { value: "9999px", customDefault: "16px" }
+  },
+  // --- Transitions ---
+  {
+    id: "default-transition-duration",
+    cssVar: "--default-transition-duration",
+    label: "default-transition-duration",
+    group: "transition",
+    default: "150ms",
+    step: 10,
+    unit: "ms"
+  }
+];
+export {
+  FONT_TOKENS,
+  SIZE_TOKENS,
+  SPACING_TOKENS
+};

package/dist/directive-vocabulary-defaults/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default directive vocabulary — the canonical seven.
+ *
+ * Ported from the `directiveVocabulary` object that every
+ * `create-zudo-doc`-generated `zfb.config.ts` previously hardcoded inline
+ * (see `packages/create-zudo-doc/src/zfb-config-gen.ts`'s `generateZfbConfig`
+ * and this repo's own `zfb.config.ts`) into a package default (epic
+ * zudolab/zudo-doc#2651, S4 #2654).
+ *
+ * Keys are directive names; values are the JSX component names the markdown
+ * pipeline's `directives` feature resolves them to (registered in the host's
+ * `pages/_mdx-components.ts`). `details` routes to a collapsible, NOT an
+ * admonition — the other six are admonition variants.
+ */
+import type { DirectiveVocabulary } from "../preset.js";
+export declare const defaultDirectiveVocabulary: DirectiveVocabulary;

package/dist/directive-vocabulary-defaults/index.js

@@ -0,0 +1,12 @@
+const defaultDirectiveVocabulary = {
+  note: "Note",
+  tip: "Tip",
+  info: "Info",
+  warning: "Warning",
+  danger: "Danger",
+  caution: "Caution",
+  details: "Details"
+};
+export {
+  defaultDirectiveVocabulary
+};

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

@@ -1,23 +1,68 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 import type { JSX } from "preact";
-/** The `settings` subset this factory reads — the three package-island flags.
+import type { FactoryComponent } from "../factory-context/index.js";
+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;
+     *  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).
+     * Controls the PACKAGE-DEFAULT `BodyEndIslands` slot only — a host that
+     * overrides the `BodyEndIslands` chrome binding must mount `FindInPageInit`
+     * itself.
+     */
+    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 {
     settings: BodyEndIslandsSettings;
+    /**
+     * The real `DesignTokenPanelBootstrap` component (#2658) — see the module
+     * header note above for why it is NOT imported directly here.
+     * `chrome/derive.tsx`'s `deriveBodyEndIslands` supplies
+     * `@takazudo/zudo-doc/design-token-panel-bootstrap`'s
+     * `DesignTokenPanelBootstrap` as the default for every `createChrome`
+     * consumer (#2659 gate-2 fix), so chrome-derived callers always carry it.
+     * Omitted (a bare `createBodyEndIslands({ settings })` call outside the
+     * chrome path, as this factory's own unit tests do) means no panel island
+     * mounts even when `settings.designTokenPanel` is `true` — a safe no-op,
+     * 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 {

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

@@ -3,10 +3,22 @@ import { Island } from "@takazudo/zfb";
 import { AiChatModal } from "../ai-chat-modal/index.js";
 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.";
 function createBodyEndIslands(deps) {
   const { settings } = deps;
+  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
@@ -28,8 +40,15 @@ function createBodyEndIslands(deps) {
       ssrFallback: /* @__PURE__ */ jsx(MermaidEnlargeSsrFallback, {}),
       children: /* @__PURE__ */ jsx(MermaidEnlarge, {})
     }) : null;
+    const findInPageInit = settings.findInPage ? Island({
+      when: "load",
+      children: /* @__PURE__ */ jsx(FindInPageInit, {})
+    }) : null;
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       settings.dynamicPageTransition ? /* @__PURE__ */ jsx(PageLoadingOverlay, {}) : null,
+      /* @__PURE__ */ jsx(DesignTokenPanelIsland, {}),
+      /* @__PURE__ */ jsx(ThemePackSwitcherIsland, {}),
+      findInPageInit,
       aiAssistant,
       imageEnlarge,
       mermaidEnlarge

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 {

package/dist/doc-page-props/index.d.ts

@@ -1,6 +1,7 @@
 export type { HeadingItem } from "../extract-headings/index.js";
 import type { HeadingItem } from "../extract-headings/index.js";
 import type { BreadcrumbItem } from "../breadcrumb/types.js";
+import type { CollectionEntry } from "@takazudo/zfb/content";
 /**
  * Nav tree node shape as consumed by doc-route pages.
  *
@@ -35,37 +36,20 @@ export interface DocPageFrontmatter {
     draft?: boolean;
     unlisted?: boolean;
     standalone?: boolean;
+    sidebar_position?: number;
+    sidebar_label?: string;
     category_no_page?: boolean;
+    category_sort_order?: "asc" | "desc";
     pagination_prev?: string | null;
     pagination_next?: string | null;
     tags?: string[];
     [key: string]: unknown;
 }
 /**
- * A zfb content collection entry augmented with the `id`/`collection` fields
- * the host's `@/utils/docs` helpers expect, plus the typed `data` and
- * renderer surface.
- *
- * Structural counterpart of the host's `DocPageEntry` (from
- * `pages/lib/doc-page-props.ts`). The host stub re-exports this type under
- * the original name.
+ * The native zfb collection entry with docs frontmatter. Route consumers
+ * derive canonical route slugs from `entry.data.slug ?? toRouteSlug(entry.slug)`.
  */
-export interface DocPageEntry {
-    /** zfb content engine slug (filename without `.md`/`.mdx`). */
-    slug: string;
-    /** Bridged from `slug` for host `@/utils/docs` compat. */
-    id: string;
-    /** Collection name, e.g. "docs", "docs-ja", "docs-v-1.0". */
-    collection: string;
-    /** Parsed frontmatter. Structural superset of `DocPageFrontmatter`. */
-    data: DocPageFrontmatter;
-    /** Raw MDX body (for heading extraction). */
-    body?: string;
-    /** zfb module specifier (for Content bridge). */
-    module_specifier: string;
-    /** zfb content renderer — callable Preact component. */
-    Content: unknown;
-}
+export type DocPageEntry = CollectionEntry<DocPageFrontmatter>;
 export interface AutoIndexNode extends DocNavNode {
     children: DocNavNode[];
 }

package/dist/doc-page-renderer/index.d.ts

@@ -121,6 +121,7 @@ export interface DocPageRendererDeps {
         slug: string;
         locale: string;
         entrySlug?: string;
+        sourceFileExt?: ".mdx" | ".md";
         contentDir?: string;
         isFallback?: boolean;
     }) => VNode | null;

package/dist/doc-page-renderer/index.js

@@ -102,6 +102,7 @@ function createRenderDocPage(ctx) {
               slug,
               locale,
               entrySlug: props.entry.slug,
+              sourceFileExt: props.entry.module_specifier.endsWith(".mdx") ? ".mdx" : props.entry.module_specifier.endsWith(".md") ? ".md" : void 0,
               contentDir: opts.docHistoryContentDir,
               isFallback
             }

package/dist/doc-page-shell/index.js

@@ -1,29 +1,32 @@
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
-import { Toc, MobileToc, getTocTitle } from "../toc/index.js";
-import { Breadcrumb } from "../breadcrumb/index.js";
+import { MobileToc, getTocTitle } from "../toc/index.js";
 import { NavCardGrid } from "../nav-indexing/index.js";
 import {
   createSidebarPrepaint,
   createSidebarVisibilityPrepaint
 } from "../sidebar-prepaint/index.js";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
-import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
-import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
-import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
+import { resolveThemePackSsrSlug } from "../theme/theme-pack-provider.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
-import { createDocPager } from "../doc-pager/index.js";
 import { deriveComposeMetaTitle } from "../chrome/derive.js";
+import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocPageShell(ctx) {
   assertChromeContext(ctx, "createDocPageShell");
   const settings = ctx.settings;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
-  const SidebarWithDefaults = createSidebarWithDefaults(ctx);
-  const HeaderWithDefaults = createHeaderWithDefaults(ctx);
-  const FooterWithDefaults = createFooterWithDefaults(ctx);
+  const {
+    Header: HeaderWithDefaults,
+    Footer: FooterWithDefaults,
+    Sidebar: SidebarWithDefaults,
+    Toc,
+    Breadcrumb,
+    DocPager
+  } = derivePrimaryChromeSlots(ctx);
+  const customTocIsPresent = ctx.hostBindings.Toc !== void 0;
   const sidebarToggleEnabled = Boolean(
     ctx.settings.sidebarToggle
   );
@@ -34,7 +37,10 @@ function createDocPageShell(ctx) {
     sidebarToggle: sidebarToggleEnabled
   });
   const DocBodyEnd = createDocBodyEnd(ctx);
-  const DocPager = createDocPager(ctx);
+  const dataThemePack = resolveThemePackSsrSlug(
+    ctx.themePackRegistry,
+    ctx.settings
+  );
   function DocPageShell(props) {
     const {
       kind,
@@ -66,7 +72,7 @@ function createDocPageShell(ctx) {
     } = props;
     const tocTitle = getTocTitle(locale);
     const shouldRenderToc = !hideToc && headings.length > 0;
-    const tocOverride = shouldRenderToc ? Island({
+    const tocOverride = shouldRenderToc ? customTocIsPresent ? /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle }) : Island({
       when: "load",
       children: /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle })
     }) : void 0;
@@ -84,6 +90,7 @@ function createDocPageShell(ctx) {
           /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar })
         ] }),
         lang: locale,
+        dataThemePack,
         noindex: settings.noindex,
         hideSidebar,
         hideToc,
@@ -128,7 +135,7 @@ function createDocPageShell(ctx) {
           /* @__PURE__ */ jsxs(Fragment, { children: [
             /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-xs", children: autoIndexLabel }),
             metainfoSlot,
-            description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", children: description }),
+            description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", "data-doc-description": true, children: description }),
             /* @__PURE__ */ jsx(NavCardGrid, { children: autoIndexChildren ?? [] })
           ] })
         ) : (

package/dist/doc-pager/index.js

@@ -5,7 +5,7 @@ function createDocPager(ctx) {
   assertChromeContext(ctx, "createDocPager");
   const t = ctx.t;
   function DocPager({ prev, next, locale }) {
-    return /* @__PURE__ */ jsxs("nav", { class: "mt-vsp-2xl grid grid-cols-2 gap-hsp-xl", children: [
+    return /* @__PURE__ */ jsxs("nav", { class: "mt-vsp-2xl grid grid-cols-2 gap-hsp-xl", "data-doc-pager": true, children: [
       prev ? /* @__PURE__ */ jsxs(
         "a",
         {

package/dist/doc-route-entries/index.d.ts

@@ -63,7 +63,7 @@ export interface DocRouteEntriesContext {
     /** Filter top-level nav nodes by a categoryMatch value. */
     getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
     /** Convert a content entry slug to a canonical route slug. */
-    toRouteSlug: (id: string) => string;
+    toRouteSlug: (entrySlug: string) => string;
     /** Convert a canonical route slug to an optional-catchall params array. */
     toSlugParams: (slug: string) => string[];
     /** Extract headings from a raw MDX body (bound to settings depth/strategy). */
@@ -91,7 +91,7 @@ export interface DocRouteEntriesAPI {
  * import { createDocRouteEntries } from "@takazudo/zudo-doc/doc-route-entries";
  * import { buildNavTree, buildBreadcrumbs, collectAutoIndexNodes } from "@/utils/docs";
  * import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
- * import { toRouteSlug, toSlugParams } from "@/utils/slug";
+ * import { toRouteSlug, toSlugParams } from "@takazudo/zudo-doc/slug";
  * import { extractHeadings } from "./_extract-headings";
  *
  * export const { buildDocRouteEntries } = createDocRouteEntries(routeContext);

package/dist/doclayout/doc-layout-with-defaults.js

@@ -120,10 +120,10 @@ function DocLayoutWithDefaults(props) {
       footer: footerOverride ?? /* @__PURE__ */ jsx(Footer, {}),
       bodyEndComponents,
       bodyEndScripts: bodyEndScripts ?? // Default body-end scripts:
-      //   - CodeBlockEnhancer wraps every <pre class="syntect-*"> with
-      //     copy + word-wrap controls and emits an SR-announce live
-      //     region for clipboard feedback. Idempotent on pages with no
-      //     fenced code.
+      //   - CodeBlockEnhancer wraps every highlighted <pre> (`.hi-root`)
+      //     with copy + word-wrap controls and emits an SR-announce live
+      //     region for clipboard feedback.
+      //     Idempotent on pages with no fenced code.
       //   - TabsInit activates the correct tab panel and wires click
       //     handlers for <Tabs> components.
       //   - MermaidInit lazily imports the mermaid library from