@mui/internal-docs-infra 0.12.1-canary.44 → 0.12.1-canary.45

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -78,8 +78,8 @@ export interface CodeControllerContext {
 export type CodeControllerProps<T extends {} = {}> = {
   children: React.ReactNode;
   /**
-   * The demo's url — identifies this controller, e.g. as the per-demo key for
-   * cross-tab sync. Supplied by the demo factory, or passed explicitly.
+   * The demo's URL, supplied by the demo factory or passed explicitly so custom
+   * controllers can identify the demo they wrap.
    */
   url?: string;
 } & T;

package/CodeHighlighter/CodeHighlighter.mjs

@@ -79,7 +79,8 @@ export function CodeHighlighter(props) {
   const renderChunk = options => {
     const userProps = {
       ...props,
-      code: options.preloaded,
+      code: props.loadPrecompute ? undefined : options.preloaded,
+      precompute: props.loadPrecompute ? options.preloaded : props.precompute,
       ContentLoading,
       initialVariant: initialKey,
       fallback: options.fallback,

package/CodeHighlighter/CodeHighlighterChunk.mjs

@@ -28,7 +28,8 @@ function CodeHighlighterChunkContent(props) {
   } = props;
   const clientProps = createClientProps({
     ...userProps,
-    code: data ?? userProps.code
+    code: userProps.loadPrecompute ? undefined : data ?? userProps.code,
+    precompute: userProps.loadPrecompute ? data ?? userProps.precompute : userProps.precompute
   });
   return /*#__PURE__*/_jsx(CodeHighlighterClient, {
     ...clientProps

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -1,7 +1,8 @@
 'use client';
 
 import * as React from 'react';
-import { useCodeContext } from "../CodeProvider/CodeContext.mjs";
+import { DemoRootContext } from "../abstractCreateDemo/DemoRootContext.mjs";
+import { useCodeContext, useDemandSourceParser } from "../CodeProvider/CodeContext.mjs";
 import { CodeHighlighterContext } from "./CodeHighlighterContext.mjs";
 import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs";
 import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
@@ -24,10 +25,15 @@ import { useCoordinatedSwap } from "../CoordinatedLazy/useCoordinatedSwap.mjs";
 import { CoordinatedFallbackContext } from "../CoordinatedLazy/CoordinatedFallbackContext.mjs";
 import { CoordinatedContentContext } from "../CoordinatedLazy/CoordinatedContentContext.mjs";
 import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
+import { scheduleDeferredPrecompute } from "./scheduleDeferredPrecompute.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
 
+// Deferred source loading should stay behind the initial paint without leaving
+// an untouched demo on its server fallback for too long.
+const DEFERRED_PRECOMPUTE_IDLE_TIMEOUT_MS = 2_000;
+
 // Safety-net deadline (ms) for the default `'idle'` highlight/enhance swaps. They
 // defer the swap to `requestIdleCallback`, which a busy main thread can starve
 // INDEFINITELY — leaving code stuck at its un-highlighted first paint until a full
@@ -78,7 +84,7 @@ function useInitialData({
   handleSetFallbackHasts
 }) {
   const {
-    sourceParser,
+    loadSourceParser,
     loadCodeMeta,
     loadVariantMeta,
     loadSource,
@@ -128,11 +134,15 @@ function useInitialData({
       // Lazily resolve the heavy fallback loader (instant under an eager
       // CodeProvider, a deduped fetch under CodeProviderLazy) before loading.
       const loadCodeFallback = await loadCodeFallbackLoader();
+
+      // Only start the parser load when the fallback is highlighted here;
+      // `loadCodeFallback` never awaits it otherwise.
+      const shouldHighlight = highlightAfter === 'init';
       const loaded = await loadCodeFallback(url, variantName, code, {
-        shouldHighlight: highlightAfter === 'init',
+        shouldHighlight,
         fallbackUsesExtraFiles,
         fallbackUsesAllVariants,
-        sourceParser,
+        sourceParser: shouldHighlight ? loadSourceParser?.() : undefined,
         loadSource,
         loadVariantMeta,
         loadCodeMeta,
@@ -174,7 +184,7 @@ function useInitialData({
       }
       return strippedCode;
     }
-  }), [reason, variantName, code, setCode, highlightAfter, url, sourceParser, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, fallbackUsesExtraFiles, fallbackUsesAllVariants, fileName, variants, globalsCode, setProcessedGlobalsCode, loadCodeFallbackLoader, handleSetFallbackHasts]);
+  }), [reason, variantName, code, setCode, highlightAfter, url, loadSourceParser, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, fallbackUsesExtraFiles, fallbackUsesAllVariants, fileName, variants, globalsCode, setProcessedGlobalsCode, loadCodeFallbackLoader, handleSetFallbackHasts]);
   const fallbackConfig = React.useMemo(() => ({
     ChunkContent: NoopChunkContent,
     source: fallbackSource
@@ -359,7 +369,7 @@ function useCodeParsing({
   url
 }) {
   const {
-    sourceParser,
+    loadSourceParser,
     parseSource,
     parseCode
   } = useCodeContext();
@@ -407,6 +417,7 @@ function useCodeParsing({
   // adds no delay on the common path.
   const grammarScopes = React.useMemo(() => code ? detectGrammarScopes(code) : [], [code]);
   const grammarsReady = useGrammarsReady(grammarScopes, !!code && shouldHighlight && !allVariantsAlreadyHighlighted);
+  useDemandSourceParser(loadSourceParser, !!code && shouldHighlight && !allVariantsAlreadyHighlighted && grammarsReady && !parseSource);
 
   // Parse the internal code state when ready and timing conditions are met
   const parsedCode = React.useMemo(() => {
@@ -419,10 +430,10 @@ 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) {
+      // A CodeProvider is present and its parser hasn't loaded yet — wait for
+      // it instead of erroring. The memo will re-run once `parseSource` is
+      // populated.
+      if (loadSourceParser) {
         return undefined;
       }
       if (forceClient) {
@@ -441,12 +452,11 @@ function useCodeParsing({
       return undefined;
     }
     return parseCode(code, parseSource);
-  }, [code, shouldHighlight, allVariantsAlreadyHighlighted, grammarsReady, sourceParser, parseSource, parseCode, forceClient, url]);
+  }, [code, shouldHighlight, allVariantsAlreadyHighlighted, grammarsReady, loadSourceParser, parseSource, parseCode, forceClient, url]);
 
   // Keep highlighting deferred until parsed HAST is actually available for the
   // variants that need it. `shouldHighlight` can flip true ~30ms after
-  // hydration, but `parseCode` only runs once the async `sourceParser` promise
-  // resolves. Without this wait, downstream consumers (e.g. the transform
+  // hydration, but `parseCode` only runs once the source parser has loaded. Without this wait, downstream consumers (e.g. the transform
   // swap) would commit while the visible variant is still rendered from its
   // raw string source, producing a structure swap on the DOM moments later.
   const waitingForParsedCode = shouldHighlight && !!code && !allVariantsAlreadyHighlighted && !parsedCode;
@@ -495,7 +505,7 @@ function useCodeTransforms({
   variantName
 }) {
   const {
-    sourceParser,
+    loadSourceParser,
     computeHastDeltasLoader
   } = useCodeContext();
   // Track which `parsedCode` the cached `transformedCode` was computed from
@@ -513,7 +523,7 @@ function useCodeTransforms({
   // the no-async case is derived during render below instead of being stored,
   // so this effect never publishes a synchronous pass-through state.
   React.useEffect(() => {
-    if (!parsedCode || !sourceParser || !computeHastDeltasLoader) {
+    if (!parsedCode || !loadSourceParser || !computeHastDeltasLoader) {
       return undefined;
     }
 
@@ -544,7 +554,7 @@ function useCodeTransforms({
         // Resolve the parser and the (lazy) transform-delta computer in parallel
         // before computing deltas. computeHastDeltas pulls jsondiffpatch, so it's
         // kept out of the initial bundle under CodeProviderLazy.
-        const [parseSource, computeHastDeltas] = await Promise.all([sourceParser, computeHastDeltasLoader()]);
+        const [parseSource, computeHastDeltas] = await Promise.all([loadSourceParser(), computeHastDeltasLoader()]);
         const enhanced = await computeHastDeltas(parsedCode, parseSource);
         commit(enhanced);
       } catch (error) {
@@ -558,7 +568,7 @@ function useCodeTransforms({
       settled = true; // a newer run (or unmount) supersedes this one; ignore late writes
       clearTimeout(timer);
     };
-  }, [parsedCode, sourceParser, computeHastDeltasLoader]);
+  }, [parsedCode, loadSourceParser, computeHastDeltasLoader]);
 
   // When the full async pipeline is wired, expose the cached output regardless
   // of whether `parsedCode` changed since the last computation — falling back
@@ -568,7 +578,7 @@ function useCodeTransforms({
   // `useTransformManagement` / `useVariantSelection`) hold off committing a
   // swap until fresh deltas land. Without the pipeline, `transformedCode` is a
   // synchronous pass-through of `parsedCode` derived during render.
-  const hasAsyncPipeline = !!parsedCode && !!sourceParser && !!computeHastDeltasLoader;
+  const hasAsyncPipeline = !!parsedCode && !!loadSourceParser && !!computeHastDeltasLoader;
   const transformedCode = hasAsyncPipeline ? transformedState.output : parsedCode;
 
   // Async hast-deltas pipeline status. While true, consumers (notably
@@ -580,7 +590,7 @@ function useCodeTransforms({
   // two later when `transformedCode` arrives, producing a visible jump
   // on top of the just-played collapse animation.
   //
-  // Only relevant when both a worker (`sourceParser`) and a deltas
+  // Only relevant when both a parser (`loadSourceParser`) and a deltas
   // computer (`computeHastDeltas`) are wired up — environments without
   // them resolve `transformedCode` synchronously to `parsedCode` in the
   // effect above, so the deltas phase is a no-op. We compare the cached
@@ -596,26 +606,29 @@ function useCodeTransforms({
 }
 function useControlledCodeParsing({
   code,
+  grammarScopes,
   forceClient,
   url,
   preParsedCache
 }) {
   const {
-    sourceParser,
+    loadSourceParser,
     parseSource,
     parseControlledCode
   } = useCodeContext();
+  const grammarsReady = useGrammarsReady(grammarScopes, Boolean(code));
+  useDemandSourceParser(loadSourceParser, Boolean(code) && grammarsReady && !parseSource);
 
   // Parse the controlled code separately (no need to check readyForContent)
   const parsedControlledCode = React.useMemo(() => {
-    if (!code) {
+    if (!code || !grammarsReady) {
       return undefined;
     }
     if (!parseSource) {
-      // A CodeProvider is present and its async `sourceParser` promise hasn't
-      // resolved yet (e.g. CodeProviderLazy dynamic-importing the engine) — wait
-      // for it instead of erroring. The memo re-runs once `parseSource` lands.
-      if (sourceParser) {
+      // A CodeProvider is present and its parser hasn't loaded yet (e.g.
+      // CodeProviderLazy dynamic-importing the engine) — wait for it instead of
+      // erroring. The memo re-runs once `parseSource` lands.
+      if (loadSourceParser) {
         return undefined;
       }
       if (forceClient) {
@@ -634,7 +647,7 @@ function useControlledCodeParsing({
       return undefined;
     }
     return parseControlledCode(code, parseSource, preParsedCache);
-  }, [code, sourceParser, parseSource, parseControlledCode, forceClient, url, preParsedCache]);
+  }, [code, grammarsReady, loadSourceParser, parseSource, parseControlledCode, forceClient, url, preParsedCache]);
   return {
     parsedControlledCode
   };
@@ -888,8 +901,41 @@ function usePropsCodeGlobalsMerging({
 }
 export function CodeHighlighterClient(props) {
   const controlled = useControlledCode();
+  const demoRootRef = React.useContext(DemoRootContext);
   const isControlled = Boolean(props.code || controlled?.code);
   const [code, setCode] = React.useState(typeof props.precompute === 'object' ? props.precompute : undefined);
+  const [deferredPrecomputeLoaded, setDeferredPrecomputeLoaded] = React.useState(!props.loadPrecompute);
+  const [deferredPrecomputeStarted, setDeferredPrecomputeStarted] = React.useState(false);
+  React.useEffect(() => {
+    if (!props.loadPrecompute || deferredPrecomputeLoaded) {
+      return undefined;
+    }
+    let active = true;
+    async function load() {
+      setDeferredPrecomputeStarted(true);
+      try {
+        const loaded = await props.loadPrecompute();
+        if (active) {
+          React.startTransition(() => {
+            setCode(loaded);
+            setDeferredPrecomputeLoaded(true);
+          });
+        }
+      } catch {
+        // Keep the server-rendered fallback when the deferred chunk fails.
+      }
+    }
+    const cancel = scheduleDeferredPrecompute({
+      root: demoRootRef?.current,
+      enhanceAfter: props.enhanceAfter,
+      load,
+      timeout: DEFERRED_PRECOMPUTE_IDLE_TIMEOUT_MS
+    });
+    return () => {
+      active = false;
+      cancel();
+    };
+  }, [props.loadPrecompute, props.enhanceAfter, deferredPrecomputeLoaded, demoRootRef]);
 
   // Sync code state with precompute prop changes (for hot-reload). Done with
   // the store-previous-prop render-phase derivation rather than an effect:
@@ -902,7 +948,7 @@ export function CodeHighlighterClient(props) {
   const [prevPrecompute, setPrevPrecompute] = React.useState(props.precompute);
   if (props.precompute !== prevPrecompute) {
     setPrevPrecompute(props.precompute);
-    if (typeof props.precompute === 'object') {
+    if (typeof props.precompute === 'object' && !(props.loadPrecompute && deferredPrecomputeLoaded)) {
       setCode(props.precompute);
     } else if (props.precompute === undefined) {
       setCode(undefined);
@@ -950,50 +996,10 @@ export function CodeHighlighterClient(props) {
   });
 
   // Per-block editing activation: flipped once when the block first engages for
-  // editing — threaded down to `useEditable.onActivate` via `CodeHighlighterContext`
+  // editing — threaded down to the textarea's focus handler via `CodeHighlighterContext`
   // (immediately in `'eager'`, on hover/focus/click in `'interaction'`). Drives
   // the editable speculative preload below and notifies the CodeControllerContext.
   const [editingActivated, setEditingActivated] = React.useState(false);
-  const controllerOnActivate = controlled?.onActivate;
-  // Which live-editing engine chunks the controller should preload on activation: `js`
-  // if the demo has any JS/TS file, `css` if any CSS file. Stable across keystrokes
-  // (editing changes source content, never which files exist), like the grammar scopes
-  // below.
-  const editableFileTypes = React.useMemo(() => {
-    const editableCode = props.code ?? code;
-    return editableCode ? detectFileTypes(editableCode) : {
-      js: false,
-      css: false
-    };
-  }, [props.code, code]);
-  const handleEditingActivated = React.useCallback(() => {
-    setEditingActivated(true);
-    controllerOnActivate?.(editableFileTypes);
-  }, [controllerOnActivate, editableFileTypes]);
-
-  // Grammar scopes the editable files need for live re-highlighting. Unlike the
-  // speculative highlight/transform preloads — which intentionally skip
-  // controlled blocks (`speculativeCode` is cleared above) — an editable block
-  // DOES re-highlight its edits on the client, so its grammars must load or the
-  // edited source falls back to plain text. The editable file set (and thus the
-  // scopes) comes from `props.code`: editing changes source *content*, never
-  // which files exist, so this stays stable across keystrokes.
-  const editableGrammarScopes = React.useMemo(() => {
-    const editableCode = props.code ?? code;
-    return editableCode ? detectGrammarScopes(editableCode) : [];
-  }, [props.code, code]);
-
-  // When the block is editable (a CodeControllerContext with `setCode` is in
-  // scope), warm the live-editing engine, the per-language grammars, and the
-  // worker so they're in flight before the user edits. Deduped page-wide. In
-  // `editActivation: 'interaction'` mode the warming waits until the block is
-  // `activated` (engaged) — that mode defers loading until the reader engages.
-  useSpeculativeEditingPreload({
-    enabled: Boolean(controlled?.setCode),
-    editActivation,
-    activated: editingActivated,
-    scopes: editableGrammarScopes
-  });
 
   // Preload the client-side transform applier (the `jsondiffpatch` chunk) when
   // the code declares transforms — so it is warm before the reader switches a
@@ -1060,7 +1066,7 @@ export function CodeHighlighterClient(props) {
     highlightAfter,
     fallbackUsesExtraFiles,
     fallbackUsesAllVariants,
-    isControlled,
+    isControlled: isControlled || !deferredPrecomputeLoaded,
     globalsCode: props.globalsCode,
     setProcessedGlobalsCode,
     handleSetFallbackHasts
@@ -1141,15 +1147,15 @@ export function CodeHighlighterClient(props) {
     }
   }, [enhanceAfter, isHydrated]);
   const readyForContent = React.useMemo(() => {
-    if (!code) {
+    if (!code || !deferredPrecomputeLoaded) {
       return false;
     }
     return hasAllVariants(variants, code);
-  }, [code, variants]);
+  }, [code, variants, deferredPrecomputeLoaded]);
 
   // Separate check for activeCode to determine when to show fallback
   const activeCodeReady = React.useMemo(() => {
-    if (!activeCode || !isEnhanceAllowed) {
+    if (!activeCode || !isEnhanceAllowed || !deferredPrecomputeLoaded) {
       return false;
     }
 
@@ -1161,13 +1167,13 @@ export function CodeHighlighterClient(props) {
     // For regular code, use the existing hasAllVariants function
     const regularCode = props.code || code;
     return regularCode ? hasAllVariants(variants, regularCode) : false;
-  }, [activeCode, isEnhanceAllowed, controlled?.code, variants, props.code, code]);
+  }, [activeCode, isEnhanceAllowed, deferredPrecomputeLoaded, controlled?.code, variants, props.code, code]);
   const {
     refresh: refreshAllVariants
   } = useAllVariants({
     readyForContent,
     variants,
-    isControlled,
+    isControlled: isControlled || !deferredPrecomputeLoaded,
     url,
     code,
     setCode,
@@ -1199,6 +1205,40 @@ export function CodeHighlighterClient(props) {
 
   // Use props.code result if available, otherwise use state code result
   const codeWithGlobals = propsCodeWithGlobals || stateCodeWithGlobals;
+
+  // Union immutable and live metadata: either graph can be partial while editing activates.
+  const editableFileTypes = React.useMemo(() => {
+    const initial = codeWithGlobals ? detectFileTypes(codeWithGlobals) : {
+      js: false,
+      css: false
+    };
+    const live = controlled?.code ? detectFileTypes(controlled.code) : {
+      js: false,
+      css: false
+    };
+    return {
+      js: initial.js || live.js,
+      css: initial.css || live.css
+    };
+  }, [codeWithGlobals, controlled]);
+  const editableGrammarScopes = React.useMemo(() => {
+    const scopes = new Set(codeWithGlobals ? detectGrammarScopes(codeWithGlobals) : []);
+    if (controlled?.code) {
+      detectGrammarScopes(controlled.code).forEach(scope => scopes.add(scope));
+    }
+    return [...scopes];
+  }, [codeWithGlobals, controlled]);
+  const controllerOnActivate = controlled?.onActivate;
+  const handleEditingActivated = React.useCallback(() => {
+    setEditingActivated(true);
+    controllerOnActivate?.(editableFileTypes);
+  }, [controllerOnActivate, editableFileTypes]);
+  useSpeculativeEditingPreload({
+    enabled: Boolean(controlled?.setCode),
+    editActivation,
+    activated: editingActivated,
+    scopes: editableGrammarScopes
+  });
   const {
     parsedCode,
     deferHighlight: deferHighlightForParsing,
@@ -1301,6 +1341,7 @@ export function CodeHighlighterClient(props) {
     parsedControlledCode
   } = useControlledCodeParsing({
     code: controlled?.code,
+    grammarScopes: editableGrammarScopes,
     forceClient: props.forceClient,
     url: props.url,
     preParsedCache
@@ -1330,9 +1371,10 @@ export function CodeHighlighterClient(props) {
   }, [hoistedFallbackHasts, variantName, codeForFallback]);
   const fallbackContext = React.useMemo(() => ({
     extraVariants: codeToFallbackProps(variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants).extraVariants,
+    canLoadContent: !props.loadPrecompute || deferredPrecomputeStarted,
     setFallbackHasts: handleSetFallbackHasts,
     onHookCalled: handleHookCalled
-  }), [variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants, handleSetFallbackHasts, handleHookCalled]);
+  }), [variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants, props.loadPrecompute, deferredPrecomputeStarted, handleSetFallbackHasts, handleHookCalled]);
 
   // Keep the build-time render for any variant the controller hasn't produced a live
   // preview for yet — an in-flight build, a build error, or a variant with no live build
@@ -1357,16 +1399,17 @@ export function CodeHighlighterClient(props) {
     for (const variant of Object.keys(live)) {
       const buildTime = props.components?.[variant];
       const liveNode = injectFallback(live[variant], buildTime);
-      merged[variant] = /*#__PURE__*/React.createElement(React.Suspense, {
-        key: variant,
-        fallback: buildTime ?? null
-      }, liveNode);
+      merged[variant] = /*#__PURE__*/_jsx(React.Suspense, {
+        fallback: buildTime ?? null,
+        children: liveNode
+      }, variant);
     }
     return merged;
   }, [controlled?.components, props.components]);
   const context = React.useMemo(() => ({
     code: overlaidCode,
     // Use processed/transformed code
+    initialCode: codeWithGlobals,
     setCode: controlled?.setCode,
     selection: controlled?.selection || selection,
     setSelection: controlled?.setSelection || setSelection,
@@ -1382,7 +1425,7 @@ export function CodeHighlighterClient(props) {
     onEditingActivated: handleEditingActivated,
     refresh,
     preParsedCache
-  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, bridgedComponents, controlled?.errors, availableTransforms, props.url, deferHighlight, activeFallbacks, highlightReady, highlightAfter, editActivation, handleEditingActivated, refresh, preParsedCache]);
+  }), [overlaidCode, codeWithGlobals, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, bridgedComponents, controlled?.errors, availableTransforms, props.url, deferHighlight, activeFallbacks, highlightReady, highlightAfter, editActivation, handleEditingActivated, refresh, preParsedCache]);
   if (!props.variants && !props.components && !activeCode) {
     throw new Errors.ErrorCodeHighlighterClientMissingData();
   }
@@ -1406,6 +1449,9 @@ export function CodeHighlighterClient(props) {
       children: props.fallback
     })
   });
+  const contentChildren = props.loadPrecompute && /*#__PURE__*/React.isValidElement(props.children) ? /*#__PURE__*/React.cloneElement(props.children, {
+    code: overlaidCode ?? codeWithGlobals ?? code
+  }) : props.children;
 
   // The content subtree. A dynamically-imported content (`LazyContent`) reads the
   // loading `fallback` from `CoordinatedContentContext` and shows it as its own
@@ -1415,7 +1461,7 @@ export function CodeHighlighterClient(props) {
     value: context,
     children: /*#__PURE__*/_jsx(CoordinatedContentContext.Provider, {
       value: contentContext,
-      children: props.children
+      children: contentChildren
     })
   });
 

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -14,6 +14,8 @@ export interface PreParsedCacheEntry {
 }
 export interface CodeHighlighterContextType {
   code?: Code;
+  /** Loaded source before controlled edits are overlaid. */
+  initialCode?: Code;
   setCode?: React.Dispatch<React.SetStateAction<ControlledCode | null>>;
   selection?: Selection;
   setSelection?: React.Dispatch<React.SetStateAction<Selection>>;
@@ -64,15 +66,14 @@ export interface CodeHighlighterContextType {
   /**
    * Echo of the `editActivation` prop on the surrounding `CodeHighlighter` /
    * `CodeHighlighterClient`. `useCode` reads it from here and threads it down to
-   * `useEditable` (which defers the `contentEditable` attach when
-   * `'interaction'`), so the editing-activation strategy can be configured at
+   * `Pre` (which defers the textarea load when `'interaction'`), so the strategy can be configured at
    * the `CodeHighlighter` / demo level rather than inside the content subtree.
    */
   editActivation?: 'eager' | 'interaction';
   /**
-   * Callback `useCode` threads down to `useEditable`'s `onActivate`, fired once
+   * Callback `useCode` threads down to the editor's `onActivate`, fired once
    * when the block first engages for editing. `CodeHighlighterClient` supplies it
-   * to flip its per-block `activated` state (warming the live-editing engine,
+   * to flip its per-block `activated` state (warming the live-editing runtime,
    * grammars, and worker) and to notify the `CodeControllerContext`.
    */
   onEditingActivated?: () => void;

package/CodeHighlighter/CodeHighlighterFallbackContext.d.mts

@@ -2,6 +2,8 @@ import * as React from 'react';
 import type { Fallbacks, ContentLoadingVariant } from "./types.mjs";
 export interface CodeHighlighterFallbackContext {
   extraVariants?: Record<string, ContentLoadingVariant>;
+  /** Whether the loading fallback may begin loading independently lazy content. */
+  canLoadContent?: boolean;
   /**
    * Callback used by `useCodeFallback` to hoist fallback data
    * back to `CodeHighlighterClient` so it can derive text dictionaries

package/CodeHighlighter/buildCodeHighlighterChunkProps.d.mts

@@ -30,7 +30,7 @@ export interface CodeHighlighterChunkProps {
   forceClient: boolean;
 }
 /** The `CodeHighlighter` props this decision reads. */
-type BuildCodeHighlighterChunkPropsInput<T extends {}> = Pick<CodeHighlighterProps<T>, 'code' | 'precompute' | 'components' | 'variants' | 'variant' | 'initialVariant' | 'defaultVariant' | 'controlled' | 'forceClient' | 'highlightAfter' | 'fallbackUsesExtraFiles' | 'fallbackUsesAllVariants' | 'loadCodeMeta' | 'loadVariantMeta' | 'loadSource' | 'sourceParser' | 'sourceTransformers' | 'url' | 'fileName'>;
+type BuildCodeHighlighterChunkPropsInput<T extends {}> = Pick<CodeHighlighterProps<T>, 'code' | 'precompute' | 'loadPrecompute' | 'components' | 'variants' | 'variant' | 'initialVariant' | 'defaultVariant' | 'controlled' | 'forceClient' | 'highlightAfter' | 'fallbackUsesExtraFiles' | 'fallbackUsesAllVariants' | 'loadCodeMeta' | 'loadVariantMeta' | 'loadSource' | 'sourceParser' | 'sourceTransformers' | 'url' | 'fileName'>;
 /**
  * Map `CodeHighlighter`'s props onto the generic chunk render-decision inputs.
  * This replaces the bespoke `renderCodeHighlighter`/`renderWithInitialSource`

package/CodeHighlighter/buildCodeHighlighterChunkProps.mjs

@@ -34,7 +34,7 @@ export function buildCodeHighlighterChunkProps(props) {
   // Every variant already highlighted (or controlled editing) -> render the
   // client directly with no loading.
   const allVariantsLoaded = Boolean(code && hasAllVariants(variants, code, true));
-  const controlled = Boolean(props.controlled) || allVariantsLoaded;
+  const controlled = !props.loadPrecompute && (Boolean(props.controlled) || allVariantsLoaded);
 
   // No loading functions (or the caller forced the client) -> the server cannot
   // load, so route to a client/content branch.

package/CodeHighlighter/createClientProps.mjs

@@ -54,6 +54,7 @@ export function createClientProps(props) {
     url,
     code,
     precompute,
+    loadPrecompute: props.loadPrecompute,
     components: props.components,
     variants: props.variants,
     variant: props.variant,

package/CodeHighlighter/fallbackFormat.d.mts

@@ -127,8 +127,7 @@ export declare function redistributeRootFallback(root: HastRoot, fallback: Fallb
  * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
  * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
  * is intentionally empty, so the first-frame fallback is skipped and an empty
- * array is returned. Mirrors the runtime rule in `Pre.tsx` /
- * `getInitialVisibleSourceLines`.
+ * array is returned. Mirrors the runtime rule in `Pre.tsx`.
  *
  * Used by `fallbackCollapsed` to paint only the on-screen lines while the
  * file's full fallback rides along compressed (see the prop-compression

package/CodeHighlighter/fallbackFormat.mjs

@@ -384,8 +384,7 @@ function fallbackFrameType(frame) {
  * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
  * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
  * is intentionally empty, so the first-frame fallback is skipped and an empty
- * array is returned. Mirrors the runtime rule in `Pre.tsx` /
- * `getInitialVisibleSourceLines`.
+ * array is returned. Mirrors the runtime rule in `Pre.tsx`.
  *
  * Used by `fallbackCollapsed` to paint only the on-screen lines while the
  * file's full fallback rides along compressed (see the prop-compression

package/CodeHighlighter/parseControlledCode.mjs

@@ -1,3 +1,6 @@
+import { isGrammarRegistered } from "../pipeline/parseSource/grammarCache.mjs";
+import { resolveGrammarScope } from "../pipeline/parseSource/grammarMaps.mjs";
+
 /**
  * Cache key for a parsed file. Qualified by variant so two variants that share a
  * file name (e.g. both have `Demo.tsx`) get independent entries instead of
@@ -28,8 +31,12 @@ export function parseControlledCode(controlledCode, parseSource, preParsedCache)
    */
   const resolveSource = (variant, fileName, source) => {
     const key = preParsedCacheKey(variant, fileName);
+    const grammarScope = resolveGrammarScope(fileName);
+    // An existing parser missing this file's grammar returns valid-looking plain HAST.
+    // Do not retain that temporary fallback across the grammar-readiness rerender.
+    const cacheable = !grammarScope || isGrammarRegistered(grammarScope) !== false;
     const entry = preParsedCache?.get(key);
-    if (entry) {
+    if (entry && cacheable) {
       if (entry.source === source) {
         return entry.hast;
       }
@@ -37,10 +44,12 @@ export function parseControlledCode(controlledCode, parseSource, preParsedCache)
     }
     try {
       const hast = parseSource(source, fileName);
-      preParsedCache?.set(key, {
-        source,
-        hast
-      });
+      if (cacheable) {
+        preParsedCache?.set(key, {
+          source,
+          hast
+        });
+      }
       return hast;
     } catch {
       return source;
@@ -84,26 +93,23 @@ export function parseControlledCode(controlledCode, parseSource, preParsedCache)
           const fileSourceToProcess = fileData.source === null ? '' : fileData.source;
           if (typeof fileSourceToProcess === 'string') {
             parsedExtraFiles[fileName] = {
-              source: resolveSource(variant, fileName, fileSourceToProcess),
-              comments: fileData.comments
+              ...fileData,
+              source: resolveSource(variant, fileName, fileSourceToProcess)
             };
           } else {
             // Keep other values as-is
             parsedExtraFiles[fileName] = {
-              source: fileSourceToProcess,
-              comments: fileData.comments
+              ...fileData,
+              source: fileSourceToProcess
             };
           }
         }
         extraFiles = parsedExtraFiles;
       }
       parsed[variant] = {
-        fileName: variantCode.fileName,
-        url: variantCode.url,
+        ...variantCode,
         source: mainSource,
-        extraFiles,
-        filesOrder: variantCode.filesOrder,
-        comments: variantCode.comments
+        extraFiles
       };
     }
   }