create-zudo-doc 0.2.21 → 1.0.0

package/dist/zfb-config-gen.js

@@ -1,265 +1,60 @@
 /**
  * Programmatically generate zfb.config.ts from user choices.
  *
- * W7A (#1736): emits zfb plugins in the host's INLINE-OBJECT shape —
- * `{ name: "./plugins/<plugin>.mjs", options: {...} }` — not the
- * pre-cutover factory-import pattern (`import { fooPlugin } from
- * "./src/integrations/foo"`). Inline functions are not supported by zfb's
- * plugin runtime (see `@takazudo/zfb/plugins` source); plugins MUST be
- * authored as standalone `.mjs` modules referenced from `zfb.config.ts`
- * by `name`. The plugin source files are shipped by the base/feature
- * templates under `plugins/<plugin>.mjs` and `templates/features/<feature>/
- * files/plugins/<plugin>.mjs`.
+ * S5b (#2329): collapsed to the thin preset-based shape that mirrors the
+ * showcase `zfb.config.ts` after S5a. All collection wiring, plugin
+ * descriptors, markdown features, codeHighlight, resolveMarkdownLinks, and
+ * trailingSlash are now owned by `zudoDocPreset()` in
+ * `@takazudo/zudo-doc/preset`. The generated config spreads the preset
+ * result into `defineConfig` and keeps only the project-owned shell fields
+ * (`framework`, `port`, `tailwind`, `base`).
  *
  * Replaces the former astro-config-gen.ts + content-config-gen.ts pair.
  * In the zfb world, content-collection schemas live inside zfb.config.ts
  * itself — there is no separate content.config.ts.
+ *
+ * `_choices` is intentionally unused: post-S5b the emitted config is a
+ * CONSTANT. All feature variation is driven by `settings.*` (read at
+ * zfb-load time inside `zudoDocPreset()`), so the generated file is byte
+ * identical for every feature combination. The parameter is retained only
+ * for call-site compatibility (`scaffold.ts` passes `choices`). Do NOT add
+ * feature-gated branches here — wire new feature behaviour into
+ * `packages/zudo-doc/src/preset.ts` and the project's `settings.ts` instead.
  */
-export function generateZfbConfig(choices) {
-    const hasDocHistory = choices.features.includes("docHistory");
-    const hasLlmsTxt = choices.features.includes("llmsTxt");
-    const hasClaudeResources = choices.features.includes("claudeResources");
+export function generateZfbConfig(_choices) {
     const lines = [];
     // --- Imports ---
-    lines.push(`import { z } from "zod";`);
     lines.push(`import { defineConfig } from "zfb/config";`);
+    lines.push(`import { zudoDocPreset } from "@takazudo/zudo-doc/preset";`);
     lines.push(`import { settings } from "./src/config/settings";`);
     lines.push(`import { buildDocsSchema } from "./src/config/docs-schema";`);
     lines.push(``);
-    // --- Schema definition — delegated to the single source of truth ---
-    // buildDocsSchema() lives in src/config/docs-schema.ts and is shared by
-    // pages/_data.ts (ZfbDocsData alias) and src/types/docs-entry.ts (DocsData).
-    // tagGovernance projects: docs-schema.ts reads settings + tagVocabulary
-    // internally, so the generated zfb.config.ts needs no extra import or
-    // inline buildTagsSchema — the schema builder encapsulates all of that.
-    lines.push(`const docsSchema = buildDocsSchema();`);
-    lines.push(``);
-    lines.push(`const docsSchemaJson = z.toJSONSchema(docsSchema) as Record<string, unknown>;`);
-    lines.push(``);
-    // --- Collection type ---
-    lines.push(`interface CollectionEntryShape {`);
-    lines.push(`  name: string;`);
-    lines.push(`  path: string;`);
-    lines.push(`  schema: Record<string, unknown>;`);
-    lines.push(`}`);
-    lines.push(``);
-    // --- Collections array ---
-    lines.push(`const collections: CollectionEntryShape[] = [];`);
-    lines.push(``);
-    lines.push(`collections.push({ name: "docs", path: settings.docsDir, schema: docsSchemaJson });`);
-    lines.push(``);
-    // Locale collections — empty loop when locales is {} (i18n disabled).
-    lines.push(`for (const [code, config] of Object.entries(settings.locales)) {`);
-    lines.push(`  collections.push({ name: \`docs-\${code}\`, path: config.dir, schema: docsSchemaJson });`);
-    lines.push(`}`);
-    lines.push(``);
-    // Version collections — outer `if` short-circuits when versions is false.
-    lines.push(`if (settings.versions) {`);
-    lines.push(`  for (const version of settings.versions) {`);
-    lines.push(`    collections.push({`);
-    lines.push(`      name: \`docs-v-\${version.slug}\`,`);
-    lines.push(`      path: version.docsDir,`);
-    lines.push(`      schema: docsSchemaJson,`);
-    lines.push(`    });`);
-    lines.push(`    if (version.locales) {`);
-    lines.push(`      for (const [code, config] of Object.entries(version.locales)) {`);
-    lines.push(`        collections.push({`);
-    lines.push(`          name: \`docs-v-\${version.slug}-\${code}\`,`);
-    lines.push(`          path: config.dir,`);
-    lines.push(`          schema: docsSchemaJson,`);
-    lines.push(`        });`);
-    lines.push(`      }`);
-    lines.push(`    }`);
-    lines.push(`  }`);
-    lines.push(`}`);
-    lines.push(``);
-    // --- Locale helpers used by integrationPlugins (always emitted because
-    //     search-index + copy-public are always-on; locale-shaped data is
-    //     consumed by search-index even when there's only the default locale).
-    lines.push(`const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({`);
-    lines.push(`  code,`);
-    lines.push(`  dir: locale.dir,`);
-    lines.push(`}));`);
-    lines.push(`const localeRecord = Object.fromEntries(`);
-    lines.push(`  Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }]),`);
-    lines.push(`);`);
-    lines.push(``);
-    // --- Plugins — inline-object shape matches host. Each entry's `name`
-    //     is a relative path to a `.mjs` plugin module shipped by the
-    //     base/feature templates. zfb's plugin runtime resolves the module
-    //     and dispatches lifecycle hooks (preBuild / postBuild / devMiddleware)
-    //     on its default export. ---
-    lines.push(`const integrationPlugins = [`);
-    if (hasClaudeResources) {
-        lines.push(`  ...(settings.claudeResources`);
-        lines.push(`    ? [`);
-        lines.push(`        {`);
-        lines.push(`          name: "./plugins/claude-resources-plugin.mjs",`);
-        lines.push(`          options: {`);
-        lines.push(`            claudeDir: settings.claudeResources.claudeDir,`);
-        lines.push(`            projectRoot: settings.claudeResources.projectRoot,`);
-        lines.push(`            docsDir: settings.docsDir,`);
-        lines.push(`          },`);
-        lines.push(`        },`);
-        lines.push(`      ]`);
-        lines.push(`    : []),`);
-    }
-    if (hasDocHistory) {
-        lines.push(`  ...(settings.docHistory`);
-        lines.push(`    ? [`);
-        lines.push(`        {`);
-        lines.push(`          name: "./plugins/doc-history-plugin.mjs",`);
-        lines.push(`          options: {`);
-        lines.push(`            docsDir: settings.docsDir,`);
-        lines.push(`            locales: localeRecord,`);
-        lines.push(`            base: settings.base,`);
-        lines.push(`          },`);
-        lines.push(`        },`);
-        lines.push(`      ]`);
-        lines.push(`    : []),`);
-    }
-    // search-index is always-on (matches host) — emits dist/search-index.json
-    // even when no <Search /> widget mounts; ~few-KB cost is acceptable and
-    // keeps the dev-middleware route registered for the always-mounted
-    // search widget in pages/lib/_header-with-defaults.tsx.
-    lines.push(`  {`);
-    lines.push(`    name: "./plugins/search-index-plugin.mjs",`);
-    lines.push(`    options: {`);
-    lines.push(`      docsDir: settings.docsDir,`);
-    lines.push(`      locales: localeRecord,`);
-    lines.push(`      base: settings.base,`);
-    lines.push(`    },`);
-    lines.push(`  },`);
-    if (hasLlmsTxt) {
-        lines.push(`  ...(settings.llmsTxt`);
-        lines.push(`    ? [`);
-        lines.push(`        {`);
-        lines.push(`          name: "./plugins/llms-txt-plugin.mjs",`);
-        lines.push(`          options: {`);
-        lines.push(`            siteName: settings.siteName,`);
-        lines.push(`            siteDescription: settings.siteDescription,`);
-        lines.push(`            base: settings.base,`);
-        lines.push(`            siteUrl: settings.siteUrl,`);
-        lines.push(`            defaultLocaleDir: settings.docsDir,`);
-        lines.push(`            locales: localeArray,`);
-        lines.push(`          },`);
-        lines.push(`        },`);
-        lines.push(`      ]`);
-        lines.push(`    : []),`);
-    }
-    // copy-public is always-on (matches host) — workaround for upstream zfb
-    // gap where `zfb build` does not copy `public/` to dist/. Empty/missing
-    // public/ is a no-op, so the cost to projects without public/ is zero.
-    lines.push(`  {`);
-    lines.push(`    name: "./plugins/copy-public-plugin.mjs",`);
-    lines.push(`    options: {`);
-    lines.push(`      publicDir: "public",`);
-    lines.push(`    },`);
-    lines.push(`  },`);
-    lines.push(`];`);
+    // --- Directive vocabulary ---
+    // The seven canonical directives registered in pages/_mdx-components.ts.
+    // "details" routes to DetailsWrapper — a collapsible, NOT an admonition.
+    lines.push(`const directiveVocabulary = {`);
+    lines.push(`  note: "Note",`);
+    lines.push(`  tip: "Tip",`);
+    lines.push(`  info: "Info",`);
+    lines.push(`  warning: "Warning",`);
+    lines.push(`  danger: "Danger",`);
+    lines.push(`  caution: "Caution",`);
+    lines.push(`  details: "Details",`);
+    lines.push(`};`);
     lines.push(``);
     // --- Export ---
     lines.push(`export default defineConfig({`);
+    lines.push(`  // ── Host-owned shell fields ──────────────────────────────────────────────`);
     lines.push(`  framework: "preact",`);
     lines.push(`  // Pin the dev/preview port — zfb defaults to 3000, but the generated`);
     lines.push(`  // CLAUDE.md and the Tauri dev wrappers assume 4321.`);
     lines.push(`  port: 4321,`);
     lines.push(`  tailwind: { enabled: true },`);
-    lines.push(`  collections,`);
-    lines.push(`  stripMdExt: true,`);
-    lines.push(`  resolveMarkdownLinks: {`);
-    lines.push(`    enabled: true,`);
-    lines.push(`    dirs: [`);
-    lines.push(`      { dir: settings.docsDir, routePrefix: "/docs/" },`);
-    lines.push(`      ...Object.entries(settings.locales).map(([code, locale]) => ({`);
-    lines.push(`        dir: locale.dir,`);
-    lines.push(`        routePrefix: \`/\${code}/docs/\`,`);
-    lines.push(`      })),`);
-    lines.push(`      // Versioned collections: each version's EN dir + per-locale dirs.`);
-    lines.push(`      ...(settings.versions`);
-    lines.push(`        ? settings.versions.flatMap((version) => [`);
-    lines.push(`            { dir: version.docsDir, routePrefix: \`/v/\${version.slug}/docs/\` },`);
-    lines.push(`            ...Object.entries(version.locales ?? {}).map(([code, locale]) => ({`);
-    lines.push(`              dir: locale.dir,`);
-    lines.push(`              routePrefix: \`/v/\${version.slug}/\${code}/docs/\`,`);
-    lines.push(`            })),`);
-    lines.push(`          ])`);
-    lines.push(`        : []),`);
-    lines.push(`    ],`);
-    lines.push(`    onBrokenLinks: "warn",`);
-    lines.push(`  },`);
+    lines.push(`  // Public URL prefix for <link rel="stylesheet"> and <script> tags.`);
     lines.push(`  base: settings.base,`);
-    lines.push(`  trailingSlash: settings.trailingSlash,`);
-    // codeHighlight — dual-theme syntect output so CSS can resolve tokens via
-    // light-dark(var(--shiki-light), var(--shiki-dark)) and code blocks follow
-    // the active light/dark toggle with no client JS. Theme names are syntect
-    // built-ins shipped with zfb (not Shiki names). Matches the host config.
-    lines.push(`  codeHighlight: {`);
-    lines.push(`    themeLight: "base16-ocean.light",`);
-    lines.push(`    themeDark: "base16-ocean.dark",`);
-    lines.push(`  },`);
-    // markdown.features block — mirrors the zfb next.13 opt-in model.
-    //
-    // Value-shape rule (empirically verified against the next.13 Rust loader):
-    // object-typed features (githubAutolinks, codeEnrichment, imageDimensions,
-    // linkValidation) REJECT the `true` shorthand and must be given an options
-    // object (`{}` or fields). Boolean-OR-object features (githubAlerts,
-    // readingTime, codeTabs, mermaid, headingMarkerToc) accept `true`.
-    // (directives is object-typed — it takes a `name → component` map, not `true`.)
-    // Note: imageEnlarge was formerly a Boolean-OR-object feature here, but
-    // next.18 hard-removed it from the Rust config schema — it is now
-    // re-implemented in userland via an MDX p-override in pages/_mdx-components.ts
-    // (gated on settings.imageEnlarge). Do NOT add imageEnlarge back here.
-    //
-    // Intentionally omitted features (known-blocked at zfb next.13):
-    //   - tocExport: injects indented `export const toc = [...]` that MDX
-    //     parses as content, breaking esbuild with "Expected }" across the
-    //     whole corpus. Re-enable when the upstream Rust pass emits the
-    //     export at column 0. (Filed as zudolab/zudo-doc#1814.)
-    //   - ruby: the `^{...}` annotation syntax 500s the SSR render at next.13.
-    //     A registered stub cannot fix it — the error is inside zfb's Rust
-    //     ruby pass. Re-enable when the upstream crate is fixed. (#1815.)
-    //   - transclude: `:::include{file="..."}` 500s SSR (no registered
-    //     <include> renderer); `![[...]]` wikilink form is a no-op.
-    //     Re-enable when a transclude renderer is wired.
-    //
-    // githubAutolinks is omitted intentionally: the showcase hardcodes
-    // `repo: "zudolab/zudo-doc"` but a scaffolded project belongs to a
-    // different repo. Users can add `githubAutolinks: { repo: "owner/repo" }`
-    // to their zfb.config.ts after scaffolding.
-    lines.push(`  markdown: {`);
-    lines.push(`    features: {`);
-    lines.push(`      // Former-Core features (were always-on before zfb next.12).`);
-    lines.push(`      // imageEnlarge was a former-Core feature but was hard-removed in zfb`);
-    lines.push(`      // next.18 — it is now re-implemented via an MDX p-override.`);
-    lines.push(`      // Admonitions recipe: register the :::name directive vocabulary`);
-    lines.push(`      // (note/tip/info/warning/danger/caution/details) → components.`);
-    lines.push(`      directives: {`);
-    lines.push(`        note: "Note",`);
-    lines.push(`        tip: "Tip",`);
-    lines.push(`        info: "Info",`);
-    lines.push(`        warning: "Warning",`);
-    lines.push(`        danger: "Danger",`);
-    lines.push(`        caution: "Caution",`);
-    lines.push(`        details: "Details", // collapsible — routes to DetailsWrapper`);
-    lines.push(`      },`);
-    lines.push(`      mermaid: true,`);
-    lines.push(`      headingMarkerToc: true,`);
-    lines.push(`      // Safe opt-in features.`);
-    lines.push(`      githubAlerts: true,`);
-    lines.push(`      readingTime: true,`);
-    lines.push(`      codeEnrichment: {},`);
-    lines.push(`      codeTabs: true,`);
-    lines.push(`      imageDimensions: {},`);
-    lines.push(`      // warn-only link validation — failOnBroken: false never fails the build.`);
-    lines.push(`      linkValidation: { failOnBroken: false },`);
-    lines.push(`      // Heading-ID (anchor) strategy — single source of truth in`);
-    lines.push(`      // settings.headingIdStrategy, also mirrored by the host TOC builder`);
-    lines.push(`      // (pages/lib/_extract-headings.ts) so TOC anchors match rendered ids.`);
-    lines.push(`      headingIds: { strategy: settings.headingIdStrategy },`);
-    lines.push(`    },`);
-    lines.push(`  },`);
-    lines.push(`  plugins: integrationPlugins,`);
+    lines.push(``);
+    lines.push(`  // ── Preset-owned fields (content collections, plugins, markdown, …) ────────`);
+    lines.push(`  ...zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary }),`);
     lines.push(`});`);
     return lines.join("\n") + "\n";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.21",
+  "version": "1.0.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/_mdx-components.ts

@@ -1,117 +1,52 @@
-// Shared MDX-component bag used by every doc-route page that renders
-// `<entry.Content components={...} />`.
+// Project MDX-components assembly — thin wrapper over the package factory.
 //
-// ## Why a shared helper
+// The bulk of the components bag (htmlOverrides, admonitions, CodeGroup,
+// Tabs/TabItem, MathBlock, the img base-rewrite, the enlargeable-`p` override)
+// now ships from `@takazudo/zudo-doc/mdx-components` (package-first migration,
+// epic #2321, S8 #2332). This file keeps ONLY what is genuinely project-bound:
 //
-// Pre-S4e the page-side `components` map only carried `htmlOverrides` plus
-// `HtmlPreview`, because the zfb content bridge wasn't installed and every
-// `<entry.Content>` call took the raw-markdown `<pre data-zfb-content-fallback>`
-// path. Now that the bridge IS installed (zudo-doc#506), the compiled
-// MDXContent functions fire for every entry — and the MDX emitter wraps
-// every named-tag access with:
-//
-//   const CategoryNav2 = _components.CategoryNav ?? components.CategoryNav;
-//   if (!CategoryNav2) throw new Error("MDX requires `CategoryNav` to be passed via the `components` prop");
-//
-// So any tag the MDX corpus uses but the page omits → 500 at render time.
-//
-// ## Strategy
-//
-// This module ships stub bindings for tags not yet ported to `@takazudo/zudo-doc`
-// (render nothing), and real Preact bindings for tags whose ports are complete.
-// As real components land, they replace their stub here and propagate to every page automatically.
-//
-// `htmlOverrides` (basic typography — h2/h3/h4/p/a/ul/ol/blockquote/strong/table)
-// and `HtmlPreview: HtmlPreviewWrapper` (Island wrapper) stay in their
-// non-stub form because their Preact bindings already exist.
-//
-// ## Locale-aware bindings (createMdxComponents factory)
-//
-// CategoryNav, CategoryTreeNav, SiteTreeNav, and SiteTreeNavDemo resolve nav
-// tree data at render time. Since the same MDX content is rendered for both
-// default-locale and non-default-locale pages, these components need to know
-// which locale to use when building the nav tree.
-//
-// The `createMdxComponents(lang)` factory returns a components map with
-// locale-bound wrappers for these nav components. Page modules should call it
-// with the active locale instead of using the static `mdxComponents` export.
-// The static export still exists for backward compatibility (using defaultLocale).
+//   - the 4 locale-bound nav wrappers (CategoryNav / CategoryTreeNav /
+//     SiteTreeNav / SiteTreeNavDemo) — they depend on the project's content
+//     collections + nav-tree utilities, so they cannot live in the package.
+//     They are passed into the factory as `navData`; the factory injects the
+//     active `locale` so `/ja` resolves the JA collection (the load-bearing
+//     locale thread — a static global mdx-components slot would render the EN
+//     tree on every `/ja` page, which is why this stays a per-call factory).
+//   - project `extras` spread last: HtmlPreview (with the host's global
+//     config), Details, the Island SSR pass-through, the PresetGenerator SSR
+//     shell, and the pure-showcase stubs (Avatar/Button/Card/MyComponent/
+//     PageLayout) that appear only as illustrative MDX prose.
 
 import type { ComponentChildren } from "preact";
-// @slot:mdx-components:enlarge-imports
-import { htmlOverrides } from "@takazudo/zudo-doc/content";
+import { createMdxComponents as createMdxComponentsBase } from "@takazudo/zudo-doc/mdx-components";
 import { HtmlPreviewWrapper, type HtmlPreviewWrapperProps } from "@takazudo/zudo-doc/html-preview-wrapper";
-import { Tabs } from "@takazudo/zudo-doc/code-syntax";
-import { TabItem } from "@takazudo/zudo-doc/tab-item";
 import { defaultLocale, type Locale } from "@/config/i18n";
 import { settings } from "@/config/settings";
-import { withBase } from "@/utils/base";
 import { CategoryNavWrapper } from "./lib/_category-nav";
 import { CategoryTreeNavWrapper } from "./lib/_category-tree-nav";
 import { SiteTreeNavWrapper } from "./lib/_site-tree-nav";
 import { DetailsWrapper } from "./lib/_details";
 import { PresetGeneratorFallback } from "./lib/_preset-generator";
-import { MathBlock } from "./lib/_math-block";
-import { CodeGroup } from "@/components/content/code-group";
-import { makeAdmonition } from "@/components/content/content-admonition";
 
-/**
- * MDX `<img>` override — rewrites root-relative src attributes to include the
- * configured site base path (settings.base). Without this, an MDX image like
- * `![alt](/img/foo.webp)` emits `src="/img/foo.webp"` which 404s when the
- * site is deployed under a sub-path prefix (e.g. /my-docs/).
- *
- * Only root-relative paths (starting with "/") are rewritten; external URLs,
- * protocol-relative URLs ("//…"), and data URIs pass through unchanged. The
- * withBase() call is generic — it reads settings.base at build time and applies
- * whatever prefix is configured.
- *
- * Note: `srcset` attributes are NOT rewritten here because the current MDX
- * corpus does not use srcset (standard markdown `![alt](src)` syntax produces
- * only `src`). If srcset with root-relative URLs is ever introduced, extend
- * this override to rewrite each srcset candidate URL as well.
- */
-function ContentImg(props: Record<string, unknown>) {
-  const src = props.src;
-  const rewrittenSrc =
-    typeof src === "string" && src.startsWith("/") && !src.startsWith("//")
-      ? withBase(src)
-      : src;
-  // Strip the "no-enlarge" sentinel from the rendered DOM — it is read by the
-  // p-override before ContentImg is called (the VNode is still unlaunched at
-  // that point), so we must delete it here to avoid leaking the sentinel into
-  // the img title attribute.
-  const { title, ...restProps } = props;
-  const finalTitle = title === "no-enlarge" ? undefined : title;
-  const mergedProps: Record<string, unknown> = { ...restProps, src: rewrittenSrc };
-  if (finalTitle !== undefined) {
-    mergedProps.title = finalTitle;
-  }
-  return { type: "img", props: mergedProps, key: null, constructor: undefined };
-}
+const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
+  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
 
 /**
- * MDX-tag stub: renders nothing. Returning `null` keeps the rendered
- * tree intact (Preact's null-vnode path) without leaking placeholder
- * markup into the SSR output.
+ * MDX-tag stub: renders nothing. Returning `null` keeps the rendered tree
+ * intact (Preact's null-vnode path) without leaking placeholder markup into
+ * the SSR output.
  */
 const MdxStub = (_props: unknown) => null;
 
 /**
  * SSR-pass-through wrapper for `<Island when="load|idle|visible">`.
  *
- * In the zfb build the zfb `<Island>` component is unavailable, so the
- * MDX corpus tags resolve to this binding instead. Rendering the
- * children directly ensures that any server-renderable content nested
- * inside `<Island>` (headings, paragraphs, etc.) appears in the SSR
- * HTML. Client-only inner components that are themselves wrapped in an
- * SSR-skip placeholder will emit their own placeholder markup; this
- * wrapper does not suppress them.
- *
- * The `when` prop is intentionally ignored at render time — it is only
- * meaningful to the zfb hydration runtime on the client, which reads
- * the `data-when` attribute on the inner SSR-skip placeholder div (if
- * present) rather than on this wrapper.
+ * In the zfb build the zfb `<Island>` component is unavailable here, so the
+ * MDX corpus tag resolves to this binding instead. Rendering the children
+ * directly ensures server-renderable content nested inside `<Island>`
+ * (headings, paragraphs, etc.) appears in the SSR HTML. The `when` prop is
+ * ignored at render time — it is only meaningful to the zfb hydration runtime
+ * on the client, which reads `data-when` on the inner SSR-skip placeholder.
  */
 function IslandWrapper(props: {
   when?: "load" | "idle" | "visible" | "media";
@@ -120,104 +55,48 @@ function IslandWrapper(props: {
   return props.children ?? null;
 }
 
-// @slot:mdx-components:enlarge-defs
-const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
-  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
-
 /**
  * Build a locale-aware MDX components map for the given locale.
  *
- * Nav components (CategoryNav, CategoryTreeNav, SiteTreeNav, SiteTreeNavDemo)
- * resolve nav tree data at render time and need the active locale so they
- * query the right collection. The factory closes over `lang` and returns
- * locale-bound wrapper functions.
- *
- * Page modules should call createMdxComponents(locale) instead of importing
- * the static mdxComponents export.
+ * Delegates the package-resident components to the `@takazudo/zudo-doc`
+ * factory and supplies the project-bound pieces:
+ *   - `navData`: the 4 locale-aware nav wrappers (the factory injects `lang`).
+ *   - `extras`: HtmlPreview (host-configured), Details, Island pass-through,
+ *     PresetGenerator SSR shell, and the showcase stubs.
  *
- * Components map includes:
- * - `htmlOverrides` — element-level overrides for native tags (h2..h4,
- *   p, a, ul/ol, blockquote, strong, table). Defined in
- *   `@takazudo/zudo-doc/content`.
- * - `HtmlPreview` — Island-wrapped preview component.
- * - Real Preact wrappers for CategoryNav, CategoryTreeNav, SiteTreeNav,
- *   SiteTreeNavDemo, and Details.
- * - `Island` — SSR pass-through wrapper so children render server-side.
- * - `PresetGenerator` — SSR fallback shell that renders the 8 h3 sections;
- *   interactive form hydrates client-side via SSR-skip placeholder.
- * - Stub bindings for every other custom tag the MDX corpus references.
- *
- * Keep this list in sync with the corpus when new MDX tags appear.
- * `pnpm exec grep -rohE '<[A-Z][a-zA-Z]+' src/content/` enumerates them.
+ * Page modules should call createMdxComponents(locale) — not the static
+ * mdxComponents export — so each render gets the locale-correct map.
  */
 export function createMdxComponents(lang: Locale | string = defaultLocale) {
-  // Locale-bound wrappers — close over `lang` so each wrapper queries
-  // the correct collection without needing a prop.
-  const CategoryNavBound = (props: Record<string, unknown>) =>
-    CategoryNavWrapper({ ...(props as Parameters<typeof CategoryNavWrapper>[0]), lang });
-  const CategoryTreeNavBound = (props: Record<string, unknown>) =>
-    CategoryTreeNavWrapper({ ...(props as Parameters<typeof CategoryTreeNavWrapper>[0]), lang });
-  const SiteTreeNavBound = (props: Record<string, unknown>) =>
-    SiteTreeNavWrapper({ ...(props as Parameters<typeof SiteTreeNavWrapper>[0]), lang });
-
-  return {
-    ...htmlOverrides,
-    // img override: rewrites root-relative src to include the site base path.
-    // Required when settings.base is a sub-path (e.g. /my-docs/) so that
-    // MDX images like ![alt](/img/foo.webp) resolve correctly on the deployed
-    // site. withBase() is generic — any configured base value works.
-    img: ContentImg,
-    // @slot:mdx-components:enlarge-p-entry
-    HtmlPreview: HtmlPreviewWithGlobalConfig,
-    // Admonitions — real typed Preact components (src/components/content/
-    // content-admonition.tsx) emitting the `.admonition` / `data-admonition`
-    // structure the design-system CSS targets. The `directives` map in
-    // zfb.config.ts emits these tags from `:::note` directives; `<Note
-    // title="…">` JSX form is also authored directly.
-    Note: makeAdmonition("note"),
-    Tip: makeAdmonition("tip"),
-    Info: makeAdmonition("info"),
-    Warning: makeAdmonition("warning"),
-    Danger: makeAdmonition("danger"),
-    // github-alerts [!IMPORTANT] and [!CAUTION] map to these variants.
-    // Without these bindings, those two alert variants 500 the SSR render.
-    Important: makeAdmonition("important"),
-    Caution: makeAdmonition("caution"),
-    // codeTabs Option A: zfb emits <CodeGroup tabs={[...]}> for :::code-group.
-    // The framework does not ship this component; we implement it here and map
-    // the tabs[] + <pre data-lang> children to the existing Tabs/TabItem UI.
-    CodeGroup: CodeGroup as unknown as (props: Record<string, unknown>) => unknown,
-    // Showcase / nav helpers — real Preact wrappers replacing MdxStub.
-    CategoryNav: CategoryNavBound,
-    CategoryTreeNav: CategoryTreeNavBound,
-    SiteTreeNav: SiteTreeNavBound,
-    SiteTreeNavDemo: SiteTreeNavBound,
-    Details: DetailsWrapper,
-    Tabs,
-    TabItem,
-    // Math rendering — KaTeX via server-side katex.renderToString().
-    // The math-equations.mdx content files write <MathBlock> JSX directly
-    // (instead of $$…$$) because the zfb Rust emitter does not yet support
-    // remark-math math nodes (zudo-front-builder #93).
-    MathBlock,
-    SmartBreak: MdxStub,
-    // Island: pass children through so server-renderable content nested
-    // inside <Island> appears in SSR HTML. See IslandWrapper comment above.
-    Island: IslandWrapper,
-    // PresetGenerator: render the 8 section headings as static SSR HTML for
-    // a11y/SEO section structure and no-JS layout stability. The interactive
-    // form loads client-side via the SSR-skip placeholder inside
-    // PresetGeneratorFallback (see pages/lib/_preset-generator.tsx).
-    PresetGenerator: PresetGeneratorFallback,
-    // Pure showcase placeholders (Avatar/Button/Card/MyComponent/PageLayout
-    // appear only inside MDX prose as illustrative examples — never
-    // implemented as real components).
-    Avatar: MdxStub,
-    Button: MdxStub,
-    Card: MdxStub,
-    MyComponent: MdxStub,
-    PageLayout: MdxStub,
-  };
+  return createMdxComponentsBase({
+    settings,
+    locale: lang,
+    navData: {
+      CategoryNav: CategoryNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+      CategoryTreeNav: CategoryTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+      SiteTreeNav: SiteTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+    },
+    extras: {
+      HtmlPreview: HtmlPreviewWithGlobalConfig,
+      Details: DetailsWrapper,
+      // SmartBreak: corpus tag with no visual rendering — render nothing.
+      SmartBreak: MdxStub,
+      // Island: pass children through so server-renderable content nested
+      // inside <Island> appears in SSR HTML. See IslandWrapper comment above.
+      Island: IslandWrapper,
+      // PresetGenerator: SSR fallback shell that renders the 8 section headings;
+      // the interactive form hydrates client-side via the SSR-skip placeholder
+      // inside PresetGeneratorFallback (see pages/lib/_preset-generator.tsx).
+      PresetGenerator: PresetGeneratorFallback,
+      // Pure showcase placeholders — appear only inside MDX prose as
+      // illustrative examples, never implemented as real components.
+      Avatar: MdxStub,
+      Button: MdxStub,
+      Card: MdxStub,
+      MyComponent: MdxStub,
+      PageLayout: MdxStub,
+    },
+  });
 }
 
 /**

package/templates/base/pages/index.tsx

@@ -27,7 +27,7 @@ import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
 import type { JSX } from "preact";
 import type { VNode } from "preact";
 import { Island } from "@takazudo/zfb";
-import SiteTreeNav from "@/components/site-tree-nav";
+import { SiteTreeNav } from "@takazudo/zudo-doc/site-tree-nav-island";
 import { FooterWithDefaults } from "./lib/_footer-with-defaults";
 import { HeaderWithDefaults } from "./lib/_header-with-defaults";
 import { HeadWithDefaults } from "./lib/_head-with-defaults";

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -32,21 +32,14 @@ import type { VNode, JSX } from "preact";
 import { Island } from "@takazudo/zfb";
 import { settings } from "@/config/settings";
 
-import AiChatModal from "@/components/ai-chat-modal";
-import ImageEnlarge, { ImageEnlargeSsrFallback } from "@/components/image-enlarge";
-import MermaidEnlarge, { MermaidEnlargeSsrFallback } from "@/components/mermaid-enlarge";
+import { AiChatModal } from "@takazudo/zudo-doc/ai-chat-modal";
+import { ImageEnlarge, ImageEnlargeSsrFallback } from "@takazudo/zudo-doc/image-enlarge";
+import { MermaidEnlarge, MermaidEnlargeSsrFallback } from "@takazudo/zudo-doc/mermaid-enlarge";
 // @slot:body-end-islands:imports
 
-// Set explicit `displayName` on each default-exported island so zfb's
-// `captureComponentName` produces a stable marker even after the SSR
-// pipeline runs the components through a function-name-rewriting layer.
-// The marker must match the third-arg literal that zfb's scanner records
-// for the same source-level identifier (zfb PR #150). esbuild preserves
-// function names by default, but the explicit assignment is a
-// belt-and-braces guard for production minification regressions.
-(AiChatModal as { displayName?: string }).displayName = "AiChatModal";
-(ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
-(MermaidEnlarge as { displayName?: string }).displayName = "MermaidEnlarge";
+// AiChatModal, ImageEnlarge, MermaidEnlarge pin displayName internally in the
+// package. Optional feature islands that still need explicit call-site pinning
+// inject their displayName assignment at the slot below only when selected.
 // @slot:body-end-islands:display-names
 
 /**