@mui/internal-docs-infra 0.11.1-canary.21 → 0.11.1-canary.22

package/useCode/useCode.mjs

@@ -42,19 +42,25 @@ export function useCode(contentProps, opts) {
   // configure the baseline (e.g., `@highlight` / `@focus` framing) while
   // individual `useCode` callers add demo-specific extras without losing the
   // shared defaults.
+  // Hoist the optional controller member into a stable local so the memo's
+  // inferred dependency matches the source dependency. `useControlledCode()`
+  // always returns a fresh object, so `controllerContext` is never null but
+  // changes identity every render; depending on the narrowed value keeps the
+  // memo correct (and lets the compiler preserve the manual memoization).
+  const controllerEnhancers = controllerContext?.sourceEnhancers;
   const mergedEnhancers = React.useMemo(() => {
     const enhancers = [];
     if (codeContext.sourceEnhancers) {
       enhancers.push(...codeContext.sourceEnhancers);
     }
-    if (controllerContext?.sourceEnhancers) {
-      enhancers.push(...controllerContext.sourceEnhancers);
+    if (controllerEnhancers) {
+      enhancers.push(...controllerEnhancers);
     }
     if (sourceEnhancers) {
       enhancers.push(...sourceEnhancers);
     }
     return enhancers.length > 0 ? enhancers : undefined;
-  }, [codeContext.sourceEnhancers, controllerContext?.sourceEnhancers, sourceEnhancers]);
+  }, [codeContext.sourceEnhancers, controllerEnhancers, sourceEnhancers]);
 
   // Get the effective code - context overrides contentProps if available
   const effectiveCode = React.useMemo(() => {
@@ -299,8 +305,10 @@ export function useCode(contentProps, opts) {
   }, []);
   React.useEffect(() => {
     if (pendingExpand && !swapInFlight) {
+      /* eslint-disable react-hooks/set-state-in-effect -- intentional queue drain: commit deferred expand only after in-flight swaps settle (swapInFlight transitions false on a later render); see comment above re: flicker-avoidance and same-batch synchronous-expand semantics */
       setPendingExpand(false);
       setExpanded(true);
+      /* eslint-enable react-hooks/set-state-in-effect */
     }
   }, [pendingExpand, swapInFlight, setExpanded]);
 

package/useCode/{liveEditingBugs.browser.mjs → useEditable.integration.browser.mjs}

@@ -1,19 +1,17 @@
 var _style;
 /**
- * Reproduction harness + tests for four live-editing bugs reported against the
- * docs live code editor:
+ * Browser integration tests for `useEditable`: the full type → flush → re-highlight →
+ * restore cycle the docs live code editor runs on every keystroke. They cover the
+ * behaviors that only emerge when the highlighted DOM is replaced underneath the caret —
+ * caret stability while typing and deleting indents, scroll-anchor `onBoundary` firing at
+ * the visible top/bottom, focus retention on the first keystroke, and a selection's
+ * direction surviving a re-render.
  *
- *   1. Erasing the last indent (tab) unit on a line makes the view jump.
- *   2. Pressing ArrowUp at the visible top doesn't trigger the scroll anchor.
- *   3. Typing `x`, then `=`, then Backspace sends the caret to column 0.
- *   4. The first keystroke in the editable loses focus.
- *
- * Unlike `useEditable.browser.ts` (which drives a static highlighted DOM with a
- * `vi.fn()` onChange and only asserts the *text* handed to onChange), these
- * tests wire `useEditable` to a real React component whose `onChange` updates
- * source state, re-highlights it into the production `.line`/`pl-*` span
- * structure, and lets the engine's `observeAndRestore` restore the caret — i.e.
- * the full type → flush → re-highlight → restore cycle that the bugs live in.
+ * Unlike `useEditable.browser.ts` (which drives a static highlighted DOM with a `vi.fn()`
+ * onChange and only asserts the *text* handed to onChange), these tests wire `useEditable`
+ * to a real React component whose `onChange` updates source state, re-highlights it into
+ * the production `.line`/`pl-*` span structure, and lets the engine's `observeAndRestore`
+ * restore the caret.
  */
 import * as React from 'react';
 import { describe, it, expect, vi, beforeAll, afterEach } from 'vitest';
@@ -270,11 +268,11 @@ function deferredPreParse() {
     }
   };
 }
-describe('live-editing bug repros', () => {
+describe('useEditable — caret & selection across re-highlights', () => {
   // -------------------------------------------------------------------------
-  // Bug 3: type x, =, Backspace -> caret jumps to column 0
+  // Caret stability when typing x, =, Backspace (must not jump to column 0)
   // -------------------------------------------------------------------------
-  it('Bug 3a: fresh line — x, =, Backspace keeps caret after x', async () => {
+  it('keeps the caret after the typed char when typing x, =, Backspace on a fresh line', async () => {
     const {
       handle,
       element
@@ -295,7 +293,7 @@ describe('live-editing bug repros', () => {
       column: 1
     });
   });
-  it('Bug 3b: x, =, Backspace with async preParse keeps caret after x', async () => {
+  it('keeps the caret after the typed char through an async re-highlight (preParse)', async () => {
     const {
       handle,
       element
@@ -320,7 +318,7 @@ describe('live-editing bug repros', () => {
       column: 1
     });
   });
-  it('Bug 3c: typing =, Backspace at end of an existing indented JSX-ish line', async () => {
+  it('keeps the caret when typing = then Backspace at the end of an indented line', async () => {
     // `      <p style=` then backspace the `=`. This mirrors typing an attribute.
     const initial = 'function App() {\n  return <p style\n}\n';
     const {
@@ -344,7 +342,7 @@ describe('live-editing bug repros', () => {
       column: '  return <p style'.length
     });
   });
-  it('Bug 3d: collapsed (minColumn) — x, =, Backspace at end of an indented line keeps caret after x', async () => {
+  it('keeps the caret at the end of an indented line in a collapsed (minColumn) gutter', async () => {
     // The collapsed editor (clipped indent gutter) is where the real bug shows.
     const initial = 'function foo() {\n  doStuff()\n}\n';
     const {
@@ -372,7 +370,7 @@ describe('live-editing bug repros', () => {
       column: '  doStuff()x'.length
     });
   });
-  it('Bug 3e: collapsed + async preParse — x, =, Backspace keeps caret after x', async () => {
+  it('keeps the caret in a collapsed gutter through an async re-highlight', async () => {
     const initial = 'function foo() {\n  doStuff()\n}\n';
     const {
       handle,
@@ -403,7 +401,7 @@ describe('live-editing bug repros', () => {
       column: '  doStuff()x'.length
     });
   });
-  it('Bug 3f: End then x, =, Backspace at a line end (caret lands at the line/gap boundary)', async () => {
+  it('lands the caret at the line/gap boundary when editing at the end of a line', async () => {
     // The real bug uses the `End` key to land the caret at the line end — which
     // in the framed `.line` structure is the boundary with the inter-line gap
     // node. Native typing there can flatten the spans / split across lines.
@@ -433,14 +431,13 @@ describe('live-editing bug repros', () => {
   });
 
   // -------------------------------------------------------------------------
-  // Bug 1: erasing the last indent on a clipped (collapsed-window) line jumps
+  // Caret restoration when erasing the last indent on a clipped (collapsed-window) line
   // -------------------------------------------------------------------------
-  it('Bug 1a: Backspace of last indent on a blank clipped line (minColumn) — where does caret land?', async () => {
+  it('restores the caret when backspacing the last indent of a blank clipped line (minColumn)', async () => {
     // Simulate a collapsed window: indentation clipped to minColumn=2, the
     // visible region is rows 1..3. Line 2 is a blank line with exactly 2 spaces.
     const initial = 'function foo() {\n  const a = 1;\n  \n  return a;\n}\n';
     const {
-      handle,
       element
     } = await setupEditor(initial, {
       indentation: 2,
@@ -459,17 +456,12 @@ describe('live-editing bug repros', () => {
     await userEvent.keyboard('{Backspace}');
     await settle();
     const after = caretLineColumn(element);
-    // The reported source + caret movement reveal whether the whole line
-    // collapsed (caret jumps to the previous line) or just one indent went away.
-    // eslint-disable-next-line no-console
-    console.log('Bug1a before', before, 'after', after, 'source', JSON.stringify(handle.getSource()));
     // Assert the (arguably correct) behavior: stay on the same line, now empty.
     expect(after.line).toBe(before.line);
   });
-  it('Bug 1b: Backspace of indent on a content line in a clipped gutter (minColumn)', async () => {
+  it('restores the caret when backspacing an indent on a content line in a clipped gutter (minColumn)', async () => {
     const initial = 'function foo() {\n  const a = 1;\n}\n';
     const {
-      handle,
       element
     } = await setupEditor(initial, {
       indentation: 2,
@@ -487,15 +479,13 @@ describe('live-editing bug repros', () => {
     await userEvent.keyboard('{Backspace}');
     await settle();
     const after = caretLineColumn(element);
-    // eslint-disable-next-line no-console
-    console.log('Bug1b after', after, 'source', JSON.stringify(handle.getSource()));
     expect(after).toBeTruthy();
   });
 
   // -------------------------------------------------------------------------
-  // Bug 2: ArrowUp at the visible top should fire onBoundary (scroll anchor)
+  // ArrowUp at the visible top fires onBoundary (scroll anchor)
   // -------------------------------------------------------------------------
-  it('Bug 2: ArrowUp at minRow fires onBoundary; ArrowDown at maxRow fires onBoundary', async () => {
+  it('fires onBoundary on ArrowUp at the first row and ArrowDown at the last row', async () => {
     const onBoundary = vi.fn();
     const initial = 'line0\nline1\nline2\nline3\nline4\n';
     const {
@@ -522,26 +512,22 @@ describe('live-editing bug repros', () => {
     await userEvent.keyboard('{ArrowDown}');
     await settle();
     const downCalls = onBoundary.mock.calls.length - upCalls;
-
-    // eslint-disable-next-line no-console
-    console.log('Bug2 onBoundary up-calls', upCalls, 'down-calls', downCalls);
     expect(upCalls).toBeGreaterThan(0); // ArrowUp must fire the boundary
     expect(downCalls).toBeGreaterThan(0); // ArrowDown must fire the boundary
   });
 
   // -------------------------------------------------------------------------
-  // Clue A: backspace last indent + async re-highlight shows the wrong thing
-  // transiently (during the worker round-trip the line is collapsed but the
-  // committed source hasn't caught up yet).
+  // Transient DOM vs committed source during an async re-highlight: backspacing the
+  // last indent collapses the line during the worker round-trip, before the committed
+  // source catches up.
   // -------------------------------------------------------------------------
-  it('Clue A: async backspace of last indent — transient DOM vs committed source', async () => {
+  it('keeps the transient DOM consistent with the committed source when async-backspacing the last indent', async () => {
     const {
       preParse,
       resolvePending
     } = deferredPreParse();
     const initial = 'function foo() {\n  const a = 1;\n  \n  return a;\n}\n';
     const {
-      handle,
       element
     } = await setupEditor(initial, {
       indentation: 2,
@@ -577,37 +563,20 @@ describe('live-editing bug repros', () => {
     await settle();
 
     // DURING the async gap (preParse not yet resolved): what does the DOM show?
-    const transientText = element.textContent ?? '';
-    const transientLineCount = element.querySelectorAll('.line').length;
     const transientSig = signature();
-    const committedDuringGap = handle.onChange.mock.calls.length;
     await resolvePending();
     await settle();
-    const finalText = element.textContent ?? '';
     const finalSig = signature();
-    const finalSource = handle.getSource();
-    // eslint-disable-next-line no-console
-    console.log('ClueA transient', JSON.stringify(transientText), 'lines', transientLineCount, 'committedDuringGap', committedDuringGap, '| final', JSON.stringify(finalText), 'source', JSON.stringify(finalSource));
-    // The transient DOM should already match the final committed text — i.e.
-    // the user must NOT see a wrong intermediate state. If they differ, the
-    // async path is showing the wrong thing for a moment.
-    void transientText;
-    void transientLineCount;
-    void committedDuringGap;
-    void finalText;
-    void finalSource;
-    // DESIRED: the DOM the user sees during the async worker round-trip should
-    // already be structurally consistent with the committed result. Currently
-    // it is NOT — `edit.insert` leaves a dangling empty `.line` span and drops
-    // the gap newline, so this fails (reproducing "shows the wrong thing for a
-    // second") until the async commit cleans it up.
+    // The transient DOM the user sees during the async worker round-trip must already
+    // be structurally consistent with the final committed result — no wrong intermediate
+    // state (no dangling empty `.line` span, no dropped gap newline), so the signatures match.
     expect(transientSig).toEqual(finalSig);
   });
 
   // -------------------------------------------------------------------------
-  // Clue B: ArrowUp navigation across empty lines is "weird".
+  // ArrowUp navigation across consecutive empty lines
   // -------------------------------------------------------------------------
-  it('Clue B: ArrowUp across an empty line lands on the empty line, then the line above', async () => {
+  it('moves ArrowUp onto an empty line first, then the line above', async () => {
     const initial = 'aaa\n\nbbb\nccc\n';
     const {
       element
@@ -643,7 +612,7 @@ describe('live-editing bug repros', () => {
   // -------------------------------------------------------------------------
   // New bug: TWO consecutive empty lines — ArrowUp skips both at once.
   // -------------------------------------------------------------------------
-  it('Clue B2: ArrowUp stops on each of two consecutive empty lines (does not skip both)', async () => {
+  it('stops ArrowUp on each of two consecutive empty lines (does not skip both)', async () => {
     // Lines: 0 "aaa", 1 "" , 2 "", 3 "bbb", 4 "ccc".
     const initial = 'aaa\n\n\nbbb\nccc\n';
     const {
@@ -682,10 +651,10 @@ describe('live-editing bug repros', () => {
   });
 
   // -------------------------------------------------------------------------
-  // Bug 5: a BACKWARD Shift+Arrow selection keeps its focus at the top across a
+  // A BACKWARD Shift+Arrow selection keeps its focus at the top across a
   // host re-render (the restore must not flip the focus to the bottom end).
   // -------------------------------------------------------------------------
-  it('Bug 5: backward Shift+ArrowUp selection survives a re-render with the focus still at the top', async () => {
+  it('preserves a backward Shift+ArrowUp selection across a re-render, focus still at the top', async () => {
     const initial = 'aaa\nbbb\nccc\nddd\n';
     const {
       handle,
@@ -747,9 +716,9 @@ describe('live-editing bug repros', () => {
   });
 
   // -------------------------------------------------------------------------
-  // Bug 4: first keystroke loses focus (async preParse path)
+  // Focus retention on the first keystroke (async preParse path)
   // -------------------------------------------------------------------------
-  it('Bug 4: editable keeps focus after the first keystroke (async preParse)', async () => {
+  it('keeps focus after the first keystroke through an async re-highlight', async () => {
     const {
       element
     } = await setupEditor('hello\n', {
@@ -822,4 +791,80 @@ describe('live-editing bug repros', () => {
       expect(caretLineColumn(element).line, 'caret jumped to the top edge').toBe(2);
     }
   });
+});
+
+// ---------------------------------------------------------------------------
+// deletedFromLineStart: whole-line removals only, not in-place collapses
+// ---------------------------------------------------------------------------
+// A selection delete reports `deletedFromLineStart` so the controlled
+// comment/highlight map drops its anchor one line — the post-delete caret sits on
+// a line that shifted up from below the deletion. That must be limited to
+// deletions that removed WHOLE lines. A selection that ends mid-line collapses the
+// spanned lines INTO the first line, which survives (emptied) under the caret;
+// reporting the flag there drags a marker on that surviving line one line too high
+// (the live-editor "the highlight shifts up instead of being deleted" bug). The
+// source stands in for an @highlight block on lines 4-6 with blank padding (3, 7).
+describe('useEditable — selection delete reports deletedFromLineStart only for whole-line removals', () => {
+  const SRC = 'const a = 1;\nconst b = 2;\n\ndoThing();\ndoOther();\ndoLast();\n\nconst c = 3;\n';
+  const lastPosition = handle => handle.onChange.mock.calls.at(-1)?.[1];
+  it('reports the flag when a column-0 selection removes whole lines', async () => {
+    const {
+      handle,
+      element
+    } = await setupEditor(SRC, {
+      indentation: 2,
+      caretSelector: '.line'
+    });
+    // Column 0 of the blank line 3 → column 0 of the blank line 7 (a line boundary):
+    // whole lines 3-6 are removed and line 7 shifts up under the caret.
+    await placeCaret(element, 26);
+    await userEvent.keyboard('{Shift>}{ArrowDown}{ArrowDown}{ArrowDown}{ArrowDown}{/Shift}');
+    await settle();
+    await userEvent.keyboard('{Backspace}');
+    await settle();
+    expect(handle.getSource()).toBe('const a = 1;\nconst b = 2;\n\nconst c = 3;\n');
+    expect(lastPosition(handle)?.deletedFromLineStart).toBe(true);
+  });
+  it('reports the flag when a column-0 selection stops on the region’s exclusive -end line', async () => {
+    const {
+      handle,
+      element
+    } = await setupEditor(SRC, {
+      indentation: 2,
+      caretSelector: '.line'
+    });
+    // Column 0 of the blank line 3 → column 0 of line 6 (still a line boundary), one
+    // ArrowDown short of scenario A. A range's @highlight-end is EXCLUSIVE — it sits
+    // on the line just below the last highlighted line — so selecting "from the line
+    // above through the last newline of the region" lands here, deleting the whole
+    // highlighted body (lines 4-5) while doLast() (the -end line) survives. This is
+    // still a whole-line removal, so the flag holds; the matching comment-map case is
+    // `useSourceEditing`'s "removes the highlight when the selection stops on the
+    // region’s exclusive -end line".
+    await placeCaret(element, 26);
+    await userEvent.keyboard('{Shift>}{ArrowDown}{ArrowDown}{ArrowDown}{/Shift}');
+    await settle();
+    await userEvent.keyboard('{Backspace}');
+    await settle();
+    expect(handle.getSource()).toBe('const a = 1;\nconst b = 2;\ndoLast();\n\nconst c = 3;\n');
+    expect(lastPosition(handle)?.deletedFromLineStart).toBe(true);
+  });
+  it('does NOT report the flag when the selection ends mid-line and collapses in place', async () => {
+    const {
+      handle,
+      element
+    } = await setupEditor(SRC, {
+      indentation: 2,
+      caretSelector: '.line'
+    });
+    // Column 0 of line 4 → the END of line 6 (mid-line, NOT a line boundary): the three
+    // region lines collapse into one empty line that survives under the caret.
+    await placeCaret(element, 27);
+    await userEvent.keyboard('{Shift>}{ArrowDown}{ArrowDown}{End}{/Shift}');
+    await settle();
+    await userEvent.keyboard('{Backspace}');
+    await settle();
+    expect(handle.getSource()).toBe('const a = 1;\nconst b = 2;\n\n\n\nconst c = 3;\n');
+    expect(lastPosition(handle)?.deletedFromLineStart).not.toBe(true);
+  });
 });

package/useCode/useFileNavigation.mjs

@@ -103,19 +103,12 @@ export function useFileNavigation({
   // Detect if the current variant change was driven by a hash change
   // A variant change is hash-driven if the hash has a variant that matches where we're going
   // AND we weren't already on that variant (i.e., the hash is what triggered the change)
-  const [prevHashVariant, setPrevHashVariant] = React.useState(hashVariant || null);
   const isHashDrivenVariantChange = hashVariant === selectedVariantKey && prevVariantKeyState !== selectedVariantKey;
 
-  // Update prevHashVariant when hashVariant changes
-  React.useEffect(() => {
-    if (hashVariant !== prevHashVariant) {
-      setPrevHashVariant(hashVariant || null);
-    }
-  }, [hashVariant, prevHashVariant]);
-
   // Update prevVariantKeyState when variant changes
   React.useEffect(() => {
     if (selectedVariantKey !== prevVariantKeyState) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- previous-value tracker; render-time rewrite changes effect ordering for the hash-update effect that reads isHashDrivenVariantChange as a dep
       setPrevVariantKeyState(selectedVariantKey);
     }
   }, [selectedVariantKey, prevVariantKeyState]);
@@ -567,18 +560,29 @@ export function useFileNavigation({
     if (selectedFile == null) {
       return 0;
     }
-    if (!transformedFiles && selectedFileLineCounts && selectedFileLineCounts.totalLines > 0) {
-      return selectedFileLineCounts.totalLines;
-    }
 
-    // If it's a string, split by newlines and count
+    // If it's a string, split by newlines and count.
     if (typeof selectedFile === 'string') {
       return selectedFile.split('\n').length;
     }
 
-    // If it's a hast object, count the children length. The selected file's
-    // `fallback` is forwarded to `decodeHastSource` so the `hastCompressed`
-    // payload is decompressed with the matching DEFLATE dictionary.
+    // A compressed payload (`hastCompressed` / `hastJson`) is never a transformed
+    // tree — transforms produce live HAST — so the stored variant count is
+    // authoritative for it. Use it instead of decompressing the source just to read
+    // the count, even when OTHER files in the variant are transformed. Only a live
+    // (transformed or in-hand) tree, or a legacy payload with no stored count, falls
+    // through to read the hast below.
+    const isCompressedSource = 'hastJson' in selectedFile || 'hastCompressed' in selectedFile;
+    if (isCompressedSource && selectedFileLineCounts && selectedFileLineCounts.totalLines > 0) {
+      return selectedFileLineCounts.totalLines;
+    }
+
+    // A live HAST tree (e.g. a transformed source) carries its own up-to-date counts
+    // in `root.data`; `decodeHastSource` returns such a tree unchanged (no
+    // decompression). A compressed source with no stored count (a legacy precompute)
+    // is the only case that actually decompresses here — and it's the same tree
+    // `<Pre>` decodes to render, so the shared decode cache amortizes it. The
+    // selected file's `fallback` is forwarded as the matching DEFLATE dictionary.
     const hastSelectedFile = decodeHastSource(selectedFile, selectedFileFallback);
     if (hastSelectedFile) {
       if (hastSelectedFile.data && 'totalLines' in hastSelectedFile.data) {
@@ -598,7 +602,7 @@ export function useFileNavigation({
       }
     }
     return 0;
-  }, [selectedFile, selectedFileFallback, selectedFileLineCounts, transformedFiles]);
+  }, [selectedFile, selectedFileFallback, selectedFileLineCounts]);
 
   // Convert files for the return interface
   const files = React.useMemo(() => {

package/useCode/useTransformManagement.mjs

@@ -89,6 +89,10 @@ export function useTransformManagement({
     }
     const warm = peekTransformEngine();
     if (warm) {
+      // Adopt a sibling-warmed engine synchronously; the surrounding effect is a
+      // real async load. `peekTransformEngine()` is an impure read of a
+      // module-mutable cache, so this cannot be derived during render.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setTransformEngine(() => warm);
       return undefined;
     }
@@ -440,21 +444,25 @@ export function useTransformManagement({
       setPostSwapWindowActive(true);
     }
   }
+  // The window only ever opens under `hasDelay` (line above), so an open window
+  // when `!hasDelay` means `hasDelay` flipped true→false — a derivable invariant,
+  // not a side-effect. Clear it during render so it lands on the same commit.
+  if (postSwapWindowActive && !hasDelay) {
+    setPostSwapWindowActive(false);
+  }
   React.useEffect(() => {
     if (!postSwapWindowActive) {
       return undefined;
     }
-    if (!hasDelay) {
-      setPostSwapWindowActive(false);
-      return undefined;
-    }
     // `delayedAppliedTransform` is in the dep array so a fresh swap
     // during an already-open window (A → B → C in rapid succession)
     // re-arms the timer for the full `transformDelay` instead of
     // inheriting whatever was left over from B's window.
     const timerId = setTimeout(() => setPostSwapWindowActive(false), transformDelay);
     return () => clearTimeout(timerId);
-  }, [postSwapWindowActive, hasDelay, transformDelay, delayedAppliedTransform]);
+    // `hasDelay` is intentionally not a dependency: the body never reads it (the
+    // `!hasDelay` window teardown is the render-time clear above).
+  }, [postSwapWindowActive, transformDelay, delayedAppliedTransform]);
 
   // If both phases are technically eligible (e.g. user clicked a third
   // target during a post-swap window), the pending pre-swap takes

package/useCode/useUIState.mjs

@@ -14,12 +14,12 @@ export function useUIState({
   const [expanded, setExpanded] = React.useState(initialExpanded || hasRelevantHash);
   const expand = React.useCallback(() => setExpanded(true), []);
 
-  // Auto-expand if hash becomes relevant
-  React.useEffect(() => {
-    if (hasRelevantHash && !expanded) {
-      setExpanded(true);
-    }
-  }, [hasRelevantHash, expanded]);
+  // Auto-expand if hash becomes relevant. This is a one-way OR-latch: it ratchets
+  // `expanded` to true but never collapses, so adjusting state during render is safe
+  // (the branch is skipped once `expanded` is true, avoiding an extra render).
+  if (hasRelevantHash && !expanded) {
+    setExpanded(true);
+  }
   return {
     expanded,
     expand,

package/useCode/useVariantSelection.mjs

@@ -198,6 +198,10 @@ export function useVariantSelection({
     if (deferHighlight) {
       return;
     }
+    // Intentional later-tick latch: see the bootstrap-gate comment above.
+    // Flipping this during render skips the receiver-flow swap animation and
+    // prevents `pendingBootstrap` from ever latching.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setAllowStoredBootstrap(true);
   }, [storedVariantSourceLoaded, deferHighlight]);
 
@@ -389,11 +393,18 @@ export function useVariantSelection({
     if (hasCommittedPastInitial || !committedVariantKey) {
       return;
     }
+    // Intentional later-tick latch: see the bootstrap-gate comment above.
+    // This freezes the first non-empty committed value and only later detects
+    // moving past it; moving the detection into render shifts exactly when
+    // `pendingBootstrap` releases relative to paint, which the
+    // highlight-suppression sequence was tuned around.
+    /* eslint-disable react-hooks/set-state-in-effect */
     if (initialCommittedVariantKey === null) {
       setInitialCommittedVariantKey(committedVariantKey);
     } else if (committedVariantKey !== initialCommittedVariantKey) {
       setHasCommittedPastInitial(true);
     }
+    /* eslint-enable react-hooks/set-state-in-effect */
   }, [committedVariantKey, hasCommittedPastInitial, initialCommittedVariantKey]);
 
   // Reset both bootstrap latches whenever the storage bucket
@@ -526,21 +537,24 @@ export function useVariantSelection({
     }
     setPrevAppliedVariant(committedVariantKey);
   }
+  // Tear down a stale window synchronously at render time: no animation
+  // window should exist without a delay, so a window left open after
+  // `hasDelay` flips to false is cleared a tick earlier than an effect would,
+  // with no animation to disrupt (there is no delay).
+  if (postSwapWindowActive && !hasDelay) {
+    setPostSwapWindowActive(false);
+    setCollapseSourceVariantKey(null);
+  }
   React.useEffect(() => {
     if (!postSwapWindowActive) {
       return undefined;
     }
-    if (!hasDelay) {
-      setPostSwapWindowActive(false);
-      setCollapseSourceVariantKey(null);
-      return undefined;
-    }
     const timerId = setTimeout(() => {
       setPostSwapWindowActive(false);
       setCollapseSourceVariantKey(null);
     }, effectiveSwapWindowMs);
     return () => clearTimeout(timerId);
-  }, [postSwapWindowActive, hasDelay, effectiveSwapWindowMs, committedVariantKey]);
+  }, [postSwapWindowActive, effectiveSwapWindowMs, committedVariantKey]);
 
   // If both phases are technically eligible, the pending pre-swap
   // takes priority — the visible tree IS the just-applied one and it

package/useCoordinated/coordinatePreference.mjs

@@ -1,29 +1,8 @@
 import { performanceMeasure } from "../pipeline/loadPrecomputedCodeHighlighter/performanceLogger.mjs";
-
-/**
- * Yield to the browser before invoking a user-supplied `preload`.
- *
- * Coordinator entries that announce a target have already triggered
- * a render (loading indicator, coordinating state, etc.) on the
- * preceding event-loop turn. Yielding here pushes the (potentially
- * CPU-bound) preload work into a fresh macrotask so the browser can
- * paint that intermediate state before the preload monopolizes the
- * main thread. Without this, preload runs inline on the same task
- * as the originating event and starves paint until it completes.
- *
- * Uses `scheduler.yield()` when available (modern Chromium) for
- * better priority handling; falls back to `setTimeout(_, 0)` which
- * macrotask-defers in every browser and in fake-timer environments.
- */
-function yieldToMain() {
-  const sch = globalThis.scheduler;
-  if (typeof sch?.yield === 'function') {
-    return sch.yield();
-  }
-  return new Promise(resolve => {
-    setTimeout(resolve, 0);
-  });
-}
+// `yieldToMain` is used here to push a user-supplied `preload` into a fresh
+// macrotask so the browser can paint the just-announced loading state before the
+// (potentially CPU-bound) preload monopolizes the main thread.
+import { yieldToMain } from "./scheduleTasks.mjs";
 
 /**
  * Generic same-tab preference coordinator. Its primary purpose is

package/useCoordinated/scheduleTasks.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Yield the current task back to the browser so it can paint and process input
+ * before the awaited continuation runs.
+ *
+ * Uses `scheduler.yield()` when available (modern Chromium) for better priority
+ * handling; falls back to `setTimeout(_, 0)`, which macrotask-defers in every
+ * browser, in Node/SSR, and in fake-timer test environments.
+ */
+export declare function yieldToMain(): Promise<void>;
+/**
+ * Run `task` during the browser's first idle period, falling back to
+ * `setTimeout(task, 0)` where `requestIdleCallback` is unavailable (Safari,
+ * Node/SSR, fake timers). Use this for genuinely deferrable background work
+ * (e.g. stale-while-revalidate refreshes, the `idle` highlight/enhance swap)
+ * that should wait for the main thread to be free.
+ *
+ * @param options.timeout forwarded to `requestIdleCallback` so the task still
+ *   runs even if the browser never goes idle.
+ * @returns a function that cancels the task if it has not run yet.
+ */
+export declare function requestIdle(task: () => void, options?: {
+  timeout?: number;
+}): () => void;