@takazudo/zudo-doc 0.2.0-next.5 → 0.2.0-next.7

package/dist/breadcrumb/breadcrumb.js

@@ -6,6 +6,7 @@ function buildBreadcrumbItems(tree, currentId, homeHref) {
   const path = findPath(tree, currentId);
   for (let i = 0; i < path.length; i++) {
     const node = path[i];
+    if (!node) continue;
     const isLast = i === path.length - 1;
     items.push({
       label: node.label,
@@ -20,7 +21,7 @@ function SmartLabel({ label }) {
   const nodes = [];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
-    if (part === "") continue;
+    if (!part) continue;
     nodes.push(part);
     if (i % 2 === 1) nodes.push(/* @__PURE__ */ jsx("wbr", {}, `wbr-${i}`));
   }

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

@@ -3,7 +3,7 @@ function dedent(text) {
   let minIndent = Infinity;
   for (const line of lines) {
     if (line.trim().length === 0) continue;
-    const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+    const indent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
     if (indent < minIndent) minIndent = indent;
   }
   if (minIndent === 0 || minIndent === Infinity) {

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

@@ -44,14 +44,52 @@ interface HtmlPreviewWrapperProps {
     defaultOpen?: boolean;
 }
 /**
- * HTML preview wrapper component.
+ * Bare HTML preview body — the actual island **hydration target**.
  *
- * Merges `settings.htmlPreview` (global config) with per-usage props and
- * forwards everything to `<HtmlPreview>`. Wraps it in
- * `<Island when="visible">`, mirroring the legacy `client:visible`
- * hydration timing — the iframe is heavy and not on the critical path,
- * so we defer hydration until the preview enters the viewport.
+ * Merges global (`settings.htmlPreview`) config with per-usage props and
+ * forwards everything to `<HtmlPreview>`. Renders the preview tree
+ * **directly**: it does NOT wrap itself in `<Island>`. `HtmlPreviewWrapper`
+ * below applies the `<Island when="visible">` wrapper around it.
+ *
+ * ## Island invariant (read before touching the displayName / Island wiring)
+ *
+ * The hydration-target export's NAME must equal its `displayName` (which
+ * becomes the `data-zfb-island="…"` marker), AND that export must NOT itself
+ * render an `<Island>`. The zfb scanner resolves the client hydration
+ * component by marker-name → export-name lookup; if the resolved export
+ * re-wraps in `Island()`, the client re-emits a second `data-zfb-island`
+ * wrapper and Preact reuses the SSR'd children one level off — re-parenting
+ * the preview + code sections inside the flex title bar (the broken
+ * side-by-side layout). This is the same class of bug fixed for
+ * Toc / MobileToc / Sidebar in zudolab/zudo-doc#1355 and was the original
+ * defect here (zudolab/zudo-doc#1925, an Astro→zfb migration regression):
+ * the inner bare component carried the *outer* wrapper's name
+ * (`displayName = "HtmlPreviewWrapper"`) and was not exported, so the marker
+ * resolved to the exported self-wrapping `HtmlPreviewWrapper` and the client
+ * double-wrapped. Fix: the bare component carries its OWN name
+ * (`HtmlPreviewWrapperInner`) and is exported, so the marker resolves to
+ * THIS bare component and the bundle hydrates it in-place.
+ */
+declare function HtmlPreviewWrapperInner(props: HtmlPreviewWrapperProps): VNode;
+declare namespace HtmlPreviewWrapperInner {
+    var displayName: string;
+}
+/**
+ * HTML preview wrapper component — the public MDX-registered binding
+ * (`HtmlPreview: HtmlPreviewWrapper`).
+ *
+ * Wraps the bare `HtmlPreviewWrapperInner` in `<Island when="visible">`,
+ * mirroring the legacy `client:visible` hydration timing — the iframe is
+ * heavy and not on the critical path, so hydration is deferred until the
+ * preview enters the viewport. The SSG output emits
+ * `data-zfb-island="HtmlPreviewWrapperInner"` around the bare tree, and the
+ * client bundle hydrates `HtmlPreviewWrapperInner` against it in-place.
+ *
+ * The public export name and signature are unchanged from before the
+ * zudolab/zudo-doc#1925 fix, so existing consumers that register
+ * `HtmlPreview: HtmlPreviewWrapper` keep working (and now hydrate correctly)
+ * with no call-site change.
  */
 declare function HtmlPreviewWrapper(props: HtmlPreviewWrapperProps): VNode;
 
-export { type HtmlPreviewGlobalConfig, HtmlPreviewWrapper, type HtmlPreviewWrapperProps };
+export { type HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperInner, type HtmlPreviewWrapperProps };

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

@@ -23,7 +23,7 @@ function HtmlPreviewWrapperInner(props) {
     }
   );
 }
-HtmlPreviewWrapperInner.displayName = "HtmlPreviewWrapper";
+HtmlPreviewWrapperInner.displayName = "HtmlPreviewWrapperInner";
 function HtmlPreviewWrapper(props) {
   const rendered = Island({
     when: "visible",
@@ -32,5 +32,6 @@ function HtmlPreviewWrapper(props) {
   return rendered;
 }
 export {
-  HtmlPreviewWrapper
+  HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner
 };

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

@@ -1,4 +1,4 @@
-export { HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperProps } from './html-preview-wrapper.js';
+export { HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperInner, HtmlPreviewWrapperProps } from './html-preview-wrapper.js';
 export { HtmlPreview, HtmlPreviewProps } from './html-preview.js';
 export { CodeBlockData, PreviewBase, PreviewBaseProps } from './preview-base.js';
 export { HighlightedCode, HighlightedCodeProps } from './highlighted-code.js';

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

@@ -1,5 +1,6 @@
 import {
-  HtmlPreviewWrapper
+  HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner
 } from "./html-preview-wrapper.js";
 import { HtmlPreview } from "./html-preview.js";
 import { PreviewBase } from "./preview-base.js";
@@ -8,5 +9,6 @@ export {
   HighlightedCode,
   HtmlPreview,
   HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner,
   PreviewBase
 };

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

@@ -53,7 +53,7 @@ function PreviewBase({
     const id = setTimeout(syncHeight, 150);
     return () => clearTimeout(id);
   }, [activeViewport, syncHeight, height]);
-  const containerWidth = VIEWPORTS[activeViewport].width;
+  const containerWidth = VIEWPORTS[activeViewport]?.width ?? "100%";
   return /* @__PURE__ */ jsxs("div", { class: "border border-muted rounded-lg overflow-hidden my-vsp-md", children: [
     /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-between px-hsp-md py-hsp-sm bg-surface border-b border-muted gap-hsp-sm flex-wrap", children: [
       title && /* @__PURE__ */ jsx("span", { class: "text-caption font-semibold text-fg", children: title }),

package/dist/integrations/claude-resources/escape-for-mdx.js

@@ -121,7 +121,7 @@ function escapeForMdx(content) {
     ).replace(/<(-+|=+)/g, "&lt;$1").replace(/<(\d)/g, "&lt;$1").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;");
     escaped = escaped.replace(
       new RegExp(`${inlinePlaceholder}(\\d+)\0`, "g"),
-      (_, idx) => inlineCodes[Number(idx)]
+      (_, idx) => inlineCodes[Number(idx)] ?? ""
     );
     return escaped;
   }).join("");

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

@@ -153,6 +153,7 @@ function getSkillFileTree(skillDir, subDirs) {
   }
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
+    if (!entry) continue;
     const isLast = i === entries.length - 1;
     const prefix = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
     if (!entry.isDir) {
@@ -161,6 +162,7 @@ function getSkillFileTree(skillDir, subDirs) {
       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 ? "    " : "\u2502   ";
         const childPrefix = childIsLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
@@ -173,7 +175,8 @@ function getSkillFileTree(skillDir, subDirs) {
 function getScriptDescription(filePath) {
   try {
     const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
-    const commentLine = topLines[0].startsWith("#!") ? topLines[1] || "" : topLines[0];
+    const firstLine = topLines[0] ?? "";
+    const commentLine = firstLine.startsWith("#!") ? topLines[1] ?? "" : firstLine;
     const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
     return match ? ` \u2014 ${match[1]}` : "";
   } catch {
@@ -187,7 +190,7 @@ function getSkillReferences(skillsDir, skillDir) {
     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));
 }
@@ -283,7 +286,7 @@ ${escapeForMdx(ref.content.trim())}
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       fs.writeFileSync(
         path.join(outputDir, `${dir}--script-${slug}.mdx`),
         `---
@@ -305,7 +308,7 @@ ${escapeForMdx(raw.trim())}
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       fs.writeFileSync(
         path.join(outputDir, `${dir}--asset-${slug}.mdx`),
         `---

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

@@ -42,6 +42,12 @@ interface DocHistoryMetaEntry {
 }
 /** 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.
+ */
+declare function makeSemaphore(concurrency: number): () => Promise<() => void>;
 /**
  * Emit `<projectRoot>/.zfb/doc-history-meta.json` from git history.
  *
@@ -55,4 +61,4 @@ type DocHistoryMetaManifest = Record<string, DocHistoryMetaEntry>;
  */
 declare function runDocHistoryMetaStep(options: RunDocHistoryMetaOptions): Promise<void>;
 
-export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, runDocHistoryMetaStep };
+export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, makeSemaphore, runDocHistoryMetaStep };

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

@@ -1,11 +1,37 @@
 import fs from "node:fs";
 import path from "node:path";
+import { cpus } from "node:os";
 import {
   collectContentFiles,
-  getFileCommitsMeta
+  getFileCommitsMetaAsync
 } from "@takazudo/zudo-doc-history-server/git-history";
 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();
+    });
+  };
+}
 async function runDocHistoryMetaStep(options) {
   const projectRoot = path.resolve(options.projectRoot);
   const zfbDir = path.join(projectRoot, META_OUT_RELATIVE_DIR);
@@ -27,24 +53,46 @@ async function runDocHistoryMetaStep(options) {
       dirEntries.push([code, path.resolve(projectRoot, locale.dir)]);
     }
   }
-  const meta = {};
+  const concurrency = Math.min(8, Math.max(2, cpus().length));
+  const acquire = makeSemaphore(concurrency);
+  const jobs = [];
   for (const [localeKey, contentDir] of dirEntries) {
     const files = collectContentFiles(contentDir);
     for (const { filePath, slug } of files) {
-      const allCommits = getFileCommitsMeta(filePath);
-      if (allCommits.length === 0) continue;
-      const newestInfo = allCommits[0];
-      const oldestInfo = allCommits[allCommits.length - 1] ?? newestInfo;
       const composedSlug = localeKey ? `${localeKey}/${slug}` : slug;
-      meta[composedSlug] = {
-        // Author comes from the FIRST (oldest) commit.
-        author: oldestInfo.author,
-        // createdDate = oldest commit; updatedDate = newest commit.
-        createdDate: oldestInfo.date,
-        updatedDate: newestInfo.date
-      };
+      jobs.push({ composedSlug, filePath });
     }
   }
+  const results = new Array(jobs.length).fill(null);
+  await Promise.all(
+    jobs.map(async ({ filePath }, i) => {
+      const release = await acquire();
+      try {
+        const allCommits = await getFileCommitsMetaAsync(filePath);
+        if (allCommits.length === 0) return;
+        const newestInfo = allCommits[0];
+        const oldestInfo = allCommits[allCommits.length - 1] ?? newestInfo;
+        results[i] = {
+          newest: { author: newestInfo.author, date: newestInfo.date },
+          oldest: { author: oldestInfo.author, date: oldestInfo.date }
+        };
+      } finally {
+        release();
+      }
+    })
+  );
+  const meta = {};
+  for (let i = 0; i < jobs.length; i++) {
+    const result = results[i];
+    if (result == null) continue;
+    meta[jobs[i].composedSlug] = {
+      // Author comes from the FIRST (oldest) commit.
+      author: result.oldest.author,
+      // createdDate = oldest commit; updatedDate = newest commit.
+      createdDate: result.oldest.date,
+      updatedDate: result.newest.date
+    };
+  }
   fs.mkdirSync(zfbDir, { recursive: true });
   fs.writeFileSync(outPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
   logger.info(
@@ -60,5 +108,6 @@ const defaultLogger = {
   }
 };
 export {
+  makeSemaphore,
   runDocHistoryMetaStep
 };

package/dist/integrations/llms-txt/dev-middleware.js

@@ -53,7 +53,7 @@ function createLlmsTxtDevMiddleware(options, logger) {
   };
 }
 function matchLlmsRoute(url, localeCodes) {
-  const pathname = url.split("?")[0];
+  const pathname = url.split("?")[0] ?? url;
   const m = pathname.match(LLMS_KIND_PATTERN);
   if (!m) return null;
   const prefix = m[1];

package/dist/toc/smart-break.js

@@ -20,7 +20,7 @@ function smartBreak(text) {
   const nodes = [];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
-    if (part === "") continue;
+    if (!part) continue;
     nodes.push(part);
     if (i % 2 === 1) nodes.push(/* @__PURE__ */ jsx("wbr", {}, `wbr-${i}`));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "0.2.0-next.5",
+  "version": "0.2.0-next.7",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -158,10 +158,10 @@
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.31",
-    "@takazudo/zfb-runtime": "^0.1.0-next.31",
+    "@takazudo/zfb": "^0.1.0-next.35",
+    "@takazudo/zfb-runtime": "^0.1.0-next.35",
     "@takazudo/zdtp": "^0.2.0-next.2",
-    "@takazudo/zudo-doc-history-server": "^0.2.0-next.5"
+    "@takazudo/zudo-doc-history-server": "^0.2.0-next.7"
   },
   "peerDependenciesMeta": {
     "@takazudo/zudo-doc-history-server": {
@@ -182,8 +182,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0",
-    "@takazudo/zfb": "0.1.0-next.31",
-    "@takazudo/zfb-runtime": "0.1.0-next.31"
+    "@takazudo/zfb": "0.1.0-next.35",
+    "@takazudo/zfb-runtime": "0.1.0-next.35"
   },
   "scripts": {
     "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 tsup",