create-zudo-doc 0.1.0 → 0.2.0-next.1

package/dist/compose.d.ts

@@ -70,15 +70,17 @@ export declare function resolveSelectedFeatures(choices: UserChoices, featureMod
 export declare function validateDependencies(features: FeatureDefinition[], allSelectedNames: Set<string>): void;
 /** Files that may contain injection anchors and need cleaning.
  *
- * W7A (#1736): the two `.astro` entries were dropped — those files no
- * longer exist in generated projects after the post-cutover .tsx
- * migration. The only surviving anchor target is `global.css`, where
- * `design-token-panel.ts` injects `@import "@takazudo/zdtp/styles.css";`
- * at `@slot:global-css:feature-styles`. The sibling
- * `@slot:global-css:theme-tokens` anchor in the same file is consumed
- * by the color-scheme palette generator and must remain. The .tsx
- * anchor form is still supported in `ANCHOR_LINE_RE` for forward
- * compatibility, but no current feature uses it.
+ * 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/_mdx-components.ts` — image-enlarge.ts injects the
+ *   EnlargeableParagraph p-override (ENLARGE_SVG, EnlargeableParagraph def,
+ *   `p:` map entry) when imageEnlarge is enabled.
+ *
+ * The .tsx anchor form is still supported in `ANCHOR_LINE_RE` for forward
+ * compatibility.
  */
 export declare const ANCHOR_FILES: string[];
 /**

package/dist/compose.js

@@ -10,7 +10,7 @@ import path from "path";
  *   - `// @slot:…`              — TypeScript/JS line comment (module scope)
  *   - `/* @slot:… *\/`          — block comment
  *   - `{/* @slot:… *\/}`        — JSX expression comment (body region in .tsx)
- *   - `<!-- @slot:… -->`        — HTML comment (legacy .astro body region)
+ *   - `<!-- @slot:… -->`        — HTML comment (supported in case future template files use HTML comments)
  *   - `# @slot:…`               — shell / YAML comment
  */
 const ANCHOR_LINE_RE = /^[ \t]*(?:\{\/\*|\/\/|\/\*|<!--|#)\s*@slot:[^\n]*(?:\*\/\}|\*\/|-->)?[ \t]*\r?\n?$/gm;
@@ -156,17 +156,19 @@ export function validateDependencies(features, allSelectedNames) {
 }
 /** Files that may contain injection anchors and need cleaning.
  *
- * W7A (#1736): the two `.astro` entries were dropped — those files no
- * longer exist in generated projects after the post-cutover .tsx
- * migration. The only surviving anchor target is `global.css`, where
- * `design-token-panel.ts` injects `@import "@takazudo/zdtp/styles.css";`
- * at `@slot:global-css:feature-styles`. The sibling
- * `@slot:global-css:theme-tokens` anchor in the same file is consumed
- * by the color-scheme palette generator and must remain. The .tsx
- * anchor form is still supported in `ANCHOR_LINE_RE` for forward
- * compatibility, but no current feature uses it.
+ * 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/_mdx-components.ts` — image-enlarge.ts injects the
+ *   EnlargeableParagraph p-override (ENLARGE_SVG, EnlargeableParagraph def,
+ *   `p:` map entry) when imageEnlarge is enabled.
+ *
+ * The .tsx anchor form is still supported in `ANCHOR_LINE_RE` for forward
+ * compatibility.
  */
-export const ANCHOR_FILES = ["src/styles/global.css"];
+export const ANCHOR_FILES = ["src/styles/global.css", "pages/_mdx-components.ts"];
 /**
  * Main composition entry point. Orchestrates the full feature composition
  * pipeline for a generated project.

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

@@ -2,13 +2,11 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Design-token-panel (zdtp) feature.
  *
- * W7A (#1736): keeps the single surviving inject() — the zdtp CSS @import
- * at `@slot:global-css:feature-styles`. The two dead .astro injections
- * (doc-layout bootstrap import + header trigger button) are dropped:
- * the bootstrap is loaded by `pages/lib/design-token-panel-bootstrap`-side
- * effect when the feature is enabled, and the header trigger is now
- * rendered by `pages/lib/_header-with-defaults.tsx` from the
- * `settings.headerRightItems` entry `{ type: "trigger", trigger:
- * "design-token-panel" }`.
+ * Injects the zdtp CSS @import at `@slot:global-css:feature-styles` in
+ * `src/styles/global.css`. The bootstrap is loaded by
+ * `pages/lib/design-token-panel-bootstrap` as a side effect when the
+ * feature is enabled, and the header trigger is rendered by
+ * `pages/lib/_header-with-defaults.tsx` from the `settings.headerRightItems`
+ * entry `{ type: "trigger", trigger: "design-token-panel" }`.
  */
 export declare const designTokenPanelFeature: FeatureModule;

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

@@ -1,14 +1,12 @@
 /**
  * Design-token-panel (zdtp) feature.
  *
- * W7A (#1736): keeps the single surviving inject() — the zdtp CSS @import
- * at `@slot:global-css:feature-styles`. The two dead .astro injections
- * (doc-layout bootstrap import + header trigger button) are dropped:
- * the bootstrap is loaded by `pages/lib/design-token-panel-bootstrap`-side
- * effect when the feature is enabled, and the header trigger is now
- * rendered by `pages/lib/_header-with-defaults.tsx` from the
- * `settings.headerRightItems` entry `{ type: "trigger", trigger:
- * "design-token-panel" }`.
+ * Injects the zdtp CSS @import at `@slot:global-css:feature-styles` in
+ * `src/styles/global.css`. The bootstrap is loaded by
+ * `pages/lib/design-token-panel-bootstrap` as a side effect when the
+ * feature is enabled, and the header trigger is rendered by
+ * `pages/lib/_header-with-defaults.tsx` from the `settings.headerRightItems`
+ * entry `{ type: "trigger", trigger: "design-token-panel" }`.
  */
 export const designTokenPanelFeature = () => ({
     name: "designTokenPanel",

package/dist/features/footer-taglist.d.ts

@@ -4,10 +4,10 @@ import type { FeatureModule } from "../compose.js";
  *
  * Purely a settings toggle: `settings-gen.ts` emits
  * `footer.taglist = { enabled: true, groupBy: "group" }` when selected,
- * and the existing `footer.astro` (part of the footer pseudo-feature) reads
+ * and the footer component (part of the footer pseudo-feature) reads
  * `settings.footer.taglist` to decide whether to render the column(s).
  *
- * `footer.astro` is only installed by the footer pseudo-feature, so
+ * The footer component is only installed by the footer pseudo-feature, so
  * `resolveSelectedFeatures` treats `footerTaglist` as one of the triggers
  * for that feature.
  */

package/dist/features/footer-taglist.js

@@ -3,10 +3,10 @@
  *
  * Purely a settings toggle: `settings-gen.ts` emits
  * `footer.taglist = { enabled: true, groupBy: "group" }` when selected,
- * and the existing `footer.astro` (part of the footer pseudo-feature) reads
+ * and the footer component (part of the footer pseudo-feature) reads
  * `settings.footer.taglist` to decide whether to render the column(s).
  *
- * `footer.astro` is only installed by the footer pseudo-feature, so
+ * The footer component is only installed by the footer pseudo-feature, so
  * `resolveSelectedFeatures` treats `footerTaglist` as one of the triggers
  * for that feature.
  */

package/dist/features/image-enlarge.d.ts

@@ -7,5 +7,16 @@ import type { FeatureModule } from "../compose.js";
  * always-loaded stub-or-real ImageEnlarge component). Image-enlarge CSS
  * lives unconditionally in `templates/base/src/styles/global.css` — the
  * selectors only activate when the runtime mounts the .zd-enlarge-btn.
+ *
+ * S2 (#1825): after zfb next.18 removed the built-in imageEnlarge Rust
+ * feature, the server-side figure/button emission is re-implemented via an
+ * MDX paragraph (p) component override in pages/_mdx-components.ts. When
+ * imageEnlarge is enabled, three injections into the template file install:
+ *   1. Additional imports: toChildArray + VNode from preact, settings.
+ *   2. ENLARGE_SVG const + EnlargeableParagraph function definition.
+ *   3. `p: EnlargeableParagraph` entry in the createMdxComponents return map.
+ * When imageEnlarge is OFF, none of these are injected, so the override is
+ * absent and paragraphs render plain (the Rust built-in is gone — "off" must
+ * mean no wrapping at all).
  */
 export declare const imageEnlargeFeature: FeatureModule;

package/dist/features/image-enlarge.js

@@ -6,8 +6,195 @@
  * always-loaded stub-or-real ImageEnlarge component). Image-enlarge CSS
  * lives unconditionally in `templates/base/src/styles/global.css` — the
  * selectors only activate when the runtime mounts the .zd-enlarge-btn.
+ *
+ * S2 (#1825): after zfb next.18 removed the built-in imageEnlarge Rust
+ * feature, the server-side figure/button emission is re-implemented via an
+ * MDX paragraph (p) component override in pages/_mdx-components.ts. When
+ * imageEnlarge is enabled, three injections into the template file install:
+ *   1. Additional imports: toChildArray + VNode from preact, settings.
+ *   2. ENLARGE_SVG const + EnlargeableParagraph function definition.
+ *   3. `p: EnlargeableParagraph` entry in the createMdxComponents return map.
+ * When imageEnlarge is OFF, none of these are injected, so the override is
+ * absent and paragraphs render plain (the Rust built-in is gone — "off" must
+ * mean no wrapping at all).
  */
 export const imageEnlargeFeature = () => ({
     name: "imageEnlarge",
-    injections: [],
+    injections: [
+        // 1. Import additions: toChildArray + VNode from preact, settings.
+        //    Inserted AFTER the `// @slot:mdx-components:enlarge-imports` anchor.
+        {
+            file: "pages/_mdx-components.ts",
+            anchor: "// @slot:mdx-components:enlarge-imports",
+            position: "after",
+            content: `import { toChildArray } from "preact";
+import type { VNode } from "preact";
+import { settings } from "@/config/settings";`,
+        },
+        // 2. ENLARGE_SVG const + EnlargeableParagraph function.
+        //    Inserted AFTER the `// @slot:mdx-components:enlarge-defs` anchor
+        //    (which sits just before the `createMdxComponents` JSDoc comment).
+        //    Markup is ported verbatim from rehype-image-enlarge.ts makeEnlargeButton()
+        //    so the island's eligibility/[hidden] logic and CSS keep working identically.
+        {
+            file: "pages/_mdx-components.ts",
+            anchor: "// @slot:mdx-components:enlarge-defs",
+            position: "after",
+            content: `/**
+ * SVG icon for the image-enlarge button (4-corner-arrows).
+ *
+ * Ported verbatim from
+ * packages/create-zudo-doc/templates/base/src/plugins/rehype-image-enlarge.ts
+ * makeEnlargeButton() — this is the same icon the old Rust plugin emitted.
+ * Must match exactly so the existing .zd-enlarge-btn CSS and the
+ * image-enlarge island (src/components/image-enlarge.tsx) keep working.
+ *
+ * Attribute spellings: HTML/Preact conventions — \`focusable\` stays a string
+ * ("false") because Preact's preact-render-to-string drops boolean false;
+ * \`aria-hidden\` is the HTML attribute name (not ariaHidden).
+ */
+const ENLARGE_SVG = {
+  type: "svg",
+  props: {
+    viewBox: "0 0 38.99 38.99",
+    fill: "currentColor",
+    focusable: "false",
+    "aria-hidden": "true",
+    children: [
+      {
+        type: "polygon",
+        props: {
+          points:
+            "16.2 13.74 5.92 3.47 11.2 3.47 11.2 0 3.47 0 0 0 0 3.47 0 11.2 3.47 11.2 3.47 5.92 13.74 16.2 16.2 13.74",
+        },
+        key: null,
+        constructor: undefined,
+      },
+      {
+        type: "polygon",
+        props: {
+          points:
+            "25.24 16.2 35.52 5.92 35.52 11.2 38.99 11.2 38.99 3.47 38.99 0 35.52 0 27.79 0 27.79 3.47 33.07 3.47 22.79 13.74 25.24 16.2",
+        },
+        key: null,
+        constructor: undefined,
+      },
+      {
+        type: "polygon",
+        props: {
+          points:
+            "22.79 25.24 33.07 35.52 27.79 35.52 27.79 38.99 35.52 38.99 38.99 38.99 38.99 35.52 38.99 27.79 35.52 27.79 35.52 33.07 25.24 22.79 22.79 25.24",
+        },
+        key: null,
+        constructor: undefined,
+      },
+      {
+        type: "polygon",
+        props: {
+          points:
+            "13.74 22.79 3.47 33.07 3.47 27.79 0 27.79 0 35.52 0 38.99 3.47 38.99 11.2 38.99 11.2 35.52 5.92 35.52 16.2 25.24 13.74 22.79",
+        },
+        key: null,
+        constructor: undefined,
+      },
+    ],
+  },
+  key: null,
+  constructor: undefined,
+};
+
+/**
+ * Enlarge-aware MDX paragraph override.
+ *
+ * When \`settings.imageEnlarge\` is enabled and a paragraph contains exactly
+ * one non-whitespace child that is a block-level image VNode (type ===
+ * ContentImg or "img"), this wraps the image in:
+ *   <figure class="zd-enlargeable">
+ *     <img ...>
+ *     <button type="button" class="zd-enlarge-btn" hidden aria-label="Enlarge image">
+ *       <svg ...>…</svg>
+ *     </button>
+ *   </figure>
+ *
+ * The \`title="no-enlarge"\` opt-out is read from the un-rendered VNode
+ * (Preact's h() is lazy — child.type is still the ContentImg function, not
+ * yet called). ContentImg strips the sentinel from the rendered img DOM.
+ *
+ * All other paragraphs delegate to htmlOverrides.p (ContentParagraph passthrough).
+ */
+function EnlargeableParagraph(props: {
+  children?: ComponentChildren;
+  [key: string]: unknown;
+}): unknown {
+  const { children, ...rest } = props;
+  // Collect children and drop whitespace-only text nodes.
+  const kids = toChildArray(children).filter((child) => {
+    if (typeof child === "string" || typeof child === "number") {
+      return String(child).trim() !== "";
+    }
+    return true;
+  });
+
+  // Check for a single-image block paragraph eligible for enlarge wrapping.
+  if (settings.imageEnlarge && kids.length === 1) {
+    const kid = kids[0];
+    // VNode type guard: must be an object with a \`type\` property.
+    if (
+      kid !== null &&
+      typeof kid === "object" &&
+      "type" in kid &&
+      "props" in kid
+    ) {
+      const vnode = kid as VNode<Record<string, unknown>>;
+      if (vnode.type === ContentImg || vnode.type === "img") {
+        const imgProps = (vnode.props ?? {}) as Record<string, unknown>;
+        // Opt-out: title="no-enlarge" — render plain paragraph (ContentImg
+        // will strip the sentinel title from the actual img DOM).
+        if (imgProps.title !== "no-enlarge") {
+          // Wrap in figure.zd-enlargeable with the enlarge button.
+          const enlargeBtn = {
+            type: "button",
+            props: {
+              type: "button",
+              class: "zd-enlarge-btn",
+              hidden: true,
+              "aria-label": "Enlarge image",
+              children: ENLARGE_SVG,
+            },
+            key: null,
+            constructor: undefined,
+          };
+          return {
+            type: "figure",
+            props: {
+              class: "zd-enlargeable",
+              children: [vnode, enlargeBtn],
+            },
+            key: null,
+            constructor: undefined,
+          };
+        }
+      }
+    }
+  }
+
+  // Fallback: delegate to the standard ContentParagraph passthrough.
+  return (htmlOverrides.p as (props: unknown) => unknown)(props);
+}
+`,
+        },
+        // 3. p: EnlargeableParagraph entry in createMdxComponents return map.
+        //    Inserted AFTER the `// @slot:mdx-components:enlarge-p-entry` anchor
+        //    (which sits between `img: ContentImg,` and `HtmlPreview:`).
+        //    Must come AFTER the ...htmlOverrides spread to override ContentParagraph.
+        {
+            file: "pages/_mdx-components.ts",
+            anchor: "// @slot:mdx-components:enlarge-p-entry",
+            position: "after",
+            content: `    // p override: wraps block-level images in <figure class="zd-enlargeable">
+    // with an enlarge button when settings.imageEnlarge is enabled.
+    // Must come AFTER the ...htmlOverrides spread to override ContentParagraph.
+    p: EnlargeableParagraph,`,
+        },
+    ],
 });

package/dist/features/versioning.d.ts

@@ -2,11 +2,11 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Versioning feature.
  *
- * W7A (#1736): post-cutover, the pages/lib wrappers gate `VersionSwitcher`
- * and `VersionBanner` on `settings.versions`. Doc-layout flow is handled by
- * route enumerators + `_inline-version-switcher.tsx`. The .astro inject
- * calls that used to wire this in have been retired (they targeted dead
- * `src/layouts/doc-layout.astro` + `src/components/header.astro` anchors).
+ * The pages/lib wrappers gate `VersionSwitcher` and `VersionBanner` on
+ * `settings.versions`. Doc-layout flow is handled by route enumerators +
+ * `_inline-version-switcher.tsx`. This feature copies versioning page
+ * templates from `templates/features/versioning/files/` via
+ * `copyFeatureFiles` (compose.ts), and injects nothing into `global.css`.
  *
  * W7C (#1738): the versioning feature ships pages under
  * `templates/features/versioning/files/pages/`:

package/dist/features/versioning.js

@@ -3,11 +3,11 @@ import path from "path";
 /**
  * Versioning feature.
  *
- * W7A (#1736): post-cutover, the pages/lib wrappers gate `VersionSwitcher`
- * and `VersionBanner` on `settings.versions`. Doc-layout flow is handled by
- * route enumerators + `_inline-version-switcher.tsx`. The .astro inject
- * calls that used to wire this in have been retired (they targeted dead
- * `src/layouts/doc-layout.astro` + `src/components/header.astro` anchors).
+ * The pages/lib wrappers gate `VersionSwitcher` and `VersionBanner` on
+ * `settings.versions`. Doc-layout flow is handled by route enumerators +
+ * `_inline-version-switcher.tsx`. This feature copies versioning page
+ * templates from `templates/features/versioning/files/` via
+ * `copyFeatureFiles` (compose.ts), and injects nothing into `global.css`.
  *
  * W7C (#1738): the versioning feature ships pages under
  * `templates/features/versioning/files/pages/`:

package/dist/index.js

@@ -69,6 +69,14 @@ async function main() {
     if (Object.keys(featureFlags).length > 0) {
         prefilled.features = { ...prefilled.features, ...featureFlags };
     }
+    // Record which features were explicitly disabled via --no-<flag> so
+    // scaffold.ts can warn when an auto-enable overrides that explicit choice.
+    const explicitlyDisabled = Object.entries(featureFlags)
+        .filter(([, v]) => v === false)
+        .map(([k]) => k);
+    if (explicitlyDisabled.length > 0) {
+        prefilled.explicitlyDisabledFeatures = explicitlyDisabled;
+    }
     // With --yes or --preset: fill all unspecified options with defaults
     if (args.yes || args.preset) {
         prefilled.projectName ??= "my-docs";

package/dist/prompts.d.ts

@@ -9,6 +9,7 @@ export interface UserChoices {
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
     features: string[];
+    explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
     packageManager: "pnpm" | "npm" | "yarn" | "bun";
@@ -24,6 +25,7 @@ export interface PartialChoices {
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
     features?: Partial<Record<string, boolean>>;
+    explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
     packageManager?: "pnpm" | "npm" | "yarn" | "bun";

package/dist/prompts.js

@@ -240,6 +240,7 @@ export async function runPrompts(prefilled = {}) {
         respectPrefersColorScheme,
         defaultMode,
         features,
+        explicitlyDisabledFeatures: prefilled.explicitlyDisabledFeatures,
         githubUrl,
         cjkFriendly: prefilled.cjkFriendly,
         packageManager,

package/dist/scaffold.js

@@ -90,12 +90,15 @@ export async function scaffold(choices) {
             throw new Error(`Directory "${choices.projectName}" already exists and is not empty`);
         }
     }
-    // body-foot-util-area.astro ships the DocHistory component inline (byte-
-    // identical to main/src/components/body-foot-util-area.astro). Selecting
+    // body-foot-util-area.tsx ships the DocHistory component inline (byte-
+    // identical to main/src/components/body-foot-util-area.tsx). Selecting
     // bodyFootUtil without docHistory would leave an unresolved import, so we
-    // silently co-enable docHistory.
+    // co-enable docHistory. Warn when this overrides an explicit --no-doc-history.
     if (choices.features.includes("bodyFootUtil") &&
         !choices.features.includes("docHistory")) {
+        if (choices.explicitlyDisabledFeatures?.includes("docHistory")) {
+            console.warn("body-foot-util requires doc-history; enabling it despite --no-doc-history");
+        }
         choices.features = [...choices.features, "docHistory"];
     }
     // Resolve template directories
@@ -211,20 +214,44 @@ function generatePackageJson(choices) {
     //   @takazudo/zudo-doc-md-plugins — zero references in generator templates/source
     //   @takazudo/zfb-adapter-cloudflare — zero references in generator templates/source
     const deps = {
-        // zfb engine — replaces astro/@astrojs/* now that the cutover (#500 S5)
-        // has retired the legacy Astro pipeline. Distributed as published npm
-        // packages (the prebuilt binary ships via an optionalDependency of
-        // @takazudo/zfb); pinned to the pre-release the scaffold targets.
+        // zfb engine — distributed as published npm packages (the prebuilt binary
+        // ships via an optionalDependency of @takazudo/zfb-<platform>); pinned to
+        // the pre-release the scaffold targets (per #500).
         // The two literals below must match root package.json's
         // dependencies["@takazudo/zfb"] / ["@takazudo/zfb-runtime"] —
         // enforced by scripts/check-pin-parity.mjs (W4A — #1732).
-        "@takazudo/zfb": "0.1.0-next.6",
-        "@takazudo/zfb-runtime": "0.1.0-next.6",
+        // Bumped to next.13 in S6 (#1808) — absorbs the next.12 breaking change
+        // (4 former-Core features moved to opt-in markdown.features block).
+        // Bumped to next.14 (#1817) — fixes the ruby SSR-500 (#1815) and the
+        // tocExport indented-export build break (#1814), letting both features
+        // be re-enabled in the showcase markdown.features block.
+        // Bumped to next.19 (#1824) — next.18 hard-removed the built-in
+        // imageEnlarge markdown feature (now re-implemented in userland via an MDX
+        // p-override); next.19 adds the islands esbuild react/jsx-runtime→preact
+        // alias fix (Takazudo/zudo-front-builder#633) that next.18 lacked.
+        // Bumped to next.21 — next.20/next.21 are Rust-engine-internal robustness
+        // releases (no SDK API change): dev cold-boot 200, dev watch-ADD discovery
+        // of newly-added content files, and bounded waits fixing build/dev hangs.
+        // Bumped to next.22 — additive bundler/markdown migration-parity release (no
+        // breaking config change): Vite import.meta.glob eager transform, bundle.exclude
+        // glob knob, opt-in markdown hardBreaks (default false), and config-eval V8
+        // web polyfills + tsconfig path-alias composition fixes.
+        // Bumped to next.23 — zfb/config ambient type improvements (BundleConfig +
+        // bundle field in ZfbConfig; fixes Takazudo/zudo-front-builder#678).
+        // Bumped to next.25 — BREAKING: removes `admonitionsPreset` (configs
+        // still setting it hard-error at load). Replaced by the generic
+        // `markdown.features.directives` map; host zfb.config.ts migrated
+        // in zudolab/zudo-doc#1840.
+        "@takazudo/zfb": "0.1.0-next.25",
+        "@takazudo/zfb-runtime": "0.1.0-next.25",
+        // zfb-adapter-cloudflare — required for any route with `prerender = false`.
+        // Pinned in lockstep with @takazudo/zfb.
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.25",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
         // version moves, so a fresh scaffold pulls the version we just published.
-        "@takazudo/zudo-doc": "^0.1.0",
+        "@takazudo/zudo-doc": "^0.2.0-next.1",
         // zod — used by the generated zfb.config.ts. zfb-config-gen emits
         // `import { z } from "zod"` for the content-collection schema +
         // `z.toJSONSchema(...)` conversion. Without this dep, the consumer
@@ -276,6 +303,13 @@ function generatePackageJson(choices) {
     }
     if (choices.features.includes("docHistory")) {
         deps["diff"] = "^8.0.3";
+        // @takazudo/zudo-doc has @takazudo/zudo-doc-history-server as an optional
+        // peer dep. When docHistory is selected the zfb plugin
+        // (plugins/doc-history-plugin.mjs) eagerly imports
+        // @takazudo/zudo-doc/integrations/doc-history which in turn imports
+        // @takazudo/zudo-doc-history-server/git-history. Without this dep the
+        // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.1";
         // W7A (#1736): doc-history-plugin.mjs spawns `tsx -e <inline-script>` to
         // run the v2 runtime in a TS-aware Node subprocess; without tsx the
         // plugin's preBuild step exits with ENOENT before zfb finishes config
@@ -289,7 +323,7 @@ function generatePackageJson(choices) {
         devDeps["tsx"] = "^4.21.0";
     }
     if (choices.features.includes("designTokenPanel")) {
-        deps["@takazudo/zdtp"] = "0.1.0-next.1";
+        deps["@takazudo/zdtp"] = "0.2.0-next.2";
     }
     if (choices.features.includes("tagGovernance")) {
         // gray-matter is already in `deps` unconditionally (base template uses it),

package/dist/settings-gen.js

@@ -71,10 +71,14 @@ export function generateSettingsFile(choices) {
     else {
         lines.push(`  locales: {} as Record<string, LocaleConfig>,`);
     }
+    // mermaid is controlled by the markdown.features block in zfb.config.ts
+    // (zfb next.12+). This field is retained for compatibility with framework
+    // components that still read settings.mermaid. See the markdown.features
+    // block in the generated zfb.config.ts for the canonical opt-in.
     lines.push(`  mermaid: true,`);
     lines.push(`  sitemap: false,`);
     lines.push(`  docMetainfo: false,`);
-    lines.push(`  docTags: false,`);
+    lines.push(`  docTags: ${choices.features.includes("docTags")},`);
     lines.push(`  tagPlacement: "after-title" as TagPlacement,`);
     if (choices.features.includes("tagGovernance")) {
         lines.push(`  tagGovernance: "warn" as TagGovernanceMode,`);
@@ -95,6 +99,14 @@ export function generateSettingsFile(choices) {
     lines.push(`  cjkFriendly: ${choices.cjkFriendly ?? false} as boolean,`);
     lines.push(`  onBrokenMarkdownLinks: "warn" as "warn" | "error" | "ignore",`);
     lines.push(`  aiAssistant: false as boolean,`);
+    // When the user wires up `pages/api/ai-chat.tsx` (not shipped in any
+    // scaffold variant — W6A spec-lock Decision 5), this toggle short-circuits
+    // the endpoint with a fixed "disabled" reply. Default `false` here — the
+    // showcase ships with `true` because it deploys without an Anthropic key,
+    // but a fresh scaffold has `aiAssistant: false` and the user only enables
+    // the chat once they're wiring up a real `ANTHROPIC_API_KEY`. Defaulting
+    // demo mode off avoids silently disabling chat for them.
+    lines.push(`  aiChatDemoMode: false as boolean,`);
     if (choices.features.includes("docHistory")) {
         lines.push(`  docHistory: true,`);
     }

package/dist/zfb-config-gen.js

@@ -216,6 +216,63 @@ export function generateZfbConfig(choices) {
     lines.push(`  },`);
     lines.push(`  base: settings.base,`);
     lines.push(`  trailingSlash: settings.trailingSlash,`);
+    // 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(`    },`);
+    lines.push(`  },`);
     lines.push(`  plugins: integrationPlugins,`);
     lines.push(`});`);
     return lines.join("\n") + "\n";