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

package/CodeHighlighter/useGrammarsReady.mjs

@@ -3,6 +3,12 @@
 import * as React from 'react';
 import { areGrammarsRegistered, ensureGrammars } from "../pipeline/parseSource/grammarCache.mjs";
 
+// Safety-net deadline (ms) for the grammar load. A load that HANGS (a stalled dynamic
+// import that never settles) — rather than rejecting — would otherwise leave `ready`
+// false forever, wedging the block un-highlighted until a reload. After the deadline we
+// fail open (plain text) just like a hard rejection.
+const GRAMMAR_LOAD_TIMEOUT_MS = 10_000;
+
 /**
  * Gates client-side highlighting on grammar readiness. Under `CodeProviderLazy`,
  * grammars load per-language and on demand, so a block must wait until the
@@ -22,24 +28,53 @@ import { areGrammarsRegistered, ensureGrammars } from "../pipeline/parseSource/g
  */
 export function useGrammarsReady(scopes, enabled) {
   const [, forceUpdate] = React.useReducer(count => count + 1, 0);
+  // The scopes whose grammar load has definitively FAILED (a hard chunk-fetch error,
+  // not a partial register). Tracked so the block can fail OPEN — render plain text for
+  // those scopes — instead of wedging on `ready === false` forever (which would leave
+  // the code permanently un-highlighted until a reload). Stored as a CONTENT key (the
+  // joined scopes), not a reference, so it stays matched if the caller passes a fresh
+  // array — and a different set of scopes (a new language) still retries.
+  const [failedScopesKey, setFailedScopesKey] = React.useState(null);
 
-  // Nothing to wait for when disabled or when every scope is already registered.
-  const ready = !enabled || areGrammarsRegistered(scopes);
+  // Nothing to wait for when disabled or when every scope is already registered. The
+  // content key (joined scopes) drives both the fail-open match AND the effect dep, so
+  // the load runs once per scope-CONTENT set — not on every render when a caller passes
+  // a fresh `scopes` array (which would otherwise re-trigger `ensureGrammars`/timeouts).
+  const registered = areGrammarsRegistered(scopes);
+  const scopesKey = scopes.join('\n');
+  const ready = !enabled || registered || failedScopesKey === scopesKey;
   React.useEffect(() => {
-    if (ready) {
+    if (!enabled || registered) {
       return undefined;
     }
     let cancelled = false;
-    // Fails open: a load error still flips ready so the block highlights what it
-    // can (and renders plain text for any scope that failed to register).
-    ensureGrammars(scopes).finally(() => {
+    // Fail open on a hard rejection (catch) OR a hang (the timer): a grammar load that
+    // never settles would otherwise leave `ready` false forever — the same wedge.
+    const failOpen = () => {
       if (!cancelled) {
-        forceUpdate();
+        setFailedScopesKey(scopesKey);
+      }
+    };
+    const timer = setTimeout(failOpen, GRAMMAR_LOAD_TIMEOUT_MS);
+    (async () => {
+      try {
+        // Reconstruct from the content key so this effect depends only on the joined
+        // content (`scopesKey`), never the array reference.
+        await ensureGrammars(scopesKey.split('\n'));
+        // Registered now — re-render so `ready` recomputes to true.
+        if (!cancelled) {
+          forceUpdate();
+        }
+      } catch {
+        failOpen();
+      } finally {
+        clearTimeout(timer);
       }
-    });
+    })();
     return () => {
       cancelled = true;
+      clearTimeout(timer);
     };
-  }, [ready, scopes]);
+  }, [enabled, registered, scopesKey]);
   return ready;
 }

package/CodeProvider/CodeProvider.d.mts

@@ -26,4 +26,4 @@ export declare function CodeProvider({
   /** Function to load raw source code and dependencies */
   loadSource?: LoadSource;
   sourceEnhancers?: SourceEnhancers;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;

package/CodeProvider/CodeProviderLazy.d.mts

@@ -36,5 +36,5 @@ interface CodeProviderLazyProps {
 export declare function CodeProviderLazy({
   children,
   ...rest
-}: CodeProviderLazyProps): import("react/jsx-runtime").JSX.Element;
+}: CodeProviderLazyProps): React.JSX.Element;
 export {};

package/CodeProvider/createParseSourceWorkerClient.d.mts

@@ -42,6 +42,12 @@ export interface ParseSourceWorkerClient {
  *
  * Each client owns exactly one underlying `Worker`. Concurrent in-flight
  * requests are demuxed by a monotonically increasing `id`.
+ *
+ * If the worker dies unexpectedly (a load/parse failure, or a message that fails
+ * to deserialize), every in-flight parse request and pending `init`/`register`
+ * handshake is rejected and the client latches `dead`, so a crash surfaces as a
+ * rejected promise (which the consumer already handles like an abort, falling back
+ * to the synchronous highlighter) rather than a request that hangs forever.
  */
 export declare function createParseSourceWorkerClient(): ParseSourceWorkerClient;
 export {};

package/CodeProvider/createParseSourceWorkerClient.mjs

@@ -16,6 +16,12 @@
  *
  * Each client owns exactly one underlying `Worker`. Concurrent in-flight
  * requests are demuxed by a monotonically increasing `id`.
+ *
+ * If the worker dies unexpectedly (a load/parse failure, or a message that fails
+ * to deserialize), every in-flight parse request and pending `init`/`register`
+ * handshake is rejected and the client latches `dead`, so a crash surfaces as a
+ * rejected promise (which the consumer already handles like an abort, falling back
+ * to the synchronous highlighter) rather than a request that hangs forever.
  */
 export function createParseSourceWorkerClient() {
   // Module workers are required (the worker uses `import` statements). On
@@ -36,6 +42,45 @@ export function createParseSourceWorkerClient() {
   const pending = new Map();
   let nextId = 1;
   let initPromise = null;
+  // Latched once the worker dies or is terminated, so later calls reject immediately
+  // rather than hanging on a worker that will never respond.
+  let dead = false;
+  // Reject callbacks for in-flight `init()`/`register()` handshakes, so a worker
+  // crash can fail them too (they listen on their own one-shot listeners, not
+  // `pending`). Each clears itself on settle.
+  const handshakeRejecters = new Set();
+
+  // Reject + forget every in-flight parse request with `reason`, detaching abort
+  // listeners first. Shared by `terminate()` (intentional) and the fatal-error path.
+  const rejectAllPending = reason => {
+    for (const entry of pending.values()) {
+      if (entry.signal && entry.onAbort) {
+        entry.signal.removeEventListener('abort', entry.onAbort);
+      }
+      entry.reject(reason);
+    }
+    pending.clear();
+  };
+
+  // The worker died unexpectedly — a load/parse failure, or a message that could not
+  // be deserialized. (A parse that merely fails is reported as an `ok: false`
+  // response, so it never reaches here.) Reject everything in flight — parse requests
+  // AND pending `init`/`register` handshakes — and latch `dead`; the consumer treats
+  // the rejection like an abort and falls back to the synchronous highlighter.
+  // Idempotent. (Unlike a crash, a deliberate `terminate()` leaves handshakes alone:
+  // the component is unmounting, so a still-pending `init` is simply abandoned.)
+  const handleFatal = error => {
+    if (dead) {
+      return;
+    }
+    dead = true;
+    worker.terminate();
+    rejectAllPending(error);
+    for (const reject of [...handshakeRejecters]) {
+      reject(error);
+    }
+    handshakeRejecters.clear();
+  };
   worker.addEventListener('message', event => {
     const data = event.data;
     if (data.type === 'init-ack' || data.type === 'init-error' || data.type === 'register-ack' || data.type === 'register-error') {
@@ -60,20 +105,34 @@ export function createParseSourceWorkerClient() {
       }
     }
   });
+  worker.addEventListener('error', event => {
+    handleFatal(new Error(event.message || 'Parse worker errored'));
+  });
+  worker.addEventListener('messageerror', () => {
+    handleFatal(new Error('Parse worker received an undeserializable message'));
+  });
   function init(grammars) {
     if (initPromise) {
       return initPromise;
     }
+    if (dead) {
+      return Promise.reject(new Error('Parse worker is no longer available'));
+    }
     initPromise = new Promise((resolve, reject) => {
-      const onMessage = event => {
+      const settle = () => {
+        handshakeRejecters.delete(reject);
+        worker.removeEventListener('message', onMessage);
+      };
+      function onMessage(event) {
         if (event.data.type === 'init-ack') {
-          worker.removeEventListener('message', onMessage);
+          settle();
           resolve();
         } else if (event.data.type === 'init-error') {
-          worker.removeEventListener('message', onMessage);
+          settle();
           reject(new Error(event.data.error));
         }
-      };
+      }
+      handshakeRejecters.add(reject);
       worker.addEventListener('message', onMessage);
       worker.postMessage({
         type: 'init',
@@ -83,16 +142,24 @@ export function createParseSourceWorkerClient() {
     return initPromise;
   }
   function register(grammars) {
+    if (dead) {
+      return Promise.reject(new Error('Parse worker is no longer available'));
+    }
     return new Promise((resolve, reject) => {
-      const onMessage = event => {
+      const settle = () => {
+        handshakeRejecters.delete(reject);
+        worker.removeEventListener('message', onMessage);
+      };
+      function onMessage(event) {
         if (event.data.type === 'register-ack') {
-          worker.removeEventListener('message', onMessage);
+          settle();
           resolve();
         } else if (event.data.type === 'register-error') {
-          worker.removeEventListener('message', onMessage);
+          settle();
           reject(new Error(event.data.error));
         }
-      };
+      }
+      handshakeRejecters.add(reject);
       worker.addEventListener('message', onMessage);
       worker.postMessage({
         type: 'register',
@@ -104,10 +171,16 @@ export function createParseSourceWorkerClient() {
     if (!initPromise) {
       throw new Error('parseSourceAsync called before init(). Call client.init(grammars) first.');
     }
+    if (dead) {
+      throw new Error('Parse worker is no longer available');
+    }
     if (signal?.aborted) {
       throw signal.reason;
     }
     await initPromise;
+    if (dead) {
+      throw new Error('Parse worker is no longer available');
+    }
     if (signal?.aborted) {
       throw signal.reason;
     }
@@ -146,14 +219,9 @@ export function createParseSourceWorkerClient() {
     });
   };
   function terminate() {
+    dead = true;
     worker.terminate();
-    for (const entry of pending.values()) {
-      if (entry.signal && entry.onAbort) {
-        entry.signal.removeEventListener('abort', entry.onAbort);
-      }
-      entry.reject(new Error('Worker terminated'));
-    }
-    pending.clear();
+    rejectAllPending(new Error('Worker terminated'));
   }
   return {
     init,

package/CodeProvider/useCodeProviderValue.mjs

@@ -17,6 +17,15 @@ import { parseControlledCode } from "../CodeHighlighter/parseControlledCode.mjs"
  * the heavy modules out of the lazy provider's chunk.
  */
 
+// The source parser (Starry Night's regex engine + grammar chunks) is created from a
+// dynamically-imported, memoized promise. A transient load failure (a CDN/network
+// blip) would otherwise reject that promise ONCE and never retry — leaving
+// `parseSource` undefined forever, which strands every client-highlighted block as
+// plain text until a FULL PAGE RELOAD. Retry a bounded number of times, with a short
+// backoff, so a transient blip self-heals without a reload.
+const MAX_PARSER_ATTEMPTS = 3;
+const PARSER_RETRY_DELAY_MS = 500;
+
 /**
  * Builds the {@link CodeContext} value shared by `CodeProvider` and
  * `CodeProviderLazy`: the (browser-only, lazily-initialized) source parser, the
@@ -36,6 +45,9 @@ export function useCodeProviderValue(props, heavy,
 createSourceParser) {
   const [parseSource, setParseSource] = React.useState(undefined);
   const [parseSourceAsync, setParseSourceAsync] = React.useState(undefined);
+  // Bumped to re-create the (memoized) source parser after a failed load, so a
+  // transient failure can recover instead of wedging highlighting (see below).
+  const [parserAttempt, setParserAttempt] = React.useState(0);
   const sourceParser = React.useMemo(() => {
     // Only initialize Starry Night in the browser, not during SSR
     if (typeof window === 'undefined') {
@@ -43,12 +55,46 @@ createSourceParser) {
         throw new Error('parseSource not available during SSR');
       });
     }
+
+    // `parserAttempt` is a dep so a retry creates a FRESH parser promise (the previous
+    // one stays rejected); see the effect below. The value isn't read in the body — it's
+    // a deliberate cache-bust — so exhaustive-deps flags it as "unnecessary".
     return createSourceParser();
-  }, [createSourceParser]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- parserAttempt is a deliberate retry cache-bust
+  }, [createSourceParser, parserAttempt]);
   React.useEffect(() => {
-    // Update the sync version when available
-    sourceParser.then(parseSourceFn => setParseSource(() => parseSourceFn));
-  }, [sourceParser]);
+    // Resolve the parser and publish the sync version. On failure, retry with backoff
+    // rather than leaving the rejection unhandled and `parseSource` undefined forever
+    // (which strands every client-highlighted block as plain text until a reload).
+    let cancelled = false;
+    let retryTimer;
+    (async () => {
+      try {
+        const parseSourceFn = await sourceParser;
+        if (!cancelled) {
+          setParseSource(() => parseSourceFn);
+        }
+      } catch (error) {
+        if (cancelled) {
+          return;
+        }
+        console.error('Failed to initialize the source parser.', error);
+        if (parserAttempt < MAX_PARSER_ATTEMPTS) {
+          retryTimer = setTimeout(() => {
+            if (!cancelled) {
+              setParserAttempt(attempt => attempt + 1);
+            }
+          }, PARSER_RETRY_DELAY_MS * (parserAttempt + 1));
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+      if (retryTimer !== undefined) {
+        clearTimeout(retryTimer);
+      }
+    };
+  }, [sourceParser, parserAttempt]);
 
   // Worker for off-main-thread parsing during live editing. Created LAZILY on the
   // first editable block (via `ensureParseSourceWorker`), not on mount, and

package/abstractCreateDemo/abstractCreateDemo.d.mts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { Code, CodeHighlighterProps, ContentLoadingProps, ContentProps, LoadCodeMeta, LoadSource, LoadVariantMeta, ParseSource, SourceEnhancers } from "../CodeHighlighter/types.mjs";
-import { type DemoGlobalData } from "../createDemoData/types.mjs";
+import type { DemoGlobalData } from "../createDemoData/types.mjs";
 type CreateDemoMeta = {
   name?: string;
   slug?: string;
@@ -36,6 +36,14 @@ type CreateDemoMeta = {
    * collapsed instead. Mirrors the demo component's `initialCollapsed` prop.
    */
   initialCollapsed?: boolean;
+  /**
+   * Start this demo's editable code read-only (a truthy value), leaving it to a
+   * `setEditable` toggle to turn editing on. Overrides a factory `initialDisabled`
+   * default (set in the `createDemoFactory` call). Distinct from `editActivation` (which
+   * only defers *when* the engine loads) and from the hard `disabled` opt (which forbids
+   * editing entirely).
+   */
+  initialDisabled?: boolean;
 };
 type AbstractCreateDemoOptions<T extends {}> = {
   DemoContent: React.ComponentType<ContentProps<T>>;
@@ -69,6 +77,12 @@ type AbstractCreateDemoOptions<T extends {}> = {
    * override with `meta.initialExpanded: false` or `<Demo initialExpanded={false} />`.
    */
   initialExpanded?: boolean;
+  /**
+   * Default every demo from this factory to start its editable code read-only — a
+   * reader toggles it on per demo with `setEditable`. Individual demos override with
+   * `meta.initialDisabled: false` or `<Demo initialDisabled={false} />`.
+   */
+  initialDisabled?: boolean;
   /**
    * `file://` URL of the project root used to resolve `url`s gathered from
    * `import.meta.url`. Combined with `projectUrl` to rewrite local `file://`

package/abstractCreateDemo/abstractCreateDemo.mjs

@@ -50,6 +50,7 @@ export function abstractCreateDemo(options, url, variants, meta) {
       showCollapsedFocus: instanceShowCollapsedFocus,
       initialExpanded: instanceInitialExpanded,
       initialCollapsed: instanceInitialCollapsed,
+      initialDisabled: instanceInitialDisabled,
       ...restProps
     } = props;
     const collapseToEmpty = resolveDemoFlag([{
@@ -66,6 +67,12 @@ export function abstractCreateDemo(options, url, variants, meta) {
       on: meta?.initialExpanded,
       off: meta?.initialCollapsed
     }], options.initialExpanded);
+    // Single flag (no off-cascade): instance prop → demo `meta` → factory default.
+    const initialDisabled = resolveDemoFlag([{
+      on: instanceInitialDisabled
+    }, {
+      on: meta?.initialDisabled
+    }], options.initialDisabled);
     const highlighter = /*#__PURE__*/_jsx(CodeHighlighter, {
       url: resolvedUrl,
       name: demoData.name,
@@ -77,6 +84,7 @@ export function abstractCreateDemo(options, url, variants, meta) {
       contentProps: restProps,
       collapseToEmpty: collapseToEmpty,
       initialExpanded: initialExpanded,
+      initialDisabled: initialDisabled,
       Content: options.DemoContent,
       ContentLoading: options.DemoContentLoading,
       loadCodeMeta: options.loadCodeMeta,

package/abstractCreateDemoClient/abstractCreateDemoClient.mjs

@@ -38,10 +38,13 @@ export function abstractCreateDemoClient(options, url, meta) {
   function ClientProvider({
     children
   }) {
+    // Pass the demo's own `url` so a controller can use it as a stable per-demo key
+    // (e.g. for cross-tab sync); the demo url wins over any `controllerProps.url`.
     if (controllerProps != null) {
       return /*#__PURE__*/_jsx(CodeExternalsContext.Provider, {
         value: context,
         children: /*#__PURE__*/React.createElement(DemoController, Object.assign({}, controllerProps, {
+          url,
           children
         }))
       });
@@ -49,6 +52,7 @@ export function abstractCreateDemoClient(options, url, meta) {
     return /*#__PURE__*/_jsx(CodeExternalsContext.Provider, {
       value: context,
       children: /*#__PURE__*/React.createElement(DemoController, Object.assign({}, {
+        url,
         children
       }))
     });

package/abstractCreateTypes/abstractCreateTypes.d.mts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import type { PluggableList } from 'unified';
 import type { HighlightedTypesMeta } from '@mui/internal-docs-infra/pipeline/loadServerTypes';
 import type { ModuleLinkMapEntry } from "../pipeline/enhanceCodeTypes/scanState.mjs";
-import { type TypesJsxOptions } from "./typesToJsx.mjs";
+import type { TypesJsxOptions } from "./typesToJsx.mjs";
 import type { TypesTableProps } from "../useTypes/useTypes.mjs";
 /**
  * Export data structure containing a main type and its related additional types.
@@ -63,6 +63,11 @@ export type TypesTableMeta = {
    * When set, overrides the factory-level TypePre.
    */
   TypePre?: TypesJsxOptions['TypePre'];
+  /**
+   * Override pre component for shortType code blocks.
+   * When set, overrides the factory-level ShortTypePre.
+   */
+  ShortTypePre?: TypesJsxOptions['ShortTypePre'];
   /**
    * Override pre component for detailed type blocks.
    * When set, overrides the factory-level DetailedTypePre.
@@ -166,6 +171,12 @@ export type AbstractCreateTypesOptions<T extends {} = {}> = {
    * Can be overridden by TypesTableMeta.TypePre.
    */
   TypePre: TypesJsxOptions['TypePre'];
+  /**
+   * Optional pre component for shortType code blocks.
+   * Falls back to `TypePre` when not provided.
+   * Can be overridden by TypesTableMeta.ShortTypePre.
+   */
+  ShortTypePre?: TypesJsxOptions['ShortTypePre'];
   /**
    * Optional pre component for detailed type blocks.
    * Falls back to `TypePre` when not provided.

package/abstractCreateTypes/abstractCreateTypes.mjs

@@ -38,6 +38,7 @@ export function abstractCreateTypes(options, url, meta, exportName) {
 
   // Resolve named component slots (meta overrides options)
   const TypePre = meta.TypePre ?? options.TypePre;
+  const ShortTypePre = meta.ShortTypePre ?? options.ShortTypePre;
   const DetailedTypePre = meta.DetailedTypePre ?? options.DetailedTypePre;
   const ShortTypeCode = meta.ShortTypeCode ?? options.ShortTypeCode;
   const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
@@ -122,6 +123,7 @@ export function abstractCreateTypes(options, url, meta, exportName) {
     } = React.useMemo(() => typeToJsx(precompute.exports[targetExportName], filteredAdditionalTypes, {
       components,
       TypePre,
+      ShortTypePre,
       DetailedTypePre,
       ShortTypeCode,
       DefaultCode,
@@ -211,6 +213,7 @@ function createAdditionalTypesComponent(options, url, meta) {
 
   // Resolve named component slots (meta overrides options)
   const TypePre = meta.TypePre ?? options.TypePre;
+  const ShortTypePre = meta.ShortTypePre ?? options.ShortTypePre;
   const DetailedTypePre = meta.DetailedTypePre ?? options.DetailedTypePre;
   const ShortTypeCode = meta.ShortTypeCode ?? options.ShortTypeCode;
   const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
@@ -271,6 +274,7 @@ function createAdditionalTypesComponent(options, url, meta) {
     const additionalTypes = React.useMemo(() => additionalTypesToJsx(allAdditionalTypes, {
       components,
       TypePre,
+      ShortTypePre,
       DetailedTypePre,
       ShortTypeCode,
       DefaultCode,

package/abstractCreateTypes/typesToJsx.d.mts

@@ -24,6 +24,14 @@ export type TypesJsxOptions = {
   DetailedTypePre?: React.ComponentType<{
     children: React.ReactNode;
   }>;
+  /**
+   * Optional pre component for shortType code blocks.
+   * Rendered inside phrasing content (e.g. a table trigger), so it should emit
+   * inline markup. Falls back to `TypePre` when not provided.
+   */
+  ShortTypePre?: React.ComponentType<{
+    children: React.ReactNode;
+  }>;
   /**
    * Optional code component for shortType fields.
    * Falls back to `components.code` when not provided.

package/abstractCreateTypes/typesToJsx.mjs

@@ -109,6 +109,7 @@ function resolveFieldMaps(options) {
     type: typeMap,
     shortType: options.ShortTypeCode ? {
       ...typeMap,
+      pre: options.ShortTypePre ?? options.TypePre,
       code: options.ShortTypeCode
     } : typeMap,
     default: options.DefaultCode ? {
@@ -878,7 +879,7 @@ function enhanceClassType(classData, components, fieldMaps, enhancers, enhancers
       ...method,
       description: method.description && hastToJsx(method.description, components, enhancers),
       parameters: enhancedMethodParams,
-      returnValue: hastToJsx(method.returnValue, fieldMaps.type, enhancers),
+      returnValue: hastToJsx(method.returnValue, fieldMaps.shortType, enhancersInline),
       returnValueDescription: method.returnValueDescription && hastToJsx(method.returnValueDescription, components, enhancers)
     };
     return [methodName, enhancedMethod];

package/cli/loadNextConfig.d.mts

@@ -23,11 +23,20 @@ export type ExtractedNextConfigOptions = {
   descriptionReplacements?: DescriptionReplacement[];
   useVisibleDescription?: boolean;
   socketDir?: string;
+  /** Page-index cache directory configured on the sitemap loader. */
+  cacheDir?: string;
   /** Demo index patterns that opted into automatic `client.ts` generation. */
   demoClientRequirements?: DemoClientRequirement[];
   /** Demo index patterns that opted into automatic `page.tsx` generation. */
   demoPageRequirements?: DemoPageRequirement[];
 };
+/**
+ * Searches turbopack rules for docs-infra options (ordering,
+ * descriptionReplacements, socketDir, useVisibleDescription, cacheDir).
+ *
+ * Exported for tests.
+ */
+export declare function extractOptionsFromTurbopack(config: any): ExtractedNextConfigOptions;
 /**
  * Walks Turbopack rules to collect demo patterns that opted into automatic
  * `page.tsx` generation via the `requirePage` option.

package/cli/loadNextConfig.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createJiti } from 'jiti';
 const TYPES_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedTypes';
+const SITEMAP_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedSitemap';
 const CODE_HIGHLIGHTER_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter';
 const TRANSFORM_METADATA_PLUGIN = '@mui/internal-docs-infra/pipeline/transformMarkdownMetadata';
 const TRANSFORM_METADATA_PLUGIN_FUNCTION_NAME = 'transformMarkdownMetadata';
@@ -49,6 +50,9 @@ function extractOptionsFromLoaderEntries(loaders) {
     if (!result.socketDir && loader.loader === TYPES_LOADER && typeof loader.options?.socketDir === 'string') {
       result.socketDir = loader.options.socketDir;
     }
+    if (!result.cacheDir && loader.loader === SITEMAP_LOADER && typeof loader.options?.cacheDir === 'string') {
+      result.cacheDir = loader.options.cacheDir;
+    }
     if (result.useVisibleDescription === undefined && loader.options?.remarkPlugins) {
       const extracted = extractUseVisibleDescriptionFromRemarkPlugins(loader.options.remarkPlugins);
       if (typeof extracted === 'boolean') {
@@ -61,9 +65,11 @@ function extractOptionsFromLoaderEntries(loaders) {
 
 /**
  * Searches turbopack rules for docs-infra options (ordering,
- * descriptionReplacements, socketDir, useVisibleDescription).
+ * descriptionReplacements, socketDir, useVisibleDescription, cacheDir).
+ *
+ * Exported for tests.
  */
-function extractOptionsFromTurbopack(config) {
+export function extractOptionsFromTurbopack(config) {
   const rules = config?.turbopack?.rules;
   if (!rules) {
     return {};
@@ -79,6 +85,7 @@ function extractOptionsFromTurbopack(config) {
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
+    merged.cacheDir ??= extracted.cacheDir;
   }
   return merged;
 }
@@ -166,6 +173,7 @@ function extractOptionsFromWebpackResult(result) {
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
+    merged.cacheDir ??= extracted.cacheDir;
   }
   return merged;
 }
@@ -323,6 +331,7 @@ export async function extractDocsInfraOptionsFromNextConfig(dir) {
     descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
     useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
     socketDir: turbopack.socketDir ?? webpack.socketDir,
+    cacheDir: turbopack.cacheDir ?? webpack.cacheDir,
     demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined,
     demoPageRequirements: demoPageRequirements.length > 0 ? demoPageRequirements : undefined
   };