create-zudo-doc 0.2.0 → 0.2.2

package/templates/features/claudeResources/files/plugins/claude-resources-plugin.mjs

@@ -1,135 +1,45 @@
+// @ts-check
 // zfb plugin module: claude-resources.
 //
 // Wires `runClaudeResourcesPreStep` (from
 // `@takazudo/zudo-doc/integrations/claude-resources`) into zfb's
-// `preBuild` lifecycle hook. Replaces the npm `prebuild`-script glue
-// in `scripts/zfb-prebuild.mjs` for this step (the script remains in
-// place during the merge window — T6 retires it).
+// `preBuild` lifecycle hook.
 //
-// Why this shim exists (and is not the v2 integration module directly):
-//
-//   1. zfb's plugin host runs `node` without any TypeScript loader, so
-//      it cannot import `.ts` source files. The v2 integration package
-//      (`@takazudo/zudo-doc/integrations/claude-resources`) currently
-//      ships only TypeScript source through its `exports` map and has
-//      no build step.
-//
-//   2. The `runClaudeResourcesPreStep` runner pulls in `gray-matter`,
-//      which performs a CJS `require("fs")` that esbuild's
-//      configuration-loader bundle (ESM-only) cannot satisfy. Loading
-//      it inline at the top of `zfb.config.ts` therefore breaks config
-//      parsing entirely.
-//
-// Both problems are solved by isolating the runner behind a child
-// process: this shim spawns `tsx` (the project's existing TS-aware
-// Node runner, pinned via `tsx` in `package.json`) on a tiny inline
-// script that imports the runner. tsx handles `.ts` resolution and
-// Node's CJS↔ESM interop for gray-matter; the parent plugin host stays
-// in plain Node and only sees a child-process exit code.
-//
-// Inline functions are not supported by zfb's plugin runtime — see
-// `@takazudo/zfb/plugins` source comment. This file is the plugin-host
-// equivalent once the npm script is retired (T6).
-
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
+// Previously this shim spawned a `tsx` subprocess because the integration
+// package shipped only TypeScript source (no build step) and `gray-matter`
+// pulled in a CJS `require("fs")` that esbuild's ESM-only config-loader
+// bundle could not satisfy. Both constraints are now lifted: the package
+// ships compiled `dist/` and the plugin host is plain Node (not an esbuild
+// bundle), so the runner can be imported directly.
 
-// `tsx` is a workspace dependency of the host project and resolves to
-// `<projectRoot>/node_modules/.bin/tsx` from this file. We resolve the
-// binary explicitly so the shim does not depend on the parent shell's
-// `PATH` (the plugin host is spawned by zfb without sourcing the
-// user's profile — Node's `PATH` is whatever zfb itself was launched
-// with).
-const HERE = dirname(fileURLToPath(import.meta.url));
-const TSX_BIN = resolve(HERE, "..", "node_modules", ".bin", "tsx");
+/** @import { ZfbBuildHookContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
 
-/**
- * Run the v2 claude-resources runner under tsx.
- *
- * Inlines a minimal ESM script via `tsx -e` so we don't have to ship a
- * second `.ts` file just to host the call site. The runner returns a
- * `{ claudemd, commands, skills, agents }` summary which we re-emit on
- * the child's stdout — the parent (this shim) parses it and forwards
- * the summary to the plugin host's logger.
- */
-function runRunnerUnderTsx({ claudeDir, projectRoot, docsDir }) {
-  // The runner accepts `projectRoot` and `docsDir` as relative paths
-  // (resolved against `process.cwd()` in the runner). To insulate the
-  // child from whatever cwd zfb spawned us with, we set cwd explicitly
-  // and pass absolute paths through.
-  // tsx's `-e` flag emits CJS by default (it picks the format from the
-  // entry's extension, and an inline `-e` script has none), so we wrap
-  // the body in an `async`-IIFE rather than relying on top-level await.
-  const childScript = `
-    (async () => {
-      const { runClaudeResourcesPreStep } = await import("@takazudo/zudo-doc/integrations/claude-resources");
-      const result = await runClaudeResourcesPreStep({
-        claudeDir: ${JSON.stringify(claudeDir)},
-        projectRoot: ${JSON.stringify(projectRoot)},
-        docsDir: ${JSON.stringify(docsDir)},
-      });
-      process.stdout.write(JSON.stringify(result));
-    })().catch((err) => {
-      process.stderr.write(err && err.stack ? err.stack : String(err));
-      process.exit(1);
-    });
-  `;
+import { runClaudeResourcesPreStep } from "@takazudo/zudo-doc/integrations/claude-resources";
 
-  return new Promise((resolveCall, reject) => {
-    const child = spawn(TSX_BIN, ["-e", childScript], {
-      cwd: projectRoot,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
-    child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
-    child.on("error", reject);
-    child.on("close", (code) => {
-      if (code !== 0) {
-        reject(
-          new Error(
-            `[${PLUGIN_NAME}] runner exited with code ${code}\n${stderr}`,
-          ),
-        );
-        return;
-      }
-      try {
-        resolveCall(JSON.parse(stdout));
-      } catch (err) {
-        reject(
-          new Error(
-            `[${PLUGIN_NAME}] failed to parse runner stdout: ${err.message}\nstdout: ${stdout}\nstderr: ${stderr}`,
-          ),
-        );
-      }
-    });
-  });
-}
+const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
 
+/** @type {ZfbPlugin} */
 export default {
   name: PLUGIN_NAME,
+
+  /** @param {ZfbBuildHookContext} ctx */
   async preBuild(ctx) {
-    const claudeDir = ctx.options.claudeDir;
+    const claudeDir = ctx.options["claudeDir"];
     if (typeof claudeDir !== "string" || claudeDir.length === 0) {
       throw new Error(
         `[${PLUGIN_NAME}] preBuild: options.claudeDir must be a non-empty string (got ${JSON.stringify(claudeDir)})`,
       );
     }
-    const projectRootOpt = ctx.options.projectRoot;
-    const docsDirOpt = ctx.options.docsDir;
-    const result = await runRunnerUnderTsx({
+    const projectRootOpt = ctx.options["projectRoot"];
+    const docsDirOpt = ctx.options["docsDir"];
+    const result = await runClaudeResourcesPreStep({
       claudeDir,
       projectRoot:
         typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
       docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs",
     });
-    // Surface a one-line summary so build logs make the migration
-    // observable (mirrors the `[zfb-prebuild]` lines from the legacy
-    // npm-script glue).
+    // Surface a one-line summary so build logs make the generation
+    // observable.
     ctx.logger.info(
       `claude-resources: ${result.claudemd} CLAUDE.md, ${result.commands} commands, ${result.skills} skills, ${result.agents} agents`,
     );

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

@@ -64,7 +64,9 @@ function parseFrontmatter(content: string) {
 }
 
 function escapeTitle(s: string): string {
-  return s.replace(/"/g, '\\"');
+  // Backslashes must be escaped first — the value is embedded in
+  // double-quoted YAML frontmatter where `\d` or `C:\path` is invalid.
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 
 function listFiles(dir: string): string[] {
@@ -93,6 +95,35 @@ generated: true
   fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
 }
 
+/**
+ * Writes an unlisted sub-page MDX file (flat file with a custom nested slug).
+ * Used for skill references, scripts, and assets.
+ */
+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`,
+  );
+}
+
+/**
+ * Guards that the given name/slug is not the reserved "index" value.
+ * Throws with a contextual message if it is.
+ */
+function assertNotIndexReserved(
+  nameOrSlug: string,
+  errorMessage: string,
+) {
+  if (nameOrSlug === "index") {
+    throw new Error(errorMessage);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // CLAUDE.md discovery
 // ---------------------------------------------------------------------------
@@ -176,11 +207,10 @@ function generateClaudemdDocs(
 
   const emittedSlugs = new Map<string, string>();
   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 !== undefined) {
       throw new Error(
@@ -232,11 +262,10 @@ function generateCommandsDocs(config: ClaudeResourcesConfig): CommandItem[] {
     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 as string) || "";
 
     items.push({ name, description });
@@ -357,11 +386,10 @@ function generateSkillsDocs(config: ClaudeResourcesConfig): SkillItem[] {
   const items: SkillItem[] = [];
 
   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",
@@ -445,46 +473,43 @@ ${body}`;
     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 ? h1Match[1] : slug;
-      fs.writeFileSync(
+      writeUnlistedSubPage(
         path.join(outputDir, `${dir}--script-${slug}.mdx`),
-        `---\ntitle: "${escapeTitle(title)}"\nslug: "${subSlug}"\nunlisted: true\ngenerated: true\n---\n\n${escapeForMdx(raw.trim())}\n`,
+        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 ? h1Match[1] : slug;
-      fs.writeFileSync(
+      writeUnlistedSubPage(
         path.join(outputDir, `${dir}--asset-${slug}.mdx`),
-        `---\ntitle: "${escapeTitle(title)}"\nslug: "${subSlug}"\nunlisted: true\ngenerated: true\n---\n\n${escapeForMdx(raw.trim())}\n`,
+        title,
+        `${skillSlugBase}/asset-${slug}`,
+        escapeForMdx(raw.trim()),
       );
     }
   }
@@ -522,11 +547,10 @@ function generateAgentsDocs(config: ClaudeResourcesConfig): AgentItem[] {
     const description = (parsed.data.description as string) || "";
     const model = (parsed.data.model as string) || "";
     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 });
 

package/templates/features/designTokenPanel/files/src/config/design-token-panel-config.ts

@@ -6,11 +6,12 @@
  *
  * Type notes:
  * - zdtp's `ColorScheme` requires a `shikiTheme: string` field that is not
- *   present in zudo-doc's local `ColorScheme` type or data. The cast below
- *   (`as unknown as Record<string, ZdtpColorScheme>`) is intentional: zdtp
- *   uses `shikiTheme` only for the code-block preview inside the panel; when
- *   absent at runtime it falls back to `colorExtras.defaultShikiTheme`. No
- *   user-visible regression results from the missing field.
+ *   present in this project's local `ColorScheme` type or data (zdtp uses it
+ *   only for the panel's client-side code-block preview). Rather than an unsafe
+ *   `as unknown as Record<string, ZdtpColorScheme>` double-cast, every local
+ *   scheme map is run through `toZdtpColorSchemes()` below, which supplies
+ *   `DEFAULT_SHIKI_THEME` as the fallback so the result satisfies zdtp's
+ *   required-field shape with an ordinary type-checked assignment.
  */
 
 import type {
@@ -28,6 +29,7 @@ import {
   SIZE_TOKENS,
 } from "./design-tokens-manifest";
 import { colorSchemes } from "./color-schemes";
+import type { ColorScheme as LocalColorScheme } from "./color-schemes";
 import { SEMANTIC_DEFAULTS, SEMANTIC_CSS_NAMES } from "./color-scheme-utils";
 import { settings } from "./settings";
 import { DESIGN_TOKEN_SCHEMA } from "@takazudo/zudo-doc/theme";
@@ -49,6 +51,30 @@ const BASE_DEFAULTS = {
  */
 const DEFAULT_SHIKI_THEME = "github-dark";
 
+/**
+ * Normalize this project's local `ColorScheme` records into zdtp's
+ * `ColorScheme` shape. zdtp's type requires `shikiTheme: string`; the local
+ * scheme type makes it optional. This helper fills `DEFAULT_SHIKI_THEME` only
+ * when a scheme doesn't declare its own, so the result is assignable to
+ * `Record<string, ZdtpColorScheme>` via an ordinary type-checked assignment —
+ * replacing the previous `as unknown as` double-cast that bypassed every field
+ * check. Tracked upstream at Takazudo/zudo-design-token-panel#342 (shikiTheme
+ * should be optional in zdtp's `ColorScheme` type); drop this helper once that
+ * lands.
+ */
+function toZdtpColorSchemes(
+  schemes: Record<string, LocalColorScheme>,
+): Record<string, ZdtpColorScheme> {
+  const normalized: Record<string, ZdtpColorScheme> = {};
+  for (const [name, scheme] of Object.entries(schemes)) {
+    normalized[name] = {
+      ...scheme,
+      shikiTheme: scheme.shikiTheme ?? DEFAULT_SHIKI_THEME,
+    };
+  }
+  return normalized;
+}
+
 /**
  * Initial palette taken from the configured active scheme.
  */
@@ -178,9 +204,9 @@ const COLOR_EXTRAS: ColorClusterExtras = {
   },
   baseDefaults: BASE_DEFAULTS,
   defaultShikiTheme: DEFAULT_SHIKI_THEME,
-  // Local ColorScheme lacks shikiTheme; cast is safe — zdtp falls back to
-  // defaultShikiTheme when shikiTheme is absent at runtime.
-  colorSchemes: colorSchemes as unknown as Record<string, ZdtpColorScheme>,
+  // toZdtpColorSchemes fills the fallback only for schemes without their own
+  // shikiTheme, so this is a type-checked assignment rather than an unsafe cast.
+  colorSchemes: toZdtpColorSchemes(colorSchemes),
   panelSettings: {
     colorScheme: settings.colorScheme,
     // colorMode: strip off respectPrefersColorScheme (not in zdtp's shape).

package/templates/features/docHistory/files/plugins/doc-history-plugin.mjs

@@ -1,12 +1,12 @@
+// @ts-check
 // zfb plugin module: doc-history.
 //
 // Wires three lifecycle hooks for the doc-history integration:
 //
 //   preBuild  — emits `.zfb/doc-history-meta.json` (per-page git metadata
-//               consumed at bundle time). Uses the tsx-e shim because the
-//               runner imports Node-only modules (`fs`, `child_process`) and
-//               TypeScript source that the plain-Node plugin host cannot load
-//               directly. Honours `SKIP_DOC_HISTORY=1` via `env: process.env`.
+//               consumed at bundle time). Calls `runDocHistoryMetaStep`
+//               directly; honours `SKIP_DOC_HISTORY=1` via the runner's
+//               own env check.
 //
 //   postBuild — invokes `runDocHistoryPostBuild` to write
 //               `<outDir>/doc-history/<slug>.json` files. Skipped by default
@@ -20,69 +20,45 @@
 // Inline functions are not supported by zfb's plugin runtime — see
 // `@takazudo/zfb/plugins` source comment. Plugins must be authored as
 // standalone modules and referenced from `zfb.config.ts` by `name`.
-//
-// The legacy `scripts/zfb-{pre,post}build.mjs` npm-script glue and
-// `scripts/dev-sidecar.mjs` stay in place during the merge window;
-// T6 retires them once all lifecycle epics land.
 
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+/** @import { ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
 
+import { runDocHistoryMetaStep } from "@takazudo/zudo-doc/integrations/doc-history";
 import { runDocHistoryPostBuild } from "@takazudo/zudo-doc/integrations/doc-history";
 import { createDocHistoryDevMiddleware } from "@takazudo/zudo-doc/integrations/doc-history";
 import { connectToZfbHandler } from "./connect-adapter.mjs";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-// tsx is a workspace dep; resolving the binary explicitly avoids PATH
-// dependency — the plugin host is spawned by zfb without the user's shell profile.
-const TSX_BIN = resolve(HERE, "..", "node_modules", ".bin", "tsx");
-
+/** @type {ZfbPlugin} */
 export default {
   name: "doc-history",
 
+  /** @param {ZfbBuildHookContext} ctx */
   async preBuild(ctx) {
     const { docsDir, locales } = ctx.options;
-    // Serialize options as JSON for the tsx-e inline script. The runner
-    // (`runDocHistoryMetaStep`) honours SKIP_DOC_HISTORY=1 internally;
-    // passing `env: process.env` propagates the flag to the child process.
-    const optsJson = JSON.stringify({
+    await runDocHistoryMetaStep({
       projectRoot: ctx.projectRoot,
       docsDir: typeof docsDir === "string" ? docsDir : "src/content/docs",
-      locales: locales ?? {},
-    });
-    const script = `
-      (async () => {
-        const { runDocHistoryMetaStep } = await import("@takazudo/zudo-doc/integrations/doc-history");
-        const opts = ${optsJson};
-        await runDocHistoryMetaStep(opts);
-      })().catch((err) => {
-        process.stderr.write(err && err.stack ? err.stack : String(err));
-        process.exit(1);
-      });
-    `;
-    const result = spawnSync(TSX_BIN, ["-e", script], {
-      cwd: ctx.projectRoot,
-      stdio: "inherit",
-      env: process.env,
+      locales:
+        locales != null
+          ? /** @type {Record<string,{dir:string}>} */ (locales)
+          : undefined,
     });
-    if (result.status !== 0) {
-      throw new Error(
-        `doc-history-meta preBuild failed (exit ${result.status})`,
-      );
-    }
   },
 
+  /** @param {ZfbBuildHookContext} ctx */
   async postBuild(ctx) {
-    const { docsDir, locales } = ctx.options;
     await runDocHistoryPostBuild(
-      { docsDir, locales },
+      /** @type {import("@takazudo/zudo-doc/integrations/doc-history").DocHistoryOptions} */ (/** @type {unknown} */ (ctx.options)),
       { outDir: ctx.outDir, logger: ctx.logger },
     );
   },
 
+  /** @param {ZfbDevMiddlewareContext} ctx */
   devMiddleware(ctx) {
-    const middleware = createDocHistoryDevMiddleware(ctx.options, ctx.logger);
+    const middleware = createDocHistoryDevMiddleware(
+      /** @type {import("@takazudo/zudo-doc/integrations/doc-history").DocHistoryOptions} */ (/** @type {unknown} */ (ctx.options)),
+      ctx.logger,
+    );
     // zfb's `register(path, handler)` matches against the FULL request
     // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
     // requests arrive as `/my-docs/doc-history/foo.json`, so we register
@@ -90,11 +66,17 @@ export default {
     // and the route is `/doc-history` as expected. The v2 middleware
     // itself is base-tolerant (matches via `url.includes("/doc-history/")`)
     // and slices from `/doc-history/` onward when proxying upstream.
-    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    const basePrefix = stripTrailingSlash(
+      typeof ctx.options["base"] === "string" ? ctx.options["base"] : "",
+    );
     ctx.register(`${basePrefix}/doc-history`, connectToZfbHandler(middleware));
   },
 };
 
+/**
+ * @param {string} s
+ * @returns {string}
+ */
 function stripTrailingSlash(s) {
   if (typeof s !== "string" || s.length === 0) return "";
   return s.endsWith("/") ? s.slice(0, -1) : s;

package/templates/features/docHistory/files/src/components/doc-history.tsx

@@ -1,5 +1,7 @@
+"use client";
+
 import { useState, useEffect, useCallback, useMemo, useRef } from "preact/compat";
-import { diffLines } from "diff";
+import type { Change } from "diff";
 import type { DocHistoryData, DocHistoryEntry } from "@/types/doc-history";
 import { SmartBreak } from "@/utils/smart-break";
 
@@ -104,8 +106,10 @@ interface DiffRow {
   type: "context" | "removed" | "added" | "changed";
 }
 
+type DiffChanges = Change[];
+
 function buildSideBySideRows(
-  changes: ReturnType<typeof diffLines>,
+  changes: DiffChanges,
 ): DiffRow[] {
   const rows: DiffRow[] = [];
   let leftNum = 0;
@@ -177,11 +181,24 @@ function DiffViewer({
   onBack: () => void;
   showBackButton: boolean;
 }) {
-  const changes = useMemo(
-    () => diffLines(selection.older.content, selection.newer.content),
-    [selection.older.content, selection.newer.content],
+  const [changes, setChanges] = useState<DiffChanges | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    // Lazy-load diff — only needed after History → Compare. This keeps the
+    // module out of the eager islands bundle.
+    import("diff").then(({ diffLines }) => {
+      if (!cancelled) {
+        setChanges(diffLines(selection.older.content, selection.newer.content));
+      }
+    });
+    return () => { cancelled = true; };
+  }, [selection.older.content, selection.newer.content]);
+
+  const rows = useMemo(
+    () => (changes ? buildSideBySideRows(changes) : []),
+    [changes],
   );
-  const rows = useMemo(() => buildSideBySideRows(changes), [changes]);
 
   return (
     <div className="flex flex-col h-full">
@@ -207,8 +224,13 @@ function DiffViewer({
         </div>
       </div>
 
-      {/* Side-by-side diff */}
-      <div className="flex-1 overflow-auto">
+      {/* Side-by-side diff — shows a loading state while the diff module lazy-loads */}
+      {!changes && (
+        <div className="flex-1 flex items-center justify-center py-vsp-xl">
+          <p className="text-small text-muted">Loading diff…</p>
+        </div>
+      )}
+      <div className={`flex-1 overflow-auto${!changes ? " hidden" : ""}`}>
         <table className="w-full border-collapse" style={{ tableLayout: "fixed" }}>
           <colgroup>
             <col style={{ width: "2.5rem" }} />