@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/features.css

@@ -14,11 +14,14 @@
  *   --spacing-{hsp-sm,hsp-2xs,hsp-lg,hsp-md,hsp-xl,vsp-xs,vsp-2xs,vsp-md,
  *              icon-sm}
  *   --z-index-local-1
+ *   --z-index-toolbar
  *   --radius-{DEFAULT,lg}
  *   --font-{mono,sans}
  *   --text-{small,caption}
  *   --leading-relaxed
  *   --zd-fg
+ *   --zd-code-{bg,fg}
+ *   --zd-syntax-{comment,string,number,keyword,callable,type,name,inserted,deleted}
  *   --zd-sidebar-w
  *   --zd-header-h
  *   --zd-transition-slow
@@ -28,6 +31,15 @@
  * pre-condition before @importing this file).
  * ─────────────────────────────────────────────────────────────────────────── */
 
+/* ========================================
+ * Shared chrome defaults
+ * ======================================== */
+
+header[data-header] {
+  background-color: var(--color-surface, var(--color-bg));
+  z-index: var(--z-index-toolbar, 20);
+}
+
 /* ========================================
  * Code block buttons (copy + word wrap)
  * ======================================== */
@@ -36,11 +48,11 @@
   position: relative;
 }
 
-pre[class^="syntect-"].word-wrap {
+:is(pre.hi-root, .tab-panel pre).word-wrap {
   overflow-x: hidden;
 }
 
-pre[class^="syntect-"].word-wrap code {
+:is(pre.hi-root, .tab-panel pre).word-wrap code {
   white-space: pre-wrap;
   overflow-wrap: anywhere;
 }
@@ -129,38 +141,49 @@ pre[class^="syntect-"].word-wrap code {
  * Code-block syntax-highlight token color rule
  * ======================================== */
 
-/* Code-block token colors come from CSS custom properties in two cases on this
- * site, both resolved here via light-dark():
- *
- *   1. Build-time — zfb DUAL-theme syntect (codeHighlight.themeLight/themeDark
- *      in zfb.config.ts). Emits <pre class="syntect-dual"> whose token spans
- *      carry style="--shiki-light:#X;--shiki-dark:#Y" (no `color` declaration)
- *      and whose <pre> carries --shiki-{light,dark}-bg. Zero client JS.
- *
- *   2. Runtime — the HtmlPreview component's Shiki blocks (<pre class="shiki">),
- *      which emit the same --shiki-* custom properties.
- *
- * Both resolve through the `color-scheme` property, which ColorSchemeProvider /
- * ThemeToggle toggle per active theme — the same mechanism the palette tokens
- * use — so code follows the in-page light/dark switch.
- *
- * Compatibility: SINGLE-theme syntect (the zfb default, NOT used here) instead
- * bakes inline style="color:#hex". This rule deliberately uses NO !important so
- * that such an inline `color` — a higher-precedence author declaration — still
- * wins, leaving single-theme output untouched. The --shiki-* spans have no
- * inline `color`, so the rule applies cleanly. Same logic for background-color
- * on the <pre>. See zudolab/zudo-doc#1457.
- *
- * NOTE: the zdtp design-token panel does NOT highlight code — its Shiki
- * integration is a no-op stub upstream. Earlier revisions of this comment
- * wrongly attributed the --shiki-* vars to a zdtp client-side re-highlight. */
-/* Token color + font-style on the spans (and harmlessly on the <pre>/<code>,
- * where the per-token --shiki-* vars are undefined so the declaration is
- * ignored). */
+/* zfb's default class-mode stylesheet lives in `@layer zfb-hi`. This adapter
+ * stays unlayered, so zudo's semantic design tokens win without specificity or
+ * import-order coupling. The indirections deliberately stay as var() values:
+ * ColorSchemeProvider and the Design Token Panel can replace any --zd-* source
+ * live, and existing highlighted DOM recomputes without a renderer pass. */
+:root {
+  --zfb-hi-fg: var(--zd-code-fg);
+  --zfb-hi-bg: var(--zd-code-bg);
+  --zfb-hi-esc: var(--zd-syntax-string);
+  --zfb-hi-op: var(--zd-code-fg);
+  --zfb-hi-com: var(--zd-syntax-comment);
+  --zfb-hi-str: var(--zd-syntax-string);
+  --zfb-hi-num: var(--zd-syntax-number);
+  --zfb-hi-const: var(--zd-syntax-number);
+  --zfb-hi-kw: var(--zd-syntax-keyword);
+  --zfb-hi-fn: var(--zd-syntax-callable);
+  --zfb-hi-ty: var(--zd-syntax-type);
+  --zfb-hi-ns: var(--zd-syntax-type);
+  --zfb-hi-prop: var(--zd-syntax-name);
+  --zfb-hi-var: var(--zd-syntax-name);
+  --zfb-hi-tag: var(--zd-syntax-name);
+  --zfb-hi-attr: var(--zd-syntax-name);
+  --zfb-hi-punct: var(--zd-code-fg);
+  --zfb-hi-ins: var(--zd-syntax-inserted);
+  --zfb-hi-ins-bg: color-mix(
+    in srgb,
+    var(--zd-syntax-inserted) 15%,
+    var(--zd-code-bg)
+  );
+  --zfb-hi-del: var(--zd-syntax-deleted);
+  --zfb-hi-del-bg: color-mix(
+    in srgb,
+    var(--zd-syntax-deleted) 15%,
+    var(--zd-code-bg)
+  );
+  --zfb-hi-hd: var(--zd-syntax-keyword);
+}
+
+/* HTML Preview remains on Shiki until #2742. Its dual-theme variables resolve
+ * through color-scheme. These selectors intentionally exclude `.hi-root`,
+ * whose colors come from the semantic bridge above. */
 [data-theme] .shiki,
-[data-theme] .shiki span,
-[data-theme] pre[class^="syntect-"],
-[data-theme] pre[class^="syntect-"] span {
+[data-theme] .shiki span {
   color: light-dark(var(--shiki-light), var(--shiki-dark));
   font-style: light-dark(
     var(--shiki-light-font-style, inherit),
@@ -173,8 +196,7 @@ pre[class^="syntect-"].word-wrap code {
  * painting them per-span would lay an opaque base background over the
  * translucent line-/word-highlight backgrounds that sit on the enclosing
  * .line span (see .line.highlighted below). */
-[data-theme] .shiki,
-[data-theme] pre[class^="syntect-"] {
+[data-theme] .shiki {
   background-color: light-dark(var(--shiki-light-bg), var(--shiki-dark-bg));
 }
 
@@ -202,13 +224,13 @@ pre[class^="syntect-"].word-wrap code {
  * zfb emits data-line-highlight="true" on the <span class="line"> element
  * (verified empirically at next.13). The .highlighted class form is kept for
  * forward-compat in case a future zfb version emits both. */
-pre[class^="syntect-"] .line.highlighted,
-pre[class^="syntect-"] [data-line-highlight="true"] {
+pre.hi-root .line.highlighted,
+pre.hi-root [data-line-highlight="true"] {
   background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
 }
 
 /* Word highlighting via /word/ meta syntax */
-pre[class^="syntect-"] .line .highlighted-word {
+pre.hi-root .line .highlighted-word {
   background-color: color-mix(in srgb, var(--color-accent) 25%, transparent);
   border-bottom: 1px solid var(--color-accent);
 }
@@ -232,7 +254,7 @@ pre[class^="syntect-"] .line .highlighted-word {
   padding: var(--spacing-vsp-2xs) var(--spacing-hsp-lg);
 }
 
-.code-block-container pre[class^="syntect-"] {
+.code-block-container pre.hi-root {
   margin-top: 0 !important;
   border-top-left-radius: 0;
   border-top-right-radius: 0;
@@ -243,10 +265,10 @@ pre[class^="syntect-"] .line .highlighted-word {
  *
  * zfb's :::code-group emits <CodeGroup tabs={[...]}> with one
  * <pre data-lang="…">{RAW text}</pre> child per fence. These <pre> elements
- * are NOT syntect-highlighted (the Rust pipeline doesn't highlight inside
- * code-group fences), so they get no `.syntect-*` class. Apply explicit
- * code-block visual treatment via tokens to match the syntect-highlighted
- * code blocks surrounding them.
+ * are NOT syntax-highlighted (the Rust pipeline doesn't highlight inside
+ * code-group fences), so they get no `.hi-root` class. Apply explicit
+ * code-block visual treatment via tokens to match the highlighted code blocks
+ * surrounding them.
  * ======================================== */
 
 .code-group-panel pre[data-lang] {

package/dist/find-in-page/find-bar.d.ts

@@ -0,0 +1,9 @@
+import type { FindInPage } from "./find-in-page.js";
+interface FindBarProps {
+    visible: boolean;
+    onClose: () => void;
+    findInPage: FindInPage;
+    containerSelector: string;
+}
+export declare function FindBar({ visible, onClose, findInPage, containerSelector }: FindBarProps): import("preact").JSX.Element | null;
+export {};

package/dist/find-in-page/find-bar.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { useState, useRef, useEffect, useCallback } from "preact/hooks";
+function toMatchInfo(result) {
+  return result.matches > 0 ? result : null;
+}
+function FindBar({ visible, onClose, findInPage, containerSelector }) {
+  const [query, setQuery] = useState("");
+  const [matchInfo, setMatchInfo] = useState(null);
+  const inputRef = useRef(null);
+  const findInPageRef = useRef(findInPage);
+  useEffect(() => {
+    findInPageRef.current = findInPage;
+  }, [findInPage]);
+  useEffect(() => {
+    if (visible) {
+      inputRef.current?.focus();
+      inputRef.current?.select();
+    }
+  }, [visible]);
+  useEffect(() => {
+    if (!visible) {
+      setQuery("");
+      setMatchInfo(null);
+      findInPageRef.current.stop();
+    }
+  }, [visible]);
+  const handleFind = useCallback(
+    (text) => {
+      const container = document.querySelector(containerSelector);
+      if (!text || !(container instanceof HTMLElement)) {
+        setMatchInfo(null);
+        findInPage.stop();
+        return;
+      }
+      const result = findInPage.find(container, text);
+      setMatchInfo(toMatchInfo(result));
+    },
+    [findInPage, containerSelector]
+  );
+  const handleKeyDown = useCallback(
+    // Plain DOM `KeyboardEvent` — matches the ai-chat-modal onKeyDown
+    // precedent (`../ai-chat-modal/index.tsx`); Preact's JSX
+    // `onKeyDown` prop accepts it directly, no React-namespace type needed.
+    (e) => {
+      if (e.key === "Escape") {
+        onClose();
+      } else if (e.key === "Enter") {
+        const result = e.shiftKey ? findInPage.prev() : findInPage.next();
+        setMatchInfo(toMatchInfo(result));
+      }
+    },
+    [onClose, findInPage]
+  );
+  if (!visible) return null;
+  return /* @__PURE__ */ jsxs("div", { className: "fixed top-[3.5rem] right-0 z-dropdown flex items-center gap-hsp-sm py-hsp-xs px-hsp-md bg-surface border-b border-l border-muted rounded-bl-lg shadow-md", children: [
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        ref: inputRef,
+        className: "w-48 py-[4px] px-hsp-sm rounded text-small bg-bg border border-muted text-fg outline-none focus:border-accent",
+        type: "text",
+        value: query,
+        placeholder: "Find in page...",
+        "aria-label": "Find in page",
+        onChange: (e) => {
+          setQuery(e.currentTarget.value);
+          handleFind(e.currentTarget.value);
+        },
+        onKeyDown: handleKeyDown
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { className: "text-caption whitespace-nowrap min-w-[3rem] text-center text-fg/60", children: matchInfo ? `${matchInfo.activeMatchOrdinal}/${matchInfo.matches}` : "" }),
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: "py-hsp-2xs px-hsp-sm rounded text-caption bg-bg border border-muted text-fg hover:bg-surface",
+        onClick: () => {
+          const result = findInPage.prev();
+          setMatchInfo(toMatchInfo(result));
+        },
+        title: "Previous (Shift+Enter)",
+        children: "Prev"
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: "py-hsp-2xs px-hsp-sm rounded text-caption bg-bg border border-muted text-fg hover:bg-surface",
+        onClick: () => {
+          const result = findInPage.next();
+          setMatchInfo(toMatchInfo(result));
+        },
+        title: "Next (Enter)",
+        children: "Next"
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: "py-hsp-2xs px-hsp-sm rounded text-caption bg-bg border border-muted text-fg hover:bg-surface",
+        onClick: onClose,
+        title: "Close (Esc)",
+        children: "Close"
+      }
+    )
+  ] });
+}
+export {
+  FindBar
+};

package/dist/find-in-page/find-in-page.d.ts

@@ -0,0 +1,17 @@
+export interface FindResult {
+    matches: number;
+    activeMatchOrdinal: number;
+}
+export interface FindInPage {
+    find(container: HTMLElement, query: string): FindResult;
+    next(): FindResult;
+    prev(): FindResult;
+    stop(): void;
+}
+/**
+ * Create a DOM-based find-in-page utility.
+ *
+ * Limitation: only matches within single text nodes. Cross-element matching
+ * (e.g. "Hello world" spanning `<strong>Hello</strong> world`) is not supported.
+ */
+export declare function createFindInPage(): FindInPage;

package/dist/find-in-page/find-in-page.js

@@ -0,0 +1,131 @@
+const MATCH_CLASS = "find-match";
+const ACTIVE_CLASS = "find-match-active";
+const MATCH_ATTR = "data-find-match";
+const ACTIVE_ATTR = "data-find-active";
+const EMPTY_RESULT = Object.freeze({ matches: 0, activeMatchOrdinal: 0 });
+function createFindInPage() {
+  let matchElements = [];
+  let activeIndex = -1;
+  function clearMarks() {
+    const parentsToNormalize = /* @__PURE__ */ new Set();
+    for (let i = matchElements.length - 1; i >= 0; i--) {
+      const mark = matchElements[i];
+      const parent = mark.parentNode;
+      if (parent) {
+        const textNode = document.createTextNode(mark.textContent || "");
+        parent.replaceChild(textNode, mark);
+        parentsToNormalize.add(parent);
+      }
+    }
+    for (const parent of parentsToNormalize) {
+      parent.normalize();
+    }
+    matchElements = [];
+    activeIndex = -1;
+  }
+  function setActive(index) {
+    if (activeIndex >= 0 && activeIndex < matchElements.length) {
+      const prev2 = matchElements[activeIndex];
+      prev2.classList.remove(ACTIVE_CLASS);
+      prev2.removeAttribute(ACTIVE_ATTR);
+    }
+    activeIndex = index;
+    if (activeIndex >= 0 && activeIndex < matchElements.length) {
+      const current = matchElements[activeIndex];
+      current.classList.add(ACTIVE_CLASS);
+      current.setAttribute(ACTIVE_ATTR, "true");
+      current.scrollIntoView?.({ block: "center" });
+    }
+  }
+  function currentResult() {
+    if (matchElements.length === 0) {
+      return EMPTY_RESULT;
+    }
+    return {
+      matches: matchElements.length,
+      activeMatchOrdinal: activeIndex + 1
+    };
+  }
+  function find(container, query) {
+    clearMarks();
+    if (!query) {
+      return EMPTY_RESULT;
+    }
+    const lowerQuery = query.toLowerCase();
+    const walker = document.createTreeWalker(
+      container,
+      NodeFilter.SHOW_TEXT,
+      null
+    );
+    const textNodes = [];
+    let node;
+    while (node = walker.nextNode()) {
+      textNodes.push(node);
+    }
+    for (const textNode of textNodes) {
+      const text = textNode.textContent || "";
+      const lowerText = text.toLowerCase();
+      const positions = [];
+      let searchFrom = 0;
+      while (searchFrom < lowerText.length) {
+        const idx = lowerText.indexOf(lowerQuery, searchFrom);
+        if (idx === -1) break;
+        positions.push(idx);
+        searchFrom = idx + lowerQuery.length;
+      }
+      if (positions.length === 0) continue;
+      const parent = textNode.parentNode;
+      if (!parent) continue;
+      let remainingNode = textNode;
+      const nodeMarks = [];
+      for (let i = positions.length - 1; i >= 0; i--) {
+        const pos = positions[i];
+        const matchLen = query.length;
+        if (pos + matchLen < remainingNode.length) {
+          remainingNode.splitText(pos + matchLen);
+        }
+        let matchNode;
+        if (pos > 0) {
+          matchNode = remainingNode.splitText(pos);
+        } else {
+          matchNode = remainingNode;
+        }
+        const mark = document.createElement("mark");
+        mark.className = MATCH_CLASS;
+        mark.setAttribute(MATCH_ATTR, "true");
+        mark.textContent = matchNode.textContent;
+        parent.replaceChild(mark, matchNode);
+        nodeMarks.unshift(mark);
+      }
+      matchElements.push(...nodeMarks);
+    }
+    if (matchElements.length === 0) {
+      return EMPTY_RESULT;
+    }
+    setActive(0);
+    return currentResult();
+  }
+  function next() {
+    if (matchElements.length === 0) {
+      return EMPTY_RESULT;
+    }
+    const newIndex = (activeIndex + 1) % matchElements.length;
+    setActive(newIndex);
+    return currentResult();
+  }
+  function prev() {
+    if (matchElements.length === 0) {
+      return EMPTY_RESULT;
+    }
+    const newIndex = (activeIndex - 1 + matchElements.length) % matchElements.length;
+    setActive(newIndex);
+    return currentResult();
+  }
+  function stop() {
+    clearMarks();
+  }
+  return { find, next, prev, stop };
+}
+export {
+  createFindInPage
+};

package/dist/find-in-page/index.d.ts

@@ -0,0 +1,11 @@
+import type { JSX } from "preact";
+/**
+ * `displayName` pinned explicitly (matching
+ * `AiChatModal`/`ImageEnlarge`/`MermaidEnlarge`/`DesignTokenPanelBootstrap`)
+ * so zfb's `captureComponentName` emits a stable
+ * `data-zfb-island="FindInPageInit"` marker independent of minification.
+ */
+export declare function FindInPageInit(): JSX.Element | null;
+export declare namespace FindInPageInit {
+    var displayName: string;
+}

package/dist/find-in-page/index.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx } from "preact/jsx-runtime";
+import { useState, useEffect, useRef } from "preact/compat";
+import { FindBar } from "./find-bar.js";
+import { createFindInPage } from "./find-in-page.js";
+const CONTENT_SELECTOR = "article.zd-content";
+function FindInPageInit() {
+  const [isTauri, setIsTauri] = useState(false);
+  const [visible, setVisible] = useState(false);
+  const findInPageRef = useRef(createFindInPage());
+  useEffect(() => {
+    if (typeof window !== "undefined" && "__TAURI_INTERNALS__" in window) {
+      setIsTauri(true);
+    }
+  }, []);
+  useEffect(() => {
+    if (!isTauri) return;
+    const handler = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "f") {
+        e.preventDefault();
+        setVisible((prev) => !prev);
+      }
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [isTauri]);
+  useEffect(() => {
+    const handler = () => {
+      findInPageRef.current.stop();
+      setVisible(false);
+    };
+    document.addEventListener("zfb:before-preparation", handler);
+    return () => document.removeEventListener("zfb:before-preparation", handler);
+  }, []);
+  if (!isTauri) return null;
+  return /* @__PURE__ */ jsx(
+    FindBar,
+    {
+      visible,
+      onClose: () => setVisible(false),
+      findInPage: findInPageRef.current,
+      containerSelector: CONTENT_SELECTOR
+    }
+  );
+}
+FindInPageInit.displayName = "FindInPageInit";
+export {
+  FindInPageInit
+};

package/dist/footer/footer.js

@@ -11,6 +11,7 @@ function Footer(props) {
     "footer",
     {
       class: "border-t border-muted bg-surface",
+      "data-footer": true,
       ...persistKey ? { "data-zfb-transition-persist": persistKey } : {},
       children: /* @__PURE__ */ jsxs("div", { class: "mx-auto max-w-[clamp(50rem,75vw,90rem)] px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl", children: [
         hasColumns && /* @__PURE__ */ jsxs("div", { class: "grid grid-cols-1 gap-vsp-lg sm:grid-cols-2 lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))]", children: [

package/dist/frontmatter-preview-defaults/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default frontmatter-preview ignore-key list.
+ *
+ * Ported verbatim from the `create-zudo-doc` base template's
+ * `src/config/frontmatter-preview-defaults.ts`
+ * `DEFAULT_FRONTMATTER_IGNORE_KEYS` export (epic zudolab/zudo-doc#2651,
+ * S4 #2654).
+ *
+ * These are the schema-managed frontmatter keys handled by the framework
+ * that should be hidden from the frontmatter preview by default. Every
+ * entry corresponds to a field declared in the default docs schema
+ * (`@takazudo/zudo-doc/docs-schema`'s `buildDocsSchema`). A project adding
+ * custom frontmatter fields via its own schema should extend this list via
+ * `ZudoDocConfig`, not edit it in place.
+ */
+export declare const defaultFrontmatterPreviewIgnoreKeys: readonly string[];

package/dist/frontmatter-preview-defaults/index.js

@@ -0,0 +1,25 @@
+const defaultFrontmatterPreviewIgnoreKeys = [
+  "title",
+  "description",
+  "category",
+  "sidebar_position",
+  "sidebar_label",
+  "tags",
+  "search_exclude",
+  "pagination_next",
+  "pagination_prev",
+  "draft",
+  "unlisted",
+  "hide_sidebar",
+  "hide_toc",
+  "wide",
+  "doc_history",
+  "standalone",
+  "slug",
+  "generated",
+  "category_no_page",
+  "category_sort_order"
+];
+export {
+  defaultFrontmatterPreviewIgnoreKeys
+};

package/dist/head-with-defaults/index.d.ts

@@ -31,6 +31,8 @@ export interface HeadWithDefaultsSettings {
     siteName: string;
     colorMode?: ColorSchemeProviderColorMode | null | false;
     sidebarResizer?: boolean;
+    /** Configured theme-pack slug (ADR `docs/adr/theme-packs.md`, #2822). */
+    themePack?: string;
 }
 /**
  * Create a `HeadWithDefaults` component from the unified {@link ChromeContext}

package/dist/head-with-defaults/index.js

@@ -2,6 +2,10 @@ import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { OgTags, TwitterCard } from "../head/index.js";
 import { SIDEBAR_RESIZER_RESTORE_SCRIPT } from "../sidebar-resizer/index.js";
 import ColorSchemeProvider from "../theme/color-scheme-provider.js";
+import ThemePackProvider, {
+  themePackVersionMap
+} from "../theme/theme-pack-provider.js";
+import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
 import { deriveComposeMetaTitle, deriveColorSchemeGenerators } from "../chrome/derive.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createHeadWithDefaults(ctx) {
@@ -11,6 +15,10 @@ function createHeadWithDefaults(ctx) {
   const withBase = ctx.withBase;
   const absoluteUrl = ctx.absoluteUrl;
   const { generateCssCustomProperties, generateLightDarkCssProperties } = deriveColorSchemeGenerators(ctx);
+  const themePackRegistry = ctx.themePackRegistry;
+  const themePackEnabled = themePackRegistry !== null ? themePackVersionMap(themePackRegistry) : null;
+  const themePackConfigured = settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
+  const themePackBase = withBase("/");
   function HeadWithDefaults({
     title,
     description,
@@ -48,6 +56,14 @@ function createHeadWithDefaults(ctx) {
         }
       ),
       /* @__PURE__ */ jsx(ColorSchemeProvider, { cssText, colorMode }),
+      themePackEnabled !== null && /* @__PURE__ */ jsx(
+        ThemePackProvider,
+        {
+          configuredSlug: themePackConfigured,
+          enabled: themePackEnabled,
+          base: themePackBase
+        }
+      ),
       settings.sidebarResizer && /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: SIDEBAR_RESIZER_RESTORE_SCRIPT } }),
       /* @__PURE__ */ jsx("link", { rel: "icon", href: withBase("/favicon.ico"), sizes: "any" }),
       /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/png", sizes: "32x32", href: withBase("/favicon-32x32.png") }),

package/dist/header/header.d.ts

@@ -1,7 +1,7 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 import type { ComponentChildren, JSX } from "preact";
-import type { HeaderNavItem, HeaderRightItem, Locale } from "./types.js";
+import type { HeaderNavItem, HeaderRightComponentRegistry, HeaderRightItem, Locale } from "./types.js";
 /**
  * Boundary helpers the host injects into `<Header>`. These are the URL
  * builders the legacy header.tsx used to import from `@/utils/base` —
@@ -71,10 +71,9 @@ export interface HeaderProps {
     /** Replacement for the `<Search />` Astro child. */
     search?: ComponentChildren;
     /**
-     * When provided, emits `data-zfb-transition-persist={persistKey}` on the
+     * Emits `data-zfb-transition-persist={persistKey}` on the
      * `<header>` element so zfb's client-router preserves DOM-node identity
-     * across same-locale View Transition swaps. Omit to disable persist
-     * (back-compat default — the header is re-rendered on every swap).
+     * across same-locale View Transition swaps.
      *
      * **Locale keying**: callers MUST key by locale (e.g. `"header-en"`,
      * `"header-ja"`). Cross-locale swaps must NOT share the same key; a
@@ -90,7 +89,7 @@ export interface HeaderProps {
      * for consistency, matching the Astro reference implementation
      * (zudolab/zudo-doc#1546).
      */
-    persistKey?: string;
+    persistKey: string;
     /** Site-name string shown in the logo anchor (host `settings.siteName`). */
     siteName: string;
     /** Header-nav items in render order (host `settings.headerNav`). */
@@ -105,6 +104,12 @@ export interface HeaderProps {
      * wrapper, matching prior behaviour.
      */
     headerRightItems: HeaderRightItem[];
+    /**
+     * Host-callable renderers for project-owned component names. The registry is
+     * carried through `chromeBindingsModule`; it is never part of the serialized
+     * settings payload. Package built-in names are reserved.
+     */
+    headerRightComponents?: HeaderRightComponentRegistry;
     /**
      * Whether the host has a `colorMode` config. Required because the
      * `theme-toggle` right-item is two-gated: the filter drops it when