@takazudo/zudo-doc 0.2.0 → 0.2.2

package/README.md

@@ -6,6 +6,7 @@ This package provides the missing-by-design framework concerns:
 
 - **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into a sidebar `SidebarNode[]`.
 - **Theme controls** (`./theme`) — color scheme provider + design-token tweak panel (Preact island that wraps an iframe).
+- **Theme toggle (bare)** (`./theme-toggle`) — the un-wrapped ThemeToggle component for call sites that compose their own `<Island>` (the `./theme` barrel exports an Island-wrapped variant of the same component).
 - **TOC** (`./toc`) — desktop and mobile TOC Preact islands fed by MDX `headings` export.
 - **Breadcrumb** (`./breadcrumb`) — JSX breadcrumb fed by the sidebar tree.
 - **DocLayout** (`./doclayout`) — composable layout shell with explicit `<Header>`, `<Sidebar>`, `<Main>`, `<Toc>`, `<Footer>` props; ships a `<DocLayoutWithDefaults>` wrapper that holds the 16 `create-zudo-doc` injection anchors.
@@ -13,6 +14,56 @@ This package provides the missing-by-design framework concerns:
 - **Head injection** (`./head`) — canonical, og:\*, twitter:\*, robots, preload hints, RSS link, sitemap link, theme-color — byte-equal to today's legacy doc-layout output.
 - **SSR-skip wrappers** (`./ssr-skip`) — `<AiChatModalIsland>`, `<ImageEnlargeIsland>`, `<DesignTokenTweakPanelIsland>`, `<MockInitIsland>` — wrap zfb's `<Island ssrFallback>` with the right fallback markup so doc pages don't have to re-implement the SSR-skip pattern.
 
-## Pre-publish dev workflow
+## Optional peer dependency: shiki
 
-Phase A npm publish is deferred (see super-epic comment 2026-04-28). During pre-publish dev, this package references zfb via the local checkout at `$HOME/repos/myoss/zfb`. Use `/refer-another-project zfb` to read zfb's APIs. If a zfb bug is discovered, fix it directly on zfb's `main` and push (zfb is not public yet).
+`./html-preview-wrapper`'s `<HighlightedCode>` lazily `import("shiki")`s at runtime for client-side syntax highlighting. `shiki` is declared as an **optional peerDependency** — install it in your project if you use that subpath:
+
+```sh
+pnpm add shiki
+```
+
+Projects scaffolded by `create-zudo-doc` already include it. If you never render `<HtmlPreview>` / `<HighlightedCode>`, you can omit it.
+
+## ⚠️ HTML preview iframe sandbox — trust assumption
+
+`<HtmlPreview>` / `<HtmlPreviewWrapper>` render their preview inside an `<iframe srcdoc>` whose `sandbox` attribute **defaults** to:
+
+- `allow-scripts allow-same-origin` when the preview contains scripts (a `js` prop or a `<script>` in `head`), or
+- `allow-same-origin` when it does not.
+
+**`allow-scripts` + `allow-same-origin` together effectively void the sandbox** — scripts running inside the preview share the parent page's origin and can reach the parent document. This default is intentional and safe for zudo-doc's own use case, where preview content is **author-trusted** MDX. The `allow-same-origin` token is what lets the component auto-measure the iframe body and sync its height.
+
+If your project renders **semi-trusted or user-submitted** HTML in a preview, override the sandbox with a stricter value via the `sandbox` prop:
+
+```tsx
+// Maximally restrictive — no script execution, opaque origin
+<HtmlPreviewWrapper html={untrustedHtml} sandbox="" height={400} />
+
+// Allow scripts but keep an opaque origin (script can't reach the parent)
+<HtmlPreviewWrapper html={untrustedHtml} sandbox="allow-scripts" height={400} />
+```
+
+**Caveat:** removing `allow-same-origin` gives the iframe an opaque origin, which blocks the parent from reading `iframe.contentDocument`. That **disables auto-height** — always pair a stricter `sandbox` with a fixed `height`. Passing the empty string `""` is honored verbatim (only omitting the prop falls back to the computed default).
+
+## Styling — Tailwind setup for consumers
+
+This package ships **no precompiled CSS** — the component utility classes are inlined in the `dist/` JavaScript, and Tailwind v4 does not scan `node_modules`. Without help, those utilities never make it into your build, so the components render unstyled.
+
+The fix is to import the package's build-generated safelist into your Tailwind CSS entry, right next to your `@import "tailwindcss";`:
+
+```css
+@import "tailwindcss";
+@import "@takazudo/zudo-doc/safelist.css";
+```
+
+`dist/safelist.css` is generated at package build time and contains an `@source inline()` set covering every utility the components use (including arbitrary-value classes like `w-[var(--zd-sidebar-w)]`). It auto-syncs whenever you upgrade the package — no drift, no manual maintenance. Available in `@takazudo/zudo-doc` **>= 0.2.0**.
+
+> **Don't `@source` into `node_modules`.** A glob like `@source "../node_modules/@takazudo/zudo-doc/dist/**"` looks plausible but is unreliable: pnpm surfaces packages via symlinks and Tailwind v4's file scanner does not reliably traverse them, so utilities get intermittently dropped across rebuilds (see zudolab/zudo-doc#1989). Import the package safelist instead.
+
+**Migrating from a pre-0.2.0 workaround?** If you vendored or copied the package `dist/` to get its styles, delete that workaround and replace it with the single `@import "@takazudo/zudo-doc/safelist.css";` line above.
+
+## Dev workflow (in this repo)
+
+This package is published to npm as `@takazudo/zudo-doc` (since `0.2.0`, `latest` tracks the current line). Inside this repo the host site consumes it as a workspace package through its compiled `dist/` — `pnpm dev` at the repo root runs `tsup --watch` so edits under `src/` rebuild automatically; for a one-off rebuild use `pnpm --filter @takazudo/zudo-doc build`.
+
+zfb itself comes from npm (versions pinned in the root `package.json`). To develop against a local zfb checkout, use the temporary `pnpm.overrides` link escape hatch documented in the root `CLAUDE.md` — do not commit the override.

package/dist/doclayout/doc-layout.js

@@ -59,25 +59,31 @@ function DocLayout(props) {
         }
       ),
       afterSidebar,
-      /* @__PURE__ */ jsxs("div", { class: showSidebar ? "lg:ml-[var(--zd-sidebar-w)]" : void 0, children: [
-        /* @__PURE__ */ jsx("div", { class: "flex min-h-[calc(100vh-3.5rem)] justify-center", children: /* @__PURE__ */ jsxs(
-          "div",
-          {
-            class: `flex w-full gap-[clamp(1.5rem,3vw,4rem)] ${showSidebar ? "max-w-[clamp(50rem,75vw,90rem)]" : "max-w-[80rem]"}`,
-            children: [
-              /* @__PURE__ */ jsxs("main", { class: "flex-1 min-w-0 px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl", children: [
-                breadcrumb,
-                afterBreadcrumb,
-                !hideToc && mobileToc,
-                /* @__PURE__ */ jsx("article", { class: "zd-content max-w-none", children: main }),
-                afterContent
-              ] }),
-              showToc && toc
-            ]
-          }
-        ) }),
-        footer
-      ] }),
+      /* @__PURE__ */ jsxs(
+        "div",
+        {
+          class: `zd-sidebar-content-wrapper${showSidebar ? " lg:ml-[var(--zd-sidebar-w)]" : ""}`,
+          children: [
+            /* @__PURE__ */ jsx("div", { class: "flex min-h-[calc(100vh-3.5rem)] justify-center", children: /* @__PURE__ */ jsxs(
+              "div",
+              {
+                class: `zd-doc-content-band flex w-full gap-[clamp(1.5rem,3vw,4rem)] ${showSidebar ? "max-w-[clamp(50rem,75vw,90rem)]" : "max-w-[80rem]"}`,
+                children: [
+                  /* @__PURE__ */ jsxs("main", { class: "flex-1 min-w-0 px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl", children: [
+                    breadcrumb,
+                    afterBreadcrumb,
+                    !hideToc && mobileToc,
+                    /* @__PURE__ */ jsx("article", { class: "zd-content max-w-none", children: main }),
+                    afterContent
+                  ] }),
+                  showToc && toc
+                ]
+              }
+            ) }),
+            footer
+          ]
+        }
+      ),
       bodyEndComponents,
       bodyEndScripts
     ] })

package/dist/header/nav-active.d.ts

@@ -17,17 +17,6 @@ interface NavItemLike {
  *   pathForMatch(null,            "ja", "en") === ""
  */
 declare function pathForMatch(pathWithoutBase: string, lang: string | undefined, defaultLocale: string): string;
-/**
- * Pick the deepest header-nav path that the current page lives under.
- *
- * The legacy template flattens parent + child paths, filters by
- * `pathForMatch.startsWith(p)`, and picks the longest match — this keeps
- * a child link active even when its parent's path is also a prefix of
- * the current page.
- *
- * Returns `undefined` when no nav entry matches; callers should treat
- * that as "no active link."
- */
 declare function computeActiveNavPath(navItems: readonly NavItemLike[], pathForMatchValue: string): string | undefined;
 /**
  * Active-state predicate for a top-level nav item: the item itself, or

package/dist/header/nav-active.js

@@ -1,6 +1,11 @@
 function pathForMatch(pathWithoutBase, lang, defaultLocale) {
   if (lang == null || lang === defaultLocale) return pathWithoutBase;
-  return pathWithoutBase.replace(new RegExp(`^/${lang}`), "");
+  return pathWithoutBase.replace(new RegExp(`^/${lang}(?=/|$)`), "");
+}
+function pathMatchesNavPath(currentPath, navPath) {
+  if (currentPath === navPath) return true;
+  const prefix = navPath.endsWith("/") ? navPath : `${navPath}/`;
+  return currentPath.startsWith(prefix);
 }
 function computeActiveNavPath(navItems, pathForMatchValue) {
   const allNavPaths = navItems.flatMap((item) => {
@@ -10,7 +15,7 @@ function computeActiveNavPath(navItems, pathForMatchValue) {
     }
     return paths;
   });
-  return allNavPaths.filter((p) => pathForMatchValue.startsWith(p)).sort((a, b) => b.length - a.length)[0];
+  return allNavPaths.filter((p) => pathMatchesNavPath(pathForMatchValue, p)).sort((a, b) => b.length - a.length)[0];
 }
 function isNavItemActive(item, activeNavPath) {
   if (activeNavPath === item.path) return true;

package/dist/html-preview-wrapper/html-preview-wrapper.d.ts

@@ -42,6 +42,19 @@ interface HtmlPreviewWrapperProps {
     height?: number;
     /** When true, the code section is expanded by default. */
     defaultOpen?: boolean;
+    /**
+     * iframe `sandbox` attribute value, forwarded to `<HtmlPreview>`. Omit to
+     * use the computed default (`allow-scripts allow-same-origin` when scripts
+     * are present, `allow-same-origin` otherwise).
+     *
+     * ⚠️ The default voids iframe sandboxing (preview scripts can reach the
+     * parent origin) and is only safe for **author-trusted** content.
+     * Downstream consumers rendering semi-trusted HTML should pass a stricter
+     * value (e.g. `"allow-scripts"` or `""`) — but note that dropping
+     * `allow-same-origin` disables auto-height, so pair it with a fixed
+     * `height`. See `HtmlPreviewProps.sandbox` for details.
+     */
+    sandbox?: string;
 }
 /**
  * Bare HTML preview body — the actual island **hydration target**.

package/dist/html-preview-wrapper/html-preview-wrapper.js

@@ -3,7 +3,17 @@ import { jsx } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { HtmlPreview } from "./html-preview.js";
 function HtmlPreviewWrapperInner(props) {
-  const { globalConfig, html, css, head, js, title, height, defaultOpen } = props;
+  const {
+    globalConfig,
+    html,
+    css,
+    head,
+    js,
+    title,
+    height,
+    defaultOpen,
+    sandbox
+  } = props;
   const mergedHead = [globalConfig?.head, head].filter(Boolean).join("\n") || void 0;
   const mergedCss = [globalConfig?.css, css].filter(Boolean).join("\n") || void 0;
   const mergedJs = [globalConfig?.js, js].filter(Boolean).join("\n") || void 0;
@@ -17,6 +27,7 @@ function HtmlPreviewWrapperInner(props) {
       title,
       height,
       defaultOpen,
+      sandbox,
       componentCss: css,
       componentHead: head,
       componentJs: js

package/dist/html-preview-wrapper/html-preview.d.ts

@@ -11,6 +11,27 @@ interface HtmlPreviewProps {
     title?: string;
     height?: number;
     defaultOpen?: boolean;
+    /**
+     * iframe `sandbox` attribute value. When omitted, defaults to the value
+     * computed from the preview content (`allow-scripts allow-same-origin`
+     * when scripts are present, `allow-same-origin` otherwise — see
+     * {@link resolveSandbox}).
+     *
+     * ⚠️ **Trust assumption.** The default keeps `allow-same-origin`, which
+     * combined with `allow-scripts` effectively *voids* the iframe sandbox:
+     * scripts inside the preview can reach the parent document's origin. This
+     * is safe only for **author-trusted** content (e.g. zudo-doc's own
+     * MDX-authored previews). Downstream consumers rendering semi-trusted or
+     * user-submitted HTML should pass a stricter value (e.g. `"allow-scripts"`
+     * or `""`).
+     *
+     * Note: removing `allow-same-origin` breaks the auto-height mechanism
+     * (the parent can no longer read `iframe.contentDocument` to measure the
+     * body), so set a fixed {@link HtmlPreviewProps.height} when you do.
+     * Passing the empty string `""` (maximally restrictive) is honored —
+     * only `undefined` triggers the computed default.
+     */
+    sandbox?: string;
     /** Per-component css for code block display (before global merge) */
     componentCss?: string;
     /** Per-component head for code block display (before global merge) */
@@ -18,6 +39,26 @@ interface HtmlPreviewProps {
     /** Per-component js for code block display (before global merge) */
     componentJs?: string;
 }
+declare function containsScript(head?: string, js?: string): boolean;
+/**
+ * Resolve the iframe `sandbox` attribute value.
+ *
+ * An explicit `sandbox` prop wins (including the empty string `""`, the most
+ * restrictive value — only `undefined` falls through). Otherwise the default
+ * is derived from `hasScripts`:
+ *
+ * - with scripts → `"allow-scripts allow-same-origin"`
+ * - without scripts → `"allow-same-origin"`
+ *
+ * `allow-same-origin` is kept in BOTH defaults on purpose: the parent reads
+ * `iframe.contentDocument` for auto-height measurement, and a srcdoc iframe
+ * sandboxed without `allow-same-origin` gets an opaque origin that blocks
+ * those reads even from the parent page. The combination voids sandboxing
+ * for script-bearing previews — acceptable here because preview content is
+ * author-trusted MDX. See {@link HtmlPreviewProps.sandbox} for the downstream
+ * trust note.
+ */
+declare function resolveSandbox(sandbox: string | undefined, hasScripts: boolean): string;
 /**
  * HTML preview widget — renders an isolated iframe with viewport
  * controls and a collapsible code section.
@@ -30,6 +71,6 @@ interface HtmlPreviewProps {
  * Astro, or wire up the SSR-skip placeholder pattern for non-Astro
  * consumers.
  */
-declare function HtmlPreview({ html, css, head, js, title, height, defaultOpen, componentCss, componentHead, componentJs, }: HtmlPreviewProps): VNode;
+declare function HtmlPreview({ html, css, head, js, title, height, defaultOpen, sandbox, componentCss, componentHead, componentJs, }: HtmlPreviewProps): VNode;
 
-export { HtmlPreview, type HtmlPreviewProps };
+export { HtmlPreview, type HtmlPreviewProps, containsScript, resolveSandbox };

package/dist/html-preview-wrapper/html-preview.js

@@ -8,6 +8,9 @@ function containsScript(head, js) {
   if (head && /<script/i.test(head)) return true;
   return false;
 }
+function resolveSandbox(sandbox, hasScripts) {
+  return sandbox ?? (hasScripts ? "allow-scripts allow-same-origin" : "allow-same-origin");
+}
 function buildSrcdoc(html, css, head, js) {
   return `<!doctype html>
 <html>
@@ -31,6 +34,7 @@ function HtmlPreview({
   title,
   height,
   defaultOpen,
+  sandbox,
   componentCss,
   componentHead,
   componentJs
@@ -41,7 +45,7 @@ function HtmlPreview({
   );
   const hasScripts = containsScript(head, js);
   const syncDelay = hasScripts ? 300 : 0;
-  const sandboxValue = hasScripts ? "allow-scripts allow-same-origin" : "allow-same-origin";
+  const sandboxValue = resolveSandbox(sandbox, hasScripts);
   const codeBlocks = useMemo(
     () => [
       { language: "html", title: "HTML", code: dedent(html) },
@@ -71,5 +75,7 @@ function HtmlPreview({
   );
 }
 export {
-  HtmlPreview
+  HtmlPreview,
+  containsScript,
+  resolveSandbox
 };

package/dist/integrations/claude-resources/generate.js

@@ -19,7 +19,7 @@ function parseFrontmatter(content) {
   }
 }
 function escapeTitle(s) {
-  return s.replace(/"/g, '\\"');
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 function listFiles(dir) {
   if (!fs.existsSync(dir)) return [];
@@ -36,6 +36,25 @@ generated: true
 `;
   fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
 }
+function writeUnlistedSubPage(outputPath, title, slug, body) {
+  fs.writeFileSync(
+    outputPath,
+    `---
+title: "${escapeTitle(title)}"
+slug: "${slug}"
+unlisted: true
+generated: true
+---
+
+${body}
+`
+  );
+}
+function assertNotIndexReserved(nameOrSlug, errorMessage) {
+  if (nameOrSlug === "index") {
+    throw new Error(errorMessage);
+  }
+}
 function findClaudeMdFiles(dir, excludeDirs) {
   const results = [];
   if (!fs.existsSync(dir)) return results;
@@ -92,11 +111,10 @@ function generateClaudemdDocs(config) {
   });
   const emittedSlugs = /* @__PURE__ */ new Map();
   items.forEach((item, index) => {
-    if (item.slug === "index") {
-      throw new Error(
-        `claude-resources: "${item.relPath}" maps to the reserved slug "index", which is used for the category metadata file. Rename the directory to resolve the conflict.`
-      );
-    }
+    assertNotIndexReserved(
+      item.slug,
+      `claude-resources: "${item.relPath}" maps to the reserved slug "index", which is used for the category metadata file. Rename the directory to resolve the conflict.`
+    );
     const previous = emittedSlugs.get(item.slug);
     if (previous !== void 0) {
       throw new Error(
@@ -136,11 +154,10 @@ function generateCommandsDocs(config) {
     const parsed = parseFrontmatter(content);
     if (!parsed) continue;
     const name = file.replace(/\.md$/, "");
-    if (name === "index") {
-      throw new Error(
-        `claude-resources: ".claude/commands/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the command file to resolve the conflict.`
-      );
-    }
+    assertNotIndexReserved(
+      name,
+      `claude-resources: ".claude/commands/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the command file to resolve the conflict.`
+    );
     const description = parsed.data.description || "";
     items.push({ name, description });
     const mdx = `---
@@ -220,11 +237,10 @@ function generateSkillsDocs(config) {
   ensureDir(outputDir);
   const items = [];
   for (const dir of dirs) {
-    if (dir === "index") {
-      throw new Error(
-        `claude-resources: skill directory ".claude/skills/index/" uses the reserved name "index", which is used for the category metadata file. Rename the skill directory to resolve the conflict.`
-      );
-    }
+    assertNotIndexReserved(
+      dir,
+      `claude-resources: skill directory ".claude/skills/index/" uses the reserved name "index", which is used for the category metadata file. Rename the skill directory to resolve the conflict.`
+    );
     const content = fs.readFileSync(
       path.join(skillsDir, dir, "SKILL.md"),
       "utf8"
@@ -284,60 +300,41 @@ ${body}`;
     fs.writeFileSync(path.join(outputDir, `${dir}.mdx`), mdx);
     const skillSlugBase = `claude-skills/${dir}`;
     for (const ref of references) {
-      const subSlug = `${skillSlugBase}/ref-${ref.name}`;
-      const refMdx = `---
-title: "${escapeTitle(ref.title)}"
-slug: "${subSlug}"
-unlisted: true
-generated: true
----
-
-${escapeForMdx(ref.content.trim())}
-`;
-      fs.writeFileSync(path.join(outputDir, `${dir}--ref-${ref.name}.mdx`), refMdx);
+      writeUnlistedSubPage(
+        path.join(outputDir, `${dir}--ref-${ref.name}.mdx`),
+        ref.title,
+        `${skillSlugBase}/ref-${ref.name}`,
+        escapeForMdx(ref.content.trim())
+      );
     }
     for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
       const slug = f.replace(/\.md$/, "");
-      const subSlug = `${skillSlugBase}/script-${slug}`;
       const raw = fs.readFileSync(
         path.join(skillsDir, dir, "scripts", f),
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
       const title = h1Match?.[1] ?? slug;
-      fs.writeFileSync(
+      writeUnlistedSubPage(
         path.join(outputDir, `${dir}--script-${slug}.mdx`),
-        `---
-title: "${escapeTitle(title)}"
-slug: "${subSlug}"
-unlisted: true
-generated: true
----
-
-${escapeForMdx(raw.trim())}
-`
+        title,
+        `${skillSlugBase}/script-${slug}`,
+        escapeForMdx(raw.trim())
       );
     }
     for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
       const slug = f.replace(/\.md$/, "");
-      const subSlug = `${skillSlugBase}/asset-${slug}`;
       const raw = fs.readFileSync(
         path.join(skillsDir, dir, "assets", f),
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
       const title = h1Match?.[1] ?? slug;
-      fs.writeFileSync(
+      writeUnlistedSubPage(
         path.join(outputDir, `${dir}--asset-${slug}.mdx`),
-        `---
-title: "${escapeTitle(title)}"
-slug: "${subSlug}"
-unlisted: true
-generated: true
----
-
-${escapeForMdx(raw.trim())}
-`
+        title,
+        `${skillSlugBase}/asset-${slug}`,
+        escapeForMdx(raw.trim())
       );
     }
   }
@@ -362,11 +359,10 @@ function generateAgentsDocs(config) {
     const description = parsed.data.description || "";
     const model = parsed.data.model || "";
     const fileSlug = file.replace(/\.md$/, "");
-    if (fileSlug === "index") {
-      throw new Error(
-        `claude-resources: ".claude/agents/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the agent file to resolve the conflict.`
-      );
-    }
+    assertNotIndexReserved(
+      fileSlug,
+      `claude-resources: ".claude/agents/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the agent file to resolve the conflict.`
+    );
     items.push({ name, file: fileSlug, description, model });
     const modelBadge = model ? `**Model:** \`${model}\`
 ` : "";

package/dist/integrations/doc-history/pre-build.d.ts

@@ -39,15 +39,23 @@ interface DocHistoryMetaEntry {
     author: string;
     createdDate: string;
     updatedDate: string;
+    /**
+     * Source file extension (".mdx" or ".md") — the content walkers accept
+     * both (`collectContentFiles` matches `\.mdx?$`), so the view-source URL
+     * builder in the host's `_doc-history-area.tsx` reads this instead of
+     * hardcoding ".mdx". Optional in older manifests; readers fall back to
+     * ".mdx" when absent.
+     */
+    ext?: ".mdx" | ".md";
 }
 /** Manifest shape — keyed by composedSlug. */
 type DocHistoryMetaManifest = Record<string, DocHistoryMetaEntry>;
 /**
- * Tiny in-file semaphore for bounded parallelism — avoids a p-limit dependency.
- * Limits concurrent async tasks to `concurrency` at a time.
- * Ported from packages/doc-history-server/src/cli.ts.
+ * Derive the manifest `ext` value from a content file path. The walkers
+ * only collect `.md` / `.mdx` files (`collectContentFiles` matches
+ * `\.mdx?$`), so anything not ending in ".md" is ".mdx".
  */
-declare function makeSemaphore(concurrency: number): () => Promise<() => void>;
+declare function deriveSourceExt(filePath: string): ".mdx" | ".md";
 /**
  * Emit `<projectRoot>/.zfb/doc-history-meta.json` from git history.
  *
@@ -61,4 +69,4 @@ declare function makeSemaphore(concurrency: number): () => Promise<() => void>;
  */
 declare function runDocHistoryMetaStep(options: RunDocHistoryMetaOptions): Promise<void>;
 
-export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, makeSemaphore, runDocHistoryMetaStep };
+export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, deriveSourceExt, runDocHistoryMetaStep };

package/dist/integrations/doc-history/pre-build.js

@@ -1,36 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
-import { cpus } from "node:os";
 import {
   collectContentFiles,
   getFileCommitsMetaAsync
 } from "@takazudo/zudo-doc-history-server/git-history";
+import {
+  makeSemaphore,
+  defaultGitConcurrency
+} from "@takazudo/zudo-doc-history-server/concurrency";
 const META_OUT_RELATIVE_DIR = ".zfb";
 const META_OUT_FILENAME = "doc-history-meta.json";
-function makeSemaphore(concurrency) {
-  let running = 0;
-  const queue = [];
-  function next() {
-    if (queue.length > 0 && running < concurrency) {
-      queue.shift()();
-    }
-  }
-  return function acquire() {
-    return new Promise((resolve) => {
-      function tryRun() {
-        if (running < concurrency) {
-          running++;
-          resolve(() => {
-            running--;
-            next();
-          });
-        } else {
-          queue.push(tryRun);
-        }
-      }
-      tryRun();
-    });
-  };
+function deriveSourceExt(filePath) {
+  return filePath.endsWith(".md") ? ".md" : ".mdx";
 }
 async function runDocHistoryMetaStep(options) {
   const projectRoot = path.resolve(options.projectRoot);
@@ -53,7 +34,7 @@ async function runDocHistoryMetaStep(options) {
       dirEntries.push([code, path.resolve(projectRoot, locale.dir)]);
     }
   }
-  const concurrency = Math.min(8, Math.max(2, cpus().length));
+  const concurrency = defaultGitConcurrency();
   const acquire = makeSemaphore(concurrency);
   const jobs = [];
   for (const [localeKey, contentDir] of dirEntries) {
@@ -90,7 +71,9 @@ async function runDocHistoryMetaStep(options) {
       author: result.oldest.author,
       // createdDate = oldest commit; updatedDate = newest commit.
       createdDate: result.oldest.date,
-      updatedDate: result.newest.date
+      updatedDate: result.newest.date,
+      // Source extension for the view-source URL (".md" walkers accepted).
+      ext: deriveSourceExt(jobs[i].filePath)
     };
   }
   fs.mkdirSync(zfbDir, { recursive: true });
@@ -108,6 +91,6 @@ const defaultLogger = {
   }
 };
 export {
-  makeSemaphore,
+  deriveSourceExt,
   runDocHistoryMetaStep
 };

package/dist/integrations/llms-txt/dev-middleware.d.ts

@@ -1,5 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { LlmsTxtSiteMeta, LlmsTxtLocaleConfig } from './types.js';
+import '../../md-utils/index.js';
 
 /** Connect-style middleware signature — works as a Vite plugin middleware. */
 type LlmsTxtNextFn = (err?: unknown) => void;

package/dist/integrations/llms-txt/emit.d.ts

@@ -1,4 +1,5 @@
 import { LlmsTxtEmitOptions, LlmsTxtEmitResult } from './types.js';
+import '../../md-utils/index.js';
 
 /**
  * Build-time emitter that writes `llms.txt` and `llms-full.txt` for the

package/dist/integrations/llms-txt/generate.d.ts

@@ -1,4 +1,5 @@
 import { LlmsDocEntry, LlmsTxtSiteMeta } from './types.js';
+import '../../md-utils/index.js';
 
 /**
  * Pure string generators for `llms.txt` and `llms-full.txt`.

package/dist/integrations/llms-txt/index.d.ts

@@ -1,7 +1,8 @@
 export { LlmsTxtDevMiddlewareOptions, LlmsTxtMiddleware, LlmsTxtMiddlewareLogger, LlmsTxtNextFn, createLlmsTxtDevMiddleware } from './dev-middleware.js';
 export { emitLlmsTxt } from './emit.js';
 export { generateLlmsFullTxt, generateLlmsTxt } from './generate.js';
-export { collectMdFiles, isExcluded, loadDocEntries, parseMarkdownFile, slugToUrl } from './load.js';
-export { stripImportsAndJsx, stripMarkdown } from './strip.js';
+export { loadDocEntries } from './load.js';
+export { stripImportsAndJsx } from './strip.js';
 export { LlmsDocEntry, LlmsTxtEmitOptions, LlmsTxtEmitResult, LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsTxtLocaleConfig, LlmsTxtLogger, LlmsTxtSiteMeta } from './types.js';
+export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, stripMarkdown } from '../../md-utils/index.js';
 import 'node:http';