@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/cli/runValidate.mjs

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'url';
 import { Worker } from 'node:worker_threads';
 import { createPerformanceLogger, logPerformance, nameMark, performanceMeasure } from "../pipeline/loadPrecomputedCodeHighlighter/performanceLogger.mjs";
 import { terminateWorkerManager } from "../pipeline/loadServerTypesMeta/workerManager.mjs";
+import { DEFAULT_CACHE_DIR } from "../pipeline/cacheUtils/index.mjs";
 import { extractDocsInfraOptionsFromNextConfig } from "./loadNextConfig.mjs";
 import { ensureDemoClients } from "./ensureDemoClients.mjs";
 import { ensureDemoPages } from "./ensureDemoPages.mjs";
@@ -89,10 +90,14 @@ const runValidate = {
       descriptionReplacements,
       useVisibleDescription = false,
       socketDir: configSocketDir,
+      cacheDir: configCacheDir,
       demoClientRequirements = [],
       demoPageRequirements = []
     } = await extractDocsInfraOptionsFromNextConfig(cwd);
     const socketDir = configSocketDir ? path.resolve(cwd, configSocketDir) : undefined;
+    // Use the same page-index cache directory that the sitemap loader reads at build time.
+    // The index validation pass writes cache entries even when committed indexes are current.
+    const cacheDir = configCacheDir ?? DEFAULT_CACHE_DIR;
 
     // If neither flag is set, run both. If one is set, run only that one.
     const runIndexes = !typesOnly || indexesOnly;
@@ -189,8 +194,8 @@ const runValidate = {
     try {
       // === Validate page.mdx index files ===
       if (runIndexes) {
-        const markerDir = '.next/cache/docs-infra/index-updates';
-        const markerDirPath = path.join(cwd, markerDir);
+        const markerDir = path.posix.join(cacheDir, 'index-updates');
+        const markerDirPath = path.resolve(cwd, markerDir);
         try {
           await rm(markerDirPath, {
             recursive: true,
@@ -222,7 +227,8 @@ const runValidate = {
           baseDir: cwd,
           onlyUpdateIndexes: true,
           markerDir,
-          useVisibleDescription
+          useVisibleDescription,
+          cacheDir
         };
         const indexResults = await Promise.all(pageMdxFiles.map(filePath => {
           const taskId = taskIdCounter;
@@ -263,8 +269,8 @@ const runValidate = {
       // === Validate types.ts files ===
       if (runTypes) {
         // Use same marker directory structure for index updates from types
-        const typesMarkerDir = '.next/cache/docs-infra/types-index-updates';
-        const typesMarkerDirPath = path.join(cwd, typesMarkerDir);
+        const typesMarkerDir = path.posix.join(cacheDir, 'types-index-updates');
+        const typesMarkerDirPath = path.resolve(cwd, typesMarkerDir);
         try {
           await rm(typesMarkerDirPath, {
             recursive: true,
@@ -289,11 +295,13 @@ const runValidate = {
             syncTypesOptions: {
               updateParentIndex: {
                 baseDir: cwd,
-                markerDir: typesMarkerDir
+                markerDir: typesMarkerDir,
+                cacheDir
               },
               ordering,
               descriptionReplacements,
-              socketDir
+              socketDir,
+              cacheDir
             }
           });
         }));

package/cli/validateWorker.d.mts

@@ -11,6 +11,7 @@ interface IndexTask {
     onlyUpdateIndexes: boolean;
     markerDir: string;
     useVisibleDescription: boolean;
+    cacheDir?: string;
   };
 }
 interface TypesTask {

package/cli/validateWorker.mjs

@@ -74,7 +74,8 @@ if (parentPort) {
             updateParentIndex: excludeFromIndex ? undefined : task.syncTypesOptions.updateParentIndex,
             ordering: task.syncTypesOptions.ordering,
             descriptionReplacements: task.syncTypesOptions.descriptionReplacements,
-            socketDir: task.syncTypesOptions.socketDir
+            socketDir: task.syncTypesOptions.socketDir,
+            cacheDir: task.syncTypesOptions.cacheDir
           });
           parentPort.postMessage({
             type: 'types',

package/createDemoData/createDemoData.d.mts

@@ -1,5 +1,5 @@
 import type * as React from 'react';
-import { type CreateDemoDataMeta, type DemoData, type DemoGlobalData, type DemoGlobalProvider } from "./types.mjs";
+import type { CreateDemoDataMeta, DemoData, DemoGlobalData, DemoGlobalProvider } from "./types.mjs";
 /**
  * Creates demo data for displaying code examples with syntax highlighting.
  * A variant is a different implementation style of the same component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.2",
+  "version": "0.12.1-canary.21",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -29,24 +29,34 @@
   },
   "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
   "dependencies": {
-    "@babel/runtime": "^7.29.2",
+    "@babel/runtime": "^7.29.7",
+    "@csstools/postcss-light-dark-function": "^3.0.1",
+    "@csstools/postcss-relative-color-syntax": "^4.0.5",
+    "@csstools/postcss-stepped-value-functions": "^5.0.3",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
     "@orama/stemmers": "^3.1.18",
     "@orama/stopwords": "^3.1.18",
     "@wooorm/starry-night": "^3.9.0",
+    "autoprefixer": "^10.5.0",
     "chalk": "^5.6.2",
     "clipboard-copy": "^4.0.1",
-    "es-toolkit": "^1.46.1",
+    "es-toolkit": "^1.49.0",
     "fflate": "^0.8.2",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-text": "^4.0.2",
+    "icss-utils": "^5.1.0",
     "import-meta-resolve": "^4.2.0",
     "jiti": "^2.7.0",
     "jsondiffpatch": "^0.7.3",
     "kebab-case": "^2.0.2",
     "lz-string": "^1.5.0",
     "path-module": "^0.1.2",
+    "postcss": "^8.5.15",
+    "postcss-modules-extract-imports": "^3.1.0",
+    "postcss-modules-local-by-default": "^4.2.0",
+    "postcss-modules-scope": "^3.2.1",
+    "postcss-modules-values": "^4.0.0",
     "proper-lockfile": "^4.1.2",
     "remark-gfm": "^4.0.1",
     "remark-mdx": "^3.1.1",
@@ -58,7 +68,6 @@
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "use-editable": "^2.3.3",
     "vscode-oniguruma": "^2.0.1",
     "yargs": "^18.0.0",
     "zx": "^8.8.5"
@@ -331,6 +340,16 @@
         "default": "./useCopier/index.mjs"
       }
     },
+    "./useCrossTabState": {
+      "import": {
+        "types": "./useCrossTabState/index.d.mts",
+        "default": "./useCrossTabState/index.mjs"
+      },
+      "default": {
+        "types": "./useCrossTabState/index.d.mts",
+        "default": "./useCrossTabState/index.mjs"
+      }
+    },
     "./useDemo": {
       "import": {
         "types": "./useDemo/index.d.mts",
@@ -341,6 +360,16 @@
         "default": "./useDemo/index.mjs"
       }
     },
+    "./useDemoController": {
+      "import": {
+        "types": "./useDemoController/index.d.mts",
+        "default": "./useDemoController/index.mjs"
+      },
+      "default": {
+        "types": "./useDemoController/index.d.mts",
+        "default": "./useDemoController/index.mjs"
+      }
+    },
     "./useErrors": {
       "import": {
         "types": "./useErrors/index.d.mts",
@@ -775,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "a53107e93d9af804bc3561ae0a183fefe49107d1"
+  "gitSha": "d7a721986aed46adb128a9b200b12729c7a55378"
 }

package/pipeline/cacheUtils/constants.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Default root directory for docs-infra build caches. Sits alongside the marker
+ * directories already written under `.next/cache/docs-infra`.
+ */
+export declare const DEFAULT_CACHE_DIR = ".next/cache/docs-infra";

package/pipeline/cacheUtils/constants.mjs

@@ -0,0 +1,5 @@
+/**
+ * Default root directory for docs-infra build caches. Sits alongside the marker
+ * directories already written under `.next/cache/docs-infra`.
+ */
+export const DEFAULT_CACHE_DIR = '.next/cache/docs-infra';

package/pipeline/cacheUtils/hashCacheContent.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Computes the sha256 hex digest of cache source content. Used to validate that a
+ * cached value still matches the file it was derived from.
+ */
+export declare function hashCacheContent(content: string): string;

package/pipeline/cacheUtils/hashCacheContent.mjs

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Computes the sha256 hex digest of cache source content. Used to validate that a
+ * cached value still matches the file it was derived from.
+ */
+export function hashCacheContent(content) {
+  return createHash('sha256').update(content).digest('hex');
+}

package/pipeline/cacheUtils/index.d.mts

@@ -0,0 +1,9 @@
+export { hashCacheContent } from "./hashCacheContent.mjs";
+export { loadFileCache } from "./loadFileCache.mjs";
+export { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+export { saveFileCache } from "./saveFileCache.mjs";
+export { resolveCachePath } from "./resolveCachePath.mjs";
+export { withFileCache } from "./withFileCache.mjs";
+export type { FileCacheTask } from "./withFileCache.mjs";
+export { DEFAULT_CACHE_DIR } from "./constants.mjs";
+export type { FileCacheRef, FileCacheEntry } from "./types.mjs";

package/pipeline/cacheUtils/index.mjs

@@ -0,0 +1,7 @@
+export { hashCacheContent } from "./hashCacheContent.mjs";
+export { loadFileCache } from "./loadFileCache.mjs";
+export { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+export { saveFileCache } from "./saveFileCache.mjs";
+export { resolveCachePath } from "./resolveCachePath.mjs";
+export { withFileCache } from "./withFileCache.mjs";
+export { DEFAULT_CACHE_DIR } from "./constants.mjs";

package/pipeline/cacheUtils/loadFileCache.d.mts

@@ -0,0 +1,13 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * Reads a cache entry and returns its data only when the stored hash matches the
+ * current content.
+ *
+ * Best-effort by design: a missing file, an unreadable file, malformed JSON, or a
+ * hash mismatch all resolve to `null` (a cache miss) rather than throwing, so a
+ * stale or corrupt cache can never break a build — it is simply recomputed.
+ *
+ * To overlap the cache read with reading the source file, use {@link loadFileCacheEntry}
+ * directly and compare the hash yourself.
+ */
+export declare function loadFileCache<T>(ref: FileCacheRef, content: string): Promise<T | null>;

package/pipeline/cacheUtils/loadFileCache.mjs

@@ -0,0 +1,20 @@
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+/**
+ * Reads a cache entry and returns its data only when the stored hash matches the
+ * current content.
+ *
+ * Best-effort by design: a missing file, an unreadable file, malformed JSON, or a
+ * hash mismatch all resolve to `null` (a cache miss) rather than throwing, so a
+ * stale or corrupt cache can never break a build — it is simply recomputed.
+ *
+ * To overlap the cache read with reading the source file, use {@link loadFileCacheEntry}
+ * directly and compare the hash yourself.
+ */
+export async function loadFileCache(ref, content) {
+  const entry = await loadFileCacheEntry(ref);
+  if (!entry || entry.hash !== hashCacheContent(content)) {
+    return null;
+  }
+  return entry.data;
+}

package/pipeline/cacheUtils/loadFileCacheEntry.d.mts

@@ -0,0 +1,13 @@
+import type { FileCacheEntry, FileCacheRef } from "./types.mjs";
+/**
+ * Reads and parses a cache entry without validating it against any content.
+ *
+ * Best-effort: a missing file, an unreadable file, malformed JSON, or a path-containment failure
+ * all resolve to `null` (a cache miss) rather than throwing — so a stale or corrupt cache never
+ * breaks a build. Use this to read the cache in parallel with the source file, then compare
+ * `entry.hash` against `hashCacheContent(content)` once both reads complete.
+ *
+ * A non-missing read failure (e.g. a permissions error silently disabling the cache) is logged
+ * under DEBUG rather than masquerading as a cold cache.
+ */
+export declare function loadFileCacheEntry<T>(ref: FileCacheRef): Promise<FileCacheEntry<T> | null>;

package/pipeline/cacheUtils/loadFileCacheEntry.mjs

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import { resolveCachePath } from "./resolveCachePath.mjs";
+// Set DOCS_INFRA_CACHE_DEBUG=1 to surface non-missing read failures and corrupt entries.
+const DEBUG = Boolean(process.env.DOCS_INFRA_CACHE_DEBUG);
+function isFileCacheEntry(value) {
+  return typeof value === 'object' && value !== null && 'hash' in value && 'data' in value && typeof value.hash === 'string';
+}
+
+/**
+ * Reads and parses a cache entry without validating it against any content.
+ *
+ * Best-effort: a missing file, an unreadable file, malformed JSON, or a path-containment failure
+ * all resolve to `null` (a cache miss) rather than throwing — so a stale or corrupt cache never
+ * breaks a build. Use this to read the cache in parallel with the source file, then compare
+ * `entry.hash` against `hashCacheContent(content)` once both reads complete.
+ *
+ * A non-missing read failure (e.g. a permissions error silently disabling the cache) is logged
+ * under DEBUG rather than masquerading as a cold cache.
+ */
+export async function loadFileCacheEntry(ref) {
+  let raw;
+  try {
+    raw = await readFile(resolveCachePath(ref), 'utf-8');
+  } catch (error) {
+    const isMissing = error instanceof Error && error.code === 'ENOENT';
+    if (DEBUG && !isMissing) {
+      console.warn(`[docs-infra cache] read failed for ${ref.namespace}/${ref.cacheKey}:`, error);
+    }
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] ignoring corrupt entry ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return null;
+  }
+  if (!isFileCacheEntry(parsed)) {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] ignoring malformed entry ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return null;
+  }
+  return parsed;
+}

package/pipeline/cacheUtils/resolveCachePath.d.mts

@@ -0,0 +1,16 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * Resolves the absolute path of a cache entry: `{cacheDir}/{namespace}/{cacheKey}.json`.
+ *
+ * Relative `cacheDir` values resolve against the current working directory so that readers and
+ * writers running from the same project root agree on the location. `cacheKey` may contain `/`
+ * separators, which become nested directories.
+ *
+ * Fails fast if a `namespace`/`cacheKey` segment (e.g. a `..`) would escape the cache directory,
+ * so a malformed route can never read or write outside `{cacheDir}`.
+ */
+export declare function resolveCachePath({
+  cacheDir,
+  namespace,
+  cacheKey
+}: FileCacheRef): string;

package/pipeline/cacheUtils/resolveCachePath.mjs

@@ -0,0 +1,24 @@
+import { resolve, sep } from 'node:path';
+/**
+ * Resolves the absolute path of a cache entry: `{cacheDir}/{namespace}/{cacheKey}.json`.
+ *
+ * Relative `cacheDir` values resolve against the current working directory so that readers and
+ * writers running from the same project root agree on the location. `cacheKey` may contain `/`
+ * separators, which become nested directories.
+ *
+ * Fails fast if a `namespace`/`cacheKey` segment (e.g. a `..`) would escape the cache directory,
+ * so a malformed route can never read or write outside `{cacheDir}`.
+ */
+export function resolveCachePath({
+  cacheDir,
+  namespace,
+  cacheKey
+}) {
+  const base = resolve(cacheDir);
+  const full = resolve(base, namespace, `${cacheKey}.json`);
+  const baseWithSep = base.endsWith(sep) ? base : `${base}${sep}`;
+  if (!full.startsWith(baseWithSep)) {
+    throw new Error(`Cache path for "${namespace}/${cacheKey}" escapes the cache directory "${cacheDir}".`);
+  }
+  return full;
+}

package/pipeline/cacheUtils/saveFileCache.d.mts

@@ -0,0 +1,17 @@
+import type { FileCacheEntry, FileCacheRef } from "./types.mjs";
+/**
+ * Writes a precomputed cache entry (`{ hash, data }`) atomically (temp file + rename) so a
+ * concurrent reader never observes a half-written file. Creates the cache directory tree as needed.
+ *
+ * Fails fast: any filesystem error propagates so a misconfigured cache directory surfaces loudly at
+ * build time. Callers that treat the write as best-effort (e.g. {@link withFileCache}) catch it.
+ *
+ * Use this (rather than {@link saveFileCache}) when the hash is already known, so the (possibly
+ * large) hash-input string does not have to be retained just to be re-hashed here.
+ */
+export declare function saveFileCacheEntry<T>(ref: FileCacheRef, entry: FileCacheEntry<T>): Promise<void>;
+/**
+ * Writes a cache entry as `{ hash: sha256(content), data }`. Convenience over
+ * {@link saveFileCacheEntry} for callers that hold the source `content` and want it hashed here.
+ */
+export declare function saveFileCache<T>(ref: FileCacheRef, content: string, data: T): Promise<void>;

package/pipeline/cacheUtils/saveFileCache.mjs

@@ -0,0 +1,54 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { threadId } from 'node:worker_threads';
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { resolveCachePath } from "./resolveCachePath.mjs";
+let tempCounter = 0;
+
+/**
+ * Writes a precomputed cache entry (`{ hash, data }`) atomically (temp file + rename) so a
+ * concurrent reader never observes a half-written file. Creates the cache directory tree as needed.
+ *
+ * Fails fast: any filesystem error propagates so a misconfigured cache directory surfaces loudly at
+ * build time. Callers that treat the write as best-effort (e.g. {@link withFileCache}) catch it.
+ *
+ * Use this (rather than {@link saveFileCache}) when the hash is already known, so the (possibly
+ * large) hash-input string does not have to be retained just to be re-hashed here.
+ */
+export async function saveFileCacheEntry(ref, entry) {
+  const cachePath = resolveCachePath(ref);
+  await mkdir(dirname(cachePath), {
+    recursive: true
+  });
+
+  // Write to a temp file then atomically rename over the target, so a torn write can never corrupt
+  // the cache file an in-flight reader is parsing. The temp name includes pid + threadId + a counter
+  // so two concurrent writers (including across worker_threads, which share a pid) never collide on
+  // it. The serialized string is transient.
+  tempCounter += 1;
+  const tempPath = `${cachePath}.${process.pid}.${threadId}.${tempCounter}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(entry), 'utf-8');
+    await rename(tempPath, cachePath);
+  } catch (error) {
+    try {
+      await rm(tempPath, {
+        force: true
+      });
+    } catch {
+      // Best-effort cleanup of the temp file; ignore.
+    }
+    throw error;
+  }
+}
+
+/**
+ * Writes a cache entry as `{ hash: sha256(content), data }`. Convenience over
+ * {@link saveFileCacheEntry} for callers that hold the source `content` and want it hashed here.
+ */
+export async function saveFileCache(ref, content, data) {
+  return saveFileCacheEntry(ref, {
+    hash: hashCacheContent(content),
+    data
+  });
+}

package/pipeline/cacheUtils/types.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Reference to a single cache entry on disk.
+ *
+ * The entry is stored at `{cacheDir}/{namespace}/{cacheKey}.json`. `cacheKey` may
+ * contain `/` separators to nest entries (e.g. `utilities/parsing`).
+ */
+export interface FileCacheRef {
+  /** Root cache directory. Relative paths resolve against the current working directory. */
+  cacheDir: string;
+  /** Subdirectory grouping related entries (e.g. `pages-index`). */
+  namespace: string;
+  /** Entry key, used as the file name without extension. May contain `/` for nesting. */
+  cacheKey: string;
+}
+/**
+ * On-disk shape of a cache entry: the validating content hash plus the cached value.
+ */
+export interface FileCacheEntry<T> {
+  /** sha256 hex digest of the source content the cached value was derived from. */
+  hash: string;
+  /** The cached value. */
+  data: T;
+}

package/pipeline/cacheUtils/types.mjs

@@ -0,0 +1 @@
+export {};

package/pipeline/cacheUtils/withFileCache.d.mts

@@ -0,0 +1,40 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * A read-through file cache task: fetch an origin, derive its validating content, and either
+ * return the cached result or compute a fresh one.
+ */
+export interface FileCacheTask<TOrigin, TData> {
+  /** The cache entry to use, or `undefined` to bypass the cache entirely. */
+  ref: FileCacheRef | undefined;
+  /** Fetches the origin (e.g. reads the source file). Runs concurrently with the cache read. */
+  readOrigin: () => Promise<TOrigin> | TOrigin;
+  /**
+   * Derives the string whose sha256 validates the cache from the origin — e.g. the file content,
+   * or the content combined with the options that affect the result. May differ from what the
+   * processor consumes.
+   */
+  getCacheContent: (origin: TOrigin) => string;
+  /** Computes the result from the origin on a cache miss. */
+  processor: (origin: TOrigin) => Promise<TData> | TData;
+}
+/**
+ * Standardizes the read-through cache flow shared by the page-index and types caches:
+ *
+ * 1. Read the cache entry while fetching and hashing the origin, so the two reads overlap and the
+ *    hash is ready before the cache read resolves.
+ * 2. On a hash match, return the cached data and skip the processor.
+ * 3. On a miss (or with no `ref`), run the processor and return its result.
+ *
+ * A rejection from `readOrigin`/`getCacheContent` surfaces to the caller; the in-flight cache read
+ * is abandoned safely because {@link loadFileCacheEntry} never rejects. Populating the cache is
+ * **best-effort** — a write failure (e.g. an unwritable cache dir) is swallowed (logged under
+ * DEBUG) and the freshly computed result is returned regardless, so a cache hiccup never fails the
+ * caller or drops its output. The explicit build/validate writers (syncPageIndex/syncTypes) call
+ * {@link saveFileCache} directly and stay fail-fast.
+ */
+export declare function withFileCache<TOrigin, TData>({
+  ref,
+  readOrigin,
+  getCacheContent,
+  processor
+}: FileCacheTask<TOrigin, TData>): Promise<TData>;

package/pipeline/cacheUtils/withFileCache.mjs

@@ -0,0 +1,81 @@
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+import { saveFileCacheEntry } from "./saveFileCache.mjs";
+// Set DOCS_INFRA_CACHE_DEBUG=1 to log cache hit/miss and best-effort write failures.
+const DEBUG = Boolean(process.env.DOCS_INFRA_CACHE_DEBUG);
+
+/**
+ * A read-through file cache task: fetch an origin, derive its validating content, and either
+ * return the cached result or compute a fresh one.
+ */
+
+/**
+ * Standardizes the read-through cache flow shared by the page-index and types caches:
+ *
+ * 1. Read the cache entry while fetching and hashing the origin, so the two reads overlap and the
+ *    hash is ready before the cache read resolves.
+ * 2. On a hash match, return the cached data and skip the processor.
+ * 3. On a miss (or with no `ref`), run the processor and return its result.
+ *
+ * A rejection from `readOrigin`/`getCacheContent` surfaces to the caller; the in-flight cache read
+ * is abandoned safely because {@link loadFileCacheEntry} never rejects. Populating the cache is
+ * **best-effort** — a write failure (e.g. an unwritable cache dir) is swallowed (logged under
+ * DEBUG) and the freshly computed result is returned regardless, so a cache hiccup never fails the
+ * caller or drops its output. The explicit build/validate writers (syncPageIndex/syncTypes) call
+ * {@link saveFileCache} directly and stay fail-fast.
+ */
+export async function withFileCache({
+  ref,
+  readOrigin,
+  getCacheContent,
+  processor
+}) {
+  if (!ref) {
+    return processor(await readOrigin());
+  }
+
+  // Start the cache read so it overlaps fetching and hashing the origin.
+  const cacheEntryPromise = loadFileCacheEntry(ref);
+  const origin = await readOrigin();
+  // Hash the cache content without binding it to a variable: the hash-input string can be large
+  // (e.g. a multi-MB JSON of the loaded types), and it is only needed to compute the hash — so we
+  // let it be collected immediately rather than retaining it through the cache read, the processor,
+  // and the write. saveFileCacheEntry below reuses the hash, so the content is never needed again.
+  const contentHash = hashCacheContent(getCacheContent(origin));
+  let cacheEntry = await cacheEntryPromise;
+  if (cacheEntry && cacheEntry.hash === contentHash) {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] hit ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return cacheEntry.data;
+  }
+
+  // Distinguish a stale (warm-but-mismatched) miss from a cold one — a perpetual writer/reader hash
+  // divergence surfaces here, and is exactly the failure DEBUG exists to make visible. Drop the
+  // stale entry before the processor runs so its (possibly multi-MB) data is not retained alongside
+  // the freshly computed result.
+  const wasStale = Boolean(cacheEntry);
+  cacheEntry = null;
+  if (DEBUG && wasStale) {
+    console.warn(`[docs-infra cache] stale ${ref.namespace}/${ref.cacheKey} (hash mismatch, recomputing)`);
+  }
+  const data = await processor(origin);
+  try {
+    await saveFileCacheEntry(ref, {
+      hash: contentHash,
+      data
+    });
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] miss → wrote ${ref.namespace}/${ref.cacheKey}`);
+    }
+  } catch (error) {
+    // Best-effort: any save failure — IO, the resolveCachePath traversal guard, or a serialization
+    // error on non-JSON-safe data — is swallowed so a misconfigured cache can never drop a page or
+    // fail a build; the computed result is returned regardless. The fail-fast writers (syncPageIndex
+    // and syncTypes, via saveFileCache) surface these instead. DEBUG logs them here.
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] write failed for ${ref.namespace}/${ref.cacheKey}:`, error);
+    }
+  }
+  return data;
+}

package/pipeline/hastUtils/hastUtils.d.mts

@@ -1,7 +1,7 @@
 import type * as React from 'react';
 import type { Nodes as HastNodes } from 'hast';
 import type { Components } from 'hast-util-to-jsx-runtime';
-import { type FallbackNode } from "./fallbackFormat.mjs";
+import type { FallbackNode } from "./fallbackFormat.mjs";
 export declare function hastToJsx(hast: HastNodes, components?: Partial<Components>): React.ReactNode;
 export declare function hastOrJsonToJsx(hastOrJson: HastNodes | {
   hastJson: string;

package/pipeline/hastUtils/hastUtils.mjs

@@ -3,7 +3,6 @@ import { toText } from 'hast-util-to-text';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
 import { decompressHast } from "./hastCompression.mjs";
 import { fallbackToText } from "./fallbackFormat.mjs";
-
 /**
  * Resolve the DEFLATE dictionary text for a `hastCompressed` payload from a
  * compact `fallback`. The loader compresses each file with its own fallback

package/pipeline/loadIsomorphicCodeSource/loadIsomorphicCodeSource.d.mts

@@ -1,5 +1,5 @@
 import type { LoadSource } from "../../CodeHighlighter/types.mjs";
-import { type StoreAtMode } from "../loaderUtils/processRelativeImports.mjs";
+import type { StoreAtMode } from "../loaderUtils/processRelativeImports.mjs";
 /**
  * Imports record passed to {@link LoadIsomorphicCodeSourceOptions.resolveImports}.
  *

package/pipeline/loadIsomorphicCodeSource/loadIsomorphicCodeSource.mjs

@@ -50,7 +50,7 @@ export function createLoadIsomorphicCodeSource(options) {
       externals,
       comments,
       code: processedCode
-    } = await parseImportsAndComments(source, url, {
+    } = parseImportsAndComments(source, url, {
       removeCommentsWithPrefix,
       notableCommentsPrefix
     });

package/pipeline/loadIsomorphicCodeVariant/applyCodeTransform.mjs

@@ -10,7 +10,6 @@
 import { decodeHastSource } from "./decodeHastSource.mjs";
 import { frameFallbackFromSpans } from "../hastUtils/index.mjs";
 import { applyCodeTransformWithComments as applyCodeTransformWithCommentsCore, applyCodeTransformsWithComments as applyCodeTransformsWithCommentsCore } from "./applyCodeTransformWithComments.mjs";
-
 // The built-in hast helpers, bound once for callers that don't inject their own
 // (the `loadIsomorphicCodeVariant` server/build pipeline, tests, etc.).
 const builtinDeps = {