@takazudo/zudo-doc 3.3.0 → 4.1.0

package/dist/factory-context/index.d.ts

@@ -1,5 +1,6 @@
 import type { Settings, TagVocabularyEntry } from "../settings.js";
 import type { ColorScheme } from "../color-scheme-utils.js";
+import type { ThemePackRegistry } from "../theme-packs-registry/index.js";
 import type { UrlHelpers } from "../url-helpers/index.js";
 import type { NavSourceDocsAPI } from "../nav-source-docs/index.js";
 import type { DocRouteEntriesAPI } from "../doc-route-entries/index.js";
@@ -8,6 +9,7 @@ import type { ResolvedTag } from "../tag-helpers/index.js";
 import type { DocNavNode, DocPageEntry } from "../doc-page-props/index.js";
 import type { HeadingItem } from "../extract-headings/index.js";
 import type { CategoryMeta } from "../sidebar-tree/index.js";
+import type { HeaderRightComponentRegistry } from "../header/types.js";
 /**
  * The i18n surface a factory may read. Parameterizes what `base.ts` used to read
  * off the project's `@/config/i18n` singleton directly, so URL/locale logic moves
@@ -103,6 +105,21 @@ export interface RouteContextPayload<S = Settings> {
     /** Host color-scheme palette map; `null` when the host passed none (chrome
      *  then falls back to a neutral default scheme). */
     colorSchemes: Record<string, ColorScheme> | null;
+    /**
+     * Resolved, enabled, ordered theme-pack registry (ADR
+     * `docs/adr/theme-packs.md`, Decision 2 "Registry threading to
+     * SSR/islands") — settings ∩ the bundled `theme-packs/` directories, in
+     * switcher order. `null` (or omitted) renders the whole feature inert (same
+     * accepted coupling class as {@link colorSchemes} for a
+     * `packageOwnedRoutes: false` host that builds its own payload without
+     * threading one).
+     *
+     * OPTIONAL on purpose: this field was added after the payload shape
+     * shipped, so an existing `packageOwnedRoutes: false` host that constructs
+     * its own payload predates it. `createRouteContext` normalizes an omitted
+     * value to `null` (→ inert) so upgrading such a host does not throw at SSR.
+     */
+    themePackRegistry?: ThemePackRegistry | null;
 }
 /** Aggregated `tag → docs` index entry built by `collectTags`. */
 export interface TagInfo {
@@ -133,6 +150,9 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     settings: S;
     /** Host color-scheme palette map (or `null`); threaded to chrome head CSS. */
     colorSchemes: Record<string, ColorScheme> | null;
+    /** Resolved, enabled, ordered theme-pack registry (or `null`) — see
+     *  {@link RouteContextPayload.themePackRegistry}. */
+    themePackRegistry: ThemePackRegistry | null;
     /** The reconstructed i18n surface. */
     i18n: FactoryI18n;
     /** Default locale code (un-prefixed `/docs/...`). */
@@ -162,14 +182,14 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     resolveTagBound(raw: string): ResolvedTag;
     /** Aggregate a `tag → docs` index from a doc collection. */
     collectTags(entries: ReadonlyArray<{
-        id: string;
+        slug: string;
         data: {
             slug?: string;
             title?: string;
             description?: string;
             tags?: string[];
         };
-    }>, slugFn: (id: string, data: {
+    }>, slugFn: (entrySlug: string, data: {
         slug?: string;
     }) => string): Map<string, TagInfo>;
     /** Build a recursive nav tree from a flat doc collection. */
@@ -188,8 +208,8 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     isNavVisible(doc: DocPageEntry): boolean;
     /** The content-bridge handle: identity-stable, draft-filtered docs loader. */
     stableDocs(collectionName: string): DocPageEntry[];
-    /** Canonical route slug for a doc id. */
-    toRouteSlug(id: string): string;
+    /** Canonical route slug for a zfb content slug. */
+    toRouteSlug(entrySlug: string): string;
     /** Split a route slug into path params. */
     toSlugParams(routeSlug: string): string[];
 }
@@ -202,8 +222,26 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
  * (HOSTCOLLAPSE wave) later passes the real bindings.
  */
 export interface ChromeHostBindings {
+    /** Primary header chrome. Default: the package HeaderWithDefaults component. */
+    Header?: FactoryComponent;
+    /** Primary footer chrome. Default: the package FooterWithDefaults component. */
+    Footer?: FactoryComponent;
+    /** Primary doc sidebar chrome. Default: the package SidebarWithDefaults component. */
+    Sidebar?: FactoryComponent;
+    /** Primary desktop table of contents. Default: the package Toc component. */
+    Toc?: FactoryComponent;
+    /** Primary breadcrumb trail. Default: the package Breadcrumb component. */
+    Breadcrumb?: FactoryComponent;
+    /** Primary previous/next document pager. Default: the package DocPager component. */
+    DocPager?: FactoryComponent;
     /** Header search widget. Default: the package SearchWidget bound to the site base. */
     SearchWidget?: FactoryComponent;
+    /**
+     * Project-owned header-right renderers keyed by the serializable component
+     * name in `settings.headerRightItems`. Built-in names are reserved and may
+     * not be shadowed. Default: `{}`.
+     */
+    headerRightComponents?: HeaderRightComponentRegistry;
     /** Per-page git-history meta manifest. Default: `{}` (no Created/Updated block). */
     docHistoryMeta?: Record<string, unknown>;
     /** Sidebar section config. Default: `{}` (auto-generated tree only). */

package/dist/features.css

@@ -20,6 +20,8 @@
  *   --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
@@ -46,11 +48,11 @@ header[data-header] {
   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;
 }
@@ -139,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),
@@ -183,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));
 }
 
@@ -212,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);
 }
@@ -242,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;
@@ -253,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] {
@@ -934,8 +946,15 @@ dialog.zd-mermaid-dialog::backdrop {
  *
  * Single source of truth: `src/config/component-tokens.ts` (tokens with
  * `surface: "chrome"`). The `gen-component-tokens` generator owns the BEGIN/END
- * block below — never hand-edit between the markers. Seeded empty: no chrome
- * tokens exist yet (S1, #2458 added only the routing mechanism).
+ * block below — never hand-edit between the markers.
+ *
+ * The `body { font-family }` rule below is the CHROME FONT SEAM (#2887): it is
+ * why a theme pack's `--font-sans` reaches the header/sidebar/TOC/footer at all.
+ * Those surfaces set no font-family of their own, and preflight's `html, :host`
+ * rule compiles to a hardcoded literal stack here (no `--default-font-family` is
+ * ever defined), so without this rule the token could only ever reach `.zd-content`
+ * prose. It works because this block is UNLAYERED and preflight is imported into
+ * `layer(zd-preflight)` — see component-tokens.ts for the full rationale.
  * ========================================================================== */
 
 /* BEGIN --zdc-* chrome component tokens (generated by gen-component-tokens; do not edit by hand) */
@@ -957,4 +976,20 @@ a[data-nav-active] {
   font-weight: var(--zdc-nav-active-weight, var(--font-weight-medium));
 }
 
+body {
+  font-family: var(--zdc-chrome-font, var(--font-sans));
+}
+
+header[data-header] {
+  font-family: var(--zdc-header-font, var(--zdc-chrome-font, var(--font-sans)));
+}
+
+#desktop-sidebar, aside[data-zd-mobile-sidebar] {
+  font-family: var(--zdc-sidebar-font, var(--zdc-chrome-font, var(--font-sans)));
+}
+
+nav[data-zd-toc], div[data-zd-mobile-toc] {
+  font-family: var(--zdc-toc-font, var(--zdc-chrome-font, var(--font-sans)));
+}
+
 /* END --zdc-* chrome component tokens */

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/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

package/dist/header/header.js

@@ -25,6 +25,7 @@ function Header(props) {
     siteName,
     headerNav,
     headerRightItems,
+    headerRightComponents,
     colorModeEnabled,
     hasLocales,
     hasVersions,
@@ -37,6 +38,7 @@ function Header(props) {
   const pathWithoutBase = urlHelpers.stripBase(currentPath);
   const matchPath = pathForMatch(pathWithoutBase, lang, i18n.defaultLocale);
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
+  const rightItemDispatch = createRightItemDispatch(headerRightComponents);
   return /* @__PURE__ */ jsxs(
     "header",
     {
@@ -114,7 +116,8 @@ function Header(props) {
                 search,
                 colorModeEnabled,
                 hasLocales
-              }
+              },
+              rightItemDispatch
             ))
           }
         ),
@@ -268,7 +271,14 @@ function SlotWrapper({
 }) {
   return /* @__PURE__ */ jsx("div", { class: className, children }, `right-${index}`);
 }
-const RIGHT_ITEM_DISPATCH = {
+const BUILTIN_COMPONENT_NAMES = [
+  "theme-toggle",
+  "language-switcher",
+  "version-switcher",
+  "github-link",
+  "search"
+];
+const BASE_RIGHT_ITEM_DISPATCH = {
   "trigger:design-token-panel": (_item, index) => /* @__PURE__ */ jsx(
     TriggerButton,
     {
@@ -385,10 +395,40 @@ const RIGHT_ITEM_DISPATCH = {
     );
   }
 };
-function renderRightItem(item, index, ctx) {
+function createRightItemDispatch(hostRegistry) {
+  const dispatch = new Map(
+    Object.entries(BASE_RIGHT_ITEM_DISPATCH)
+  );
+  if (hostRegistry === void 0) return dispatch;
+  for (const [name, component] of Object.entries(hostRegistry)) {
+    if (BUILTIN_COMPONENT_NAMES.includes(name)) {
+      throw new Error(
+        `[zudo-doc] Duplicate header-right component name "${name}" at chromeBindings.headerRightComponents[${JSON.stringify(name)}]: built-in names are reserved and cannot be shadowed. Remove this registry entry or choose a project-owned name.`
+      );
+    }
+    if (typeof component !== "function") {
+      throw new TypeError(
+        `[zudo-doc] Invalid header-right component "${name}" at chromeBindings.headerRightComponents[${JSON.stringify(name)}]: expected a callable renderer.`
+      );
+    }
+    dispatch.set(`component:${name}`, (item, index, ctx) => {
+      if (item.type !== "component") return null;
+      const CustomComponent = component;
+      return /* @__PURE__ */ jsx(SlotWrapper, { index, children: /* @__PURE__ */ jsx(CustomComponent, { item, index, ...ctx }) });
+    });
+  }
+  return dispatch;
+}
+function renderRightItem(item, index, ctx, dispatch) {
   const key = item.type === "trigger" ? `trigger:${item.trigger}` : item.type === "component" ? `component:${item.component}` : item.type;
-  const handler = RIGHT_ITEM_DISPATCH[key];
-  return handler ? handler(item, index, ctx) : null;
+  const handler = dispatch.get(key);
+  if (handler) return handler(item, index, ctx);
+  if (item.type === "component") {
+    throw new Error(
+      `[zudo-doc] Unknown header-right component "${item.component}" at Header.headerRightItems[${index}].component. Register a callable renderer as chromeBindings.headerRightComponents["${item.component}"] through settings.chromeBindingsModule, or use a built-in name: ${BUILTIN_COMPONENT_NAMES.join(", ")}.`
+    );
+  }
+  return null;
 }
 export {
   Header

package/dist/header/index.d.ts

@@ -9,7 +9,7 @@
  * so downstream tests / custom layouts can reuse them without rebuilding
  * the `pathForMatch` / `computeActiveNavPath` regex logic.
  */
-export type { Locale, HeaderNavChildItem, HeaderNavItem, HeaderRightComponentItem, HeaderRightComponentName, HeaderRightHtmlItem, HeaderRightItem, HeaderRightLinkItem, HeaderRightTriggerItem, HeaderRightTriggerName, } from "./types.js";
+export type { Locale, HeaderNavChildItem, HeaderNavItem, HeaderRightBuiltinComponentName, HeaderRightComponentItem, HeaderRightComponentName, HeaderRightComponentProps, HeaderRightComponentRegistry, HeaderRightHtmlItem, HeaderRightItem, HeaderRightLinkItem, HeaderRightTriggerItem, HeaderRightTriggerName, } from "./types.js";
 export { filterHeaderRightItems, type HeaderRightItemFlags, } from "./right-items.js";
 export { Header, type HeaderProps } from "./header.js";
 export { computeActiveNavPath, isNavItemActive, pathForMatch, type NavItemLike, } from "./nav-active.js";

package/dist/header/types.d.ts

@@ -1,3 +1,4 @@
+import type { ComponentChildren } from "preact";
 /**
  * Locale code as seen by the header. Widened from the host's literal
  * union (`"en" | "ja" | …`) to plain `string` at the v2 boundary so the
@@ -14,12 +15,40 @@ export interface HeaderNavChildItem {
 export interface HeaderNavItem extends HeaderNavChildItem {
     children?: HeaderNavChildItem[];
 }
-export type HeaderRightComponentName = "theme-toggle" | "language-switcher" | "version-switcher" | "github-link" | "search";
+export type HeaderRightBuiltinComponentName = "theme-toggle" | "language-switcher" | "version-switcher" | "github-link" | "search";
+/**
+ * A serializable name resolved against the package built-ins plus the host's
+ * `headerRightComponents` chrome-binding registry. The intersection preserves
+ * built-in autocomplete while allowing project-owned names.
+ */
+export type HeaderRightComponentName = HeaderRightBuiltinComponentName | (string & {});
 export type HeaderRightTriggerName = "design-token-panel" | "ai-chat";
 export interface HeaderRightComponentItem {
     type: "component";
     component: HeaderRightComponentName;
 }
+/**
+ * Exact props passed to a host `headerRightComponents` renderer. They mirror
+ * the existing header-right dispatch context; no callable enters the
+ * serialized {@link HeaderRightComponentItem}.
+ */
+export interface HeaderRightComponentProps {
+    /** The serialized item that selected this renderer. */
+    item: HeaderRightComponentItem;
+    /** Zero-based position in the rendered `headerRightItems` array. */
+    index: number;
+    lang: Locale | undefined;
+    githubRepoUrl: string | null;
+    githubLabel: string;
+    themeToggle: ComponentChildren;
+    languageSwitcher: ComponentChildren;
+    versionSwitcher: ComponentChildren;
+    search: ComponentChildren;
+    colorModeEnabled: boolean;
+    hasLocales: boolean;
+}
+/** A callable-only host registry keyed by serialized component name. */
+export type HeaderRightComponentRegistry = Record<string, (props: HeaderRightComponentProps) => ComponentChildren>;
 export interface HeaderRightTriggerItem {
     type: "trigger";
     trigger: HeaderRightTriggerName;

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

@@ -149,6 +149,7 @@ function createHeaderWithDefaults(ctx) {
         siteName: settings.siteName,
         headerNav: settings.headerNav,
         headerRightItems,
+        headerRightComponents: ctx.hostBindings.headerRightComponents,
         colorModeEnabled: Boolean(settings.colorMode),
         hasLocales: locales.length > 1,
         hasVersions: Boolean(settings.versions),

package/dist/home-page/index.d.ts

@@ -30,6 +30,8 @@ export interface HomePageViewProps {
     tree: DocNavNode[];
     /** Ordered category prefixes, passed through to `SiteTreeNav`. */
     categoryOrder: string[];
+    /** Root-category slugs that should start collapsed in `SiteTreeNav`. */
+    initiallyCollapsedCategorySlugs?: string[];
     /** Unique tag count for the current locale — gates the "all tags" section
      *  together with `settings.docTags`. */
     tagCount: number;

package/dist/home-page/index.js

@@ -3,9 +3,9 @@ import { Island } from "@takazudo/zfb";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
 import { SiteTreeNav } from "../site-tree-nav-island/index.js";
 import { createHeadWithDefaults } from "../head-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 { deriveComposeMetaTitle, deriveBodyEndIslands } from "../chrome/derive.js";
+import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 import { prepareHomeData } from "./prepare-home-data.js";
 function createHomePageView(ctx) {
@@ -16,15 +16,19 @@ function createHomePageView(ctx) {
   const defaultLocale = ctx.defaultLocale;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
-  const HeaderWithDefaults = createHeaderWithDefaults(ctx);
-  const FooterWithDefaults = createFooterWithDefaults(ctx);
+  const { Header: HeaderWithDefaults, Footer: FooterWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const homeExtras = ctx.hostBindings.homeExtras;
+  const dataThemePack = resolveThemePackSsrSlug(
+    ctx.themePackRegistry,
+    ctx.settings
+  );
   function HomePageView({
     locale,
     extras,
     tree,
     categoryOrder,
+    initiallyCollapsedCategorySlugs,
     tagCount,
     wide
   }) {
@@ -39,6 +43,7 @@ function createHomePageView(ctx) {
         title: composeMetaTitle(settings.siteName),
         head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: settings.siteName }),
         lang: locale,
+        dataThemePack,
         noindex: settings.noindex,
         hideSidebar: true,
         hideToc: true,
@@ -99,7 +104,8 @@ function createHomePageView(ctx) {
               {
                 tree,
                 categoryOrder,
-                categoryIgnore: ["inbox", "develop"]
+                categoryIgnore: ["inbox", "develop"],
+                initiallyCollapsedCategorySlugs
               }
             )
           }),

package/dist/home-page/prepare-home-data.js

@@ -28,7 +28,7 @@ function prepareHomeData(ctx, locale, options) {
   const grouped = ctx.groupSatelliteNodes(tree, categoryOrder);
   const tagCount = ctx.collectTags(
     navDocs.filter((d) => !d.data.category_no_page),
-    (id, data) => data.slug ?? ctx.toRouteSlug(id)
+    (entrySlug, data) => data.slug ?? ctx.toRouteSlug(entrySlug)
   ).size;
   return { tree: grouped, categoryOrder, tagCount };
 }