@takazudo/zudo-doc 3.2.0 → 4.0.0

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/i18n-defaults/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Default UI-string translation table.
+ *
+ * Ported verbatim from the `create-zudo-doc` base template's
+ * `src/config/i18n.ts` `translations` export (epic zudolab/zudo-doc#2651,
+ * S4 #2654) so a generated project needs no i18n config file of its own.
+ *
+ * Locale code → key → translated string. Fully populated for `en`, `ja`, and
+ * `de`; the other locales in the generator's `SUPPORTED_LANGS` list
+ * (zh-cn/zh-tw/ko/es/fr/pt) fall back to `en` at lookup time (the template's
+ * `t()` helper does `translations[locale]?.[key] ?? translations[defaultLocale]?.[key] ?? key`)
+ * rather than shipping their own fully-translated table here.
+ *
+ * Locale label/derivation (mapping a locale code to its display label,
+ * detecting the active locale from a URL, etc.) stays settings-driven and is
+ * reconstructed by `route-context`/`url-helpers` — this module is DATA only.
+ * A project's `ZudoDocConfig.translations` override is merged over this
+ * default by `zudoDoc()` (#2657); the merge/lookup helper itself is not part
+ * of this module.
+ */
+import type { PresetTranslations } from "../preset.js";
+export declare const defaultTranslations: PresetTranslations;

package/dist/i18n-defaults/index.js

@@ -0,0 +1,167 @@
+const defaultTranslations = {
+  en: {
+    "nav.gettingStarted": "Getting Started",
+    "nav.learn": "Learn",
+    "nav.guides": "Guides",
+    "nav.components": "Components",
+    "nav.reference": "Reference",
+    "nav.claude": "Claude",
+    "nav.changelog": "Changelog",
+    "nav.develop": "Develop",
+    "nav.previous": "Previous",
+    "nav.next": "Next",
+    "nav.overview": "Overview",
+    "toc.title": "On this page",
+    "docs.browseAll": "Browse all documentation sections.",
+    "search.label": "Search",
+    "search.placeholder": "Type to search...",
+    "search.shortcutHint": "to open search from anywhere",
+    "search.resultCount": "{count} results",
+    "search.unavailable": "Search unavailable",
+    "search.loadingIndex": "Loading search index\u2026",
+    "search.noResults": "No results found.",
+    "code.copy": "Copy code",
+    "code.copied": "Copied!",
+    "code.wrapToggle": "Toggle word wrap",
+    "doc.editPage": "Edit this page",
+    "doc.viewSource": "View source on GitHub",
+    "header.github": "GitHub repository",
+    "doc.tags": "Tags",
+    "doc.taggedWith": "Pages tagged with",
+    "doc.allTags": "All Tags",
+    "doc.created": "Created",
+    "doc.updated": "Updated",
+    "doc.noTags": "No tags found.",
+    "doc.pageCount": "{count} pages",
+    "doc.pageCountSingle": "{count} page",
+    "nav.backToMenu": "Back to main menu",
+    "doc.fallbackNotice": "This page has not been translated yet and is shown in the original language.",
+    "frontmatter.preview.title": "Frontmatter",
+    "frontmatter.preview.keyCol": "Key",
+    "frontmatter.preview.valueCol": "Value",
+    "version.latest": "Latest",
+    "version.switcher.label": "Version",
+    "version.banner.unmaintained": "You are viewing documentation for an older version.",
+    "version.banner.unreleased": "You are viewing unreleased documentation.",
+    "version.banner.latestLink": "View the latest version",
+    "version.switcher.unavailable": "Not available in this version",
+    "version.switcher.allVersions": "All versions",
+    "version.page.title": "Documentation Versions",
+    "version.page.latest.title": "Latest Version (Current)",
+    "version.page.latest.description": "The most up-to-date documentation for the latest stable release.",
+    "version.page.latest.link": "View latest docs",
+    "version.page.past.title": "Past Versions",
+    "version.page.past.description": "Documentation for previously released versions.",
+    "version.page.unmaintained": "Unmaintained",
+    "version.page.unreleased": "Unreleased",
+    "version.page.status": "Status",
+    "version.page.docs": "Docs"
+  },
+  ja: {
+    "nav.gettingStarted": "\u306F\u3058\u3081\u306B",
+    "nav.learn": "\u5B66\u3076",
+    "nav.guides": "\u30AC\u30A4\u30C9",
+    "nav.components": "\u30B3\u30F3\u30DD\u30FC\u30CD\u30F3\u30C8",
+    "nav.reference": "\u30EA\u30D5\u30A1\u30EC\u30F3\u30B9",
+    "nav.claude": "Claude",
+    "nav.changelog": "\u5909\u66F4\u5C65\u6B74",
+    "nav.develop": "\u958B\u767A",
+    "nav.previous": "\u524D\u3078",
+    "nav.next": "\u6B21\u3078",
+    "nav.overview": "\u6982\u8981",
+    "toc.title": "\u76EE\u6B21",
+    "docs.browseAll": "\u3059\u3079\u3066\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u30BB\u30AF\u30B7\u30E7\u30F3\u3092\u95B2\u89A7",
+    "search.label": "\u691C\u7D22",
+    "search.placeholder": "\u691C\u7D22\u3057\u305F\u3044\u5358\u8A9E\u3092\u5165\u529B",
+    "search.shortcutHint": "\u3044\u3064\u3067\u3082\u691C\u7D22\u30D0\u30FC\u3092\u958B\u3051\u308B",
+    "search.resultCount": "{count} \u4EF6",
+    "search.unavailable": "\u691C\u7D22\u3092\u5229\u7528\u3067\u304D\u307E\u305B\u3093",
+    "search.loadingIndex": "\u691C\u7D22\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u3092\u8AAD\u307F\u8FBC\u307F\u4E2D\u2026",
+    "search.noResults": "\u691C\u7D22\u7D50\u679C\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3067\u3057\u305F\u3002",
+    "code.copy": "\u30B3\u30FC\u30C9\u3092\u30B3\u30D4\u30FC",
+    "code.copied": "\u30B3\u30D4\u30FC\u3057\u307E\u3057\u305F\uFF01",
+    "code.wrapToggle": "\u6298\u308A\u8FD4\u3057\u5207\u66FF",
+    "doc.editPage": "\u3053\u306E\u30DA\u30FC\u30B8\u3092\u7DE8\u96C6",
+    "doc.viewSource": "GitHub \u3067\u30BD\u30FC\u30B9\u3092\u898B\u308B",
+    "header.github": "GitHub \u30EA\u30DD\u30B8\u30C8\u30EA",
+    "doc.tags": "\u30BF\u30B0",
+    "doc.taggedWith": "\u30BF\u30B0\u4ED8\u304D\u30DA\u30FC\u30B8",
+    "doc.allTags": "\u3059\u3079\u3066\u306E\u30BF\u30B0",
+    "doc.created": "\u4F5C\u6210",
+    "doc.updated": "\u66F4\u65B0",
+    "doc.noTags": "\u30BF\u30B0\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002",
+    "doc.pageCount": "{count}\u30DA\u30FC\u30B8",
+    "doc.pageCountSingle": "{count}\u30DA\u30FC\u30B8",
+    "nav.backToMenu": "\u30E1\u30A4\u30F3\u30E1\u30CB\u30E5\u30FC\u306B\u623B\u308B",
+    "doc.fallbackNotice": "\u3053\u306E\u30DA\u30FC\u30B8\u306F\u307E\u3060\u7FFB\u8A33\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u539F\u6587\u306E\u307E\u307E\u8868\u793A\u3057\u3066\u3044\u307E\u3059\u3002",
+    "frontmatter.preview.title": "\u30D5\u30ED\u30F3\u30C8\u30DE\u30BF\u30FC",
+    "frontmatter.preview.keyCol": "\u30AD\u30FC",
+    "frontmatter.preview.valueCol": "\u5024",
+    "version.latest": "\u6700\u65B0",
+    "version.switcher.label": "\u30D0\u30FC\u30B8\u30E7\u30F3",
+    "version.banner.unmaintained": "\u3053\u308C\u306F\u65E7\u30D0\u30FC\u30B8\u30E7\u30F3\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3067\u3059\u3002",
+    "version.banner.unreleased": "\u3053\u308C\u306F\u672A\u30EA\u30EA\u30FC\u30B9\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3067\u3059\u3002",
+    "version.banner.latestLink": "\u6700\u65B0\u30D0\u30FC\u30B8\u30E7\u30F3\u3092\u898B\u308B",
+    "version.switcher.unavailable": "\u3053\u306E\u30D0\u30FC\u30B8\u30E7\u30F3\u3067\u306F\u5229\u7528\u3067\u304D\u307E\u305B\u3093",
+    "version.switcher.allVersions": "\u3059\u3079\u3066\u306E\u30D0\u30FC\u30B8\u30E7\u30F3",
+    "version.page.title": "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u30D0\u30FC\u30B8\u30E7\u30F3",
+    "version.page.latest.title": "\u6700\u65B0\u30D0\u30FC\u30B8\u30E7\u30F3\uFF08\u73FE\u5728\uFF09",
+    "version.page.latest.description": "\u6700\u65B0\u306E\u5B89\u5B9A\u7248\u30EA\u30EA\u30FC\u30B9\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3067\u3059\u3002",
+    "version.page.latest.link": "\u6700\u65B0\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u898B\u308B",
+    "version.page.past.title": "\u904E\u53BB\u306E\u30D0\u30FC\u30B8\u30E7\u30F3",
+    "version.page.past.description": "\u4EE5\u524D\u306B\u30EA\u30EA\u30FC\u30B9\u3055\u308C\u305F\u30D0\u30FC\u30B8\u30E7\u30F3\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3067\u3059\u3002",
+    "version.page.unmaintained": "\u30E1\u30F3\u30C6\u30CA\u30F3\u30B9\u7D42\u4E86",
+    "version.page.unreleased": "\u672A\u30EA\u30EA\u30FC\u30B9",
+    "version.page.status": "\u30B9\u30C6\u30FC\u30BF\u30B9",
+    "version.page.docs": "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8"
+  },
+  de: {
+    "nav.gettingStarted": "Erste Schritte",
+    "nav.learn": "Lernen",
+    "nav.guides": "Anleitungen",
+    "nav.components": "Komponenten",
+    "nav.reference": "Referenz",
+    "nav.claude": "Claude",
+    "nav.changelog": "Changelog",
+    "nav.develop": "Entwicklung",
+    "nav.previous": "Zur\xFCck",
+    "nav.next": "Weiter",
+    "nav.overview": "\xDCberblick",
+    "toc.title": "Auf dieser Seite",
+    "docs.browseAll": "Alle Dokumentationsabschnitte durchsuchen.",
+    "search.label": "Suche",
+    "search.placeholder": "Suchbegriff eingeben...",
+    "search.shortcutHint": "Suche von \xFCberall \xF6ffnen",
+    "search.resultCount": "{count} Ergebnisse",
+    "search.unavailable": "Suche nicht verf\xFCgbar",
+    "search.loadingIndex": "Suchindex wird geladen\u2026",
+    "search.noResults": "Keine Ergebnisse gefunden.",
+    "code.copy": "Code kopieren",
+    "code.copied": "Kopiert!",
+    "code.wrapToggle": "Zeilenumbruch umschalten",
+    "nav.backToMenu": "Zur\xFCck zum Hauptmen\xFC",
+    "doc.editPage": "Diese Seite bearbeiten",
+    "doc.viewSource": "Quellcode auf GitHub ansehen",
+    "header.github": "GitHub-Repository",
+    "doc.tags": "Tags",
+    "doc.taggedWith": "Seiten mit Tag",
+    "doc.allTags": "Alle Tags",
+    "doc.created": "Erstellt",
+    "doc.updated": "Aktualisiert",
+    "doc.noTags": "Keine Tags gefunden.",
+    "doc.pageCount": "{count} Seiten",
+    "doc.pageCountSingle": "{count} Seite",
+    "doc.fallbackNotice": "Diese Seite wurde noch nicht \xFCbersetzt und wird in der Originalsprache angezeigt.",
+    "frontmatter.preview.title": "Frontmatter",
+    "frontmatter.preview.keyCol": "Schl\xFCssel",
+    "frontmatter.preview.valueCol": "Wert",
+    "version.latest": "Neueste",
+    "version.switcher.label": "Version",
+    "version.banner.unmaintained": "Sie sehen die Dokumentation einer \xE4lteren Version.",
+    "version.banner.unreleased": "Sie sehen unver\xF6ffentlichte Dokumentation.",
+    "version.banner.latestLink": "Neueste Version anzeigen"
+  }
+};
+export {
+  defaultTranslations
+};

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

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

@@ -2,13 +2,6 @@ import path from "node:path";
 import {
   generateClaudeResourcesDocs
 } from "./generate.js";
-const CLAUDE_RESOURCES_PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
-function claudeResourcesPlugin(options) {
-  return {
-    name: CLAUDE_RESOURCES_PLUGIN_NAME,
-    options: { ...options }
-  };
-}
 function runClaudeResourcesPreStep(options) {
   const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
   const claudeDir = path.isAbsolute(options.claudeDir) ? options.claudeDir : path.resolve(projectRoot, options.claudeDir);
@@ -18,8 +11,6 @@ function runClaudeResourcesPreStep(options) {
   return generateClaudeResourcesDocs({ claudeDir, projectRoot: scanRoot, docsDir });
 }
 export {
-  CLAUDE_RESOURCES_PLUGIN_NAME,
-  claudeResourcesPlugin,
   generateClaudeResourcesDocs,
   runClaudeResourcesPreStep
 };

package/dist/{integrations → plugins/internal}/doc-history/index.d.ts

@@ -24,13 +24,6 @@ export interface DocHistoryOptions {
      */
     maxEntries?: number;
 }
-/** zfb v0 plugin descriptor — mirrors `PluginConfig` in `zfb/config`. */
-export interface DocHistoryPluginDescriptor {
-    /** Stable plugin id used by the future zfb plugin runtime to dispatch hooks. */
-    name: "doc-history";
-    /** Options forwarded verbatim into the zfb config; must be JSON-serialisable. */
-    options: DocHistoryOptions;
-}
 /** Default doc-history-server port — matches `@takazudo/zudo-doc-history-server`. */
 export declare const DEFAULT_SERVER_PORT = 4322;
 /** Default git history depth — matches `@takazudo/zudo-doc-history-server`. */
@@ -41,16 +34,6 @@ export declare const DOC_HISTORY_ROUTE_PREFIX = "/doc-history/";
 export declare const DOC_HISTORY_OUTPUT_DIRNAME = "doc-history";
 /** CLI bin name exposed by `@takazudo/zudo-doc-history-server` for inline generation. */
 export declare const DOC_HISTORY_GENERATE_BIN = "doc-history-generate";
-/**
- * Build the zfb config-side descriptor. Add the return value to the
- * `plugins: [...]` array in `zfb.config.ts`.
- *
- * The shape is intentionally limited to `{ name, options }` because
- * that is the only thing today's zfb config loader consumes (see the
- * Rust `PluginConfig` struct in zfb's `config.rs`). Runtime wiring is
- * done through the sibling helpers in this module.
- */
-export declare function docHistoryPlugin(options: DocHistoryOptions): DocHistoryPluginDescriptor;
 /** Connect-style middleware signature — works as a Vite plugin middleware. */
 export type ConnectMiddleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
 /** Minimal logger surface used by the middleware on proxy failure. */