@mui/internal-docs-infra 0.12.1-canary.5 → 0.12.1-canary.7

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/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,
@@ -337,7 +366,9 @@ 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]);
@@ -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

@@ -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/createClientProps.mjs

@@ -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/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/types.d.mts

@@ -240,6 +240,14 @@ export type ControlledVariantCode = CodeMeta & {
   collapseMap?: CollapseMap;
   totalLines?: number;
   emptyLines?: number[];
+  /**
+   * The pre-edit build inputs, carried ONLY on the first edit of a variant (the
+   * transition from precomputed to controlled). The live runner builds this as a
+   * baseline first — so a broken first edit has a good last-good render to fall
+   * back to — then swaps to the edited `source`. Read by `useVariantBuilds`;
+   * stripped on the next edit so it does not linger in the controlled state.
+   */
+  original?: Pick<ControlledVariantCode, 'source' | 'extraFiles'>;
 };
 export type ControlledCode = {
   [key: string]: undefined | null | ControlledVariantCode;
@@ -261,6 +269,14 @@ type BaseContentProps = CodeIdentityProps & Pick<CodeContentProps, 'code' | 'com
    * see it too.
    */
   initialExpanded?: boolean;
+  /**
+   * Start an editable block read-only (a truthy value), leaving it to the
+   * `editable` / `setEditable` toggle `useCode` returns to turn editing on.
+   * Runtime-only; lives on `contentProps` — the demo factory resolves a demo's
+   * `initialDisabled` (instance prop → `meta` → `createDemoFactory` default) into it.
+   * Distinct from the hard `disabled` opt, which forbids editing outright.
+   */
+  initialDisabled?: boolean;
 };
 export type ContentProps<T extends {}> = BaseContentProps & T;
 /**
@@ -622,6 +638,11 @@ export interface CodeHighlighterBaseProps<T extends {}> extends CodeIdentityProp
    * `contentProps` so both `useCode` and the loading fallback honor it.
    */
   initialExpanded?: boolean;
+  /**
+   * Start the editable code read-only. Threaded into `contentProps`; `useCode` seeds its
+   * `editable` toggle from it (a reader flips it back with `setEditable`). Runtime-only.
+   */
+  initialDisabled?: boolean;
 }
 /**
  * Props for the client-side CodeHighlighter component.

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/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 {};