@docubook/flame 2.0.0-beta.1 → 2.0.0-beta.3

package/.docu/lib/utils-DA17MyQG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils-DA17MyQG.js","names":[],"sources":["../node/security.ts","../node/utils.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport { resolve } from \"node:path\";\nimport { realpathSync } from \"node:fs\";\n\nexport const SECURITY_HEADERS: Record<string, string> = {\n  \"Strict-Transport-Security\": \"max-age=63072000; includeSubDomains; preload\",\n  \"X-Frame-Options\": \"DENY\",\n  \"X-Content-Type-Options\": \"nosniff\",\n  \"Referrer-Policy\": \"strict-origin-when-cross-origin\",\n  \"Permissions-Policy\": \"camera=(), microphone=(), geolocation=()\",\n};\n\nexport function generateNonce(): string {\n  return randomBytes(16).toString(\"base64\");\n}\n\nexport function cspHeader(nonce: string, allowEval = false): string {\n  const scriptSrc = allowEval\n    ? `script-src 'self' 'nonce-${nonce}' 'unsafe-eval'`\n    : `script-src 'self' 'nonce-${nonce}'`;\n  return [\n    \"default-src 'self'\",\n    scriptSrc,\n    \"style-src 'self' 'unsafe-inline'\",\n    \"img-src 'self' https: data:\",\n    \"font-src 'self' data:\",\n    \"connect-src 'self' https:\",\n    \"frame-src https://www.youtube-nocookie.com\",\n    \"frame-ancestors 'none'\",\n  ].join(\"; \");\n}\n\nexport function isPathSafe(pathname: string, baseDir: string): boolean {\n  const decoded = decodeURIComponent(pathname);\n  const resolved = resolve(baseDir, decoded.slice(1));\n  const baseDirSlash = baseDir.endsWith(\"/\") ? baseDir : baseDir + \"/\";\n  if (!(resolved === baseDir || resolved.startsWith(baseDirSlash))) {\n    return false;\n  }\n\n  if (resolved === baseDir) return true;\n  try {\n    const real = realpathSync(resolved);\n    const realBase = realpathSync(baseDir);\n    const realBaseDirSlash = realBase.endsWith(\"/\") ? realBase : realBase + \"/\";\n    return real.startsWith(realBaseDirSlash);\n  } catch (err) {\n    const nodeErr = err as NodeJS.ErrnoException;\n    if (nodeErr.code === \"ENOENT\") {\n      return true;\n    }\n    console.error(\n      `[security] isPathSafe error for pathname=\"${pathname}\": ${nodeErr.message} (code=${nodeErr.code})`\n    );\n    return false;\n  }\n}\n\nexport function isSlugSafe(slug: string, docsDir: string): boolean {\n  const resolved = resolve(docsDir, slug);\n  const docsDirSlash = docsDir.endsWith(\"/\") ? docsDir : docsDir + \"/\";\n  if (!(resolved === docsDir || resolved.startsWith(docsDirSlash))) {\n    return false;\n  }\n\n  if (resolved === docsDir) return true;\n  try {\n    const real = realpathSync(resolved);\n    const realDocsDir = realpathSync(docsDir);\n    const realDocsDirSlash = realDocsDir.endsWith(\"/\") ? realDocsDir : realDocsDir + \"/\";\n    return real.startsWith(realDocsDirSlash);\n  } catch (err) {\n    const nodeErr = err as NodeJS.ErrnoException;\n    if (nodeErr.code === \"ENOENT\") {\n      return true;\n    }\n    console.error(\n      `[security] isSlugSafe error for slug=\"${slug}\": ${nodeErr.message} (code=${nodeErr.code})`\n    );\n    return false;\n  }\n}\n\n/** Normalize an esbuild importer path to a canonical forward-slash absolute form. */\nexport function normalizeImporterPath(importer: string): string {\n  return resolve(importer).replace(/\\\\/g, \"/\");\n}\n\nexport function injectNonce(html: string, nonce: string): string {\n  return html.replace(/<script\\b(?![^>]*\\bsrc\\s*=)([^>]*)>/gi, (match) => {\n    if (/nonce\\s*=/i.test(match)) {\n      return match.replace(/nonce=\"[^\"]*\"/i, `nonce=\"${nonce}\"`);\n    }\n    return match.replace(/>$/, ` nonce=\"${nonce}\">`);\n  });\n}\n\nexport interface PluginResponseLike {\n  status: number;\n  statusText?: string;\n  headers: Headers;\n  body: BodyInit | null;\n}\n\n/**\n * Wrap a plugin response with security headers.\n * - Fills in SECURITY_HEADERS defaults where plugin hasn't set a value\n * - Adds Content-Security-Policy for HTML responses (with optional unsafe-eval)\n * - Preserves plugin body, status, statusText unchanged\n */\nexport function wrapPluginResponse(\n  pluginResponse: PluginResponseLike,\n  allowEval = false\n): Response {\n  const securedHeaders = new Headers(pluginResponse.headers);\n  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {\n    if (!securedHeaders.has(key)) {\n      securedHeaders.set(key, value);\n    }\n  }\n  let body = pluginResponse.body;\n  const contentType = securedHeaders.get(\"Content-Type\") || \"\";\n  if (contentType.includes(\"text/html\") && !securedHeaders.has(\"Content-Security-Policy\")) {\n    const nonce = generateNonce();\n    securedHeaders.set(\"Content-Security-Policy\", cspHeader(nonce, allowEval));\n    if (typeof body === \"string\") {\n      body = injectNonce(body, nonce);\n    }\n  }\n  return new Response(body, {\n    status: pluginResponse.status,\n    statusText: pluginResponse.statusText,\n    headers: securedHeaders,\n  });\n}\n\nexport function htmlResponse(\n  html: string,\n  nonce: string,\n  status = 200,\n  allowEval = false\n): Response {\n  return new Response(html, {\n    status,\n    headers: {\n      \"Content-Type\": \"text/html\",\n      ...SECURITY_HEADERS,\n      \"Content-Security-Policy\": cspHeader(nonce, allowEval),\n    },\n  });\n}\n","export { cn, parseDate, formatDate, formatDate2 } from \"@docubook/core\";\n\nimport { readdir, stat } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nexport interface ScannedMdxFile {\n  path: string;\n  absPath: string;\n  mtime: number;\n}\n\n/**\n * Scan a directory recursively for MDX/MD files.\n * Skips \"assets\" directories, hidden directories (dot-prefixed), and root-level index.mdx.\n * Shared between build.ts and search-indexer.ts.\n */\nexport async function scanMdxFiles(dir: string, baseDir = \"\"): Promise<ScannedMdxFile[]> {\n  const files: ScannedMdxFile[] = [];\n  const entries = await readdir(dir, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const fullPath = join(dir, entry.name);\n    const relativePath = baseDir ? `${baseDir}/${entry.name}` : entry.name;\n\n    if (entry.isDirectory()) {\n      if (entry.name === \"assets\" || entry.name.startsWith(\".\")) continue;\n      files.push(...(await scanMdxFiles(fullPath, relativePath)));\n    } else if (entry.name.endsWith(\".mdx\") || entry.name.endsWith(\".md\")) {\n      if (entry.name === \"index.mdx\" && !baseDir) continue;\n      const stats = await stat(fullPath);\n      let path = relativePath.replace(/\\.(mdx|md)$/, \"\");\n\n      if (/\\/index$/.test(path)) {\n        path = path.replace(/\\/index$/, \"\");\n      }\n      files.push({ path, absPath: fullPath, mtime: stats.mtimeMs });\n    }\n  }\n\n  return files;\n}\n\nexport function isExternalUrl(url: string): boolean {\n  return /^(https?:\\/\\/|\\/\\/)/.test(url);\n}\n\n/** Suffix an internal docs link with `.html` to match the flat static build output. */\nexport function docsHtmlHref(path: string): string {\n  return `${path}.html`;\n}\n\n/** Map a `/docs{.html,/*.html}` request back to its extensionless route (dev server).\n *  Handles both `/docs/*.html` (pages) and `/docs.html` (edge case). */\nexport function stripDocsHtmlSuffix(pathname: string): string {\n  if (pathname === \"/docs.html\") return \"/docs\";\n  if (pathname.startsWith(\"/docs/\") && pathname.endsWith(\".html\"))\n    return pathname.slice(0, -\".html\".length);\n  return pathname;\n}\n\nexport function getPath(url: string): string {\n  try {\n    return new URL(url).pathname;\n  } catch (err) {\n    console.error(\"Failed to parse URL\", url, err);\n    return url;\n  }\n}\n\n/** Get git last modified date for a file */\nexport async function getGitLastModified(filePath: string): Promise<string | null> {\n  try {\n    const cleanPath = filePath.replace(/^\\//, \"\");\n    if (\n      !cleanPath ||\n      !/^[a-zA-Z0-9\\-_/.\\s]+$/.test(cleanPath) ||\n      /(^|\\/)\\.\\.($|\\/)/.test(cleanPath)\n    )\n      return null;\n    const proc = Bun.spawn([\"git\", \"log\", \"-1\", \"--format=%cI\", \"--\", cleanPath], {\n      stderr: \"ignore\",\n    });\n    const text = await new Response(proc.stdout).text();\n    const date = text.trim();\n    return date || null;\n  } catch (err) {\n    console.error(\"Failed to get git last modified for\", filePath, err);\n    return null;\n  }\n}\n\n/** Batch git last modified dates for multiple files in a single spawn */\nexport async function getGitLastModifiedBatch(filePaths: string[]): Promise<Map<string, string>> {\n  const result = new Map<string, string>();\n  if (filePaths.length === 0) return result;\n\n  // Filter and validate paths — same guard as getGitLastModified\n  const safePaths: string[] = [];\n  for (const fp of filePaths) {\n    const cleanPath = fp.replace(/^\\//, \"\");\n    if (\n      !cleanPath ||\n      !/^[a-zA-Z0-9\\-_/.\\s]+$/.test(cleanPath) ||\n      /(^|\\/)\\.\\.($|\\/)/.test(cleanPath)\n    ) {\n      console.warn(`[utils] getGitLastModifiedBatch: skipping invalid path \"${fp}\"`);\n      continue;\n    }\n    safePaths.push(cleanPath);\n  }\n\n  if (safePaths.length === 0) return result;\n\n  try {\n    const proc = Bun.spawn(\n      [\"git\", \"log\", \"--format=%cI\", \"--name-only\", \"--diff-filter=ACMR\", ...safePaths],\n      { stderr: \"ignore\" }\n    );\n    const text = await new Response(proc.stdout).text();\n    let currentDate = \"\";\n\n    for (const line of text.split(\"\\n\")) {\n      const trimmed = line.trim();\n      if (!trimmed) continue;\n      if (/^\\d{4}-\\d{2}-\\d{2}T/.test(trimmed)) {\n        currentDate = trimmed;\n      } else if (currentDate && !result.has(trimmed)) {\n        result.set(trimmed, currentDate);\n      }\n    }\n  } catch (err) {\n    console.error(\"Failed to get git last modified batch for\", filePaths, err);\n  }\n\n  return result;\n}\n\nconst MIME_TYPES: Record<string, string> = {\n  html: \"text/html\",\n  css: \"text/css\",\n  js: \"application/javascript\",\n  json: \"application/json\",\n  png: \"image/png\",\n  jpg: \"image/jpeg\",\n  jpeg: \"image/jpeg\",\n  svg: \"image/svg+xml\",\n  ico: \"image/x-icon\",\n  woff: \"font/woff\",\n  woff2: \"font/woff2\",\n};\n\nexport function getContentType(pathname: string): string {\n  const ext = pathname.split(\".\").pop()?.toLowerCase();\n  return MIME_TYPES[ext || \"\"] || \"application/octet-stream\";\n}\n"],"mappings":"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"}

package/.docu/node/build.impl.ts

@@ -6,7 +6,7 @@
  * The Node/Deno build entries call `runBuildCli()`.
  */
 
-import { readFile, writeFile, mkdir, readdir, copyFile } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, copyFile, rename, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
@@ -39,7 +39,16 @@ import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { scanMdxFiles } from "./utils";
-import type { BuildCache, CliArgs } from "./types";
+import type { BuildCache, BuildCacheMeta, CliArgs } from "./types";
+import { isCacheEntry } from "./types";
+import {
+  BUILD_CACHE_VERSION,
+  atomicWriteFile,
+  hashMdxSources,
+  hookMemoryPressure,
+  runtimeStamp,
+} from "./cache-key";
+import { clearDerivedPageCaches } from "./mdx";
 import { generateNonce, cspHeader } from "./security";
 import type { PageMeta, PageContext } from "./plugin";
 import { buildSeoMeta } from "./seo";
@@ -64,7 +73,12 @@ async function readCache(): Promise<BuildCache> {
   try {
     if (existsSync(CACHE_FILE)) {
       const data = await readFile(CACHE_FILE, "utf-8");
-      return JSON.parse(data);
+      const parsed = JSON.parse(data) as BuildCache;
+      const meta = parsed.__meta__ as BuildCacheMeta | undefined;
+      if (!meta || meta.version !== BUILD_CACHE_VERSION || meta.runtime !== runtimeStamp()) {
+        return {};
+      }
+      return parsed;
     }
   } catch (err) {
     console.error("Failed to load build cache:", (err as Error).message);
@@ -72,8 +86,19 @@ async function readCache(): Promise<BuildCache> {
   return {};
 }
 
+function stampCache(cache: BuildCache): void {
+  cache.__meta__ = {
+    hash: `${BUILD_CACHE_VERSION}:${runtimeStamp()}`,
+    mtime: 0,
+    builtAt: Date.now(),
+    version: BUILD_CACHE_VERSION,
+    runtime: runtimeStamp(),
+  };
+}
+
 async function writeCache(cache: BuildCache): Promise<void> {
-  await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2));
+  stampCache(cache);
+  await atomicWriteFile(writeFile, rename, unlink, CACHE_FILE, JSON.stringify(cache, null, 2));
 }
 
 function parseConcurrency(): number {
@@ -84,13 +109,38 @@ type RebuildDecision = "yes" | "hash_check" | "no";
 
 function shouldRebuild(path: string, mtime: number, cache: BuildCache): RebuildDecision {
   const cached = cache[path];
-  if (!cached) return "yes";
-  if (mtime > cached.builtAt) return "hash_check";
+  if (!isCacheEntry(cached)) return "yes";
+  if (mtime > cached.builtAt + 2000) return "hash_check";
+  if (Math.abs(mtime - cached.builtAt) <= 2000 && mtime !== cached.mtime) return "hash_check";
+  if (mtime !== cached.mtime && mtime > cached.mtime) return "hash_check";
   return "no";
 }
 
 let assetManifest = { js: "client.js", css: "client.css" };
 
+/**
+ * Reuse manifest.json on bundle cache hit; fall back to a full rebuild
+ * when the manifest is missing or malformed.
+ */
+async function resolveAssetManifest(
+  bundleHit: boolean,
+  mdxSources: Record<string, string>
+): Promise<{ js: string; css: string }> {
+  if (!bundleHit) return buildClientBundle(mdxSources);
+  try {
+    const manifest = JSON.parse(await readFile(join(ASSETS_DIR, "manifest.json"), "utf-8")) as {
+      js?: string;
+      css?: string;
+    };
+    if (typeof manifest.js === "string" && typeof manifest.css === "string") {
+      return { js: manifest.js, css: manifest.css };
+    }
+  } catch {
+    // corrupt/missing manifest — rebuild below
+  }
+  return buildClientBundle(mdxSources);
+}
+
 let inlineThemeCss: string | undefined;
 
 async function renderDocsPage(
@@ -180,7 +230,7 @@ async function renderDocsPage(
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
   // MDX content hydrates from the bundled ESM module (mdx-hydrate), not
   // new Function — no 'unsafe-eval' needed in the CSP.
-  const csp = cspHeader(nonce);
+  const csp = nonce ? cspHeader(nonce) : undefined;
   let html = htmlShell({
     title,
     description,
@@ -223,6 +273,8 @@ export async function runBuild(): Promise<void> {
   const docuConfig = loadDocuConfig();
   const args = parseArgs();
 
+  hookMemoryPressure(clearDerivedPageCaches);
+
   logger.buildStart();
 
   if (args.clean) {
@@ -311,14 +363,20 @@ export async function runBuild(): Promise<void> {
 
   logger.bundleStart();
   let t = performance.now();
-  assetManifest = await buildClientBundle(mdxSources);
+  const bundleHash = hashMdxSources(mdxSources);
+  const lastBundle = cache["__bundle__"];
+  const bundleHit =
+    isCacheEntry(lastBundle) &&
+    lastBundle.hash === bundleHash &&
+    existsSync(join(ASSETS_DIR, "manifest.json"));
+  assetManifest = await resolveAssetManifest(bundleHit, mdxSources);
   logger.bundleDone(Math.round(performance.now() - t));
 
   inlineThemeCss = computeInlineThemeCss();
 
   const lastManifest = cache["__assets__"];
   const assetsChanged =
-    !lastManifest || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;
+    !isCacheEntry(lastManifest) || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;
   if (assetsChanged) {
     cache["__assets__"] = {
       hash: `${assetManifest.js}:${assetManifest.css}`,
@@ -326,6 +384,9 @@ export async function runBuild(): Promise<void> {
       builtAt: Date.now(),
     };
   }
+  if (!bundleHit) {
+    cache["__bundle__"] = { hash: bundleHash, mtime: 0, builtAt: Date.now() };
+  }
 
   logger.spinner.start("Building pages...");
   t = performance.now();
@@ -366,7 +427,7 @@ export async function runBuild(): Promise<void> {
     if (rebuildDecision === "hash_check") {
       const contentHash = hashContent(rawMdx);
       const cached = cache[file.path];
-      if (cached && cached.hash === contentHash) {
+      if (isCacheEntry(cached) && cached.hash === contentHash) {
         if (!assetsChanged) {
           const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
           if (existsSync(outputPath)) {
@@ -438,7 +499,11 @@ export async function runBuild(): Promise<void> {
 
   const landingPage = React.createElement(IndexPage);
   const landingFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
-  const landingSeo = buildSeoMeta(docuConfig, docuConfig.meta as Record<string, unknown>, "");
+  const landingSeo = buildSeoMeta(
+    docuConfig,
+    docuConfig.meta as unknown as Record<string, unknown>,
+    ""
+  );
   const landingNonce = generateNonce();
   const landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",

package/.docu/node/build.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir, readdir, copyFile } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, copyFile, rename, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
@@ -31,7 +31,16 @@ import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
 import { scanMdxFiles } from "./utils";
-import type { BuildCache, CliArgs } from "./types";
+import type { BuildCache, BuildCacheMeta, CliArgs } from "./types";
+import { isCacheEntry } from "./types";
+import {
+  BUILD_CACHE_VERSION,
+  atomicWriteFile,
+  hashMdxSources,
+  hookMemoryPressure,
+  runtimeStamp,
+} from "./cache-key";
+import { clearDerivedPageCaches } from "./mdx";
 import { generateNonce } from "./security";
 import type { PageMeta, PageContext } from "./plugin";
 import { buildSeoMeta } from "./seo";
@@ -58,7 +67,15 @@ async function readCache(): Promise<BuildCache> {
   try {
     if (existsSync(CACHE_FILE)) {
       const data = await readFile(CACHE_FILE, "utf-8");
-      return JSON.parse(data);
+      const parsed = JSON.parse(data) as BuildCache;
+      // Toolchain upgrade (Bun 1.3 → 1.4, Tailwind CLI bump) changes build
+      // output without changing page content — a stale cache would false-hit.
+      // Discard when the version stamp or runtime fingerprint mismatches.
+      const meta = parsed.__meta__ as BuildCacheMeta | undefined;
+      if (!meta || meta.version !== BUILD_CACHE_VERSION || meta.runtime !== runtimeStamp()) {
+        return {};
+      }
+      return parsed;
     }
   } catch (err) {
     console.error("Failed to load build cache:", (err as Error).message);
@@ -66,8 +83,21 @@ async function readCache(): Promise<BuildCache> {
   return {};
 }
 
+/** Stamp the cache with the current toolchain fingerprint. */
+function stampCache(cache: BuildCache): void {
+  cache.__meta__ = {
+    hash: `${BUILD_CACHE_VERSION}:${runtimeStamp()}`,
+    mtime: 0,
+    builtAt: Date.now(),
+    version: BUILD_CACHE_VERSION,
+    runtime: runtimeStamp(),
+  };
+}
+
 async function writeCache(cache: BuildCache): Promise<void> {
-  await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2));
+  stampCache(cache);
+  // Atomic tmp+rename: a crash mid-write never leaves a corrupt cache file.
+  await atomicWriteFile(writeFile, rename, unlink, CACHE_FILE, JSON.stringify(cache, null, 2));
 }
 
 export function parseConcurrency(): number {
@@ -78,13 +108,41 @@ type RebuildDecision = "yes" | "hash_check" | "no";
 
 export function shouldRebuild(path: string, mtime: number, cache: BuildCache): RebuildDecision {
   const cached = cache[path];
-  if (!cached) return "yes";
-  if (mtime > cached.builtAt) return "hash_check";
+  if (!isCacheEntry(cached)) return "yes";
+  // 2s tolerance: mtimeMs (float, fs precision) vs builtAt (int, Date.now())
+  // can miss on fast rebuilds after Bun 1.4's 2x faster startup — equality
+  // within tolerance still falls through to the hash check, never to "no".
+  if (mtime > cached.builtAt + 2000) return "hash_check";
+  if (Math.abs(mtime - cached.builtAt) <= 2000 && mtime !== cached.mtime) return "hash_check";
+  if (mtime !== cached.mtime && mtime > cached.mtime) return "hash_check";
   return "no";
 }
 
 let assetManifest = { js: "client.js", css: "client.css" };
 
+/**
+ * Reuse manifest.json on bundle cache hit; fall back to a full rebuild
+ * when the manifest is missing or malformed.
+ */
+async function resolveAssetManifest(
+  bundleHit: boolean,
+  mdxSources: Record<string, string>
+): Promise<{ js: string; css: string }> {
+  if (!bundleHit) return buildClientBundle(mdxSources);
+  try {
+    const manifest = JSON.parse(await readFile(join(ASSETS_DIR, "manifest.json"), "utf-8")) as {
+      js?: string;
+      css?: string;
+    };
+    if (typeof manifest.js === "string" && typeof manifest.css === "string") {
+      return { js: manifest.js, css: manifest.css };
+    }
+  } catch {
+    // corrupt/missing manifest — rebuild below
+  }
+  return buildClientBundle(mdxSources);
+}
+
 let inlineThemeCss: string | undefined;
 
 async function renderDocsPage(
@@ -211,6 +269,10 @@ async function copyDirectoryRecursive(src: string, dest: string): Promise<void>
 async function build() {
   const args = parseArgs();
 
+  // Bun 1.4 `process.on("memoryPressure")`: drop parsed page maps when the
+  // OS runs low on memory (long CI builds). No-op on older runtimes.
+  hookMemoryPressure(clearDerivedPageCaches);
+
   logger.buildStart();
 
   if (args.clean) {
@@ -299,14 +361,23 @@ async function build() {
 
   logger.bundleStart();
   let t = performance.now();
-  assetManifest = await buildClientBundle(mdxSources);
+  // Skip the JS bundle when compiled MDX sources are unchanged: the bundle
+  // is shared by every page, so its hash doubles as the content fingerprint.
+  // CSS still builds via its own content-keyed cache inside the hydrator.
+  const bundleHash = hashMdxSources(mdxSources);
+  const lastBundle = cache["__bundle__"];
+  const bundleHit =
+    isCacheEntry(lastBundle) &&
+    lastBundle.hash === bundleHash &&
+    existsSync(join(ASSETS_DIR, "manifest.json"));
+  assetManifest = await resolveAssetManifest(bundleHit, mdxSources);
   logger.bundleDone(Math.round(performance.now() - t));
 
   inlineThemeCss = computeInlineThemeCss();
 
   const lastManifest = cache["__assets__"];
   const assetsChanged =
-    !lastManifest || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;
+    !isCacheEntry(lastManifest) || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;
   if (assetsChanged) {
     cache["__assets__"] = {
       hash: `${assetManifest.js}:${assetManifest.css}`,
@@ -314,6 +385,9 @@ async function build() {
       builtAt: Date.now(),
     };
   }
+  if (!bundleHit) {
+    cache["__bundle__"] = { hash: bundleHash, mtime: 0, builtAt: Date.now() };
+  }
 
   logger.spinner.start("Building pages...");
   t = performance.now();
@@ -354,7 +428,7 @@ async function build() {
     if (rebuildDecision === "hash_check") {
       const contentHash = hashContent(rawMdx);
       const cached = cache[file.path];
-      if (cached && cached.hash === contentHash) {
+      if (isCacheEntry(cached) && cached.hash === contentHash) {
         if (!assetsChanged) {
           const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
           if (existsSync(outputPath)) {

package/.docu/node/cache-key.ts

@@ -0,0 +1,311 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { FRAMEWORK_ROOT, STYLES_DIR, resolveProjectFile } from "./paths";
+
+/**
+ * Build cache version — bump when the toolchain output contract changes
+ * (e.g. Bun.build barrel optimization, Tailwind CLI upgrade). Old caches
+ * with a mismatched version are discarded on read (see build.ts readCache).
+ */
+export const BUILD_CACHE_VERSION = 3;
+
+/** Toolchain fingerprint: Bun version on Bun, Deno version on Deno, Node elsewhere. */
+export function runtimeStamp(): string {
+  const g = globalThis as Record<string, unknown>;
+  const bun = g.Bun as { version?: string } | undefined;
+  if (typeof bun?.version === "string" && bun.version.length > 0) return `bun-${bun.version}`;
+  const deno = g.Deno as { version?: { deno?: string } } | undefined;
+  if (typeof deno?.version?.deno === "string" && deno.version.deno.length > 0)
+    return `deno-${deno.version.deno}`;
+  const proc = g.process as { version?: string } | undefined;
+  if (typeof proc?.version === "string" && proc.version.length > 0) return `node-${proc.version}`;
+  return "node-unknown";
+}
+
+/**
+ * True when a CSS file can change Tailwind v4 output.
+ * v4 is CSS-first: `@theme`, `@source`, `@plugin`, `@custom-variant`,
+ * `@utility`, `@config`, `@apply`/`@variant`, and `@import "tailwindcss"`
+ * all live in CSS. Plain CSS without these cannot affect the CLI output,
+ * so it is excluded to avoid false cache busts. Broad match deliberate:
+ * false positive busts safe, false negative serves stale CSS.
+ */
+export function isTailwindRelevantCss(content: string): boolean {
+  return (
+    content.includes("@theme") ||
+    content.includes("@source") ||
+    content.includes("@plugin") ||
+    content.includes("@custom-variant") ||
+    content.includes("@utility") ||
+    content.includes("@config") ||
+    content.includes("@apply") ||
+    content.includes("@variant") ||
+    content.includes("@layer") ||
+    content.includes("tailwindcss")
+  );
+}
+
+const IMPORT_RE = /@import\s+(?:url\()?["']([^"']+)["']/g;
+const MAX_IMPORT_DEPTH = 10;
+
+/** Resolve `./` + `../` imports only — bare specifiers are version-pinned deps. */
+function resolveRelativeImport(spec: string, fromDir: string): string | undefined {
+  if (!spec.startsWith(".")) return undefined;
+  const clean = spec.split("?")[0]!.split("#")[0]!;
+  if (clean.length === 0) return undefined;
+  return join(fromDir, clean);
+}
+
+/**
+ * Read a CSS file plus transitively imported relative files.
+ * Non-relevant files contribute "" themselves, but their imports are still
+ * followed (nested file may carry `@theme`). `visited` breaks import cycles.
+ * Missing/unreadable files resolve to "" — never throws.
+ */
+function readCssWithImports(path: string, visited: Set<string>, depth = 0): string {
+  if (depth > MAX_IMPORT_DEPTH || visited.has(path)) return "";
+  visited.add(path);
+  let content = "";
+  try {
+    if (!existsSync(path)) return "";
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+  let out = isTailwindRelevantCss(content) ? content : "";
+  try {
+    const dir = join(path, "..");
+    for (const m of content.matchAll(IMPORT_RE)) {
+      const resolved = resolveRelativeImport(m[1] ?? "", dir);
+      if (resolved) out += readCssWithImports(resolved, visited, depth + 1);
+    }
+  } catch {
+    // import scan failed — keep what we have
+  }
+  return out;
+}
+
+function scanCssDir(dir: string, visited: Set<string>): string {
+  let out = "";
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "assets" || e.name.startsWith(".") || e.name === "node_modules") continue;
+        out += scanCssDir(full, visited);
+      } else if (e.name.endsWith(".css")) {
+        out += readCssWithImports(full, visited);
+      }
+    }
+  } catch {
+    // docs/ missing — nothing to add
+  }
+  return out;
+}
+
+function scanRootCss(root: string, visited: Set<string>): string {
+  let out = "";
+  try {
+    const entries = readdirSync(root, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isFile() && e.name.endsWith(".css")) {
+        out += readCssWithImports(join(root, e.name), visited);
+      }
+    }
+  } catch {
+    // unreadable root — proceed without
+  }
+  return out;
+}
+
+/** Hash @theme/@source/@plugin-bearing CSS in project docs/ + root *.css. */
+function tailwindCssThemeInputs(root: string): string {
+  const visited = new Set<string>();
+  return scanCssDir(join(root, "docs"), visited) + scanRootCss(root, visited);
+}
+
+const TAILWIND_CONFIG_FILES = [
+  "tailwind.config.ts",
+  "tailwind.config.js",
+  "tailwind.config.mjs",
+  "tailwind.config.cjs",
+  "tailwind.config.mts",
+  "tailwind.config.cts",
+  "postcss.config.js",
+  "postcss.config.mjs",
+  "postcss.config.cjs",
+];
+
+/**
+ * JS config still affects v4 when referenced via `@config`
+ * (plus PostCSS pipeline config). Content hashed when present.
+ */
+function tailwindJsConfigInputs(root: string): string {
+  let out = "";
+  for (const name of TAILWIND_CONFIG_FILES) {
+    try {
+      const p = join(root, name);
+      if (existsSync(p)) out += readFileSync(p, "utf-8") + "\0";
+    } catch {
+      // unreadable config — skip
+    }
+  }
+  return out;
+}
+
+function readInstalledVersion(pkg: string, roots: string[]): string {
+  for (const root of roots) {
+    try {
+      const p = join(root, "node_modules", ...pkg.split("/"), "package.json");
+      if (existsSync(p)) {
+        const parsed = JSON.parse(readFileSync(p, "utf-8")) as { version?: string };
+        if (typeof parsed.version === "string" && parsed.version.length > 0) return parsed.version;
+      }
+    } catch {
+      // try next root
+    }
+  }
+  return "";
+}
+
+/** Pin resolved CSS-affecting deps into the key (installed version wins). */
+function tailwindVersionPins(root: string): string {
+  const names = ["tailwindcss", "@tailwindcss/cli", "@tailwindcss/typography", "daisyui"] as const;
+  let extra = "";
+  const roots = [root, FRAMEWORK_ROOT];
+  for (const name of names) {
+    const installed = readInstalledVersion(name, roots);
+    if (installed) extra += `${name}@${installed}\0`;
+  }
+  try {
+    const pkgPath = join(root, "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      for (const name of names) {
+        const range = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? "";
+        if (range) extra += `${name}:${range}\0`;
+      }
+    }
+  } catch {
+    // package.json unreadable — proceed without version pin
+  }
+  return extra;
+}
+
+/**
+ * Extra Tailwind inputs beyond globals.css + theme.
+ * v4 is CSS-first: user overrides live in `@theme`/`@source`/`@plugin`
+ * blocks inside CSS files under the project root (e.g. docs slash star dot css),
+ * plus JS config referenced via `@config` and installed plugin versions.
+ * Missing files resolve to "" — never throws.
+ */
+export function tailwindExtraInputs(root: string = resolveProjectFile()): string {
+  return (
+    tailwindCssThemeInputs(root) + "\0" + tailwindJsConfigInputs(root) + tailwindVersionPins(root)
+  );
+}
+
+/**
+ * Shared Tailwind cache key: globals.css + theme + tailwind config +
+ * toolchain version. Used by both hydrate.ts (Bun) and hydrate.node.ts
+ * (Vite) so the two runtimes agree on filenames. Segments joined with NUL
+ * so `("ab","c")` and `("a","bc")` hash differently.
+ */
+export function computeTailwindCacheKey(
+  globals: string,
+  themeSuffix: string,
+  projectRoot: string = resolveProjectFile()
+): string {
+  const h = createHash("sha256");
+  h.update(globals);
+  h.update("\0");
+  h.update(themeSuffix);
+  h.update("\0");
+  h.update(tailwindExtraInputs(projectRoot));
+  h.update("\0");
+  h.update(runtimeStamp());
+  h.update("\0");
+  h.update(`v${BUILD_CACHE_VERSION}`);
+  return h.digest("hex").slice(0, 16);
+}
+
+/** Read globals.css content ("" when missing). Shared by both hydrators. */
+export function readGlobalsCss(): string {
+  const globalsPath = join(STYLES_DIR, "globals.css");
+  return existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+}
+
+/**
+ * Atomic file write: tmp + rename so a crash mid-write never leaves a
+ * half-written cache/CSS behind. Tmp name includes pid so parallel
+ * builds (`bun run --parallel`) do not clobber each other.
+ */
+export async function atomicWriteFile(
+  writeFile: (p: string, data: string | Uint8Array) => Promise<void>,
+  rename: (from: string, to: string) => Promise<void>,
+  unlink: (p: string) => Promise<void>,
+  target: string,
+  data: string | Uint8Array
+): Promise<void> {
+  const g = globalThis as Record<string, unknown>;
+  const proc = g.process as { pid?: number } | undefined;
+  const pid = typeof proc?.pid === "number" ? proc.pid : Math.floor(Math.random() * 1e9);
+  const tmp = `${target}.tmp-${pid}-${Date.now()}`;
+  try {
+    await writeFile(tmp, data);
+    await rename(tmp, target);
+  } catch (err) {
+    try {
+      await unlink(tmp);
+    } catch {
+      // best-effort tmp cleanup
+    }
+    throw err;
+  }
+}
+
+/** Wire memory-pressure hook once: OS low-memory → drop parsed page maps. */
+let memoryPressureHooked = false;
+export function hookMemoryPressure(clear: () => void): void {
+  if (memoryPressureHooked) return;
+  memoryPressureHooked = true;
+  try {
+    const g = globalThis as Record<string, unknown>;
+    const proc = g.process as
+      | {
+          on?: (event: string, listener: (level: string) => void) => void;
+        }
+      | undefined;
+    proc?.on?.("memoryPressure", () => {
+      try {
+        clear();
+      } catch {
+        // never throw out of a pressure handler
+      }
+    });
+  } catch {
+    // runtimes without the event (Node < Bun 1.4 backport) — no-op
+  }
+}
+
+/**
+ * Hash of compiled MDX module sources (sorted keys + content).
+ * Used to skip the JS bundle rebuild when no page content changed.
+ */
+export function hashMdxSources(mdxSources: Record<string, string>): string {
+  const h = createHash("sha256");
+  const slugs = Object.keys(mdxSources).sort();
+  h.update(`v${BUILD_CACHE_VERSION}:${runtimeStamp()}:`);
+  for (const slug of slugs) {
+    h.update(slug);
+    h.update("\0");
+    h.update(mdxSources[slug]);
+    h.update("\0");
+  }
+  return h.digest("hex").slice(0, 16);
+}