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

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";
@@ -38,8 +38,17 @@ import { logger } from "./logger";
 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 { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
+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,40 @@ 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";
+  // Any mtime drift vs the recorded one — a newer edit, or mtime moving
+  // backwards (rsync -a, cp -p, snapshot restore) — falls through to the
+  // hash check: hashing an unchanged file is cheap, serving a stale page
+  // is not. Only an untouched mtime skips without reading the file.
+  if (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(
@@ -176,11 +228,11 @@ async function renderDocsPage(
   const bodyExtra = builder?.collectBody(ctx);
 
   const depth = slug ? slug.split("/").length : 1;
-  const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const favicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
   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 +275,8 @@ export async function runBuild(): Promise<void> {
   const docuConfig = loadDocuConfig();
   const args = parseArgs();
 
+  hookMemoryPressure(clearDerivedPageCaches);
+
   logger.buildStart();
 
   if (args.clean) {
@@ -287,15 +341,16 @@ export async function runBuild(): Promise<void> {
   });
   await Promise.all(prePassTasks);
 
-  // The docs root (index.mdx) renders with slug "" — mirror that key so the
-  // index page hydrates too. Its render has its own try/catch; skip on error.
-  const indexMdxPath = join(DOCS_DIR, "index.mdx");
-  if (existsSync(indexMdxPath)) {
+  // The docs root (index.mdx, or index.md) renders with slug "" — mirror that
+  // key so the index page hydrates too. Its render has its own try/catch; skip
+  // on error.
+  const indexSource = resolveDocsIndexSource(DOCS_DIR);
+  if (indexSource) {
     try {
-      const indexRaw = await readFile(indexMdxPath, "utf-8");
+      const indexRaw = await readFile(indexSource, "utf-8");
       let indexContent = indexRaw;
       if (builder) {
-        const relPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
+        const relPath = indexSource.replace(PROJECT_ROOT + "/", "");
         const transformed = await builder.runOnLoad(relPath, indexContent);
         if (transformed?.contents) indexContent = transformed.contents;
       }
@@ -311,14 +366,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,15 +387,17 @@ 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();
 
   const allRelPaths = mdxFiles.map((f) => f.absPath.replace(PROJECT_ROOT + "/", ""));
 
-  const indexMdxFull = join(DOCS_DIR, "index.mdx");
-  if (existsSync(indexMdxFull)) {
-    allRelPaths.push(indexMdxFull.replace(PROJECT_ROOT + "/", ""));
+  if (indexSource) {
+    allRelPaths.push(indexSource.replace(PROJECT_ROOT + "/", ""));
   }
   const gitDates = await getGitLastModifiedBatch(allRelPaths);
 
@@ -366,7 +429,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)) {
@@ -415,30 +478,39 @@ export async function runBuild(): Promise<void> {
     await Promise.all(buildTasks.slice(i, i + CONCURRENCY).map((fn) => fn()));
   }
 
-  try {
-    const indexMdxPath = join(DOCS_DIR, "index.mdx");
-    const indexRaw = await readFile(indexMdxPath, "utf-8");
-    const indexRelPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
-    const indexHtml = await renderDocsPage(
-      docuConfig,
-      "",
-      indexRaw,
-      indexRelPath,
-      gitDates,
-      builder,
-      generateNonce()
-    );
-    await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-    await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    errors.push(`index.mdx: ${msg}`);
-    console.error(`\n\u274C Failed to build index: ${msg}\n`);
+  if (indexSource) {
+    try {
+      const indexRaw = await readFile(indexSource, "utf-8");
+      const indexRelPath = indexSource.replace(PROJECT_ROOT + "/", "");
+      const indexHtml = await renderDocsPage(
+        docuConfig,
+        "",
+        indexRaw,
+        indexRelPath,
+        gitDates,
+        builder,
+        generateNonce()
+      );
+      await mkdir(join(DIST_DIR, "docs"), { recursive: true });
+      await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      errors.push(`index: ${msg}`);
+      console.error(`\n❌ Failed to build index: ${msg}\n`);
+    }
+  } else {
+    const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
+    errors.push(`index: ${msg}`);
+    console.error(`\n❌ Failed to build index: ${msg}\n`);
   }
 
   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 landingFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const landingSeo = buildSeoMeta(
+    docuConfig,
+    docuConfig.meta as unknown as Record<string, unknown>,
+    ""
+  );
   const landingNonce = generateNonce();
   const landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",
@@ -459,7 +531,7 @@ export async function runBuild(): Promise<void> {
     { repoUrl: docuConfig.repo?.url },
     React.createElement(NotFoundPage)
   );
-  const notFoundFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
   const notFoundNonce = generateNonce();
   const notFoundHtml = htmlShell({
     title: "404 - Not Found",

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";
@@ -30,9 +30,18 @@ import { logger } from "./logger";
 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 { generateNonce } from "./security";
+import { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
+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";
 import DocsPage from "../pages/docs/[[...slug]]";
@@ -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,40 @@ 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";
+  // Any mtime drift vs the recorded one — a newer edit, or mtime moving
+  // backwards (rsync -a, cp -p, snapshot restore) — falls through to the
+  // hash check: hashing an unchanged file is cheap, serving a stale page
+  // is not. Only an untouched mtime skips without reading the file.
+  if (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(
@@ -169,14 +226,18 @@ async function renderDocsPage(
   const bodyExtra = builder?.collectBody(ctx);
 
   const depth = slug ? slug.split("/").length : 1;
-  const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const favicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
+  // Parity with build.impl.ts: static hosts without header control (GitHub
+  // Pages) rely on the <meta> CSP for the per-page script policy.
+  const csp = nonce ? cspHeader(nonce) : undefined;
   let html = htmlShell({
     title,
     description,
     body,
     favicon,
     seo,
+    csp,
     css: assetManifest.css,
     js: assetManifest.js,
     nonce,
@@ -211,6 +272,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) {
@@ -275,15 +340,16 @@ async function build() {
   });
   await Promise.all(prePassTasks);
 
-  // The docs root (index.mdx) renders with slug "" — mirror that key so the
-  // index page hydrates too. Its render has its own try/catch; skip on error.
-  const indexMdxPath = join(DOCS_DIR, "index.mdx");
-  if (existsSync(indexMdxPath)) {
+  // The docs root (index.mdx, or index.md) renders with slug "" — mirror that
+  // key so the index page hydrates too. Its render has its own try/catch; skip
+  // on error.
+  const indexSource = resolveDocsIndexSource(DOCS_DIR);
+  if (indexSource) {
     try {
-      const indexRaw = await readFile(indexMdxPath, "utf-8");
+      const indexRaw = await readFile(indexSource, "utf-8");
       let indexContent = indexRaw;
       if (builder) {
-        const relPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
+        const relPath = indexSource.replace(PROJECT_ROOT + "/", "");
         const transformed = await builder.runOnLoad(relPath, indexContent);
         if (transformed?.contents) indexContent = transformed.contents;
       }
@@ -299,14 +365,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,15 +389,17 @@ 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();
 
   const allRelPaths = mdxFiles.map((f) => f.absPath.replace(PROJECT_ROOT + "/", ""));
 
-  const indexMdxFull = join(DOCS_DIR, "index.mdx");
-  if (existsSync(indexMdxFull)) {
-    allRelPaths.push(indexMdxFull.replace(PROJECT_ROOT + "/", ""));
+  if (indexSource) {
+    allRelPaths.push(indexSource.replace(PROJECT_ROOT + "/", ""));
   }
   const gitDates = await getGitLastModifiedBatch(allRelPaths);
 
@@ -354,7 +431,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)) {
@@ -402,38 +479,49 @@ async function build() {
     await Promise.all(buildTasks.slice(i, i + CONCURRENCY).map((fn) => fn()));
   }
 
-  try {
-    const indexMdxPath = join(DOCS_DIR, "index.mdx");
-    const indexRaw = await readFile(indexMdxPath, "utf-8");
-    const indexRelPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
-    const indexHtml = await renderDocsPage(
-      "",
-      indexRaw,
-      indexRelPath,
-      gitDates,
-      builder,
-      generateNonce()
-    );
-    await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-    await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    errors.push(`index.mdx: ${msg}`);
-    console.error(`\n\u274C Failed to build index: ${msg}\n`);
+  if (indexSource) {
+    try {
+      const indexRaw = await readFile(indexSource, "utf-8");
+      const indexRelPath = indexSource.replace(PROJECT_ROOT + "/", "");
+      const indexHtml = await renderDocsPage(
+        "",
+        indexRaw,
+        indexRelPath,
+        gitDates,
+        builder,
+        generateNonce()
+      );
+      await mkdir(join(DIST_DIR, "docs"), { recursive: true });
+      await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      errors.push(`index: ${msg}`);
+      console.error(`\n❌ Failed to build index: ${msg}\n`);
+    }
+  } else {
+    const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
+    errors.push(`index: ${msg}`);
+    console.error(`\n❌ Failed to build index: ${msg}\n`);
   }
 
   const landingPage = React.createElement(IndexPage);
-  const landingFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
-  const landingSeo = buildSeoMeta(docuConfig, {}, "");
+  const landingFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const landingSeo = buildSeoMeta(
+    docuConfig,
+    docuConfig.meta as unknown as Record<string, unknown>,
+    ""
+  );
+  const landingNonce = generateNonce();
   const landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",
     description: docuConfig.meta?.description || "",
     body: renderToString(landingPage),
     favicon: landingFavicon,
     seo: landingSeo,
+    csp: cspHeader(landingNonce),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: landingNonce,
     themeCss: inlineThemeCss,
   });
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
@@ -443,16 +531,18 @@ async function build() {
     { repoUrl: docuConfig.repo?.url },
     React.createElement(NotFoundPage)
   );
-  const notFoundFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const notFoundNonce = generateNonce();
   const notFoundHtml = htmlShell({
     title: "404 - Not Found",
     description: "",
     body: renderToString(notFoundPage),
     favicon: notFoundFavicon,
     headExtra: ['<meta name="robots" content="noindex,follow">'],
+    csp: cspHeader(notFoundNonce),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: notFoundNonce,
     themeCss: inlineThemeCss,
     // Served as the static-host fallback at ANY requested path — relative
     // depth can never be right there, so use root-absolute asset URLs.