create-zudo-doc 3.2.0 → 3.3.0

package/dist/claude-md-gen.d.ts

@@ -1,2 +1,10 @@
 import type { UserChoices } from "./prompts.js";
+/**
+ * Generate the per-project `CLAUDE.md` (minimal-scaffold shape, epic
+ * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
+ * generator described a 64-file project (`src/components/admonitions/`,
+ * `src/layouts/`, `src/utils/`, per-page `pages/lib/*` wiring) that no
+ * longer exists. The scaffolded project is now ~12 files; almost
+ * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
+ */
 export declare function generateCLAUDEFile(choices: UserChoices): string;

package/dist/claude-md-gen.js

@@ -1,53 +1,62 @@
-import { capitalize } from "./utils.js";
-function runCmd(pm, script) {
-    if (pm === "npm")
-        return `npm run ${script}`;
-    return `${pm} ${script}`;
-}
+import { capitalize, pmRunCommand } from "./utils.js";
+/**
+ * Generate the per-project `CLAUDE.md` (minimal-scaffold shape, epic
+ * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
+ * generator described a 64-file project (`src/components/admonitions/`,
+ * `src/layouts/`, `src/utils/`, per-page `pages/lib/*` wiring) that no
+ * longer exists. The scaffolded project is now ~12 files; almost
+ * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
+ */
 export function generateCLAUDEFile(choices) {
     const siteName = capitalize(choices.projectName.replace(/-/g, " "));
     const lines = [];
     lines.push(`# ${siteName}`);
     lines.push(``);
-    lines.push(`Documentation site built with [zudo-doc](https://github.com/zudolab/zudo-doc) — a zfb-based documentation framework with MDX, Tailwind CSS v4, and Preact islands.`);
+    lines.push(`Documentation site built with [zudo-doc](https://github.com/zudolab/zudo-doc) — a zfb-based documentation framework with MDX, Tailwind CSS v4, and Preact islands. This project is intentionally minimal: one config file (\`zfb.config.ts\`) plus markdown content — layout, chrome, and islands all ship from \`@takazudo/zudo-doc\` in \`node_modules\`.`);
     lines.push(``);
     // Tech stack
     lines.push(`## Tech Stack`);
     lines.push(``);
     lines.push(`- **zfb** — documentation build framework`);
-    lines.push(`- **MDX** — content format`);
+    lines.push(`- **MDX** — content format, authored under \`src/content/\``);
     lines.push(`- **Tailwind CSS v4** — via \`@tailwindcss/vite\``);
     lines.push(`- **Preact** — for interactive islands only (with compat mode for React API)`);
-    lines.push(`- **syntect** — built-in code highlighting, run by zfb's Rust pipeline at build time (single fixed theme: \`base16-ocean-dark\`)`);
+    lines.push(`- **syntect** — built-in code highlighting, run by zfb's Rust pipeline at build time (dual light/dark theme, follows the site's color-mode toggle)`);
+    lines.push(`- **@takazudo/zudo-doc** — the package that owns everything: layout, chrome, islands, default \`@theme\` design tokens, and (via \`packageOwnedRoutes\`, on by default) the doc routes themselves`);
     lines.push(``);
     // Commands
     lines.push(`## Commands`);
     lines.push(``);
     const pm = choices.packageManager;
-    lines.push(`- \`${runCmd(pm, "dev")}\` — zfb dev server (port 4321)`);
-    lines.push(`- \`${runCmd(pm, "build")}\` — static HTML export to \`dist/\``);
-    lines.push(`- \`${runCmd(pm, "check")}\` — TypeScript type checking`);
+    lines.push(`- \`${pmRunCommand(pm, "dev")}\` — zfb dev server (port 4321)`);
+    lines.push(`- \`${pmRunCommand(pm, "build")}\` — static HTML export to \`dist/\``);
+    lines.push(`- \`${pmRunCommand(pm, "check")}\` — TypeScript type checking`);
+    lines.push(`- \`${pmRunCommand(pm, "preview")}\` — serve the built \`dist/\``);
     lines.push(``);
     // Key directories
     lines.push(`## Key Directories`);
     lines.push(``);
     lines.push("```");
+    lines.push(`zfb.config.ts             # THE one config file — zudoDoc({ ...only fields you chose })`);
+    lines.push(`pages/`);
+    lines.push(`├── index.tsx             # 1-line re-export of the package home route`);
+    lines.push(`└── docs/[[...slug]].tsx  # self-contained doc-route stub (required for \`${pm} dev\`)`);
+    if (choices.features.includes("i18n")) {
+        lines.push(`  [locale]/docs/[[...slug]].tsx  # same, for non-default locales`);
+    }
     lines.push(`src/`);
-    lines.push(`├── components/          # JSX + Preact components`);
-    lines.push(`│   └── admonitions/     # Note, Tip, Info, Warning, Danger`);
-    lines.push(`├── config/              # Settings, color schemes`);
     lines.push(`├── content/`);
-    lines.push(`│   └── docs/            # MDX content`);
+    lines.push(`│   └── docs/             # MDX content (this project's showcase docs)`);
     if (choices.features.includes("i18n")) {
         const secondaryLang = choices.defaultLang === "ja" ? "en" : "ja";
         lines.push(`│   └── docs-${secondaryLang}/         # ${secondaryLang === "ja" ? "Japanese" : "English"} MDX content (mirrors docs/)`);
     }
-    lines.push(`├── layouts/             # JSX layouts`);
-    lines.push(`├── pages/               # File-based routing`);
     lines.push(`└── styles/`);
-    lines.push(`    └── global.css       # Design tokens & Tailwind config`);
+    lines.push(`    └── global.css        # @import chain + a token-override slot — that's it`);
     lines.push("```");
     lines.push(``);
+    lines.push(`Everything else — layout, header, sidebar, footer, doc chrome, islands, and the default design tokens — lives in \`node_modules/@takazudo/zudo-doc\`. To customize a specific piece, use the eject CLI: \`npx zudo-doc eject <component>\` copies one package component into this project so you can edit it (see \`@takazudo/zudo-doc\`'s eject-contract docs). Settings you didn't set explicitly in \`zfb.config.ts\` use the package's documented defaults — hover \`zudoDoc\`'s \`ZudoDocConfig\` argument in your editor to see every field and its \`@default\`.`);
+    lines.push(``);
     // Content conventions
     lines.push(`## Content Conventions`);
     lines.push(``);
@@ -59,18 +68,24 @@ export function generateCLAUDEFile(choices) {
     lines.push(``);
     lines.push(`### Admonitions`);
     lines.push(``);
-    lines.push(`Available in all MDX files without imports: \`<Note>\`, \`<Tip>\`, \`<Info>\`, \`<Warning>\`, \`<Danger>\``);
-    lines.push(`Each accepts an optional \`title\` prop.`);
+    lines.push(`Available in all MDX files without imports, via directive syntax: \`:::note\`, \`:::tip\`, \`:::info\`, \`:::warning\`, \`:::danger\`, \`:::caution\`, \`:::details\`. Each accepts an optional \`{title="..."}\` attribute.`);
     lines.push(``);
     lines.push(`### Headings`);
     lines.push(``);
     lines.push(`Do NOT use h1 (\`#\`) in doc content — the page title from frontmatter is rendered as h1. Start content headings from h2 (\`##\`).`);
     lines.push(``);
-    // Components
-    lines.push(`## Components`);
+    // Built-in MDX components. The seeded getting-started/index.mdx uses
+    // <CategoryNav>, a package-provided global — without this section a new user
+    // has no in-project pointer to what it is or which siblings exist (#2703).
+    lines.push(`### Built-in MDX components`);
+    lines.push(``);
+    lines.push(`\`@takazudo/zudo-doc\` ships a few **globally-available MDX components** — usable in any \`.mdx\` file with **no import**. The seeded \`getting-started/index.mdx\` already uses one:`);
+    lines.push(``);
+    lines.push(`- \`<CategoryNav category="..." />\` — a card-grid list of the pages in a docs category (this is the one seeded into \`getting-started/index.mdx\`).`);
+    lines.push(`- \`<CategoryTreeNav category="..." />\` — the same listing as a compact nested tree, better for deeper hierarchies.`);
+    lines.push(`- \`<SiteTreeNavDemo />\` — a full-site documentation tree (the MDX-available wrapper of the \`SiteTreeNav\` island).`);
     lines.push(``);
-    lines.push(`- Default to **server-rendered JSX components** (\`.tsx\`) — zero JS, server-rendered`);
-    lines.push(`- Use **Preact islands** (\`client:load\`) only when client-side interactivity is needed`);
+    lines.push(`Admonitions (above), tabbed content (\`<Tabs>\` / \`<TabItem>\`, \`<CodeGroup>\`), and block math (\`<MathBlock>\`) work the same way — no import. Full reference: https://zudo-doc.takazudomodular.com/docs/components/`);
     lines.push(``);
     // i18n section
     if (choices.features.includes("i18n")) {
@@ -82,12 +97,12 @@ export function generateCLAUDEFile(choices) {
         lines.push(`- ${defaultLabel} (default): \`/docs/...\` — content in \`src/content/docs/\``);
         lines.push(`- ${secondaryLabel}: \`/${secondaryLang}/docs/...\` — content in \`src/content/docs-${secondaryLang}/\``);
         lines.push(`- ${secondaryLabel} docs should mirror the ${defaultLabel} directory structure`);
+        lines.push(`- Both \`pages/docs/[[...slug]].tsx\` and \`pages/[locale]/docs/[[...slug]].tsx\` are self-contained doc-route stubs shipped by the generator — required so \`${pm} dev\` doesn't 404 on doc pages (a zfb dev-mode limitation on package-injected dynamic routes). Don't delete them.`);
         lines.push(``);
     }
     // Enabled features
     const featureDescriptions = {
         search: "Full-text search via Pagefind",
-        sidebarFilter: "Real-time sidebar filtering",
         designTokenPanel: "Interactive tabbed panel for tweaking spacing, font, size, and color tokens",
         sidebarResizer: "Draggable sidebar width",
         sidebarToggle: "Show/hide desktop sidebar",
@@ -96,6 +111,8 @@ export function generateCLAUDEFile(choices) {
         llmsTxt: "Generates llms.txt for LLM consumption",
         claudeResources: "Auto-generated docs for Claude Code resources",
         changelog: "Changelog page at `/docs/changelog`",
+        tauri: "Desktop app wrapper (`cargo tauri dev` / `cargo tauri build`) — Cmd/Ctrl+F find bar via the package-owned `FindInPageInit` island (`findInPage: true` in `zfb.config.ts`)",
+        tagGovernance: "Vocabulary-aware tag audit (`tags:audit`) / suggest (`tags:suggest`) scripts",
     };
     const enabledFeatures = choices.features.filter((f) => featureDescriptions[f] !== undefined &&
         f !== "footerNavGroup" &&

package/dist/compose.d.ts

@@ -68,27 +68,21 @@ export declare function resolveSelectedFeatures(choices: UserChoices, featureMod
  * Throws if a selected feature depends on one that isn't selected.
  */
 export declare function validateDependencies(features: FeatureDefinition[], allSelectedNames: Set<string>): void;
-/** Files that may contain injection anchors and need cleaning.
- *
- * The anchor targets today are:
- * - `global.css` — design-token-panel.ts injects
- *   `@import "@takazudo/zdtp/styles.css";` at `@slot:global-css:feature-styles`.
- *   The sibling `@slot:global-css:theme-tokens` anchor is consumed by the
- *   color-scheme palette generator and must remain.
- * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
- *   island (import, displayName, Island mount) when tauri is enabled.
- *   design-token-panel.ts injects the DesignTokenPanelBootstrap island
- *   (import, displayName, Island mount + toggle shim) when designTokenPanel
- *   is enabled.
- * - `src/config/settings-types.ts` — design-token-panel.ts injects the
- *   `"design-token-panel"` member into `HeaderRightTriggerName` when the
- *   feature is enabled (replace-range between the :start/:end anchors).
+/**
+ * Files that may contain injection anchors and need cleaning.
  *
- * NOTE: `pages/_mdx-components.ts` was removed (#2360 / E2). The imageEnlarge
- * p-override injections (ENLARGE_SVG, EnlargeableParagraph, p: entry) are now
- * handled inside the @takazudo/zudo-doc/mdx-components factory — the template
- * no longer carries @slot anchors for this file and the feature module's
- * injections are a no-op (the factory reads settings.imageEnlarge at render time).
+ * EMPTY as of the minimal-scaffold cutover (epic zudolab/zudo-doc#2651,
+ * Wave 6 #2660). Every anchor target this list used to name —
+ * `src/styles/global.css`'s `@slot:global-css:*` comments,
+ * `pages/lib/_body-end-islands.tsx`, `src/config/settings-types.ts` — is
+ * GONE from `templates/base/` (the package now owns chrome/islands/settings
+ * types entirely; see `templates/base/src/styles/global.css`'s fixed
+ * ~20-line `@import` chain). Feature modules are pure settings-field
+ * emission + genuine file copies now (see `src/features/*.ts`) — none of
+ * them call `applyInjections` with a real anchor anymore. The
+ * `Injection`/`applyInjections`/`cleanAnchors` machinery below is kept as
+ * infrastructure for a future feature that genuinely needs it (e.g. an
+ * eventual host-side extension point), not because anything uses it today.
  */
 export declare const ANCHOR_FILES: string[];
 /**

package/dist/compose.js

@@ -154,33 +154,23 @@ export function validateDependencies(features, allSelectedNames) {
         }
     }
 }
-/** Files that may contain injection anchors and need cleaning.
- *
- * The anchor targets today are:
- * - `global.css` — design-token-panel.ts injects
- *   `@import "@takazudo/zdtp/styles.css";` at `@slot:global-css:feature-styles`.
- *   The sibling `@slot:global-css:theme-tokens` anchor is consumed by the
- *   color-scheme palette generator and must remain.
- * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
- *   island (import, displayName, Island mount) when tauri is enabled.
- *   design-token-panel.ts injects the DesignTokenPanelBootstrap island
- *   (import, displayName, Island mount + toggle shim) when designTokenPanel
- *   is enabled.
- * - `src/config/settings-types.ts` — design-token-panel.ts injects the
- *   `"design-token-panel"` member into `HeaderRightTriggerName` when the
- *   feature is enabled (replace-range between the :start/:end anchors).
+/**
+ * Files that may contain injection anchors and need cleaning.
  *
- * NOTE: `pages/_mdx-components.ts` was removed (#2360 / E2). The imageEnlarge
- * p-override injections (ENLARGE_SVG, EnlargeableParagraph, p: entry) are now
- * handled inside the @takazudo/zudo-doc/mdx-components factory — the template
- * no longer carries @slot anchors for this file and the feature module's
- * injections are a no-op (the factory reads settings.imageEnlarge at render time).
+ * EMPTY as of the minimal-scaffold cutover (epic zudolab/zudo-doc#2651,
+ * Wave 6 #2660). Every anchor target this list used to name —
+ * `src/styles/global.css`'s `@slot:global-css:*` comments,
+ * `pages/lib/_body-end-islands.tsx`, `src/config/settings-types.ts` — is
+ * GONE from `templates/base/` (the package now owns chrome/islands/settings
+ * types entirely; see `templates/base/src/styles/global.css`'s fixed
+ * ~20-line `@import` chain). Feature modules are pure settings-field
+ * emission + genuine file copies now (see `src/features/*.ts`) — none of
+ * them call `applyInjections` with a real anchor anymore. The
+ * `Injection`/`applyInjections`/`cleanAnchors` machinery below is kept as
+ * infrastructure for a future feature that genuinely needs it (e.g. an
+ * eventual host-side extension point), not because anything uses it today.
  */
-export const ANCHOR_FILES = [
-    "src/styles/global.css",
-    "pages/lib/_body-end-islands.tsx",
-    "src/config/settings-types.ts",
-];
+export const ANCHOR_FILES = [];
 /**
  * Main composition entry point. Orchestrates the full feature composition
  * pipeline for a generated project.

package/dist/features/body-foot-util.d.ts

@@ -2,9 +2,13 @@ import type { FeatureModule } from "../compose.js";
 /**
  * body-foot-util feature.
  *
- * W7A (#1736): post-cutover, the body-foot-util area is hosted by
- * `pages/lib/_doc-history-area.tsx` which wraps `BodyFootUtilArea`
- * unconditionally. The component itself runtime-gates on
- * `settings.bodyFootUtilArea`, so there is nothing to inject.
+ * Purely a `zudoDoc({ bodyFootUtilArea: {...} })` field (see
+ * `zfb-config-gen.ts`) — `BodyFootUtilArea` is fully package-owned
+ * (`@takazudo/zudo-doc/body-foot-util`, wired through `doc-page-shell`) and
+ * runtime-gates on `settings.bodyFootUtilArea`. The old host thin-stub
+ * (`src/utils/github.ts`, which depended on the now-deleted
+ * `@/config/settings`) is gone too — the package component reads
+ * `settings.githubUrl` from the route context directly via
+ * `@takazudo/zudo-doc/github-helpers`. Nothing to inject or copy.
  */
 export declare const bodyFootUtilFeature: FeatureModule;

package/dist/features/body-foot-util.js

@@ -1,10 +1,14 @@
 /**
  * body-foot-util feature.
  *
- * W7A (#1736): post-cutover, the body-foot-util area is hosted by
- * `pages/lib/_doc-history-area.tsx` which wraps `BodyFootUtilArea`
- * unconditionally. The component itself runtime-gates on
- * `settings.bodyFootUtilArea`, so there is nothing to inject.
+ * Purely a `zudoDoc({ bodyFootUtilArea: {...} })` field (see
+ * `zfb-config-gen.ts`) — `BodyFootUtilArea` is fully package-owned
+ * (`@takazudo/zudo-doc/body-foot-util`, wired through `doc-page-shell`) and
+ * runtime-gates on `settings.bodyFootUtilArea`. The old host thin-stub
+ * (`src/utils/github.ts`, which depended on the now-deleted
+ * `@/config/settings`) is gone too — the package component reads
+ * `settings.githubUrl` from the route context directly via
+ * `@takazudo/zudo-doc/github-helpers`. Nothing to inject or copy.
  */
 export const bodyFootUtilFeature = () => ({
     name: "bodyFootUtil",

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

@@ -1,2 +1,14 @@
 import type { FeatureModule } from "../compose.js";
+/**
+ * Claude-resources feature.
+ *
+ * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
+ * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
+ * truthy). The old `src/integrations/claude-resources/*` host copy
+ * (escape-for-mdx.ts / generate.ts + tests) was a pre-package-first
+ * duplicate implementation nothing imported — deleted in the minimal-scaffold
+ * cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660). This feature's touch
+ * points are now just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
+ * (`zfb-config-gen.ts`).
+ */
 export declare const claudeResourcesFeature: FeatureModule;

package/dist/features/claude-resources.js

@@ -1,9 +1,16 @@
+/**
+ * Claude-resources feature.
+ *
+ * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
+ * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
+ * truthy). The old `src/integrations/claude-resources/*` host copy
+ * (escape-for-mdx.ts / generate.ts + tests) was a pre-package-first
+ * duplicate implementation nothing imported — deleted in the minimal-scaffold
+ * cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660). This feature's touch
+ * points are now just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
+ * (`zfb-config-gen.ts`).
+ */
 export const claudeResourcesFeature = () => ({
     name: "claudeResources",
-    injections: [
-    // No shared file injection needed — this feature's touch points are:
-    //   - plugin entry: zfb-config-gen.ts (claudeResources conditional import/plugin)
-    //   - settings: settings-gen.ts (claudeResources object + defaultLocaleOnlyPrefixes array)
-    //   - devDep: scaffold.ts (tsx devDep — same subprocess runner as docHistory)
-    ],
+    injections: [],
 });

package/dist/features/design-token-panel.d.ts

@@ -1,14 +1,2 @@
 import type { FeatureModule } from "../compose.js";
-/**
- * Design-token-panel (zdtp) feature.
- *
- * Injects:
- * 1. The zdtp CSS @import at `@slot:global-css:feature-styles` in
- *    `src/styles/global.css`.
- * 2. The DesignTokenPanelBootstrap import, displayName, and Island mount
- *    (with pre-hydration toggle shim) into
- *    `pages/lib/_body-end-islands.tsx` via the three @slot: anchors
- *    (imports / display-names / extra-islands). Mirrors the tauri feature
- *    injection shape (zudolab/zudo-doc#2162).
- */
 export declare const designTokenPanelFeature: FeatureModule;

package/dist/features/design-token-panel.js

@@ -1,100 +1,39 @@
-/**
- * Pre-hydration toggle shim for the zdtp panel (inline, minified).
- *
- * Emitted as a <script dangerouslySetInnerHTML> alongside the
- * DesignTokenPanelBootstrap Island so the header palette button is
- * responsive before the island hydrates. Records the first click as a
- * boolean flag and exposes window.__zdtpReadyClicks so the bootstrap
- * module can drain and re-dispatch once the real zdtp listener is live.
- * Guards against double-installation across SPA body swaps via
- * __zdtpToggleShimInstalled. Mirrors the host's ZDTP_TOGGLE_SHIM_SRC
- * constant (pages/lib/_body-end-islands.tsx, zudolab/zudo-doc#1627 Part B).
- */
-const ZDTP_TOGGLE_SHIM_SRC = `(function(){
-if(window.__zdtpToggleShimInstalled)return;
-window.__zdtpToggleShimInstalled=true;
-var pending=false;
-function shim(){pending=true;}
-window.addEventListener('toggle-design-token-panel',shim);
-window.__zdtpReadyClicks=function(){
-window.removeEventListener('toggle-design-token-panel',shim);
-delete window.__zdtpReadyClicks;
-if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
-};
-})();`;
+import fs from "fs-extra";
+import path from "path";
 /**
  * Design-token-panel (zdtp) feature.
  *
- * Injects:
- * 1. The zdtp CSS @import at `@slot:global-css:feature-styles` in
- *    `src/styles/global.css`.
- * 2. The DesignTokenPanelBootstrap import, displayName, and Island mount
- *    (with pre-hydration toggle shim) into
- *    `pages/lib/_body-end-islands.tsx` via the three @slot: anchors
- *    (imports / display-names / extra-islands). Mirrors the tauri feature
- *    injection shape (zudolab/zudo-doc#2162).
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660): the
+ * bootstrap island, its config builder, and the pre-hydration toggle shim
+ * are ALL package-owned now —
+ * `chrome/derive.tsx`'s `deriveBodyEndIslands` auto-defaults the real
+ * `DesignTokenPanelBootstrap` island for every `createChrome` consumer
+ * (#2658 gate-2 fix, verified against the locked-manifest self-contained
+ * doc stub in the target-manifest confirm fixture), and
+ * `doc-body-end-islands/index.tsx` carries the toggle shim inline. So this
+ * feature has nothing left to inject into `pages/lib/_body-end-islands.tsx`
+ * or `src/config/settings-types.ts` — both files are gone anyway.
+ *
+ * The ONE thing that stays generator-owned: `@takazudo/zdtp/styles.css` is
+ * the single conditional line in `src/styles/global.css` (documented in
+ * that file's header comment) — it can't ship unconditionally from
+ * `@takazudo/zudo-doc/theme.css` because it pulls in zdtp's own bytes.
+ * Inserted right after the `@layer zd-preflight, zd-flow;` line (the same
+ * position the locked-manifest reference shape uses).
  */
+const ZDTP_IMPORT_LINE = `@import "@takazudo/zdtp/styles.css";`;
+const LAYER_LINE = `@layer zd-preflight, zd-flow;`;
 export const designTokenPanelFeature = () => ({
     name: "designTokenPanel",
-    injections: [
-        {
-            // Panel chrome CSS — imported here so the rules land in the main page
-            // CSS bundle (not a deferred chunk), ensuring the panel renders
-            // correctly on first click. Vite library mode strips the source CSS
-            // import from the emitted JS, so this CSS-side import is the required
-            // pull point. See @takazudo/zdtp PORTABLE-CONTRACT.md §7.
-            file: "src/styles/global.css",
-            anchor: "/* @slot:global-css:feature-styles */",
-            content: `@import "@takazudo/zdtp/styles.css";`,
-        },
-        // 1. Import the island entry. Inserted AFTER the
-        //    `// @slot:body-end-islands:imports` anchor.
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "// @slot:body-end-islands:imports",
-            position: "after",
-            content: `import DesignTokenPanelBootstrap from "@/components/design-token-panel-bootstrap";`,
-        },
-        // 2. Stable island marker name (belt-and-braces guard matching the
-        //    sibling islands in the file). Inserted AFTER the
-        //    `// @slot:body-end-islands:display-names` anchor.
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "// @slot:body-end-islands:display-names",
-            position: "after",
-            content: `(DesignTokenPanelBootstrap as { displayName?: string }).displayName = "DesignTokenPanelBootstrap";`,
-        },
-        // 4. Extend HeaderRightTriggerName with "design-token-panel". Uses
-        //    replace-range between the :start/:end anchors in settings-types.ts
-        //    so the base template emits only "ai-chat" and this injection adds
-        //    the zdtp trigger only when the feature is on (zudolab/zudo-doc#2162).
-        {
-            file: "src/config/settings-types.ts",
-            anchor: "// @slot:settings-types:trigger-names:start",
-            position: "replace",
-            content: `export type HeaderRightTriggerName = "design-token-panel" | "ai-chat";`,
-        },
-        // 3. Island mount + pre-hydration toggle shim. Inserted AFTER the
-        //    `{/* @slot:body-end-islands:extra-islands */}` anchor.
-        //    when="load" (not "idle"): the bootstrap module registers the
-        //    `toggle-design-token-panel` window listener as a side effect of
-        //    its import, so it must hydrate as early as possible (zudolab/zudo-doc#1623).
-        //    The inline <script> is the pre-hydration shim (zudolab/zudo-doc#1627 Part B).
-        {
-            file: "pages/lib/_body-end-islands.tsx",
-            anchor: "{/* @slot:body-end-islands:extra-islands */}",
-            position: "after",
-            content: `      {/* zdtp panel bootstrap: hydrates on load so configurePanel() runs early
-          and the toggle-design-token-panel listener is live before the user
-          clicks the header trigger. The inline script is the pre-hydration
-          shim that queues the first click (zudolab/zudo-doc#1627 Part B). */}
-      <script
-        dangerouslySetInnerHTML={{ __html: ${JSON.stringify(ZDTP_TOGGLE_SHIM_SRC)} }}
-      />
-      {Island({
-        when: "load",
-        children: <DesignTokenPanelBootstrap />,
-      }) as unknown as VNode}`,
-        },
-    ],
+    injections: [],
+    postProcess: async (targetDir) => {
+        const cssPath = path.join(targetDir, "src/styles/global.css");
+        if (!(await fs.pathExists(cssPath)))
+            return;
+        let content = await fs.readFile(cssPath, "utf-8");
+        if (content.includes(ZDTP_IMPORT_LINE))
+            return; // already patched (idempotent)
+        content = content.replace(LAYER_LINE, `${LAYER_LINE}\n${ZDTP_IMPORT_LINE}`);
+        await fs.writeFile(cssPath, content);
+    },
 });

package/dist/features/doc-history.d.ts

@@ -2,8 +2,23 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Doc-history feature.
  *
- * W7A (#1736): post-cutover, `pages/lib/_doc-history-area.tsx` is mounted
- * unconditionally and self-gates on `settings.docHistory`. The plugin entry
- * is wired by `zfb-config-gen.ts`.
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660):
+ * `settings.docHistory` is a plain zudoDoc() field now (see zfb-config-gen.ts)
+ * and the diff-viewer CSS (`.diff-row`/`.diff-line-*`) ships unconditionally
+ * from `@takazudo/zudo-doc/features.css` (epic #2344 S4) — the old
+ * `@slot:global-css:feature-styles` CSS injection this module used to carry
+ * is DEAD (the anchor no longer exists in the ~20-line `global.css`) and has
+ * been removed.
+ *
+ * What's left to wire: the self-contained doc-route stub(s)
+ * (`pages/docs/[[...slug]].tsx`, and its i18n locale sibling when i18n is
+ * also selected) call `createChrome(routeCtx)` with NO hostBindings — unlike
+ * `DesignTokenPanelBootstrap` (auto-defaulted at the chrome-derive seam,
+ * #2658 gate-2 fix), `DocHistory`'s derive-level default is a deliberate
+ * no-op stub (see `routes/_chrome.tsx`'s comment on why — its own island
+ * needs the REAL host binding to hydrate). So when docHistory is selected,
+ * this feature patches the stub(s) to statically import the real
+ * `DocHistory` component and thread it through — the same #2480 chain
+ * `routes/_chrome.tsx` uses for the package's own routes.
  */
 export declare const docHistoryFeature: FeatureModule;

package/dist/features/doc-history.js

@@ -1,67 +1,52 @@
+import fs from "fs-extra";
+import path from "path";
 /**
  * Doc-history feature.
  *
- * W7A (#1736): post-cutover, `pages/lib/_doc-history-area.tsx` is mounted
- * unconditionally and self-gates on `settings.docHistory`. The plugin entry
- * is wired by `zfb-config-gen.ts`.
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660):
+ * `settings.docHistory` is a plain zudoDoc() field now (see zfb-config-gen.ts)
+ * and the diff-viewer CSS (`.diff-row`/`.diff-line-*`) ships unconditionally
+ * from `@takazudo/zudo-doc/features.css` (epic #2344 S4) — the old
+ * `@slot:global-css:feature-styles` CSS injection this module used to carry
+ * is DEAD (the anchor no longer exists in the ~20-line `global.css`) and has
+ * been removed.
+ *
+ * What's left to wire: the self-contained doc-route stub(s)
+ * (`pages/docs/[[...slug]].tsx`, and its i18n locale sibling when i18n is
+ * also selected) call `createChrome(routeCtx)` with NO hostBindings — unlike
+ * `DesignTokenPanelBootstrap` (auto-defaulted at the chrome-derive seam,
+ * #2658 gate-2 fix), `DocHistory`'s derive-level default is a deliberate
+ * no-op stub (see `routes/_chrome.tsx`'s comment on why — its own island
+ * needs the REAL host binding to hydrate). So when docHistory is selected,
+ * this feature patches the stub(s) to statically import the real
+ * `DocHistory` component and thread it through — the same #2480 chain
+ * `routes/_chrome.tsx` uses for the package's own routes.
  */
 export const docHistoryFeature = () => ({
     name: "docHistory",
-    injections: [
-        {
-            // Diff-viewer CSS — the DocHistory island's side-by-side diff markup
-            // (.diff-row / .diff-line-*) is styled only here; without this block
-            // scaffolded projects render the diff viewer unstyled (#2081). Values
-            // mirror the showcase src/styles/global.css (per-line separators at
-            // the 15% muted mix, #2077).
-            file: "src/styles/global.css",
-            anchor: "/* @slot:global-css:feature-styles */",
-            content: `/* ========================================
- * Doc History Diff Viewer (side-by-side)
- * ======================================== */
-
-.diff-row {
-  border-bottom: 1px solid color-mix(in oklch, var(--color-muted) 15%, transparent);
-}
-
-.diff-line-num {
-  font-family: var(--font-mono, ui-monospace, monospace);
-  font-size: var(--text-caption);
-  line-height: 1.5;
-  padding: 0 var(--spacing-hsp-xs);
-  text-align: right;
-  color: var(--color-muted);
-  user-select: none;
-  vertical-align: top;
-  border-right: 1px solid color-mix(in oklch, var(--color-muted) 15%, transparent);
-}
-
-.diff-line-content {
-  font-family: var(--font-mono, ui-monospace, monospace);
-  font-size: var(--text-caption);
-  line-height: 1.5;
-  padding: 0 var(--spacing-hsp-sm);
-  white-space: pre-wrap;
-  word-break: break-all;
-  vertical-align: top;
-}
-
-/* Left column right border to separate the two sides */
-.diff-row td:nth-child(2) {
-  border-right: 2px solid var(--color-muted);
-}
-
-.diff-line-added {
-  background-color: color-mix(in oklch, var(--color-success) 15%, transparent);
-}
-
-.diff-line-removed {
-  background-color: color-mix(in oklch, var(--color-danger) 15%, transparent);
-}
-
-.diff-line-empty {
-  background-color: color-mix(in oklch, var(--color-muted) 8%, transparent);
-}`,
-        },
-    ],
+    injections: [],
+    postProcess: async (targetDir) => {
+        const stubPaths = [
+            path.join(targetDir, "pages", "docs", "[[...slug]].tsx"),
+            path.join(targetDir, "pages", "[locale]", "docs", "[[...slug]].tsx"),
+        ];
+        for (const stubPath of stubPaths) {
+            if (!(await fs.pathExists(stubPath)))
+                continue;
+            let content = await fs.readFile(stubPath, "utf-8");
+            // Idempotency guard: check for the actual inserted import statement,
+            // NOT a bare `.includes("DocHistory")` — this file's own header
+            // comment (explaining WHY this patch exists) mentions "DocHistory" in
+            // prose, which would false-positive a weaker check and skip patching
+            // on every run.
+            const importMarker = `import { DocHistory } from "@takazudo/zudo-doc/doc-history";`;
+            if (content.includes(importMarker))
+                continue; // already patched
+            content = content.replace(`import { createChrome } from "@takazudo/zudo-doc/chrome";`, `import { createChrome } from "@takazudo/zudo-doc/chrome";
+${importMarker}
+import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";`);
+            content = content.replace(`const { renderDocPage } = createChrome(routeCtx);`, `const { renderDocPage } = createChrome(routeCtx, defineChromeBindings({ DocHistory }));`);
+            await fs.writeFile(stubPath, content);
+        }
+    },
 });