@takazudo/zudo-doc 3.3.0 → 4.0.0

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] {

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

package/dist/locale-merge/index.d.ts

@@ -1,12 +1,11 @@
 /**
  * Minimal structural interface for a docs entry.
  *
- * Structurally compatible with the host's `DocsEntry` from
- * `@/types/docs-entry`. Callers pass their concrete entry arrays and
- * TypeScript's structural typing ensures compatibility.
+ * Structurally compatible with a current zfb collection entry. Callers pass
+ * concrete entry arrays and TypeScript preserves the subtype in the result.
  */
 export interface MergeDocsEntry {
-    id: string;
+    slug: string;
     data: {
         slug?: string;
         unlisted?: boolean;
@@ -58,13 +57,10 @@ export interface MergeLocaleDocsOptions<T extends MergeDocsEntry = MergeDocsEntr
      * Only called when `applyDefaultLocaleOnlyFilter` is true. The host stub
      * passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
      *
-     * When omitted (or when `applyDefaultLocaleOnlyFilter` is false), no path
-     * filtering is applied.
-     *
-     * Example: host passes `(path) => isDefaultLocaleOnlyPath(path)` where
-     * `isDefaultLocaleOnlyPath` is from `src/utils/base.ts`.
+     * Required explicitly so the merge never silently omits the current
+     * default-locale-only path contract.
      */
-    isDefaultLocaleOnlyPath?: (path: string) => boolean;
+    isDefaultLocaleOnlyPath: (path: string) => boolean;
 }
 /**
  * Result of mergeLocaleDocs.
@@ -103,10 +99,9 @@ export interface MergeLocaleDocsResult<T extends MergeDocsEntry = MergeDocsEntry
  * Locale docs take priority; base docs fill in slugs not covered by the locale
  * collection. Optionally excludes default-locale-only paths and/or unlisted pages.
  *
- * **Slug keying**: slug identity uses `d.data.slug ?? d.id`. Since `loadDocs`
- * already strips the `/index` suffix (via `stripIndexSuffix` in `pages/_data.ts`),
- * this key is consistent across all call sites regardless of whether they
- * loaded docs via `loadDocs` or `bridgeEntries`.
+ * **Slug keying**: slug identity uses the explicit frontmatter override or
+ * the canonical route form of the current zfb `entry.slug`. This preserves
+ * root `index` and nested index-page behavior without mutating the entries.
  *
  * **Array identity**: returns a fresh array on each call — see
  * {@link MergeLocaleDocsResult} for caching guidance.

package/dist/locale-merge/index.js

@@ -1,3 +1,4 @@
+import { toRouteSlug } from "../slug/index.js";
 function mergeLocaleDocs(options) {
   const {
     baseDocs,
@@ -8,13 +9,14 @@ function mergeLocaleDocs(options) {
   } = options;
   const filteredLocale = keepUnlisted ? localeDocs : localeDocs.filter((d) => !d.data.unlisted);
   const filteredBase = keepUnlisted ? baseDocs : baseDocs.filter((d) => !d.data.unlisted);
-  const localeSlugSet = new Set(filteredLocale.map((d) => d.data.slug ?? d.id));
+  const routeSlug = (entry) => entry.data.slug ?? toRouteSlug(entry.slug);
+  const localeSlugSet = new Set(filteredLocale.map(routeSlug));
   let fallbackDocs = filteredBase.filter(
-    (d) => !localeSlugSet.has(d.data.slug ?? d.id)
+    (entry) => !localeSlugSet.has(routeSlug(entry))
   );
-  if (applyDefaultLocaleOnlyFilter && isDefaultLocaleOnlyPath) {
+  if (applyDefaultLocaleOnlyFilter) {
     fallbackDocs = fallbackDocs.filter(
-      (d) => !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? d.id}`)
+      (entry) => !isDefaultLocaleOnlyPath("/docs/" + routeSlug(entry))
     );
   }
   return {

package/dist/mdx-components/index.js

@@ -1,5 +1,5 @@
 import { toChildArray } from "preact";
-import { htmlOverrides } from "../content/index.js";
+import { defaultComponents } from "../content/index.js";
 import { makeAdmonition } from "../content-admonition/index.js";
 import { CodeGroup } from "../code-group/index.js";
 import { Tabs } from "../code-syntax/index.js";
@@ -105,7 +105,7 @@ function makeEnlargeableParagraph(imageEnlarge, ContentImg) {
         }
       }
     }
-    return htmlOverrides.p(props);
+    return defaultComponents.p(props);
   };
 }
 function createMdxComponents(options) {
@@ -119,11 +119,11 @@ function createMdxComponents(options) {
   const CategoryTreeNavBound = (props) => navData.CategoryTreeNav({ ...props, lang: locale });
   const SiteTreeNavBound = (props) => navData.SiteTreeNav({ ...props, lang: locale });
   return {
-    ...htmlOverrides,
+    ...defaultComponents,
     // img override: rewrites root-relative src to include settings.base.
     img: ContentImg,
     // p override: wraps block-level images in <figure class="zd-enlargeable">.
-    // Must come AFTER ...htmlOverrides to override ContentParagraph.
+    // Must come AFTER ...defaultComponents to override ContentParagraph.
     p: EnlargeableParagraph,
     // Admonitions — real typed Preact components emitting the
     // `.admonition` / `data-admonition` structure the design-system CSS

package/dist/plugins/claude-resources.d.ts

@@ -1,3 +1,4 @@
 import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+export { runClaudeResourcesPreStep } from "./internal/claude-resources/index.js";
 declare const plugin: ZfbPlugin;
 export default plugin;

package/dist/plugins/claude-resources.js

@@ -1,4 +1,5 @@
-import { runClaudeResourcesPreStep } from "../integrations/claude-resources/index.js";
+import { runClaudeResourcesPreStep } from "./internal/claude-resources/index.js";
+import { runClaudeResourcesPreStep as runClaudeResourcesPreStep2 } from "./internal/claude-resources/index.js";
 const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
 const plugin = {
   name: PLUGIN_NAME,
@@ -25,5 +26,6 @@ const plugin = {
 };
 var claude_resources_default = plugin;
 export {
-  claude_resources_default as default
+  claude_resources_default as default,
+  runClaudeResourcesPreStep2 as runClaudeResourcesPreStep
 };

package/dist/plugins/doc-history.js

@@ -2,7 +2,7 @@ import {
   runDocHistoryMetaStep,
   runDocHistoryPostBuild,
   createDocHistoryDevMiddleware
-} from "../integrations/doc-history/index.js";
+} from "./internal/doc-history/index.js";
 import { connectToZfbHandler } from "./connect-adapter.js";
 import { getBasePrefix } from "./plugin-utils.js";
 const plugin = {

package/dist/{integrations → plugins/internal}/claude-resources/index.d.ts

@@ -1,10 +1,5 @@
 import { generateClaudeResourcesDocs, type ClaudeResourcesConfig } from "./generate.js";
-export interface ZfbPluginConfig {
-    name: string;
-    options?: Record<string, unknown>;
-}
-export declare const CLAUDE_RESOURCES_PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
-/** Options accepted by both the plugin entry and the imperative runner. */
+/** Options accepted by the plugin's generator runner. */
 export interface ClaudeResourcesPluginOptions {
     /**
      * Path to the project's `.claude/` directory holding `commands/`,
@@ -40,16 +35,6 @@ export interface ClaudeResourcesPluginOptions {
      */
     docsDir?: string;
 }
-/**
- * Declarative plugin entry for `zfb.config.ts`. Returns the
- * `{ name, options }` shape that zfb's plugins array consumes.
- *
- * v0 note: zfb does not yet invoke plugin lifecycles, so registering the
- * plugin alone does not run generation today. Pair it with a call to
- * `runClaudeResourcesPreStep` from a `prebuild`-style script until the
- * lifecycle hook lands. The plugin entry itself is forward-compatible.
- */
-export declare function claudeResourcesPlugin(options: ClaudeResourcesPluginOptions): ZfbPluginConfig;
 /**
  * Imperative pre-step runner. Resolves relative paths against
  * `projectRoot` (defaults to `process.cwd()`) and invokes the underlying