create-zudo-doc 0.2.22 → 1.0.1

package/dist/compose.d.ts

@@ -75,9 +75,6 @@ export declare function validateDependencies(features: FeatureDefinition[], allS
  *   `@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.
  * - `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
@@ -86,6 +83,12 @@ export declare function validateDependencies(features: FeatureDefinition[], allS
  * - `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).
+ *
+ * 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).
  */
 export declare const ANCHOR_FILES: string[];
 /**

package/dist/compose.js

@@ -161,9 +161,6 @@ export function validateDependencies(features, allSelectedNames) {
  *   `@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.
  * - `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
@@ -172,10 +169,15 @@ export function validateDependencies(features, allSelectedNames) {
  * - `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).
+ *
+ * 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).
  */
 export const ANCHOR_FILES = [
     "src/styles/global.css",
-    "pages/_mdx-components.ts",
     "pages/lib/_body-end-islands.tsx",
     "src/config/settings-types.ts",
 ];

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

@@ -9,22 +9,24 @@ import type { FeatureModule } from "../compose.js";
  * `global.css` in S3 #2348) — 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.
- *   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).
+ * S2 (#1825): the server-side figure/button emission was re-implemented via an
+ * MDX paragraph (p) component override in pages/_mdx-components.ts. Three
+ * injections installed the ENLARGE_SVG + EnlargeableParagraph code when
+ * imageEnlarge was enabled.
+ *
+ * S8 / #2360 (E2): the full MDX component assembly moved into the
+ * @takazudo/zudo-doc/mdx-components factory (createMdxComponentsBase). The
+ * factory reads settings.imageEnlarge at render time and conditionally wraps
+ * block-level images in <figure class="zd-enlargeable"> — the same logic the
+ * old injections installed, now handled once inside the package. The three
+ * _mdx-components.ts injections (enlarge-imports, enlarge-defs,
+ * enlarge-p-entry) are therefore removed; the feature is a no-op from the
+ * compose engine's perspective (the runtime gate in the factory is always
+ * present in the scaffolded template).
  *
  * S3 (#2348): the ImageEnlarge island and its SSR fallback moved from
  * src/components/image-enlarge.tsx into @takazudo/zudo-doc/image-enlarge.
  * The pages/lib/_body-end-islands.tsx template now imports them from the
- * package, so the local component file overlay was removed from
- * templates/features/imageEnlarge/files/. No file-copy injections remain
- * in this feature module — only _mdx-components.ts injections.
+ * package, so no file-copy injections exist in this feature module either.
  */
 export declare const imageEnlargeFeature: FeatureModule;

package/dist/features/image-enlarge.js

@@ -8,203 +8,27 @@
  * `global.css` in S3 #2348) — 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.
- *   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).
+ * S2 (#1825): the server-side figure/button emission was re-implemented via an
+ * MDX paragraph (p) component override in pages/_mdx-components.ts. Three
+ * injections installed the ENLARGE_SVG + EnlargeableParagraph code when
+ * imageEnlarge was enabled.
+ *
+ * S8 / #2360 (E2): the full MDX component assembly moved into the
+ * @takazudo/zudo-doc/mdx-components factory (createMdxComponentsBase). The
+ * factory reads settings.imageEnlarge at render time and conditionally wraps
+ * block-level images in <figure class="zd-enlargeable"> — the same logic the
+ * old injections installed, now handled once inside the package. The three
+ * _mdx-components.ts injections (enlarge-imports, enlarge-defs,
+ * enlarge-p-entry) are therefore removed; the feature is a no-op from the
+ * compose engine's perspective (the runtime gate in the factory is always
+ * present in the scaffolded template).
  *
  * S3 (#2348): the ImageEnlarge island and its SSR fallback moved from
  * src/components/image-enlarge.tsx into @takazudo/zudo-doc/image-enlarge.
  * The pages/lib/_body-end-islands.tsx template now imports them from the
- * package, so the local component file overlay was removed from
- * templates/features/imageEnlarge/files/. No file-copy injections remain
- * in this feature module — only _mdx-components.ts injections.
+ * package, so no file-copy injections exist in this feature module either.
  */
 export const imageEnlargeFeature = () => ({
     name: "imageEnlarge",
-    injections: [
-        // 1. Import additions: toChildArray + VNode from preact.
-        //    Inserted AFTER the `// @slot:mdx-components:enlarge-imports` anchor.
-        //    NOTE: `settings` is NOT injected here — the base template already
-        //    imports it (#2172); injecting it again caused a duplicate ES-module
-        //    lexical binding.
-        {
-            file: "pages/_mdx-components.ts",
-            anchor: "// @slot:mdx-components:enlarge-imports",
-            position: "after",
-            content: `import { toChildArray } from "preact";
-import type { VNode } from "preact";`,
-        },
-        // 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,`,
-        },
-    ],
+    injections: [],
 });

package/dist/scaffold.d.ts

@@ -1,4 +1,15 @@
 import type { UserChoices } from "./prompts.js";
 import { getSecondaryLang } from "./utils.js";
 export { getSecondaryLang };
+/**
+ * Pinned `@takazudo/zudo-doc` version used in both `generatePackageJson()`
+ * and the `.zudo-doc.json` seed written by `scaffold()`. Hoisted as a shared
+ * constant so the dep pin and the provenance seed can never drift.
+ *
+ * Strip the caret from this string to get the bare version for provenance:
+ *   ZUDO_DOC_PIN.replace(/^\^/, "")   →  "1.0.0"
+ *
+ * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
+ */
+export declare const ZUDO_DOC_PIN = "^1.0.1";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -8,6 +8,17 @@ import { composeFeatures } from "./compose.js";
 import { featureModules } from "./features/index.js";
 import { capitalize, getSecondaryLang } from "./utils.js";
 export { getSecondaryLang };
+/**
+ * Pinned `@takazudo/zudo-doc` version used in both `generatePackageJson()`
+ * and the `.zudo-doc.json` seed written by `scaffold()`. Hoisted as a shared
+ * constant so the dep pin and the provenance seed can never drift.
+ *
+ * Strip the caret from this string to get the bare version for provenance:
+ *   ZUDO_DOC_PIN.replace(/^\^/, "")   →  "1.0.0"
+ *
+ * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
+ */
+export const ZUDO_DOC_PIN = "^1.0.1";
 /**
  * Files in `templates/base/**` that must never be copied into a generated
  * project. Each entry is matched against the path relative to `templates/base/`
@@ -280,6 +291,14 @@ export async function scaffold(choices) {
     await fs.outputFile(path.join(targetDir, "zfb.config.ts"), zfbConfigContent);
     const pkg = generatePackageJson(choices);
     await fs.outputFile(path.join(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+    // Seed .zudo-doc.json — provenance marker for `zudo-doc eject <component>`.
+    // packageVersion is the bare version string (caret stripped from ZUDO_DOC_PIN)
+    // so it records the concrete version the scaffold targets; the eject CLI
+    // records the actually-installed version on first eject.
+    await fs.outputFile(path.join(targetDir, ".zudo-doc.json"), JSON.stringify({
+        packageVersion: ZUDO_DOC_PIN.replace(/^\^/, ""),
+        ejected: {},
+    }, null, 2) + "\n");
     const gitignoreLines = [
         "# Build output",
         "node_modules",
@@ -303,6 +322,9 @@ export async function scaffold(choices) {
         "# Cloudflare Wrangler",
         ".wrangler/",
         "",
+        "# zudo-doc build artifact (routes-src/ staged here at build time)",
+        ".zudo-doc/",
+        "",
     ];
     // The doc-lookup skill is only generated when skillSymlinker is selected
     // (the setup-doc-skill.sh script and `setup:doc-skill` npm script are gated
@@ -444,15 +466,20 @@ function generatePackageJson(choices) {
         // zfb-content GFM-autolink fix — terminate the autolink path at CJK
         // boundaries (zfb#1105). Content-rendering bug fix, additive; relevant for
         // CJK (e.g. Japanese) docs. No consumer-facing / CLI breaking change.
-        // next.54 (current pin): bug-fix + perf release — cross-OS CSS hash
-        // stability, multi-valued response headers (e.g. multiple Set-Cookie),
+        // next.54: bug-fix + perf release — cross-OS CSS hash stability,
+        // multi-valued response headers (e.g. multiple Set-Cookie),
         // supplementary-plane CJK reading-time, plus CLI/server/runtime hardening
         // and render perf passes. No consumer-facing / CLI breaking change.
-        "@takazudo/zfb": "0.1.0-next.62",
-        "@takazudo/zfb-runtime": "0.1.0-next.62",
+        // next.65 (current pin): dev-render of package-injected routes (zfb#1227,
+        // landed next.63) + islands bundler now seeds the host tsconfig `paths`
+        // (e.g. `@/*`) into its synthetic tsconfig (zfb#1238) — fixes silent island
+        // hydration failure under route injection. Unblocks packageOwnedRoutes.
+        // No consumer-facing / CLI breaking change.
+        "@takazudo/zfb": "0.1.0-next.65",
+        "@takazudo/zfb-runtime": "0.1.0-next.65",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.62",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.65",
         // @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
@@ -464,7 +491,9 @@ function generatePackageJson(choices) {
         // ties this pin to packages/zudo-doc's version, so the lockstep release
         // bumps both together; do not cut a create-zudo-doc release until the
         // matching @takazudo/zudo-doc version (with content.css) is on npm.
-        "@takazudo/zudo-doc": "^0.2.22",
+        // ZUDO_DOC_PIN is the shared constant — scaffold() uses the same value
+        // to seed .zudo-doc.json so the provenance and the dep can never drift.
+        "@takazudo/zudo-doc": ZUDO_DOC_PIN,
         // 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
@@ -497,6 +526,19 @@ function generatePackageJson(choices) {
         // consumer-build verification — the import lives in the mirrored
         // pages, not behind any feature gate. Same pin as host.
         katex: "^0.16.38",
+        // diff — required at build time by EVERY generated project, not just
+        // docHistory ones. The always-copied host base template
+        // `pages/lib/_doc-history-area.tsx` statically imports the real
+        // `DocHistory` from `@takazudo/zudo-doc/doc-history` (to keep zfb's island
+        // scanner chain page→stub→DocHistory walkable), which pulls
+        // `@takazudo/zudo-doc/dist/doc-history/index.js`'s `await import("diff")`
+        // into the bundle. With packageOwnedRoutes default ON (1.0), a
+        // docHistory-off project still bundles that path, so without `diff` here
+        // `zfb build` fails at esbuild with "Could not resolve 'diff'" (#2342).
+        // `diff` is an *optional* peerDependency of @takazudo/zudo-doc, so a
+        // missing copy produces no `pnpm install` warning — which is why this gap
+        // shipped silently and only surfaced at build time.
+        diff: "^8.0.3",
     };
     const devDeps = {
         "@tailwindcss/vite": "^4.2.0",
@@ -511,14 +553,16 @@ function generatePackageJson(choices) {
         devDeps["pagefind"] = "^1.4.0";
     }
     if (choices.features.includes("docHistory")) {
-        deps["diff"] = "^8.0.3";
+        // (diff is now an unconditional base dep — see the `deps` block above:
+        // packageOwnedRoutes always bundles the doc-history-area path, so diff is
+        // required regardless of this feature flag.)
         // @takazudo/zudo-doc has @takazudo/zudo-doc-history-server as an optional
         // peer dep. When docHistory is selected the zfb plugin
         // (@takazudo/zudo-doc/plugins/doc-history) 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.22";
+        deps["@takazudo/zudo-doc-history-server"] = "^1.0.1";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).

package/dist/settings-gen.js

@@ -150,6 +150,10 @@ export function generateSettingsFile(choices) {
     else {
         lines.push(`  docHistory: false,`);
     }
+    // Package-owned route injection is on by default since the fast-follow (#2372).
+    // Generated projects include the field explicitly so settings.ts stays in sync
+    // with src/config/settings.ts (checked by check-fixture-settings-drift.mjs).
+    lines.push(`  packageOwnedRoutes: true,`);
     if (choices.features.includes("bodyFootUtil")) {
         lines.push(`  bodyFootUtilArea: {`);
         lines.push(`    docHistory: ${choices.features.includes("docHistory")},`);

package/package.json

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