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

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);
+}

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;