@docubook/flame 2.0.0-beta.2 → 2.0.0-beta.4

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 = 4;
+
+/** 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);
+}

package/.docu/node/html.shared.ts

@@ -7,6 +7,7 @@
  */
 
 import { escapeHtml } from "./escapeHtml";
+import { cspMeta } from "./security";
 
 import type { SeoMeta } from "./seo";
 
@@ -86,7 +87,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${escapeHtml(resolvePath(favicon))}">` : ""}${themeStyle}
   <link rel="preload" href="${escapeHtml(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${escapeHtml(assetPrefix + css)}">
-  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">` : ""}
+  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(cspMeta(csp))}">` : ""}
   ${seoTags}
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>

package/.docu/node/html.ts

@@ -1,5 +1,6 @@
 import type { HtmlShellOptions } from "./html.shared";
 export type { HtmlShellOptions };
+import { cspMeta } from "./security";
 
 export function htmlShell(opts: HtmlShellOptions): string {
   const {
@@ -48,7 +49,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(resolvePath(favicon))}">` : ""}${themeStyle}
   <link rel="preload" href="${Bun.escapeHTML(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${Bun.escapeHTML(assetPrefix + css)}">
-  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(csp)}">` : ""}
+  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(cspMeta(csp))}">` : ""}
   ${seoTags}
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>

package/.docu/node/hydrate.node.ts

@@ -13,8 +13,7 @@ import { builtinModules, createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { promisify } from "node:util";
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { build as viteBuild } from "vite";
 import {
   ASSETS_DIR,
@@ -25,6 +24,7 @@ import {
   loadDocuConfig,
 } from "./paths";
 import { buildThemeCss, getThemeConfig } from "./hydrate";
+import { atomicWriteFile, computeTailwindCacheKey, readGlobalsCss } from "./cache-key";
 import { resolveRoutes } from "./fs-scanner";
 import { normalizeImporterPath } from "./security";
 import type { DocuConfig, DocuRoute } from "./types";
@@ -59,10 +59,9 @@ function resolveTailwindBin(): string {
   return join(dirname(pkgPath), binRel);
 }
 
-/** Compute a cache key from globals.css + theme config content. */
+/** Compute a cache key from globals.css + theme + config + toolchain. */
 function tailwindCacheKey(): string {
-  const globalsPath = join(STYLES_DIR, "globals.css");
-  const globalsContent = existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+  const globalsContent = readGlobalsCss();
   let themeSuffix = "";
   try {
     const themeColors = getThemeConfig();
@@ -72,10 +71,7 @@ function tailwindCacheKey(): string {
   } catch {
     // theme config unavailable — proceed without it
   }
-  return createHash("sha256")
-    .update(globalsContent + themeSuffix)
-    .digest("hex")
-    .slice(0, 16);
+  return computeTailwindCacheKey(globalsContent, themeSuffix);
 }
 
 /**
@@ -105,7 +101,7 @@ async function buildTailwindCss(key: string): Promise<{ file: string; content: s
   }
 
   let cssContent = await readFile(tmpCss, "utf-8");
-  await unlink(tmpCss);
+  await unlink(tmpCss).catch(() => {});
 
   try {
     const themeColors = getThemeConfig();
@@ -120,11 +116,12 @@ async function buildTailwindCss(key: string): Promise<{ file: string; content: s
 
   // Use the same input-derived key for lookup and output — if inputs change,
   // the key changes, cache busting works without a separate content hash.
+  // Atomic tmp+rename with pid suffix: parallel builds never clobber each other.
   const cssFile = `client-${key}.css`;
   const outPath = join(ASSETS_DIR, cssFile);
 
   if (!existsSync(outPath)) {
-    await writeFile(outPath, cssContent);
+    await atomicWriteFile(writeFile, rename, unlink, outPath, cssContent);
   }
 
   return { file: cssFile, content: cssContent };

package/.docu/node/hydrate.ts

@@ -1,9 +1,9 @@
 import { join } from "node:path";
-import { mkdir, unlink } from "node:fs/promises";
-import { existsSync, readFileSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { mkdir, unlink, rename } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { resolveTheme, generateThemeCss, presetRegistry } from "@docubook/themes-colors";
 import { ASSETS_DIR, cleanOldBundles, LIB_DIR, STYLES_DIR, loadDocuConfig } from "./paths";
+import { atomicWriteFile, computeTailwindCacheKey, readGlobalsCss } from "./cache-key";
 import { resolveRoutes } from "./fs-scanner";
 import type { DocuRoute } from "./types";
 import type { ThemeConfig } from "@docubook/themes-colors";
@@ -57,10 +57,9 @@ export function computeInlineThemeCss(): string | undefined {
   return undefined;
 }
 
-/** Compute Tailwind cache key from globals.css + theme config. */
+/** Compute Tailwind cache key from globals.css + theme + config + toolchain. */
 function twCacheKey(): string {
-  const globalsPath = join(STYLES_DIR, "globals.css");
-  const globals = existsSync(globalsPath) ? readFileSync(globalsPath, "utf-8") : "";
+  const globals = readGlobalsCss();
   let themeSuffix = "";
   try {
     const themeColors = getThemeConfig();
@@ -68,10 +67,7 @@ function twCacheKey(): string {
   } catch {
     // theme config unavailable — proceed without
   }
-  return createHash("sha256")
-    .update(globals + themeSuffix)
-    .digest("hex")
-    .slice(0, 16);
+  return computeTailwindCacheKey(globals, themeSuffix);
 }
 
 /** Run Tailwind CLI, caching by content hash. */
@@ -105,7 +101,7 @@ async function buildTailwindCss(key: string): Promise<{ file: string; content: s
   }
 
   let cssContent = await Bun.file(tmpCss).text();
-  await unlink(tmpCss);
+  await unlink(tmpCss).catch(() => {});
 
   try {
     const themeColors = getThemeConfig();
@@ -116,11 +112,14 @@ async function buildTailwindCss(key: string): Promise<{ file: string; content: s
     );
   }
 
-  // Use the same input-derived key for lookup and output — if inputs change,
-  // the key changes, cache busting works without a separate content hash.
   const cssFile = `client-${key}.css`;
   const outPath = join(ASSETS_DIR, cssFile);
-  if (!existsSync(outPath)) await Bun.write(outPath, cssContent);
+  // Atomic tmp+rename with pid suffix: parallel builds never clobber each
+  // other, and a crash cannot leave a half-written CSS file behind.
+  if (!existsSync(outPath)) {
+    const { writeFile } = await import("node:fs/promises");
+    await atomicWriteFile(writeFile, rename, unlink, outPath, cssContent);
+  }
 
   return { file: cssFile, content: cssContent };
 }

package/.docu/node/mdx.ts

@@ -174,7 +174,10 @@ async function serializeWithDocPlugins(
   // Parse-once: when the prePass already extracted the frontmatter + stripped
   // content, reuse it instead of re-parsing (the SSR phase skips extraction).
   const { strippedContent, frontmatter } =
-    pre ?? extractFrontmatterWithContent<Frontmatter>(rawMdx, opts.frontmatterSchema);
+    pre ??
+    (opts.frontmatterSchema
+      ? extractFrontmatterWithContent<Frontmatter>(rawMdx, opts.frontmatterSchema)
+      : extractFrontmatterWithContent<Frontmatter>(rawMdx));
 
   const defaultRemark = createDefaultRemarkPlugins();
   const defaultRehype = createDefaultRehypePlugins();
@@ -221,7 +224,9 @@ export async function compileMdx(
   const tocs = extractTocsFromRawMdx(rawMdx);
   const frontmatter =
     pre?.frontmatter ??
-    extractFrontmatterWithContent<Frontmatter>(rawMdx, frontmatterSchema).frontmatter;
+    (frontmatterSchema
+      ? extractFrontmatterWithContent<Frontmatter>(rawMdx, frontmatterSchema).frontmatter
+      : extractFrontmatterWithContent<Frontmatter>(rawMdx).frontmatter);
   const serialized = await serializeWithDocPlugins(
     rawMdx,
     { remarkPlugins, rehypePlugins, frontmatterSchema },
@@ -304,6 +309,13 @@ export function getPageContent(href: string): string | undefined {
   return pageContent.get(href);
 }
 
+/** Drop derived page maps under OS memory pressure (Bun 1.4 `memoryPressure`). */
+export function clearDerivedPageCaches(): void {
+  pageContent.clear();
+  pageStripped.clear();
+  pageFrontmatter.clear();
+}
+
 export async function compileMdxModule(
   rawMdx: string,
   remarkPlugins?: Pluggable[],

package/.docu/node/paths.ts

@@ -10,7 +10,28 @@ import type { DocuConfig } from "./types";
 
 // .docu/node/paths.ts → package root is 2 levels up
 export const FRAMEWORK_ROOT = resolve(import.meta.dirname, "../..");
-export const PROJECT_ROOT = process.cwd();
+
+/**
+ * Find the project root by walking up from cwd until docu.json is found.
+ * Falls back to cwd when not found (tests, ad-hoc scripts). Bun 1.4
+ * `run --parallel --filter` may change cwd per workspace task, so a bare
+ * process.cwd() can point at the wrong package.
+ */
+function findProjectRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 6; i++) {
+    try {
+      if (existsSync(join(dir, "docu.json"))) return dir;
+    } catch {
+      break;
+    }
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+export const PROJECT_ROOT = findProjectRoot();
 
 // Framework paths (internal)
 export const PAGES_DIR = join(FRAMEWORK_ROOT, ".docu/pages");
@@ -29,6 +50,11 @@ export const DOCS_DIR = join(PROJECT_ROOT, "docs");
 export const DOCS_ASSETS_DIR = join(PROJECT_ROOT, "docs/assets");
 export const DOCU_CONFIG_PATH = join(PROJECT_ROOT, "docu.json");
 
+/** Resolve a project-relative file against the discovered PROJECT_ROOT. */
+export function resolveProjectFile(...segments: string[]): string {
+  return join(PROJECT_ROOT, ...segments);
+}
+
 // Config singleton
 let _config: DocuConfig | null = null;
 

package/.docu/node/plugin-builder.ts

@@ -408,6 +408,8 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Execute the transformHtml chain in pipeline pattern.
    * Each callback receives the **previous** callback's return value (or the
    * original HTML for the first). Every callback **must** return a string.
+   * Callbacks returning a non-string (e.g. `undefined`) are skipped with a
+   * warning — the current HTML passes through unchanged for that step.
    * Errors inside individual callbacks are caught and logged — the current
    * HTML passes through unchanged for that step.
    *
@@ -419,7 +421,14 @@ export class BuildPluginBuilder implements PluginBuilder {
     let result = html;
     for (let i = 0; i < this._transformHtml.length; i++) {
       try {
-        result = await this._transformHtml[i](result, context);
+        const next = await this._transformHtml[i](result, context);
+        if (typeof next === "string") {
+          result = next;
+        } else {
+          console.warn(
+            `[plugin] transformHtml callback #${i + 1} returned invalid type (expected a string), keeping previous HTML`
+          );
+        }
       } catch (err) {
         console.error(
           `[plugin] transformHtml callback #${i + 1} error: ${err instanceof Error ? err.message : String(err)}`

package/.docu/node/route.ts

@@ -47,6 +47,22 @@ export function getRouteMap(): Map<string, string> {
   return map;
 }
 
+/**
+ * Single pagination entry builder (DRY) — one `readPageFrontmatter` call
+ * serves both prev + next from the parse-once registry, so no file is
+ * re-read or re-parsed. `description` rides along on prev too; the UI
+ * keeps the paired prev minimal by design and only renders the rich
+ * title + description when prev stands alone (last page, no next).
+ */
+function toPaginationEntry(href: string, routeMap: Map<string, string>) {
+  const fm = readPageFrontmatter(href);
+  return {
+    href,
+    title: fm.title || routeMap.get(href) || "",
+    description: fm.description || "",
+  };
+}
+
 /**
  * Frontmatter for a page — read from the parse-once registry (populated
  * during compilation) instead of re-reading + re-parsing the file. Falls
@@ -86,15 +102,7 @@ export function getPreviousNext(pathname: string) {
     const routeMap = getRouteMap();
     const first = paths[0];
     if (!first) return { prev: null, next: null };
-    const fm = readPageFrontmatter(first);
-    return {
-      prev: null,
-      next: {
-        href: first,
-        title: fm.title || routeMap.get(first) || "",
-        description: fm.description || "",
-      },
-    };
+    return { prev: null, next: toPaginationEntry(first, routeMap) };
   }
 
   const paths = flattenRoutes();
@@ -109,19 +117,9 @@ export function getPreviousNext(pathname: string) {
   const prevHref = index > 0 ? paths[index - 1] : null;
   const nextHref = index < paths.length - 1 ? paths[index + 1] : null;
 
-  const prevFm = prevHref ? readPageFrontmatter(prevHref) : null;
-  const nextFm = nextHref ? readPageFrontmatter(nextHref) : null;
   return {
-    prev: prevHref
-      ? { href: prevHref, title: prevFm?.title || routeMap.get(prevHref) || "" }
-      : null,
-    next: nextHref
-      ? {
-          href: nextHref,
-          title: nextFm?.title || routeMap.get(nextHref) || "",
-          description: nextFm?.description || "",
-        }
-      : null,
+    prev: prevHref ? toPaginationEntry(prevHref, routeMap) : null,
+    next: nextHref ? toPaginationEntry(nextHref, routeMap) : null,
   };
 }
 

package/.docu/node/security.ts

@@ -30,6 +30,15 @@ export function cspHeader(nonce: string, allowEval = false): string {
   ].join("; ");
 }
 
+/**
+ * Strip `frame-ancestors` for `<meta http-equiv="Content-Security-Policy">`.
+ * Browsers ignore `frame-ancestors` in meta CSP (header-only directive)
+ * and log a console warning. HTTP header from `cspHeader()` keeps it.
+ */
+export function cspMeta(csp: string): string {
+  return csp.replace(/;\s*frame-ancestors 'none'/, "");
+}
+
 export function isPathSafe(pathname: string, baseDir: string): boolean {
   const decoded = decodeURIComponent(pathname);
   const resolved = resolve(baseDir, decoded.slice(1));
@@ -87,12 +96,20 @@ export function normalizeImporterPath(importer: string): string {
 }
 
 export function injectNonce(html: string, nonce: string): string {
-  return html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
+  const scripts = html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
     if (/nonce\s*=/i.test(match)) {
       return match.replace(/nonce="[^"]*"/i, `nonce="${nonce}"`);
     }
     return match.replace(/>$/, ` nonce="${nonce}">`);
   });
+  // Keep the <meta> CSP nonce in sync: browsers intersect the meta policy
+  // with the response-header policy, so a stale build-time nonce would block
+  // the very scripts re-tagged above.
+  return scripts.replace(/<meta\b[^>]*Content-Security-Policy[^>]*>/gi, (tag) =>
+    tag.replace(/'nonce-[^']*'|&#(?:x27;|39;)nonce-[^&]*(?:&#(?:x27;|39;))/i, (match) =>
+      match.startsWith("&#") ? `&#x27;nonce-${nonce}&#x27;` : `'nonce-${nonce}'`
+    )
+  );
 }
 
 export interface PluginResponseLike {