create-zudo-doc 1.2.0 → 2.0.0

package/templates/features/claudeResources/files/src/integrations/claude-resources/__tests__/generate.test.ts

@@ -111,15 +111,20 @@ describe("generateClaudeResourcesDocs", () => {
       }
     });
 
-    it("generates skill as flat .mdx file", () => {
+    it("generates skill page as <dir>/index.mdx", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
+      // The skill page is the directory index so `./ref-<name>` links resolve
+      // against the source file path (#2411) — NOT a flat `<dir>.mdx`.
+      const indexPath = path.join(docsDir, "claude-skills", "test-skill", "index.mdx");
+      expect(fs.existsSync(indexPath)).toBe(true);
+
       const flatPath = path.join(docsDir, "claude-skills", "test-skill.mdx");
-      expect(fs.existsSync(flatPath)).toBe(true);
+      expect(fs.existsSync(flatPath)).toBe(false);
     });
   });
 
@@ -150,7 +155,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
       const parsed = matter(skillPage);
@@ -168,7 +173,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
@@ -179,7 +184,7 @@ describe("generateClaudeResourcesDocs", () => {
       expect(skillPage).toContain("SKILL.md");
     });
 
-    it("skill page has links to sub-files that resolve correctly from the page URL", () => {
+    it("skill page has links to sub-files that resolve to sibling nested files", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
@@ -187,12 +192,12 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
-      // Links use ./<subpage> format (relative to the skill page URL which
-      // already includes the skill dir, e.g. /docs/claude-skills/test-skill/)
+      // Links use ./<subpage>; the skill page is <dir>/index.mdx so these
+      // resolve against the file path to the sibling <dir>/<subpage>.mdx (#2411).
       expect(skillPage).toContain("./ref-guide");
       expect(skillPage).toContain("./asset-template");
 
@@ -200,8 +205,9 @@ describe("generateClaudeResourcesDocs", () => {
       expect(skillPage).not.toContain("./test-skill/ref-guide");
       expect(skillPage).not.toContain("./test-skill/asset-template");
 
-      // Each linked sub-page must exist as a generated flat .mdx file
-      // The file is flat (test-skill--ref-guide.mdx) but slug is nested
+      // Each linked sub-page must exist as a sibling nested file inside <dir>/,
+      // i.e. claude-skills/test-skill/<subpage>.mdx — which is exactly where the
+      // ./<subpage> relative link resolves to.
       const linkPattern = /\]\(\.\/([\w-]+)\)/g;
       let match;
       while ((match = linkPattern.exec(skillPage)) !== null) {
@@ -209,11 +215,12 @@ describe("generateClaudeResourcesDocs", () => {
         const targetFile = path.join(
           docsDir,
           "claude-skills",
-          `test-skill--${subPage}.mdx`,
+          "test-skill",
+          `${subPage}.mdx`,
         );
         expect(
           fs.existsSync(targetFile),
-          `Link target "test-skill--${subPage}.mdx" should exist`,
+          `Link target "test-skill/${subPage}.mdx" should exist`,
         ).toBe(true);
       }
     });
@@ -226,7 +233,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
@@ -255,28 +262,28 @@ describe("generateClaudeResourcesDocs", () => {
   // ---------------------------------------------------------------------------
 
   describe("sub-file pages", () => {
-    it("generates unlisted reference page", () => {
+    it("generates unlisted reference page as a nested file", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
-      const refPage = path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx");
+      const refPage = path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx");
       expect(fs.existsSync(refPage)).toBe(true);
 
       const parsed = matter(fs.readFileSync(refPage, "utf8"));
       expect(parsed.data.unlisted).toBe(true);
     });
 
-    it("generates unlisted asset page for .md files", () => {
+    it("generates unlisted asset page for .md files as a nested file", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
-      const assetPage = path.join(docsDir, "claude-skills", "test-skill--asset-template.mdx");
+      const assetPage = path.join(docsDir, "claude-skills", "test-skill", "asset-template.mdx");
       expect(fs.existsSync(assetPage)).toBe(true);
 
       const parsed = matter(fs.readFileSync(assetPage, "utf8"));
@@ -290,23 +297,26 @@ describe("generateClaudeResourcesDocs", () => {
         docsDir,
       });
 
-      const scriptPage = path.join(docsDir, "claude-skills", "test-skill--script-run.mdx");
+      const scriptPage = path.join(docsDir, "claude-skills", "test-skill", "script-run.mdx");
       expect(fs.existsSync(scriptPage)).toBe(false);
     });
 
-    it("sub-pages have custom slug for nested breadcrumbs", () => {
+    it("sub-pages derive their route from the file path (no explicit slug)", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
+      // The page lives at claude-skills/test-skill/ref-guide.mdx, so its route
+      // is claude-skills/test-skill/ref-guide — nested breadcrumbs come from the
+      // file path, not an explicit slug (which zfb's link resolver ignores, #2411).
       const refPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx"),
         "utf8",
       );
       const parsed = matter(refPage);
-      expect(parsed.data.slug).toBe("claude-skills/test-skill/ref-guide");
+      expect(parsed.data.slug).toBeUndefined();
     });
 
     it("reference page content is correct", () => {
@@ -317,7 +327,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const refPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx"),
         "utf8",
       );
       const parsed = matter(refPage);
@@ -532,4 +542,109 @@ describe("generateClaudeResourcesDocs", () => {
       ).toThrow(/reserved name "index"/);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // projectRoot default scope regression test
+  // ---------------------------------------------------------------------------
+
+  describe("projectRoot default scope", () => {
+    it("walks claudeDir (not its parent) when projectRoot is omitted", () => {
+      // The fixture already writes tmpDir/CLAUDE.md (outside claudeDir).
+      // With the old bug (projectRoot = path.dirname(claudeDir) = tmpDir), the
+      // walk starts at tmpDir and picks up tmpDir/CLAUDE.md. With the fix
+      // (projectRoot = claudeDir), the walk starts inside claudeDir and does NOT
+      // reach tmpDir/CLAUDE.md (parent dirs are never walked upward).
+      //
+      // To distinguish, we write a CLAUDE.md inside claudeDir with unique content
+      // and verify the generated page body matches IT, not the outside one.
+      fs.writeFileSync(
+        path.join(claudeDir, "CLAUDE.md"),
+        "# Claude dir unique content xyz123",
+      );
+
+      // Call with NO projectRoot.
+      generateClaudeResourcesDocs({ claudeDir, docsDir });
+
+      // The generated root.mdx body must contain the inside-claudeDir content.
+      const claudeMdDir = path.join(docsDir, "claude-md");
+      const rootMdx = fs.readFileSync(path.join(claudeMdDir, "root.mdx"), "utf8");
+      expect(rootMdx).toContain("xyz123");
+
+      // And must NOT contain the outside content (from tmpDir/CLAUDE.md).
+      expect(rootMdx).not.toContain("Project instructions");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // CLAUDE.md repo-relative link downgrade (#2411, Class B)
+  // ---------------------------------------------------------------------------
+
+  describe("CLAUDE.md repo-relative link downgrade", () => {
+    const claudeMdBody = [
+      "# Project",
+      "",
+      "See [wrangler.toml](./wrangler.toml) and [schema](../../schema/photos.sql).",
+      "Also a [workflow](../../.github/workflows/deploy.yml) and a [bare](docs/guide.md) link.",
+      "External [site](https://example.com), [anchor](#section), [site-abs](/docs/getting-started), [mail](mailto:x@y.com).",
+      "Image: ![diagram](./diagram.png)",
+      "",
+      "Inline code stays: `[x](./y)`",
+      "",
+      "```",
+      "[code](./should-not-change.md)",
+      "```",
+      "",
+      "~~~",
+      "[tilde-code](./also-should-not-change.md)",
+      "~~~",
+      "",
+    ].join("\n");
+
+    function genRoot() {
+      fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), claudeMdBody);
+      generateClaudeResourcesDocs({ claudeDir, projectRoot: tmpDir, docsDir });
+      return fs.readFileSync(
+        path.join(docsDir, "claude-md", "root.mdx"),
+        "utf8",
+      );
+    }
+
+    it("downgrades repo-relative file links to inline code", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("`wrangler.toml`");
+      expect(rootMdx).toContain("`schema`");
+      expect(rootMdx).toContain("`workflow`");
+      expect(rootMdx).toContain("`bare`");
+      // The dangling hrefs must be gone.
+      expect(rootMdx).not.toContain("](./wrangler.toml)");
+      expect(rootMdx).not.toContain("](../../schema/photos.sql)");
+      expect(rootMdx).not.toContain("](../../.github/workflows/deploy.yml)");
+      expect(rootMdx).not.toContain("](docs/guide.md)");
+    });
+
+    it("preserves resolvable links (external, anchor, site-absolute, scheme)", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("](https://example.com)");
+      expect(rootMdx).toContain("](#section)");
+      expect(rootMdx).toContain("](/docs/getting-started)");
+      expect(rootMdx).toContain("](mailto:x@y.com)");
+    });
+
+    it("downgrades repo-relative image links without leaving a stray '!'", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("`diagram`");
+      expect(rootMdx).not.toContain("](./diagram.png)");
+      expect(rootMdx).not.toContain("!`diagram`");
+    });
+
+    it("does not rewrite links inside inline code or fenced code blocks", () => {
+      const rootMdx = genRoot();
+      // Inline-code span is preserved verbatim.
+      expect(rootMdx).toContain("`[x](./y)`");
+      // Backtick-fenced code block content is preserved verbatim.
+      expect(rootMdx).toContain("[code](./should-not-change.md)");
+      // Tilde-fenced code block content is preserved verbatim too.
+      expect(rootMdx).toContain("[tilde-code](./also-should-not-change.md)");
+    });
+  });
 });

package/templates/features/claudeResources/files/src/integrations/claude-resources/generate.ts

@@ -96,18 +96,24 @@ generated: true
 }
 
 /**
- * Writes an unlisted sub-page MDX file (flat file with a custom nested slug).
- * Used for skill references, scripts, and assets.
+ * Writes an unlisted sub-page MDX file. Used for skill references, scripts,
+ * and assets.
+ *
+ * The route is derived from the file's path within the content collection —
+ * deliberately NOT from an explicit `slug:`. zfb's `resolveMarkdownLinks`
+ * resolves relative links against the *source file path*, so the on-disk
+ * location of these pages must match the URL the skill page links to. Writing
+ * them at `<dir>/ref-<name>.mdx` (siblings of the skill's `index.mdx`) is what
+ * makes the `./ref-<name>` links resolve (#2411).
  */
 function writeUnlistedSubPage(
   outputPath: string,
   title: string,
-  slug: string,
   body: string,
 ) {
   fs.writeFileSync(
     outputPath,
-    `---\ntitle: "${escapeTitle(title)}"\nslug: "${slug}"\nunlisted: true\ngenerated: true\n---\n\n${body}\n`,
+    `---\ntitle: "${escapeTitle(title)}"\nunlisted: true\ngenerated: true\n---\n\n${body}\n`,
   );
 }
 
@@ -124,6 +130,82 @@ function assertNotIndexReserved(
   }
 }
 
+/**
+ * Whether a markdown link target is a repo-relative file reference
+ * (`./wrangler.toml`, `../../schema/photos.sql`, `foo/bar.md`) rather than
+ * something the doc site can resolve: an absolute URL (`https://…`), a
+ * protocol-relative URL (`//…`), a site-absolute path (`/docs/…`), a pure
+ * anchor (`#…`), or a scheme (`mailto:`, `tel:`).
+ */
+function isRepoRelativeLink(url: string): boolean {
+  const trimmed = url.trim();
+  if (trimmed === "") return false;
+  if (trimmed.startsWith("#")) return false; // anchor
+  if (trimmed.startsWith("/")) return false; // site-absolute or protocol-relative (//host)
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false; // has a scheme (http:, mailto:, …)
+  return true;
+}
+
+/**
+ * Downgrade repo-relative markdown links in a mirrored `CLAUDE.md` body to
+ * inline code so they don't dangle in the flattened mirror tree (#2411).
+ *
+ * A `CLAUDE.md`'s relative links point at real repo files (correct for an
+ * in-repo reader), but the mirror flattens each file into a single
+ * `claude-md/<name>.mdx` page with no counterpart for those targets — left as
+ * links they surface as `broken link:` warnings on every affected page. Inline
+ * code keeps the reference legible (`` `wrangler.toml` ``) without a href.
+ *
+ * Code spans are preserved verbatim: a `[x](./y)` inside a fenced block or an
+ * inline-code span is literal text, not a link, and must not be rewritten.
+ */
+function downgradeRepoRelativeLinks(content: string): string {
+  const blockPlaceholder = "\x00CRLINK_BLOCK_";
+  const inlinePlaceholder = "\x00CRLINK_INLINE_";
+
+  // Extract fenced code blocks so their contents are untouched. Both backtick
+  // (```) and tilde (~~~) fences are recognised; the `\1` backreference makes
+  // the closing fence match the same delimiter the block opened with.
+  const codeBlocks: string[] = [];
+  const withBlocks = content.replace(/(`{3,}|~{3,})[^\n]*\n[\s\S]*?\1/g, (match) => {
+    codeBlocks.push(match);
+    return `${blockPlaceholder}${codeBlocks.length - 1}\x00`;
+  });
+
+  const transformed = withBlocks
+    .split(new RegExp(`(${blockPlaceholder}\\d+\x00)`, "g"))
+    .map((part) => {
+      if (new RegExp(`^${blockPlaceholder}\\d+\x00$`).test(part)) return part;
+
+      // Preserve inline-code spans, then rewrite links in the remaining text.
+      const inlineCodes: string[] = [];
+      const withInline = part.replace(
+        /(`{1,3})(?!`)([\s\S]*?[^`])\1(?!`)/g,
+        (match) => {
+          inlineCodes.push(match);
+          return `${inlinePlaceholder}${inlineCodes.length - 1}\x00`;
+        },
+      );
+
+      const rewritten = withInline.replace(
+        /!?\[([^\]]*)\]\(([^)]+)\)/g,
+        (match, text: string, url: string) =>
+          isRepoRelativeLink(url) ? `\`${text}\`` : match,
+      );
+
+      return rewritten.replace(
+        new RegExp(`${inlinePlaceholder}(\\d+)\x00`, "g"),
+        (_, idx: string) => inlineCodes[Number(idx)] ?? "",
+      );
+    })
+    .join("");
+
+  return transformed.replace(
+    new RegExp(`${blockPlaceholder}(\\d+)\x00`, "g"),
+    (_, idx: string) => codeBlocks[Number(idx)] ?? "",
+  );
+}
+
 // ---------------------------------------------------------------------------
 // CLAUDE.md discovery
 // ---------------------------------------------------------------------------
@@ -164,7 +246,7 @@ function findClaudeMdFiles(dir: string, excludeDirs: string[]): string[] {
 function generateClaudemdDocs(
   config: ClaudeResourcesConfig,
 ): ClaudeMdItem[] {
-  const projectRoot = config.projectRoot ?? path.dirname(config.claudeDir);
+  const projectRoot = config.projectRoot ?? config.claudeDir;
   const outputDir = path.join(config.docsDir, "claude-md");
 
   cleanDir(outputDir);
@@ -229,7 +311,7 @@ generated: true
 
 **Path:** \`${item.relPath}\`
 
-${escapeForMdx(content.trim())}
+${escapeForMdx(downgradeRepoRelativeLinks(content.trim()))}
 `;
     fs.writeFileSync(path.join(outputDir, `${item.slug}.mdx`), mdx);
   });
@@ -309,6 +391,7 @@ function getSkillFileTree(
 
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
+    if (!entry) continue;
     const isLast = i === entries.length - 1;
     const prefix = isLast ? "└── " : "├── ";
 
@@ -318,6 +401,7 @@ function getSkillFileTree(
       lines.push(`${prefix}${entry.name}/`);
       for (let j = 0; j < entry.children.length; j++) {
         const child = entry.children[j];
+        if (!child) continue;
         const childIsLast = j === entry.children.length - 1;
         const continuation = isLast ? "    " : "│   ";
         const childPrefix = childIsLast ? "└── " : "├── ";
@@ -333,9 +417,10 @@ function getScriptDescription(filePath: string): string {
   try {
     const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
     // Skip shebang, use second line if available
-    const commentLine = topLines[0].startsWith("#!")
-      ? topLines[1] || ""
-      : topLines[0];
+    const firstLine = topLines[0] ?? "";
+    const commentLine = firstLine.startsWith("#!")
+      ? topLines[1] ?? ""
+      : firstLine;
     // Match # comments (shell/python) or // comments (JS/TS)
     const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
     return match ? ` — ${match[1]}` : "";
@@ -358,7 +443,7 @@ function getSkillReferences(
       const content = fs.readFileSync(path.join(refsDir, f), "utf8");
       const name = f.replace(/\.md$/, "");
       const h1Match = content.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : name;
+      const title = h1Match?.[1] ?? name;
       return { name, title, content };
     })
     .sort((a, b) => a.name.localeCompare(b.name));
@@ -418,9 +503,9 @@ function generateSkillsDocs(config: ClaudeResourcesConfig): SkillItem[] {
     if (subDirs.length > 0) {
       const tree = `\`\`\`\n${getSkillFileTree(dir, subDirs)}\n\`\`\``;
 
-      // Collect links to all .md sub-files that get pages
-      // Links use ./<subpage> which resolves correctly from the skill page URL
-      // (the page URL already includes the dir, e.g. /docs/claude-skills/<dir>/)
+      // Collect links to all .md sub-files that get pages. Links use
+      // ./<subpage>; because the skill page is written as `<dir>/index.mdx`,
+      // these resolve to the sibling `<dir>/<subpage>.mdx` files (#2411).
       const links: string[] = [];
       for (const ref of references) {
         links.push(`- [references/${ref.name}.md](./ref-${ref.name})`);
@@ -465,18 +550,22 @@ generated: true
 
 ${body}`;
 
-    // Write skill page as flat file
-    fs.writeFileSync(path.join(outputDir, `${dir}.mdx`), mdx);
-
-    // Generate unlisted sub-pages (flat files with custom slug for nested breadcrumbs)
-    // File: <dir>--ref-<name>.mdx, slug: claude-skills/<dir>/ref-<name>
-    const skillSlugBase = `claude-skills/${dir}`;
-
+    // Write the skill page as the directory index (`<dir>/index.mdx`) so its
+    // route is `claude-skills/<dir>` served at URL `.../claude-skills/<dir>/`.
+    // This makes the reference/script/asset pages genuine siblings inside
+    // `<dir>/`, which is what lets the `./ref-<name>` links above resolve.
+    const skillDirOut = path.join(outputDir, dir);
+    ensureDir(skillDirOut);
+    fs.writeFileSync(path.join(skillDirOut, "index.mdx"), mdx);
+
+    // Generate unlisted sub-pages as nested files inside `<dir>/`. Their routes
+    // (`claude-skills/<dir>/ref-<name>`, …) are derived from these file paths
+    // and therefore match the `./ref-<name>` / `./script-<name>` /
+    // `./asset-<name>` links emitted above (#2411).
     for (const ref of references) {
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--ref-${ref.name}.mdx`),
+        path.join(skillDirOut, `ref-${ref.name}.mdx`),
         ref.title,
-        `${skillSlugBase}/ref-${ref.name}`,
         escapeForMdx(ref.content.trim()),
       );
     }
@@ -488,11 +577,10 @@ ${body}`;
         "utf8",
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--script-${slug}.mdx`),
+        path.join(skillDirOut, `script-${slug}.mdx`),
         title,
-        `${skillSlugBase}/script-${slug}`,
         escapeForMdx(raw.trim()),
       );
     }
@@ -504,11 +592,10 @@ ${body}`;
         "utf8",
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--asset-${slug}.mdx`),
+        path.join(skillDirOut, `asset-${slug}.mdx`),
         title,
-        `${skillSlugBase}/asset-${slug}`,
         escapeForMdx(raw.trim()),
       );
     }

package/templates/features/i18n/files/pages/[locale]/index.tsx

@@ -32,10 +32,12 @@ import type { VNode } from "preact";
 import { Island } from "@takazudo/zfb";
 import { SiteTreeNav } from "@takazudo/zudo-doc/site-tree-nav-island";
 import { resolveNavSource } from "../lib/_nav-source-docs";
-import { FooterWithDefaults } from "../lib/_footer-with-defaults";
-import { HeaderWithDefaults } from "../lib/_header-with-defaults";
-import { HeadWithDefaults } from "../lib/_head-with-defaults";
-import { composeMetaTitle } from "../lib/_compose-meta-title";
+import {
+  FooterWithDefaults,
+  HeaderWithDefaults,
+  HeadWithDefaults,
+  composeMetaTitle,
+} from "../lib/_chrome";
 import { BodyEndIslands } from "../lib/_body-end-islands";
 
 export const frontmatter = { title: "Home" };

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

@@ -1,106 +0,0 @@
-// Project MDX-components assembly — thin wrapper over the package factory.
-//
-// The bulk of the components bag (htmlOverrides, admonitions, CodeGroup,
-// Tabs/TabItem, MathBlock, the img base-rewrite, the enlargeable-`p` override)
-// now ships from `@takazudo/zudo-doc/mdx-components` (package-first migration,
-// epic #2321, S8 #2332). This file keeps ONLY what is genuinely project-bound:
-//
-//   - the 4 locale-bound nav wrappers (CategoryNav / CategoryTreeNav /
-//     SiteTreeNav / SiteTreeNavDemo) — they depend on the project's content
-//     collections + nav-tree utilities, so they cannot live in the package.
-//     They are passed into the factory as `navData`; the factory injects the
-//     active `locale` so `/ja` resolves the JA collection (the load-bearing
-//     locale thread — a static global mdx-components slot would render the EN
-//     tree on every `/ja` page, which is why this stays a per-call factory).
-//   - project `extras` spread last: HtmlPreview (with the host's global
-//     config), Details, the Island SSR pass-through, the PresetGenerator SSR
-//     shell, and the pure-showcase stubs (Avatar/Button/Card/MyComponent/
-//     PageLayout) that appear only as illustrative MDX prose.
-
-import type { ComponentChildren } from "preact";
-import { createMdxComponents as createMdxComponentsBase } from "@takazudo/zudo-doc/mdx-components";
-import { HtmlPreviewWrapper, type HtmlPreviewWrapperProps } from "@takazudo/zudo-doc/html-preview-wrapper";
-import { defaultLocale, type Locale } from "@/config/i18n";
-import { settings } from "@/config/settings";
-import { CategoryNavWrapper } from "./lib/_category-nav";
-import { CategoryTreeNavWrapper } from "./lib/_category-tree-nav";
-import { SiteTreeNavWrapper } from "./lib/_site-tree-nav";
-import { DetailsWrapper } from "./lib/_details";
-import { PresetGeneratorFallback } from "./lib/_preset-generator";
-
-const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
-  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
-
-/**
- * MDX-tag stub: renders nothing. Returning `null` keeps the rendered tree
- * intact (Preact's null-vnode path) without leaking placeholder markup into
- * the SSR output.
- */
-const MdxStub = (_props: unknown) => null;
-
-/**
- * SSR-pass-through wrapper for `<Island when="load|idle|visible">`.
- *
- * In the zfb build the zfb `<Island>` component is unavailable here, so the
- * MDX corpus tag resolves to this binding instead. Rendering the children
- * directly ensures server-renderable content nested inside `<Island>`
- * (headings, paragraphs, etc.) appears in the SSR HTML. The `when` prop is
- * ignored at render time — it is only meaningful to the zfb hydration runtime
- * on the client, which reads `data-when` on the inner SSR-skip placeholder.
- */
-function IslandWrapper(props: {
-  when?: "load" | "idle" | "visible" | "media";
-  children?: ComponentChildren;
-}): ComponentChildren {
-  return props.children ?? null;
-}
-
-/**
- * Build a locale-aware MDX components map for the given locale.
- *
- * Delegates the package-resident components to the `@takazudo/zudo-doc`
- * factory and supplies the project-bound pieces:
- *   - `navData`: the 4 locale-aware nav wrappers (the factory injects `lang`).
- *   - `extras`: HtmlPreview (host-configured), Details, Island pass-through,
- *     PresetGenerator SSR shell, and the showcase stubs.
- *
- * Page modules should call createMdxComponents(locale) — not the static
- * mdxComponents export — so each render gets the locale-correct map.
- */
-export function createMdxComponents(lang: Locale | string = defaultLocale) {
-  return createMdxComponentsBase({
-    settings,
-    locale: lang,
-    navData: {
-      CategoryNav: CategoryNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
-      CategoryTreeNav: CategoryTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
-      SiteTreeNav: SiteTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
-    },
-    extras: {
-      HtmlPreview: HtmlPreviewWithGlobalConfig,
-      Details: DetailsWrapper,
-      // SmartBreak: corpus tag with no visual rendering — render nothing.
-      SmartBreak: MdxStub,
-      // Island: pass children through so server-renderable content nested
-      // inside <Island> appears in SSR HTML. See IslandWrapper comment above.
-      Island: IslandWrapper,
-      // PresetGenerator: SSR fallback shell that renders the 8 section headings;
-      // the interactive form hydrates client-side via the SSR-skip placeholder
-      // inside PresetGeneratorFallback (see pages/lib/_preset-generator.tsx).
-      PresetGenerator: PresetGeneratorFallback,
-      // Pure showcase placeholders — appear only inside MDX prose as
-      // illustrative examples, never implemented as real components.
-      Avatar: MdxStub,
-      Button: MdxStub,
-      Card: MdxStub,
-      MyComponent: MdxStub,
-      PageLayout: MdxStub,
-    },
-  });
-}
-
-/**
- * Static default-locale components map for backward compatibility.
- * New page modules should call createMdxComponents(locale) instead.
- */
-export const mdxComponents = createMdxComponents(defaultLocale);