@mui/internal-docs-infra 0.10.1-canary.7 → 0.11.1-canary.1

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { ControlledCode } from "../CodeHighlighter/types.mjs";
+import type { ControlledCode, SourceEnhancers } from "../CodeHighlighter/types.mjs";
 export type Selection = {
   variant: string;
   fileName?: string;
@@ -43,6 +43,11 @@ export interface CodeControllerContext {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode> | undefined;
+  /**
+   * Additional source enhancers to apply to parsed HAST sources.
+   * These are merged with enhancers from CodeProvider and useCode opts.
+   */
+  sourceEnhancers?: SourceEnhancers;
 }
 export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
 /**
@@ -66,4 +71,5 @@ export declare function useControlledCode(): {
   setCode: React.Dispatch<React.SetStateAction<ControlledCode | undefined>> | undefined;
   setSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
   components: Record<string, React.ReactNode> | undefined;
+  sourceEnhancers: SourceEnhancers | undefined;
 };

package/CodeControllerContext/CodeControllerContext.mjs

@@ -35,6 +35,7 @@ export function useControlledCode() {
     selection: context?.selection,
     setCode: context?.setCode,
     setSelection: context?.setSelection,
-    components: context?.components
+    components: context?.components,
+    sourceEnhancers: context?.sourceEnhancers
   };
 }

package/CodeHighlighter/CodeHighlighter.mjs

@@ -1,10 +1,11 @@
 import * as React from 'react';
-import { loadCodeVariant } from "../pipeline/loadCodeVariant/loadCodeVariant.mjs";
-import { loadCodeFallback } from "../pipeline/loadCodeVariant/loadCodeFallback.mjs";
+import { loadIsomorphicCodeVariant } from "../pipeline/loadIsomorphicCodeVariant/loadIsomorphicCodeVariant.mjs";
+import { loadCodeFallback } from "../pipeline/loadIsomorphicCodeVariant/loadCodeFallback.mjs";
 import { CodeHighlighterClient } from "./CodeHighlighterClient.mjs";
-import { maybeCodeInitialData } from "../pipeline/loadCodeVariant/maybeCodeInitialData.mjs";
-import { hasAllVariants } from "../pipeline/loadCodeVariant/hasAllCodeVariants.mjs";
+import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs";
+import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
 import { getFileNameFromUrl, getLanguageFromExtension } from "../pipeline/loaderUtils/index.mjs";
+import { replaceUrlPrefix } from "../pipeline/loaderUtils/applyUrlPrefix.mjs";
 import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -13,17 +14,25 @@ const DEBUG = false; // Set to true for debugging purposes
 function createClientProps(props) {
   const highlightAfter = props.highlightAfter === 'stream' ? 'init' : props.highlightAfter;
   const enhanceAfter = props.enhanceAfter === 'stream' ? 'init' : props.enhanceAfter;
+
+  // Rewrite the top-level URL before it leaves the server. The client never
+  // receives `urlPrefix` (and shouldn't deal with `file://` URLs), so any
+  // local URL must be translated to its hosted form here. Variant-level URLs
+  // inside `code`/`precompute` are already rewritten upstream (by
+  // `loadIsomorphicCodeVariant` on the server, or by the demo factory for precomputed
+  // input).
+  const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
   const contentProps = {
     code: props.code || props.precompute,
     components: props.components,
     name: props.name,
     slug: props.slug,
-    url: props.url,
+    url,
     variantType: props.variantType,
     ...props.contentProps
   };
   return {
-    url: props.url,
+    url,
     code: props.code,
     precompute: props.precompute,
     components: props.components,
@@ -115,14 +124,15 @@ async function CodeSourceLoader(props) {
     } else if (props.deferParsing === 'none') {
       output = 'hast';
     }
-    return loadCodeVariant(variantUrl, variantName, variantCode, {
+    return loadIsomorphicCodeVariant(variantUrl, variantName, variantCode, {
       sourceParser: props.sourceParser,
       loadSource: props.loadSource,
       loadVariantMeta: props.loadVariantMeta,
       sourceTransformers: props.sourceTransformers,
       sourceEnhancers: props.sourceEnhancers,
       globalsCode: resolvedGlobalsCode,
-      output
+      output,
+      urlPrefix: props.urlPrefix
     }).then(variant => ({
       name: variantName,
       variant
@@ -182,7 +192,6 @@ async function CodeHighlighterSuspense(props) {
 function renderWithInitialSource(props) {
   const ContentLoading = props.ContentLoading;
   const {
-    url,
     slug,
     name,
     initialVariant,
@@ -191,6 +200,11 @@ function renderWithInitialSource(props) {
     fallbackUsesExtraFiles,
     fallbackUsesAllVariants
   } = props;
+
+  // Rewrite the top-level URL before it reaches the loading fallback so the
+  // browser never sees `file://` URLs. See `createClientProps` for the same
+  // rewrite on the regular client path.
+  const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
   const fallbackProps = codeToFallbackProps(initialVariant, code, initialFilename, fallbackUsesExtraFiles, fallbackUsesAllVariants);
 
   // Get the component for the selected variant
@@ -272,7 +286,8 @@ async function CodeInitialSourceLoader(props) {
     initialFilename: fileName,
     variants,
     globalsCode,
-    output
+    output,
+    urlPrefix: props.urlPrefix
   });
   return renderWithInitialSource({
     ...props,

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -3,12 +3,12 @@
 import * as React from 'react';
 import { useCodeContext } from "../CodeProvider/CodeContext.mjs";
 import { CodeHighlighterContext } from "./CodeHighlighterContext.mjs";
-import { maybeCodeInitialData } from "../pipeline/loadCodeVariant/maybeCodeInitialData.mjs";
-import { hasAllVariants } from "../pipeline/loadCodeVariant/hasAllCodeVariants.mjs";
+import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs";
+import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
 import { CodeHighlighterFallbackContext } from "./CodeHighlighterFallbackContext.mjs";
 import { useControlledCode } from "../CodeControllerContext/index.mjs";
 import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
-import { mergeCodeMetadata } from "../pipeline/loadCodeVariant/mergeCodeMetadata.mjs";
+import { mergeCodeMetadata } from "../pipeline/loadIsomorphicCodeVariant/mergeCodeMetadata.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
@@ -50,6 +50,11 @@ function useInitialData({
     }
   }
 
+  // Signal to downstream loaders that a fallback fetch is pending. Used to gate
+  // `useAllVariants` so it can reuse the data populated by the fallback rather
+  // than racing it and re-fetching the same variant.
+  const fallbackPending = Boolean(needsFallback && url && loadCodeFallback);
+
   // TODO: fallbackInitialRenderOnly option? this would mean we can't fetch fallback data on the client side
   // Load initial data if not provided
   React.useEffect(() => {
@@ -90,6 +95,9 @@ function useInitialData({
       }
     })();
   }, [initialData, reason, needsFallback, variantName, code, setCode, highlightAfter, url, sourceParser, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, fallbackUsesExtraFiles, fallbackUsesAllVariants, fileName, variants, globalsCode, setProcessedGlobalsCode, loadCodeFallback]);
+  return {
+    fallbackPending
+  };
 }
 function useAllVariants({
   readyForContent,
@@ -100,16 +108,17 @@ function useAllVariants({
   setCode,
   processedGlobalsCode,
   globalsCode,
-  setProcessedGlobalsCode
+  setProcessedGlobalsCode,
+  fallbackPending
 }) {
   const {
     loadCodeMeta,
     loadVariantMeta,
     loadSource,
-    loadCodeVariant,
+    loadIsomorphicCodeVariant,
     sourceEnhancers
   } = useCodeContext();
-  const needsData = !readyForContent && !isControlled;
+  const needsData = !readyForContent && !isControlled && !fallbackPending;
 
   // validation
   React.useMemo(() => {
@@ -117,7 +126,7 @@ function useAllVariants({
       if (!url) {
         throw new Errors.ErrorCodeHighlighterClientMissingUrlForVariants();
       }
-      if (!loadCodeVariant) {
+      if (!loadIsomorphicCodeVariant) {
         throw new Errors.ErrorCodeHighlighterClientMissingLoadVariant(url);
       }
       if (!code && !loadCodeMeta) {
@@ -143,9 +152,9 @@ function useAllVariants({
         throw new Errors.ErrorCodeHighlighterClientMissingLoadSourceForUnloadedUrls();
       }
     }
-  }, [code, globalsCode, loadCodeMeta, loadCodeVariant, loadSource, needsData, url]);
+  }, [code, globalsCode, loadCodeMeta, loadIsomorphicCodeVariant, loadSource, needsData, url]);
   React.useEffect(() => {
-    if (!needsData || !url || !loadCodeVariant) {
+    if (!needsData || !url || !loadIsomorphicCodeVariant) {
       return;
     }
 
@@ -190,7 +199,7 @@ function useAllVariants({
             // Only include if this variant exists in the globalsCode
             return codeObj[name];
           }).filter(item => Boolean(item));
-          return loadCodeVariant(url, name, loadedCode[name], {
+          return loadIsomorphicCodeVariant(url, name, loadedCode[name], {
             disableParsing: true,
             disableTransforms: true,
             loadSource,
@@ -222,7 +231,7 @@ function useAllVariants({
         console.error(new Errors.ErrorCodeHighlighterClientLoadAllVariantsFailure(url, error));
       }
     })();
-  }, [needsData, variants, url, code, setCode, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, processedGlobalsCode, globalsCode, setProcessedGlobalsCode, loadCodeVariant]);
+  }, [needsData, variants, url, code, setCode, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, processedGlobalsCode, globalsCode, setProcessedGlobalsCode, loadIsomorphicCodeVariant]);
   return {
     readyForContent
   };
@@ -246,6 +255,7 @@ function useCodeParsing({
   url
 }) {
   const {
+    sourceParser,
     parseSource,
     parseCode
   } = useCodeContext();
@@ -285,6 +295,12 @@ function useCodeParsing({
       return undefined;
     }
     if (!parseSource) {
+      // A CodeProvider is present and its async `sourceParser` promise hasn't
+      // resolved yet — wait for it instead of erroring. The memo will re-run
+      // once `parseSource` is populated.
+      if (sourceParser) {
+        return undefined;
+      }
       if (forceClient) {
         console.error(new Errors.ErrorCodeHighlighterClientMissingParseSource(url, true));
       } else {
@@ -301,7 +317,7 @@ function useCodeParsing({
       return undefined;
     }
     return parseCode(code, parseSource);
-  }, [code, shouldHighlight, parseSource, parseCode, forceClient, url]);
+  }, [code, shouldHighlight, sourceParser, parseSource, parseCode, forceClient, url]);
   const deferHighlight = !shouldHighlight;
   return {
     parsedCode,
@@ -354,7 +370,8 @@ function useCodeTransforms({
 function useControlledCodeParsing({
   code,
   forceClient,
-  url
+  url,
+  preParsedCache
 }) {
   const {
     parseSource,
@@ -384,8 +401,8 @@ function useControlledCodeParsing({
       }
       return undefined;
     }
-    return parseControlledCode(code, parseSource);
-  }, [code, parseSource, parseControlledCode, forceClient, url]);
+    return parseControlledCode(code, parseSource, preParsedCache);
+  }, [code, parseSource, parseControlledCode, forceClient, url, preParsedCache]);
   return {
     parsedControlledCode
   };
@@ -403,7 +420,7 @@ function useGlobalsCodeMerging({
     loadCodeMeta,
     loadSource,
     loadVariantMeta,
-    loadCodeVariant
+    loadIsomorphicCodeVariant
   } = useCodeContext();
 
   // Set processedGlobalsCode if we have ready Code objects but haven't stored them yet
@@ -423,7 +440,7 @@ function useGlobalsCodeMerging({
       }
       // If not all ready, fall through to loading logic below
     }
-    if (!loadCodeVariant) {
+    if (!loadIsomorphicCodeVariant) {
       console.error(new Errors.ErrorCodeHighlighterClientMissingLoadVariantForGlobals());
       return;
     }
@@ -469,7 +486,7 @@ function useGlobalsCodeMerging({
 
             // Need to load this variant
             try {
-              const result = await loadCodeVariant(originalUrl || '',
+              const result = await loadIsomorphicCodeVariant(originalUrl || '',
               // Use the original URL if available
               variantName, codeObj[variantName],
               // May be undefined or string
@@ -492,7 +509,7 @@ function useGlobalsCodeMerging({
         console.error(new Errors.ErrorCodeHighlighterClientLoadGlobalsCodeFailure(url || 'No URL', error));
       }
     })();
-  }, [url, globalsCode, processedGlobalsCode, setProcessedGlobalsCode, loadCodeMeta, loadSource, loadVariantMeta, variants, loadCodeVariant]);
+  }, [url, globalsCode, processedGlobalsCode, setProcessedGlobalsCode, loadCodeMeta, loadSource, loadVariantMeta, variants, loadIsomorphicCodeVariant]);
 
   // Determine globalsCodeObjects to use (prefer processed, fallback to direct if ready)
   const globalsCodeObjects = React.useMemo(() => {
@@ -674,7 +691,9 @@ export function CodeHighlighterClient(props) {
     fallbackUsesExtraFiles,
     fallbackUsesAllVariants
   } = props;
-  useInitialData({
+  const {
+    fallbackPending
+  } = useInitialData({
     variants,
     variantName,
     code,
@@ -747,7 +766,8 @@ export function CodeHighlighterClient(props) {
     setCode,
     processedGlobalsCode,
     globalsCode: props.globalsCode,
-    setProcessedGlobalsCode
+    setProcessedGlobalsCode,
+    fallbackPending
   });
 
   // Merge globalsCode with internal state code (fetched data) - this should be stable once ready
@@ -790,12 +810,20 @@ export function CodeHighlighterClient(props) {
     parsedCode,
     variantName
   });
+
+  // Per-highlighter pre-parsed HAST cache. Lives in a ref so the same Map
+  // instance is shared across renders without becoming a React dep. The
+  // editable populates it via `useSourceEditing` (which reads it from
+  // `CodeHighlighterContext`), and `parseControlledCode` consults it on
+  // every render to skip the sync main-thread parse on exact source matches.
+  const [preParsedCache] = React.useState(() => new Map());
   const {
     parsedControlledCode
   } = useControlledCodeParsing({
     code: controlled?.code,
     forceClient: props.forceClient,
-    url: props.url
+    url: props.url,
+    preParsedCache
   });
 
   // Determine the final overlaid code (controlled takes precedence)
@@ -803,7 +831,7 @@ export function CodeHighlighterClient(props) {
 
   // For fallback context, use the processed code or fall back to non-controlled code
   const codeForFallback = overlaidCode || (controlled?.code ? undefined : props.code || code);
-  const fallbackContext = React.useMemo(() => codeToFallbackProps(variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants), [variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants]);
+  const fallbackContext = React.useMemo(() => activeCodeReady ? undefined : codeToFallbackProps(variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants), [activeCodeReady, variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants]);
   const context = React.useMemo(() => ({
     code: overlaidCode,
     // Use processed/transformed code
@@ -813,8 +841,9 @@ export function CodeHighlighterClient(props) {
     components: controlled?.components || props.components,
     availableTransforms: isControlled ? [] : availableTransforms,
     url: props.url,
-    deferHighlight
-  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, isControlled, availableTransforms, props.url, deferHighlight]);
+    deferHighlight,
+    preParsedCache
+  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, isControlled, availableTransforms, props.url, deferHighlight, preParsedCache]);
   if (!props.variants && !props.components && !activeCode) {
     throw new Errors.ErrorCodeHighlighterClientMissingData();
   }

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -1,6 +1,17 @@
 import * as React from 'react';
-import { type Code, type ControlledCode } from "./types.mjs";
+import { type Code, type ControlledCode, type HastRoot } from "./types.mjs";
 import { type Selection } from "../CodeControllerContext/index.mjs";
+/**
+ * One cached pre-parsed file. Stored per-fileName: each new write replaces
+ * any previous entry for that file. The `source` string is the cache key —
+ * `parseControlledCode` only reuses `hast` when the controlled-code source
+ * is byte-identical, which guarantees the cached HAST matches the input
+ * that produced it.
+ */
+export interface PreParsedCacheEntry {
+  source: string;
+  hast: HastRoot;
+}
 export interface CodeHighlighterContextType {
   code?: Code;
   setCode?: React.Dispatch<React.SetStateAction<ControlledCode | undefined>>;
@@ -10,6 +21,15 @@ export interface CodeHighlighterContextType {
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;
+  /**
+   * Per-file pre-parsed HAST cache. Populated by `useSourceEditing` when the
+   * editable supplies a worker-parsed result alongside a source change, and
+   * read by `parseControlledCode` to skip the (sync, main-thread) parse on
+   * exact source matches. Owned by `CodeHighlighterClient` via `useRef` so
+   * the same `Map` instance is shared across render cycles without being a
+   * React dep.
+   */
+  preParsedCache?: Map<string, PreParsedCacheEntry>;
 }
 export declare const CodeHighlighterContext: React.Context<CodeHighlighterContextType | undefined>;
 export declare function useCodeHighlighterContext(): CodeHighlighterContextType;

package/CodeHighlighter/CodeHighlighterContext.mjs

@@ -1,6 +1,15 @@
 'use client';
 
 import * as React from 'react';
+
+/**
+ * One cached pre-parsed file. Stored per-fileName: each new write replaces
+ * any previous entry for that file. The `source` string is the cache key —
+ * `parseControlledCode` only reuses `hast` when the controlled-code source
+ * is byte-identical, which guarantees the cached HAST matches the input
+ * that produced it.
+ */
+
 export const CodeHighlighterContext = /*#__PURE__*/React.createContext(undefined);
 if (process.env.NODE_ENV !== "production") CodeHighlighterContext.displayName = "CodeHighlighterContext";
 export function useCodeHighlighterContext() {

package/CodeHighlighter/errors.mjs

@@ -156,7 +156,7 @@ export class ErrorCodeHighlighterClientMissingLoadFallbackCode extends ErrorCode
 }
 export class ErrorCodeHighlighterClientMissingLoadVariant extends ErrorCodeHighlighterClientProvider {
   constructor(url) {
-    super(`Missing loadCodeVariant function - loadCodeVariant function is required when no initial code is provided (${url || 'No URL'})`);
+    super(`Missing loadIsomorphicCodeVariant function - loadIsomorphicCodeVariant function is required when no initial code is provided (${url || 'No URL'})`);
   }
 }
 export class ErrorCodeHighlighterClientMissingLoadCodeMeta extends ErrorCodeHighlighterClientProvider {
@@ -273,7 +273,7 @@ export class ErrorCodeHighlighterClientTransformProcessingFailure extends ErrorC
 }
 export class ErrorCodeHighlighterClientMissingLoadVariantForGlobals extends ErrorCodeHighlighterClientProvider {
   constructor() {
-    super(`loadCodeVariant function is required for loading missing variants in globalsCode`);
+    super(`loadIsomorphicCodeVariant function is required for loading missing variants in globalsCode`);
   }
 }
 export class ErrorCodeHighlighterClientLoadVariantFailureForGlobals extends ErrorCodeHighlighterClientLoader {

package/CodeHighlighter/parseControlledCode.d.mts

@@ -1,6 +1,13 @@
 import type { Code, ControlledCode, ParseSource } from "./types.mjs";
+import type { PreParsedCacheEntry } from "./CodeHighlighterContext.mjs";
 /**
  * Pure function to parse controlled code and convert it to regular Code format.
  * Handles the conversion from ControlledCode (string|null sources) to Code (HAST nodes).
+ *
+ * When `preParsedCache` is supplied, each file's source is first looked up in
+ * the cache. If the cached entry's source string matches byte-for-byte, the
+ * cached HAST is reused and `parseSource` is skipped for that file. On a
+ * mismatch the stale entry is evicted before re-parsing so the cache cannot
+ * grow stale across rapid edits.
  */
-export declare function parseControlledCode(controlledCode: ControlledCode, parseSource: ParseSource): Code;
+export declare function parseControlledCode(controlledCode: ControlledCode, parseSource: ParseSource, preParsedCache?: Map<string, PreParsedCacheEntry>): Code;

package/CodeHighlighter/parseControlledCode.mjs

@@ -1,8 +1,32 @@
 /**
  * Pure function to parse controlled code and convert it to regular Code format.
  * Handles the conversion from ControlledCode (string|null sources) to Code (HAST nodes).
+ *
+ * When `preParsedCache` is supplied, each file's source is first looked up in
+ * the cache. If the cached entry's source string matches byte-for-byte, the
+ * cached HAST is reused and `parseSource` is skipped for that file. On a
+ * mismatch the stale entry is evicted before re-parsing so the cache cannot
+ * grow stale across rapid edits.
  */
-export function parseControlledCode(controlledCode, parseSource) {
+export function parseControlledCode(controlledCode, parseSource, preParsedCache) {
+  /**
+   * Try the cache for `fileName`/`source`. Returns the cached HAST on an
+   * exact match; evicts and returns `undefined` on a mismatch.
+   */
+  const tryCache = (fileName, source) => {
+    if (!preParsedCache) {
+      return undefined;
+    }
+    const entry = preParsedCache.get(fileName);
+    if (!entry) {
+      return undefined;
+    }
+    if (entry.source === source) {
+      return entry.hast;
+    }
+    preParsedCache.delete(fileName);
+    return undefined;
+  };
   const parsed = {};
   for (const [variant, variantCode] of Object.entries(controlledCode)) {
     if (variantCode === null) {
@@ -15,11 +39,16 @@ export function parseControlledCode(controlledCode, parseSource) {
       // Convert null to empty string, then parse
       const sourceToProcess = variantCode.source === null ? '' : variantCode.source;
       if (typeof sourceToProcess === 'string' && variantCode.fileName) {
-        try {
-          mainSource = parseSource(sourceToProcess, variantCode.fileName);
-        } catch (error) {
-          // Keep original string if parsing fails
-          mainSource = sourceToProcess;
+        const cached = tryCache(variantCode.fileName, sourceToProcess);
+        if (cached) {
+          mainSource = cached;
+        } else {
+          try {
+            mainSource = parseSource(sourceToProcess, variantCode.fileName);
+          } catch (error) {
+            // Keep original string if parsing fails
+            mainSource = sourceToProcess;
+          }
         }
       } else if (typeof sourceToProcess === 'string' && !variantCode.fileName) {
         // Return a basic HAST root node with the source text for unsupported file types
@@ -45,22 +74,32 @@ export function parseControlledCode(controlledCode, parseSource) {
           // Convert null to empty string, then parse
           const fileSourceToProcess = fileData.source === null ? '' : fileData.source;
           if (typeof fileSourceToProcess === 'string') {
-            // Parse string sources
-            try {
-              const parsedSource = parseSource(fileSourceToProcess, fileName);
-              parsedExtraFiles[fileName] = {
-                source: parsedSource
-              };
-            } catch (error) {
-              // Keep original if parsing fails
+            const cached = tryCache(fileName, fileSourceToProcess);
+            if (cached) {
               parsedExtraFiles[fileName] = {
-                source: fileSourceToProcess
+                source: cached,
+                comments: fileData.comments
               };
+            } else {
+              try {
+                const parsedSource = parseSource(fileSourceToProcess, fileName);
+                parsedExtraFiles[fileName] = {
+                  source: parsedSource,
+                  comments: fileData.comments
+                };
+              } catch (error) {
+                // Keep original if parsing fails
+                parsedExtraFiles[fileName] = {
+                  source: fileSourceToProcess,
+                  comments: fileData.comments
+                };
+              }
             }
           } else {
             // Keep other values as-is
             parsedExtraFiles[fileName] = {
-              source: fileSourceToProcess
+              source: fileSourceToProcess,
+              comments: fileData.comments
             };
           }
         }
@@ -71,7 +110,8 @@ export function parseControlledCode(controlledCode, parseSource) {
         url: variantCode.url,
         source: mainSource,
         extraFiles,
-        filesOrder: variantCode.filesOrder
+        filesOrder: variantCode.filesOrder,
+        comments: variantCode.comments
       };
     }
   }