create-zudo-doc 3.2.0 → 4.0.0

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,24 @@ 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) always thread the host's `chromeBindings`. 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 merge it over those bindings — preserving every
+ * configured host slot while maintaining the same #2480 scanner-reachability
+ * 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,56 @@
+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) always thread the host's `chromeBindings`. 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 merge it over those bindings — preserving every
+ * configured host slot while maintaining the same #2480 scanner-reachability
+ * 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, chromeBindings);`, `const { renderDocPage } = createChrome(routeCtx, {
+  ...chromeBindings,
+  ...defineChromeBindings({ DocHistory }),
+});`);
+            await fs.writeFile(stubPath, content);
+        }
+    },
 });

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

@@ -1,19 +1,15 @@
 import type { FeatureModule } from "../compose.js";
 /**
- * docTags feature (W7C — #1738).
+ * docTags feature.
  *
- * Settings gate: `settings.docTags === true`.
+ * Purely a `zudoDoc({ docTags: true })` field (see `zfb-config-gen.ts`) —
+ * the `/docs/tags` + `/docs/tags/[tag]` routes are PACKAGE-INJECTED
+ * (`routes/docs-tags-index.tsx` / `routes/docs-tags-tag.tsx`), gated on
+ * `settings.docTags`. `templates/features/docTags/files/` has been empty
+ * since the host catch-all stubs were retired in favor of package
+ * injection — there is nothing left to copy or postProcess.
  *
- * Ships feature-conditional pages from
- * `templates/features/docTags/files/pages/`:
- *
- *   docs/tags/[tag].tsx
- *   docs/tags/index.tsx
- *   [locale]/docs/tags/[tag].tsx    — only when i18n ALSO selected
- *   [locale]/docs/tags/index.tsx    — only when i18n ALSO selected
- *
- * `copyFeatureFiles` (compose.ts) auto-emits every file under
- * `files/`; postProcess removes the `[locale]/**` subset when i18n
- * is NOT selected. See W2 spec-lock §Cross-feature interaction.
+ * Known limitation: same injected-DYNAMIC-route dev-mode gap noted on the
+ * versioning feature — the tag routes may 404 in `zfb dev` (build is fine).
  */
 export declare const docTagsFeature: FeatureModule;

package/dist/features/doc-tags.js

@@ -1,33 +1,17 @@
-import fs from "fs-extra";
-import path from "path";
 /**
- * docTags feature (W7C — #1738).
+ * docTags feature.
  *
- * Settings gate: `settings.docTags === true`.
+ * Purely a `zudoDoc({ docTags: true })` field (see `zfb-config-gen.ts`) —
+ * the `/docs/tags` + `/docs/tags/[tag]` routes are PACKAGE-INJECTED
+ * (`routes/docs-tags-index.tsx` / `routes/docs-tags-tag.tsx`), gated on
+ * `settings.docTags`. `templates/features/docTags/files/` has been empty
+ * since the host catch-all stubs were retired in favor of package
+ * injection — there is nothing left to copy or postProcess.
  *
- * Ships feature-conditional pages from
- * `templates/features/docTags/files/pages/`:
- *
- *   docs/tags/[tag].tsx
- *   docs/tags/index.tsx
- *   [locale]/docs/tags/[tag].tsx    — only when i18n ALSO selected
- *   [locale]/docs/tags/index.tsx    — only when i18n ALSO selected
- *
- * `copyFeatureFiles` (compose.ts) auto-emits every file under
- * `files/`; postProcess removes the `[locale]/**` subset when i18n
- * is NOT selected. See W2 spec-lock §Cross-feature interaction.
+ * Known limitation: same injected-DYNAMIC-route dev-mode gap noted on the
+ * versioning feature — the tag routes may 404 in `zfb dev` (build is fine).
  */
-export const docTagsFeature = (choices) => ({
+export const docTagsFeature = () => ({
     name: "docTags",
     injections: [],
-    postProcess: async (targetDir) => {
-        if (!choices.features.includes("i18n")) {
-            // i18n is OFF — strip the locale-scoped tag pages that were
-            // copied unconditionally by copyFeatureFiles.
-            const localeTagsDir = path.join(targetDir, "pages", "[locale]", "docs", "tags");
-            if (await fs.pathExists(localeTagsDir)) {
-                await fs.remove(localeTagsDir);
-            }
-        }
-    },
 });

package/dist/features/dynamic-page-transition.d.ts

@@ -2,36 +2,25 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Dynamic page transition feature.
  *
- * When enabled:
- * - Sets `enableClientRouter={settings.dynamicPageTransition}` on every
- *   `<DocLayoutWithDefaults>` render site — the SSR `<ClientRouter />` render
- *   self-activates the SPA router on the client as a top-level module side
- *   effect (primary activation path).
- * - Wires the ClientRouterBootstrap island and the PageLoadingOverlay (pure
- *   SSR) into body-end-islands — the island is now a redundant fallback;
- *   PageLoadingOverlay provides the loading spinner UI.
- * - Injects `@import "@takazudo/zudo-doc/page-loading.css"` at the
- *   `@slot:global-css:imports` anchor (top of global.css, before rule blocks).
- * - Injects the `--color-page-loading-overlay` token into `@theme` at the
- *   `@slot:global-css:theme-tokens` anchor.
- * - Injects the View-Transitions CSS into global.css at
- *   `@slot:global-css:feature-styles`.
+ * Minimal-scaffold cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660):
+ * purely a `zudoDoc({ dynamicPageTransition: true })` field now (see
+ * `zfb-config-gen.ts`). The primary activation path —
+ * `<ClientRouter enableClientRouter={settings.dynamicPageTransition} />`
+ * rendered by the package's own `doc-page-shell`/`doclayout` — and the
+ * pure-SSR `<PageLoadingOverlay/>` mount are BOTH already handled inside
+ * `doc-body-end-islands/index.tsx`, gated on the same flag; the View-
+ * Transitions CSS ships unconditionally from `@takazudo/zudo-doc/features.css`.
  *
- * Bug fix (#2265): the page-loading overlay CSS (.page-loading-overlay /
- * .page-loading-spinner / @keyframes page-loading-spin / [data-zd-nav-pending])
- * was never reaching scaffolded projects because it lived unconditionally in
- * the host global.css but had no corresponding injection for the template.
- * Gating this feature makes both the JS island and the CSS land together.
- *
- * The page-loading CSS now ships as a package artifact
- * `@takazudo/zudo-doc/page-loading.css` (Topic A, #2283) — the generator
- * injects a gated `@import` instead of inline rule bodies. The
- * `--color-page-loading-overlay` token is defined inline (inside `@theme`) so
- * it lives alongside the other project tokens and can be overridden per-project.
- *
- * The ClientRouterBootstrap component lives in
- * templates/features/dynamicPageTransition/files/src/components/ and is
- * byte-identical to the host src/components/client-router-bootstrap.tsx.
- * The feature-template drift checker enforces this parity automatically.
+ * DROPPED: the host `ClientRouterBootstrap` island
+ * (`templates/features/dynamicPageTransition/files/src/components/`) —
+ * its old host-owned mount point (`pages/lib/_body-end-islands.tsx`) no
+ * longer exists, and the package's own doc-body-end-islands header comment
+ * already calls it "a redundant fallback" once PageLoadingOverlay covers the
+ * loading UI. Known gap (documented, out of this generator's scope): the
+ * package's SSR-only `<ClientRouter/>` import may still need a "use client"
+ * bootstrap to guarantee the click-intercept ships to the browser bundle —
+ * same class of issue as tauri's find-in-page island (see tauri.ts). If a
+ * project needs it restored, wire a custom island through
+ * `settings.chromeBindingsModule`'s `BodyEndIslands` slot.
  */
 export declare const dynamicPageTransitionFeature: FeatureModule;