@mui/internal-docs-infra 0.12.1-canary.1 → 0.12.1-canary.11

package/ChunkProvider/PreloadProvider.mjs

@@ -2,7 +2,7 @@
 
 import * as React from 'react';
 import { PreloadContext } from "./PreloadContext.mjs";
-
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * Scopes a cross-instance preload cache (typically at a layout). Descendants
  * call `usePreload` to start dynamic imports of shared helpers keyed by a
@@ -10,7 +10,6 @@ import { PreloadContext } from "./PreloadContext.mjs";
  * instance reuses its promise - so a helper a chunk's data implies (a transform
  * fn, say) is fetched once, in parallel with the content, across the page.
  */
-import { jsx as _jsx } from "react/jsx-runtime";
 export function PreloadProvider({
   children
 }) {

package/ChunkProvider/usePreload.d.mts

@@ -1,4 +1,4 @@
-import { type PreloadFn } from "./PreloadContext.mjs";
+import type { PreloadFn } from "./PreloadContext.mjs";
 /**
  * Returns the cross-instance `PreloadFn` from the surrounding
  * `PreloadProvider`, or a direct-call fallback when there is none. Use it inside

package/ChunkProvider/usePreload.mjs

@@ -2,7 +2,6 @@
 
 import * as React from 'react';
 import { PreloadContext } from "./PreloadContext.mjs";
-
 /**
  * Calls the factory directly when there is no `PreloadProvider`. The browser's
  * module cache still dedups identical `import()`s, so this only loses the

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -43,6 +43,12 @@ export interface CodeControllerContext {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode> | undefined;
+  /**
+   * Current runtime error message per variant key (or `null` when the variant
+   * rendered cleanly), as reported by the preview components. Demos surface the
+   * selected variant's error via `useDemo().error`.
+   */
+  errors?: Record<string, string | null> | undefined;
   /**
    * Additional source enhancers to apply to parsed HAST sources.
    * These are merged with enhancers from CodeProvider and useCode opts.
@@ -52,13 +58,38 @@ export interface CodeControllerContext {
    * Called once when a block in this controller's scope first activates for
    * editing — immediately for `editActivation: 'eager'`, or on first engagement
    * (hover / focus / click) for `'interaction'`. Lets the host react to "editing
-   * has begun" (e.g. fetch the editable source, light up UI). `CodeHighlighter`
-   * separately warms its own live-editing dependencies (engine, grammars, worker)
-   * at the same moment, so a host that only wants the default behavior can leave
-   * this unset.
+   * has begun" (e.g. fetch the editable source, light up UI, or preload its live
+   * runtime). `deps` reports which file kinds the block spans — `js` when it has any
+   * JS/TS/JSX/TSX/MJS file, `css` when it has any CSS file — so the host can warm only
+   * the engine chunks it will need. `CodeHighlighter` separately warms its own
+   * live-editing dependencies (engine, grammars, worker) at the same moment, so a host
+   * that only wants the default behavior can leave this unset.
    */
-  onActivate?: () => void;
+  onActivate?: (deps: {
+    js: boolean;
+    css: boolean;
+  }) => void;
 }
+/**
+ * Props a code-controller component receives: `children` to wrap and the optional
+ * `url` identifying the demo, plus any custom props `T` (typically a specific
+ * controller's options). Mirrors `ContentProps` — a small base extended by `T`.
+ */
+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.
+   */
+  url?: string;
+} & T;
+/**
+ * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
+ * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
+ * such as `useDemoController`. Parameterize with `T` for the controller's own props
+ * (e.g. `CodeController<UseDemoControllerOptions>`).
+ */
+export type CodeController<T extends {} = {}> = React.ComponentType<CodeControllerProps<T>>;
 export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
 /**
  * Hook to access controlled code state and setters. This is useful for custom
@@ -81,6 +112,10 @@ 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;
+  errors: Record<string, string | null> | undefined;
   sourceEnhancers: SourceEnhancers | undefined;
-  onActivate: (() => void) | undefined;
+  onActivate: ((deps: {
+    js: boolean;
+    css: boolean;
+  }) => void) | undefined;
 };

package/CodeControllerContext/CodeControllerContext.mjs

@@ -10,6 +10,19 @@ import * as React from 'react';
  * event fires.
  */
 
+/**
+ * Props a code-controller component receives: `children` to wrap and the optional
+ * `url` identifying the demo, plus any custom props `T` (typically a specific
+ * controller's options). Mirrors `ContentProps` — a small base extended by `T`.
+ */
+
+/**
+ * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
+ * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
+ * such as `useDemoController`. Parameterize with `T` for the controller's own props
+ * (e.g. `CodeController<UseDemoControllerOptions>`).
+ */
+
 export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
 
 /**
@@ -36,6 +49,7 @@ export function useControlledCode() {
     setCode: context?.setCode,
     setSelection: context?.setSelection,
     components: context?.components,
+    errors: context?.errors,
     sourceEnhancers: context?.sourceEnhancers,
     onActivate: context?.onActivate
   };

package/CodeHighlighter/CodeHighlighter.mjs

@@ -107,7 +107,7 @@ export function CodeHighlighter(props) {
 
   // No ContentLoading: render the content/full-load directly, with no loading
   // fallback (the client shows nothing until content is ready). For
-  // `highlightAt: 'init'`, `createClientProps` folds each variant's highlighted-visible
+  // `highlightAfter: 'init'`, `createClientProps` folds each variant's highlighted-visible
   // `fallbackCritical` over its plain `fallback`, so `<Pre>` paints the visible frames
   // highlighted on the first render (no decompression) and decodes the full tree after
   // paint (the `decodeAllowed` latch).

package/CodeHighlighter/CodeHighlighterClient.d.mts

@@ -1,2 +1,2 @@
-import { type CodeHighlighterClientProps } from "./types.mjs";
+import type { CodeHighlighterClientProps } from "./types.mjs";
 export declare function CodeHighlighterClient(props: CodeHighlighterClientProps): import("react/jsx-runtime").JSX.Element;

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -18,6 +18,7 @@ import { useSpeculativeUseCodePreload } from "./useSpeculativeUseCodePreload.mjs
 import { useSpeculativeGrammarPreload } from "./useSpeculativeGrammarPreload.mjs";
 import { useGrammarsReady } from "./useGrammarsReady.mjs";
 import { detectGrammarScopes } from "../pipeline/parseSource/detectGrammarScopes.mjs";
+import { detectFileTypes } from "../pipeline/parseSource/detectFileTypes.mjs";
 import { useChunk } from "../CoordinatedLazy/useChunk.mjs";
 import { useCoordinatedSwap } from "../CoordinatedLazy/useCoordinatedSwap.mjs";
 import { CoordinatedFallbackContext } from "../CoordinatedLazy/CoordinatedFallbackContext.mjs";
@@ -27,12 +28,40 @@ import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
 
+// 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
+// reload. The `timeout` guarantees the swap still runs even if the browser never
+// goes idle (idle normally wins long before this deadline).
+const IDLE_SWAP_TIMEOUT_MS = 10_000;
+
+// Safety-net deadline (ms) for the async transform-deltas pipeline. If it neither
+// resolves nor rejects (a stalled worker / hung delta computation), the block would
+// otherwise wait on `waitingForTransformedCode` forever — code stuck un-highlighted
+// until a reload. On timeout we publish the un-delta'd parsed HAST so the gate drops.
+const TRANSFORM_PIPELINE_TIMEOUT_MS = 10_000;
+
 // `useChunk` is the chunk loader/renderer, but here we use only its loading
 // engine (load-when-enabled + abort + `refresh()` with stale-while-revalidate),
 // so the content component is an unused placeholder.
 function NoopChunkContent() {
   return null;
 }
+
+/**
+ * Inject a build-time `fallback` into a bridged live-preview node. The controller's
+ * components are erased to `ReactNode` across the context, so the type argument on
+ * `isValidElement` re-narrows the node to one that accepts `fallback` — no cast. A
+ * non-element node (nothing to clone) is returned untouched.
+ */
+function injectFallback(node, fallback) {
+  if (! /*#__PURE__*/React.isValidElement(node)) {
+    return node;
+  }
+  return /*#__PURE__*/React.cloneElement(node, {
+    fallback
+  });
+}
 function useInitialData({
   variants,
   variantName,
@@ -120,7 +149,7 @@ function useInitialData({
       }
 
       // Fold each variant's highlighted-visible `fallbackCritical` over its plain
-      // `fallback` (under `highlightAt: 'init'`) and strip the staging field, so the
+      // `fallback` (under `highlightAfter: 'init'`) and strip the staging field, so the
       // hoisted loading fallback is already highlighted and nothing leaks to the
       // content. `collapseToEmpty` isn't threaded into the client here, so the `false`
       // form is assumed: under collapse-to-empty this may promote a few frames that are
@@ -337,13 +366,15 @@ function useCodeParsing({
   const [isHighlightAllowed, setIsHighlightAllowed] = React.useState(highlightAfter === 'init' || highlightAfter === 'hydration' && isHydrated);
   React.useEffect(() => {
     if (highlightAfter === 'idle') {
-      return requestIdle(() => setIsHighlightAllowed(true));
+      return requestIdle(() => setIsHighlightAllowed(true), {
+        timeout: IDLE_SWAP_TIMEOUT_MS
+      });
     }
     return undefined;
   }, [highlightAfter]);
 
   // Highlight instantly once hydrated, as a non-blocking client transition,
-  // rather than deferring to a scheduled task. (`highlightAt: 'idle'` above is
+  // rather than deferring to a scheduled task. (`highlightAfter: 'idle'` above is
   // the mode that deliberately keeps the unhighlighted first paint and swaps in
   // the highlighted tree on a later idle render.)
   React.useEffect(() => {
@@ -421,9 +452,9 @@ function useCodeParsing({
   const waitingForParsedCode = shouldHighlight && !!code && !allVariantsAlreadyHighlighted && !parsedCode;
 
   // Only signal `deferHighlight` while a highlight pass is actively in
-  // flight. When `shouldHighlight` is `false` (e.g. `highlightAt: 'idle'`
-  // before the idle window fires, or `'view'` before the block scrolls
-  // into view) we render the un-highlighted source as-is — downstream
+  // flight. When `shouldHighlight` is `false` (e.g. `highlightAfter: 'idle'`
+  // before the idle window fires) we render the un-highlighted source
+  // as-is — downstream
   // consumers like `useTransformManagement`'s `awaitHighlight` gate must
   // commit eagerly against that source instead of blocking the barrier
   // indefinitely. Once the trigger fires, `shouldHighlight` flips true,
@@ -436,7 +467,7 @@ function useCodeParsing({
   // needs to know whether the published `code` should be rendered as
   // highlighted HAST *now*. That answer is false in two distinct
   // windows that `deferHighlight` deliberately collapses out:
-  //   1. The trigger for `highlightAt: 'hydration' | 'idle' | 'visible'`
+  //   1. The trigger for `highlightAfter: 'hydration' | 'idle'`
   //      hasn't fired yet — `shouldHighlight` is still false. The
   //      precomputed `codeWithGlobals` already contains HAST, so
   //      without a render-side gate `<Pre>` would render highlighted
@@ -483,9 +514,30 @@ function useCodeTransforms({
   // so this effect never publishes a synchronous pass-through state.
   React.useEffect(() => {
     if (!parsedCode || !sourceParser || !computeHastDeltasLoader) {
-      return;
+      return undefined;
     }
 
+    // `settled` guards against two wedges: (1) a late write from a SUPERSEDED run
+    // (the cleanup flips it so an in-flight pipeline for an older `parsedCode` can't
+    // clobber the current one), and (2) the timeout below committing twice. The first
+    // commit wins.
+    let settled = false;
+    const commit = output => {
+      if (!settled) {
+        settled = true;
+        setTransformedState({
+          input: parsedCode,
+          output
+        });
+      }
+    };
+
+    // Safety net: if the pipeline neither resolves NOR rejects (a stalled worker / hung
+    // delta computation), the `catch` never fires and `waitingForTransformedCode` would
+    // stay true forever. Fall back to the un-delta'd parsed HAST so the gate drops and
+    // the block shows highlighted (un-transformed) code rather than plain text forever.
+    const timer = setTimeout(() => commit(parsedCode), TRANSFORM_PIPELINE_TIMEOUT_MS);
+
     // Process transformations for all variants
     (async () => {
       try {
@@ -494,18 +546,18 @@ function useCodeTransforms({
         // kept out of the initial bundle under CodeProviderLazy.
         const [parseSource, computeHastDeltas] = await Promise.all([sourceParser, computeHastDeltasLoader()]);
         const enhanced = await computeHastDeltas(parsedCode, parseSource);
-        setTransformedState({
-          input: parsedCode,
-          output: enhanced
-        });
+        commit(enhanced);
       } catch (error) {
         console.error(new Errors.ErrorCodeHighlighterClientTransformProcessingFailure(error));
-        setTransformedState({
-          input: parsedCode,
-          output: parsedCode
-        });
+        commit(parsedCode);
+      } finally {
+        clearTimeout(timer);
       }
     })();
+    return () => {
+      settled = true; // a newer run (or unmount) supersedes this one; ignore late writes
+      clearTimeout(timer);
+    };
   }, [parsedCode, sourceParser, computeHastDeltasLoader]);
 
   // When the full async pipeline is wired, expose the cached output regardless
@@ -903,10 +955,21 @@ export function CodeHighlighterClient(props) {
   // 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?.();
-  }, [controllerOnActivate]);
+    controllerOnActivate?.(editableFileTypes);
+  }, [controllerOnActivate, editableFileTypes]);
 
   // Grammar scopes the editable files need for live re-highlighting. Unlike the
   // speculative highlight/transform preloads — which intentionally skip
@@ -1061,7 +1124,9 @@ export function CodeHighlighterClient(props) {
   const [isEnhanceAllowed, setIsEnhanceAllowed] = React.useState(enhanceAfter === 'init' || enhanceAfter === 'hydration' && isHydrated);
   React.useEffect(() => {
     if (enhanceAfter === 'idle') {
-      return requestIdle(() => setIsEnhanceAllowed(true));
+      return requestIdle(() => setIsEnhanceAllowed(true), {
+        timeout: IDLE_SWAP_TIMEOUT_MS
+      });
     }
     return undefined;
   }, [enhanceAfter]);
@@ -1268,13 +1333,45 @@ export function CodeHighlighterClient(props) {
     setFallbackHasts: handleSetFallbackHasts,
     onHookCalled: handleHookCalled
   }), [variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants, 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
+  // at all — by merging PER VARIANT (live entries override the build-time ones; the rest
+  // stay visible). A whole-object swap (`controlled?.components || props.components`) would
+  // drop the build-time render for ALL variants the instant ANY one went live, flashing
+  // empty previews; the merge keeps "no live entry ⇒ show the build-time render".
+  //
+  // Each live entry is the lazy `DemoRunner`. Render it under a `Suspense` whose fallback is
+  // that variant's build-time render (shown while the chunk resolves), AND inject the same
+  // build-time render as the runner's `fallback` prop — so a live preview that throws on its
+  // FIRST render, before any successful one (e.g. a render-error first edit, where the
+  // baseline never got to paint), shows the original instead of blanking.
+  const bridgedComponents = React.useMemo(() => {
+    const live = controlled?.components;
+    if (!live) {
+      return props.components;
+    }
+    const merged = {
+      ...(props.components || {})
+    };
+    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);
+    }
+    return merged;
+  }, [controlled?.components, props.components]);
   const context = React.useMemo(() => ({
     code: overlaidCode,
     // Use processed/transformed code
     setCode: controlled?.setCode,
     selection: controlled?.selection || selection,
     setSelection: controlled?.setSelection || setSelection,
-    components: controlled?.components || props.components,
+    components: bridgedComponents,
+    errors: controlled?.errors,
     // Only suppress when an external CodeController owns the code; static
     // `props.code` still needs the locally-computed list.
     availableTransforms: controlled?.code ? [] : availableTransforms,
@@ -1287,7 +1384,7 @@ export function CodeHighlighterClient(props) {
     onEditingActivated: handleEditingActivated,
     refresh,
     preParsedCache
-  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, controlled?.code, availableTransforms, props.url, deferHighlight, activeFallbacks, highlightReady, highlightAfter, editActivation, handleEditingActivated, refresh, preParsedCache]);
+  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, bridgedComponents, controlled?.errors, controlled?.code, availableTransforms, props.url, deferHighlight, activeFallbacks, highlightReady, highlightAfter, editActivation, handleEditingActivated, refresh, preParsedCache]);
   if (!props.variants && !props.components && !activeCode) {
     throw new Errors.ErrorCodeHighlighterClientMissingData();
   }

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { type Code, type ControlledCode, type Fallbacks, type HastRoot } from "./types.mjs";
-import { type Selection } from "../CodeControllerContext/index.mjs";
+import type { Code, ControlledCode, Fallbacks, 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 —
@@ -18,6 +18,12 @@ export interface CodeHighlighterContextType {
   selection?: Selection;
   setSelection?: React.Dispatch<React.SetStateAction<Selection>>;
   components?: Record<string, React.ReactNode>;
+  /**
+   * Current runtime error message per variant key (or `null` when the variant
+   * rendered cleanly), bridged from the controller context. Surfaced through
+   * `useDemo().error`.
+   */
+  errors?: Record<string, string | null>;
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;

package/CodeHighlighter/buildStringFallback.d.mts

@@ -1,5 +1,5 @@
 import type { SourceComments, SourceEnhancers } from "./types.mjs";
-import { type FallbackNode } from "./fallbackFormat.mjs";
+import type { FallbackNode } from "./fallbackFormat.mjs";
 export interface StringFallbackResult {
   /** Compact, windowed fallback frames (text only — `.line` spans stripped). */
   fallback: FallbackNode[];

package/CodeHighlighter/codeToFallbackProps.d.mts

@@ -1,5 +1,5 @@
 import type { BaseContentLoadingProps, Code, Fallbacks } from "./types.mjs";
-import { type SourceLineCounts } from "../useCode/sourceLineCounts.mjs";
+import type { SourceLineCounts } from "../useCode/sourceLineCounts.mjs";
 /** Per-variant → per-file line metadata threaded for the fallback. */
 export type LineCountsByVariant = Record<string, Record<string, SourceLineCounts>>;
 export declare function codeToFallbackProps(variant: string, code?: Code, _fileName?: string, _needsAllFiles?: boolean, needsAllVariants?: boolean, allFallbackHasts?: Record<string, Fallbacks>, allLineCounts?: LineCountsByVariant): BaseContentLoadingProps;

package/CodeHighlighter/createClientProps.mjs

@@ -13,7 +13,7 @@ export function createClientProps(props) {
   const enhanceAfter = props.enhanceAfter === 'stream' ? 'init' : props.enhanceAfter;
 
   // Resolve the staging `fallbackCritical` on every variant of both carriers before
-  // they cross to the client: under `highlightAt: 'init'` (not `collapseToEmpty`)
+  // they cross to the client: under `highlightAfter: 'init'` (not `collapseToEmpty`)
   // promote it over the plain `fallback` so the first paint is highlighted with no
   // decompression, and always strip it so it never reaches `Content`/`ContentLoading`
   // or bloats the payload. `code` and `precompute` are forwarded separately (the
@@ -45,6 +45,9 @@ export function createClientProps(props) {
     } : undefined),
     ...(props.initialExpanded !== undefined ? {
       initialExpanded: props.initialExpanded
+    } : undefined),
+    ...(props.initialDisabled !== undefined ? {
+      initialDisabled: props.initialDisabled
     } : undefined)
   };
   return {

package/CodeHighlighter/fallbackCompression.d.mts

@@ -1,4 +1,4 @@
-import { type CompressedFallback } from "./fallbackFormat.mjs";
+import type { CompressedFallback } from "./fallbackFormat.mjs";
 import type { Code, Fallbacks } from "./types.mjs";
 /**
  * The residual fallbacks a `ContentLoading` component never renders, grouped

package/CodeHighlighter/fallbackFormat.d.mts

@@ -79,7 +79,7 @@ export declare function fallbackIsHighlighted(fallback: FallbackNode[]): boolean
  * render (`visibleFrames`). Off-screen frames are omitted — they flatten to exactly
  * {@link buildRootFallback}'s plain output, so storing them would just duplicate
  * `fallback` in the precompute. {@link promoteCriticalFallback} splices these back
- * over the plain fallback for `highlightAt: 'init'` (paint highlighted on the first
+ * over the plain fallback for `highlightAfter: 'init'` (paint highlighted on the first
  * render, zero decompression). Frame indices count `span.frame` children only,
  * matching `getInitialVisibleFrames`.
  *

package/CodeHighlighter/fallbackFormat.mjs

@@ -259,7 +259,7 @@ export function fallbackIsHighlighted(fallback) {
  * render (`visibleFrames`). Off-screen frames are omitted — they flatten to exactly
  * {@link buildRootFallback}'s plain output, so storing them would just duplicate
  * `fallback` in the precompute. {@link promoteCriticalFallback} splices these back
- * over the plain fallback for `highlightAt: 'init'` (paint highlighted on the first
+ * over the plain fallback for `highlightAfter: 'init'` (paint highlighted on the first
  * render, zero decompression). Frame indices count `span.frame` children only,
  * matching `getInitialVisibleFrames`.
  *

package/CodeHighlighter/parseControlledCode.d.mts

@@ -1,13 +1,22 @@
 import type { Code, ControlledCode, ParseSource } from "./types.mjs";
 import type { PreParsedCacheEntry } from "./CodeHighlighterContext.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
+ * evicting each other. The `\u0000` separator cannot appear in a variant key or
+ * file name, so the two parts can never run together ambiguously.
+ */
+export declare function preParsedCacheKey(variant: string, fileName: string): string;
 /**
  * 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.
+ * the cache (keyed by variant + file name). If the cached entry's source string
+ * matches byte-for-byte, the cached HAST is reused and `parseSource` is skipped.
+ * A fresh parse is WRITTEN THROUGH to the cache, so on the next controlled-code
+ * change (a keystroke updates one file) every unchanged file is reused instead
+ * of re-parsed — only the edited file's source differs. A stale entry is evicted
+ * and replaced; a parse failure keeps the raw string and is not cached.
  */
 export declare function parseControlledCode(controlledCode: ControlledCode, parseSource: ParseSource, preParsedCache?: Map<string, PreParsedCacheEntry>): Code;

package/CodeHighlighter/parseControlledCode.mjs

@@ -1,31 +1,50 @@
+/**
+ * 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
+ * evicting each other. The `\u0000` separator cannot appear in a variant key or
+ * file name, so the two parts can never run together ambiguously.
+ */
+export function preParsedCacheKey(variant, fileName) {
+  return `${variant}\u0000${fileName}`;
+}
+
 /**
  * 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.
+ * the cache (keyed by variant + file name). If the cached entry's source string
+ * matches byte-for-byte, the cached HAST is reused and `parseSource` is skipped.
+ * A fresh parse is WRITTEN THROUGH to the cache, so on the next controlled-code
+ * change (a keystroke updates one file) every unchanged file is reused instead
+ * of re-parsed — only the edited file's source differs. A stale entry is evicted
+ * and replaced; a parse failure keeps the raw string and is not cached.
  */
 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.
+   * Resolves one file's string source to HAST, reusing a cached parse on an exact
+   * source match and writing a fresh parse through to the cache. Returns the raw
+   * string (uncached) if `parseSource` throws.
    */
-  const tryCache = (fileName, source) => {
-    if (!preParsedCache) {
-      return undefined;
-    }
-    const entry = preParsedCache.get(fileName);
-    if (!entry) {
-      return undefined;
+  const resolveSource = (variant, fileName, source) => {
+    const key = preParsedCacheKey(variant, fileName);
+    const entry = preParsedCache?.get(key);
+    if (entry) {
+      if (entry.source === source) {
+        return entry.hast;
+      }
+      preParsedCache?.delete(key);
     }
-    if (entry.source === source) {
-      return entry.hast;
+    try {
+      const hast = parseSource(source, fileName);
+      preParsedCache?.set(key, {
+        source,
+        hast
+      });
+      return hast;
+    } catch {
+      return source;
     }
-    preParsedCache.delete(fileName);
-    return undefined;
   };
   const parsed = {};
   for (const [variant, variantCode] of Object.entries(controlledCode)) {
@@ -39,17 +58,7 @@ export function parseControlledCode(controlledCode, parseSource, preParsedCache)
       // Convert null to empty string, then parse
       const sourceToProcess = variantCode.source === null ? '' : variantCode.source;
       if (typeof sourceToProcess === 'string' && variantCode.fileName) {
-        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;
-          }
-        }
+        mainSource = resolveSource(variant, variantCode.fileName, sourceToProcess);
       } else if (typeof sourceToProcess === 'string' && !variantCode.fileName) {
         // Return a basic HAST root node with the source text for unsupported file types
         // This indicates that the source has at least passed through the parsing pipeline
@@ -74,27 +83,10 @@ export function parseControlledCode(controlledCode, parseSource, preParsedCache)
           // Convert null to empty string, then parse
           const fileSourceToProcess = fileData.source === null ? '' : fileData.source;
           if (typeof fileSourceToProcess === 'string') {
-            const cached = tryCache(fileName, fileSourceToProcess);
-            if (cached) {
-              parsedExtraFiles[fileName] = {
-                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
-                };
-              }
-            }
+            parsedExtraFiles[fileName] = {
+              source: resolveSource(variant, fileName, fileSourceToProcess),
+              comments: fileData.comments
+            };
           } else {
             // Keep other values as-is
             parsedExtraFiles[fileName] = {

package/CodeHighlighter/prepareInitialSource.mjs

@@ -33,7 +33,7 @@ export function prepareInitialSource(props) {
   const initialExpandedEnabled = initialExpanded === true;
 
   // Fold each variant's staging `fallbackCritical` into its plain `fallback` up front
-  // (under `highlightAt: 'init'`, not `collapseToEmpty`), then strip it. The hoisted
+  // (under `highlightAfter: 'init'`, not `collapseToEmpty`), then strip it. The hoisted
   // loading fallback is therefore already highlighted-visible — so the first paint is
   // highlighted with no decompression — while the rest of this function (strip, hoist,
   // window, compress) operates on a single `fallback` field with no awareness of the

package/CodeHighlighter/resolveFallbackCritical.d.mts

@@ -4,7 +4,7 @@ type HighlightAfter = CodeHighlighterBaseProps<{}>['highlightAfter'];
  * Resolve the staging `fallbackCritical` field at a server→client (or client-load)
  * boundary, returning a clone of `code` ready to cross to the client:
  *
- * - **Promote** — under `highlightAt: 'init'` (and not `collapseToEmpty`), each
+ * - **Promote** — under `highlightAfter: 'init'` (and not `collapseToEmpty`), each
  *   variant whose `fallbackCritical` *and* plain `fallback` are both present has the
  *   sparse `fallbackCritical` diff spliced over its `fallback` (`promoteCriticalFallback`)
  *   — the visible frames become highlighted, the rest stay plain — so the first paint is