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

package/CodeHighlighter/types.d.mts

@@ -163,6 +163,22 @@ export type VariantCode = CodeMeta & {
    * decompressing `hastCompressed` payloads.
    */
   fallback?: FallbackNode[];
+  /**
+   * Staging-only highlighted-visible fallback, stored **sparsely**: a map from frame
+   * index to the highlighted `FallbackNode` for ONLY the frames visible on the initial
+   * (collapsed, `collapseToEmpty: false`) render. Off-screen frames are omitted — they
+   * are byte-identical to `fallback`'s plain output, so storing them would just
+   * duplicate `fallback` in the precompute. Computed at load time (where the source is
+   * still a live `HastRoot`, so no decompression) and carried in precomputed payloads
+   * alongside `fallback`. Under `highlightAt: 'init'` the server/client boundary
+   * `promoteCriticalFallback`s it over `fallback` so the first paint is highlighted with
+   * no client-side decompression, then deletes it: `fallbackCritical` must NEVER reach
+   * the `Content`/`ContentLoading` components. The promoted `fallback` has byte-identical
+   * text, so it stays a valid DEFLATE dictionary. See `resolveFallbackCritical`.
+   */
+  fallbackCritical?: {
+    [frameIndex: number]: FallbackNode;
+  };
   /**
    * Line counts for this variant's main source — the same for the full (highlighted)
    * source and its `fallback`, since they're the same file. `totalLines` is the whole

package/CoordinatedLazy/useChunk.mjs

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { useChunkContext } from "../ChunkProvider/ChunkContext.mjs";
+import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
 
 /** Result of {@link useChunk}. */
 
@@ -40,11 +41,15 @@ export function useChunk(config, props = {}) {
     return undefined;
   }, [preloaded, config, options]);
   const [data, setData] = React.useState(isLoaded ? preloaded : initialData);
-  const [loading, setLoading] = React.useState(!isLoaded);
+  // `true` once the async `data`-mode load has resolved. Derive `loading` during
+  // render so that when `isLoaded` becomes true after mount (a `preloaded` value
+  // or `controlled` flag arriving later via props) `loading` flips to false on
+  // the next render without an extra effect pass.
+  const [loaded, setLoaded] = React.useState(false);
   const [revalidating, setRevalidating] = React.useState(false);
+  const loading = !isLoaded && !loaded;
   React.useEffect(() => {
     if (isLoaded) {
-      setLoading(false);
       return undefined;
     }
     const controller = new AbortController();
@@ -65,7 +70,7 @@ export function useChunk(config, props = {}) {
         const result = await source.load(options, controller.signal);
         if (!controller.signal.aborted) {
           setData(result);
-          setLoading(false);
+          setLoaded(true);
         }
       } catch {
         // Aborted by a newer load, or the load failed - leave the loading
@@ -95,7 +100,7 @@ export function useChunk(config, props = {}) {
       const result = await source.load(options, controller.signal);
       if (!controller.signal.aborted) {
         setData(result);
-        setLoading(false);
+        setLoaded(true);
         setRevalidating(false);
       }
     } catch {
@@ -112,12 +117,9 @@ export function useChunk(config, props = {}) {
     if (!config.revalidateOnIdle || loading || typeof window === 'undefined') {
       return undefined;
     }
-    const requestIdle = window.requestIdleCallback ?? (callback => setTimeout(callback, 1));
-    const cancelIdle = window.cancelIdleCallback ?? clearTimeout;
-    const handle = requestIdle(() => {
+    return requestIdle(() => {
       refresh().catch(() => {});
     });
-    return () => cancelIdle(handle);
   }, [config.revalidateOnIdle, loading, refresh]);
 
   // Abort any in-flight refresh on unmount.

package/CoordinatedLazy/useCoordinatedSwap.mjs

@@ -61,6 +61,7 @@ export function useCoordinatedSwap(options) {
   // flip `fallbackMounted` and the swap proceeds.
   React.useEffect(() => {
     if (!fallbackMounted && hasFallback && !skipFallback) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- force-mount-once latch: must flip AFTER the first fallback commit so child hoist effects run first; see comment above
       setFallbackMounted(true);
     }
   }, [fallbackMounted, hasFallback, skipFallback]);

package/abstractCreateTypes/TypeCode.mjs

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { decompressHast, hastToJsx } from "../pipeline/hastUtils/index.mjs";
 import { useCodeComponents } from "../useCode/CodeComponentsContext.mjs";
 import { fallbackToHast, fallbackToText } from "../pipeline/hastUtils/fallbackFormat.mjs";
+import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
 /**
  * Find the children of the first `<code>` element in a parsed HAST tree.
  */
@@ -50,10 +51,15 @@ export function TypeCode({
   const [isVisible, setIsVisible] = React.useState(effectiveMode !== 'visible');
   const [codeElement, setCodeElement] = React.useState(null);
 
-  // Synchronize visibility state when the effective mode changes.
-  React.useEffect(() => {
+  // Re-seed visibility state during render when the effective mode changes
+  // (the 'store previous prop value, set state during render' pattern). The
+  // IntersectionObserver effect still owns runtime true/false toggling because
+  // it runs after this render-time seed.
+  const [prevEffectiveMode, setPrevEffectiveMode] = React.useState(effectiveMode);
+  if (prevEffectiveMode !== effectiveMode) {
+    setPrevEffectiveMode(effectiveMode);
     setIsVisible(effectiveMode !== 'visible');
-  }, [effectiveMode]);
+  }
 
   // Convert compact fallback to HAST for rendering.
   const fallbackHastRoot = React.useMemo(() => fallback ? fallbackToHast(fallback) : undefined, [fallback]);
@@ -143,14 +149,9 @@ export function TypeCode({
     }
 
     // 'idle' and 'visible' both defer to idle time to avoid blocking the main thread.
-    if (typeof requestIdleCallback !== 'undefined') {
-      const id = requestIdleCallback(parse, {
-        timeout: 2000
-      });
-      return () => cancelIdleCallback(id);
-    }
-    const id = setTimeout(parse, 0);
-    return () => clearTimeout(id);
+    return requestIdle(parse, {
+      timeout: 2000
+    });
   }, [isVisible, hastJson, hastCompressed, effectiveMode, textDictionary]);
   const highlighted = React.useMemo(() => hast !== null ? hastToJsx(hast, components) : null, [hast, components]);
   const content = highlighted ?? fallbackJsx;

package/abstractCreateTypes/typesToJsx.mjs

@@ -313,14 +313,19 @@ function hastToJsxDeferred(hastOrJson, components, enhancers, highlightAt) {
   // Derive dictionary text from the fallback, then compress the full
   // highlighted HAST with that dictionary. On the client, TypeCode
   // calls fallbackToText(fallback) to reconstruct the same dictionary.
-  const textContent = fallbackToText(fallback);
-
-  // Serialize the enhanced HAST (post-enhancer) for the client.
-  // Compress using the fallback text as a DEFLATE dictionary.
-  // TypeCode derives the same text from the fallback prop
-  // to decompress on the client.
+  // Serialize the enhanced HAST (post-enhancer) for the client. DEFLATE-compressing it
+  // (with the fallback text as the dictionary) only shrinks the server→client wire, so
+  // do it ONLY on the server. On the client there is no wire — the JSON is consumed
+  // in-process by TypeCode — so skip the synchronous, main-thread compress and hand it
+  // the JSON directly; TypeCode reads `hastJson` without decompressing (it only rebuilds
+  // the DEFLATE dictionary from `fallback` when it actually has a `hastCompressed`
+  // payload). `typeof window` is the isomorphic server check.
   const enhancedJson = JSON.stringify(hast);
-  const hastCompressed = compressHast(enhancedJson, textContent);
+  const hastPayload = typeof window === 'undefined' ? {
+    hastCompressed: compressHast(enhancedJson, fallbackToText(fallback))
+  } : {
+    hastJson: enhancedJson
+  };
 
   // Find the <pre> element for wrapper props
   const preElement = findPreElement(hast);
@@ -330,7 +335,7 @@ function hastToJsxDeferred(hastOrJson, components, enhancers, highlightAt) {
   // fallback crosses the boundary as a serialized prop — no separate
   // text dictionary string is needed.
   return /*#__PURE__*/React.createElement(PreComponent, hastPropsToReactProps(preElement?.properties), /*#__PURE__*/React.createElement(TypeCode, {
-    hastCompressed,
+    ...hastPayload,
     highlightAt,
     fallback,
     codeProps: hastPropsToReactProps(codeElement.properties)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.21",
+  "version": "0.11.1-canary.22",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -768,5 +768,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "335d2d92539a04d65a56580de65b240bf4a2273b"
+  "gitSha": "c0380f22916148bebba5dee261c1a2a3a9211a5e"
 }

package/pipeline/loadIsomorphicCodeVariant/loadIsomorphicCodeVariant.mjs

@@ -1,6 +1,7 @@
 import * as path from 'path-module';
 import { compressHastAsync } from "../hastUtils/index.mjs";
-import { buildRootFallback, fallbackToText } from "../../CodeHighlighter/fallbackFormat.mjs";
+import { buildRootFallback, buildCriticalFallback, fallbackToText } from "../../CodeHighlighter/fallbackFormat.mjs";
+import { getInitialVisibleFrames } from "../parseSource/frameVisibility.mjs";
 import { transformSource } from "./transformSource.mjs";
 import { diffHast } from "./diffHast.mjs";
 import { isFrameSpan } from "../parseSource/isFrameSpan.mjs";
@@ -182,6 +183,7 @@ async function loadSingleFile(variantName, fileName, source, url, loadSource, so
   } = options;
   let finalSource = source;
   let finalFallback;
+  let finalFallbackCritical;
   let finalTotalLines;
   let finalFocusedLines;
   let finalCollapsible;
@@ -373,6 +375,32 @@ async function loadSingleFile(variantName, fileName, source, url, loadSource, so
       // decompressed on the client once the fallback travels over via context.
       if (finalSource && typeof finalSource === 'object' && !('hastJson' in finalSource) && !('hastCompressed' in finalSource)) {
         finalFallback = buildRootFallback(finalSource);
+        // Sparse highlighted-visible companion (see `VariantCode.fallbackCritical`),
+        // computed here while the source is still a live `HastRoot` (no
+        // decompression) and BEFORE `stripFrameFallbacks` removes the per-frame
+        // text it reuses. `false` builds the `collapseToEmpty: false` form (the only
+        // one carrying highlighting); the boundary skips promoting it under
+        // `collapseToEmpty`. Empty (no visible frames) → omit it entirely.
+        const critical = buildCriticalFallback(finalSource, getInitialVisibleFrames(finalSource, false));
+        finalFallbackCritical = Object.keys(critical).length > 0 ? critical : undefined;
+
+        // Hoist the window counts off `root.data` while the source is still a live
+        // `HastRoot`. They then ride on the variant (see the return below) so every
+        // downstream reader (`prepareInitialSource`, `getVariantFileLineCounts`,
+        // layout-shift classification) gets `totalLines`/`focusedLines`/`collapsible`
+        // WITHOUT decompressing the payload — the compact fallback and the compressed
+        // source both drop `root.data`, so without this the only way to recover the
+        // counts is to decode the hast (the first-render decompression we want to avoid).
+        const rootData = finalSource.data;
+        if (rootData?.totalLines !== undefined) {
+          const total = Number(rootData.totalLines);
+          if (Number.isFinite(total) && total >= 0) {
+            finalTotalLines = total;
+            const focused = Number(rootData.focusedLines);
+            finalFocusedLines = Number.isFinite(focused) && focused >= 0 ? focused : total;
+            finalCollapsible = rootData.collapsible === true;
+          }
+        }
       }
       if (options.output === 'hastCompressed' && process.env.NODE_ENV === 'production') {
         if (finalFallback) {
@@ -439,6 +467,7 @@ async function loadSingleFile(variantName, fileName, source, url, loadSource, so
   return {
     source: finalSource,
     fallback: finalFallback,
+    fallbackCritical: finalFallbackCritical,
     totalLines: finalTotalLines,
     focusedLines: finalFocusedLines,
     collapsible: finalCollapsible,
@@ -782,6 +811,7 @@ export async function loadIsomorphicCodeVariant(url, variantName, variant, optio
   if (!fileName && !url) {
     let finalSource = variant.source;
     let finalFallback;
+    let finalFallbackCritical;
 
     // Parse the source if we have language and sourceParser
     if (typeof finalSource === 'string' && language && sourceParser && !disableParsing) {
@@ -814,6 +844,10 @@ export async function loadIsomorphicCodeVariant(url, variantName, variant, optio
       // Always derive a variant-level root fallback from the per-frame text so a
       // `ContentLoading` component can render before the hast is decoded.
       finalFallback = buildRootFallback(finalSource);
+      // Sparse highlighted-visible companion (see `VariantCode.fallbackCritical`),
+      // built from the live `HastRoot` before `stripFrameFallbacks` runs.
+      const critical = buildCriticalFallback(finalSource, getInitialVisibleFrames(finalSource, false));
+      finalFallbackCritical = Object.keys(critical).length > 0 ? critical : undefined;
       if (options.output === 'hastCompressed' && process.env.NODE_ENV === 'production') {
         if (finalFallback) {
           stripFrameFallbacks(finalSource);
@@ -832,6 +866,9 @@ export async function loadIsomorphicCodeVariant(url, variantName, variant, optio
       source: finalSource,
       ...(finalFallback ? {
         fallback: finalFallback
+      } : {}),
+      ...(finalFallbackCritical ? {
+        fallbackCritical: finalFallbackCritical
       } : {})
     };
     return {
@@ -1084,6 +1121,9 @@ export async function loadIsomorphicCodeVariant(url, variantName, variant, optio
     ...(mainFileResult.fallback && {
       fallback: mainFileResult.fallback
     }),
+    ...(mainFileResult.fallbackCritical && {
+      fallbackCritical: mainFileResult.fallbackCritical
+    }),
     ...(mainFileResult.totalLines !== undefined && {
       totalLines: mainFileResult.totalLines
     }),

package/pipeline/parseSource/frameVisibility.d.mts

@@ -1,3 +1,4 @@
+import type { HastRoot } from "../../CodeHighlighter/types.mjs";
 /**
  * Set form of {@link COLLAPSED_VISIBLE_FRAME_TYPE_LIST} for fast membership
  * checks. Typed as `ReadonlySet<string>` so callers can pass a raw
@@ -28,4 +29,19 @@ export declare const COLLAPSED_VISIBLE_FRAME_TYPES: ReadonlySet<string>;
  * @param frameType - The frame's `data-frame-type` (may be `undefined` for `normal`)
  * @param collapseToEmpty - Whether the block is rendered collapse-to-empty
  */
-export declare function resolveCollapsedFrameType(frameType: string | undefined, collapseToEmpty: boolean): string | undefined;
+export declare function resolveCollapsedFrameType(frameType: string | undefined, collapseToEmpty: boolean): string | undefined;
+/**
+ * The set of frame indices that are visible on the initial (collapsed) render of
+ * a code block: the contiguous focused window
+ * ({@link COLLAPSED_VISIBLE_FRAME_TYPES}), falling back to the first frame when no
+ * frame carries an emphasis type. Returns an empty set for `collapseToEmpty` (an
+ * empty collapsed window) and for a `focusedLines === 0` carve-out
+ * (`oversizedFocus: 'hide'`).
+ *
+ * Shared by the runtime rule in `useCode/Pre.tsx` and the server-side
+ * highlighted-visible fallback builder, so the frames highlighted on the first
+ * paint match exactly. Isomorphic — reads only precomputed HAST attributes.
+ */
+export declare function getInitialVisibleFrames(hast: HastRoot | null, collapseToEmpty?: boolean): {
+  [key: number]: boolean;
+};

package/pipeline/parseSource/frameVisibility.mjs

@@ -1,3 +1,5 @@
+import { isFrameSpan } from "./isFrameSpan.mjs";
+
 /**
  * The `data-frame-type` values whose frames make up the window a collapsible
  * code block shows while collapsed (the contiguous focused window:
@@ -58,4 +60,55 @@ export function resolveCollapsedFrameType(frameType, collapseToEmpty) {
     default:
       return frameType;
   }
+}
+
+/**
+ * The set of frame indices that are visible on the initial (collapsed) render of
+ * a code block: the contiguous focused window
+ * ({@link COLLAPSED_VISIBLE_FRAME_TYPES}), falling back to the first frame when no
+ * frame carries an emphasis type. Returns an empty set for `collapseToEmpty` (an
+ * empty collapsed window) and for a `focusedLines === 0` carve-out
+ * (`oversizedFocus: 'hide'`).
+ *
+ * Shared by the runtime rule in `useCode/Pre.tsx` and the server-side
+ * highlighted-visible fallback builder, so the frames highlighted on the first
+ * paint match exactly. Isomorphic — reads only precomputed HAST attributes.
+ */
+export function getInitialVisibleFrames(hast, collapseToEmpty = false) {
+  if (!hast) {
+    return collapseToEmpty ? {} : {
+      0: true
+    };
+  }
+
+  // Collapse-to-empty renders an empty collapsed window — no frame is visible while
+  // collapsed, regardless of the precomputed frame types.
+  if (collapseToEmpty) {
+    return {};
+  }
+  const visibleFrames = {};
+  let frameIndex = 0;
+  let hasVisibleEmphasisFrame = false;
+  hast.children.forEach(child => {
+    if (child.type !== 'element' || !isFrameSpan(child)) {
+      return;
+    }
+    const frameType = child.properties.dataFrameType;
+    if (typeof frameType === 'string' && COLLAPSED_VISIBLE_FRAME_TYPES.has(frameType)) {
+      visibleFrames[frameIndex] = true;
+      hasVisibleEmphasisFrame = true;
+    }
+    frameIndex += 1;
+  });
+
+  // Collapse-to-nothing (oversizedFocus: 'hide'): `focusedLines === 0` means
+  // the collapsed window is intentionally empty, so skip the first-frame
+  // fallback and keep every frame hidden when collapsed.
+  if (hast.data?.focusedLines === 0) {
+    return visibleFrames;
+  }
+  if (!hasVisibleEmphasisFrame && frameIndex > 0) {
+    visibleFrames[0] = true;
+  }
+  return visibleFrames;
 }

package/useCode/EditableEngine.mjs

@@ -939,10 +939,16 @@ export const createEditableEngine = ctx => {
         const beforePosition = getPosition(element);
         const range = getCurrentRange();
         if (!range.collapsed) {
-          // Whether the selection started at column 0 — i.e. the deletion removes
-          // whole lines from the first line down, so its comment-map anchor sits
-          // one line higher than the post-delete caret (see `deletedFromLineStart`).
-          const deletedFromLineStart = beforePosition.content.length === 0;
+          // Whether the deletion removed WHOLE lines from the first line down. True
+          // only when the selection BOTH started at column 0 (no content before it)
+          // AND ended at a line boundary (its text ends with a newline) — then the
+          // first line is gone and the post-delete caret lands on the line that
+          // shifted up from below, so the comment-map anchor sits one line higher
+          // (see `deletedFromLineStart`). A selection that ends MID-line instead
+          // collapses the spanned lines INTO the first line, which survives (emptied)
+          // under the caret — no shift-up — so the flag must stay false, or a marker
+          // on that surviving line is dragged one line too high.
+          const deletedFromLineStart = beforePosition.content.length === 0 && range.toString().endsWith('\n');
           edit.insert('', 0);
           // A multi-line selection delete can natively remove whole `.frame`
           // wrapper elements (e.g. selecting exactly one emphasis frame). That
@@ -1014,7 +1020,11 @@ export const createEditableEngine = ctx => {
         event.preventDefault();
         const range = getCurrentRange();
         if (!range.collapsed) {
-          const deletedFromLineStart = getPosition(element).content.length === 0;
+          // See the Backspace branch above: deletedFromLineStart holds only when the
+          // selection removed whole lines (started at column 0 AND ended at a line
+          // boundary). A mid-line end collapses the lines in place, leaving the first
+          // line emptied under the caret — no shift-up — so the flag must stay false.
+          const deletedFromLineStart = getPosition(element).content.length === 0 && range.toString().endsWith('\n');
           edit.insert('', 0);
           // Same frame-wrapper detach crash as the Backspace branch above: a
           // multi-line selection delete must reconcile synchronously so React

package/useCode/Pre.mjs

@@ -3,12 +3,12 @@
 var _kbd;
 import * as React from 'react';
 import { useEditable } from "./useEditable.mjs";
-import { fallbackToHast } from "../CodeHighlighter/fallbackFormat.mjs";
+import { fallbackToHast, fallbackIsHighlighted } from "../CodeHighlighter/fallbackFormat.mjs";
 import { useCodeContext } from "../CodeProvider/CodeContext.mjs";
 import { hastToJsx, frameFallbackFromSpans } from "../pipeline/hastUtils/index.mjs";
 import { stripHighlightingSpans } from "../pipeline/hastUtils/stripHighlightingSpans.mjs";
 import { decodeHastSource } from "../pipeline/loadIsomorphicCodeVariant/decodeHastSource.mjs";
-import { COLLAPSED_VISIBLE_FRAME_TYPES, resolveCollapsedFrameType } from "../pipeline/parseSource/frameVisibility.mjs";
+import { COLLAPSED_VISIBLE_FRAME_TYPES, resolveCollapsedFrameType, getInitialVisibleFrames } from "../pipeline/parseSource/frameVisibility.mjs";
 import { isFrameSpan } from "../pipeline/parseSource/isFrameSpan.mjs";
 import { getSourceLineCounts } from "./sourceLineCounts.mjs";
 import { subscribeToggleNudge } from "./subscribeToggleNudge.mjs";
@@ -25,44 +25,6 @@ function resolveFrameTypeAttribute(frameType, collapseToEmpty) {
   const resolved = resolveCollapsedFrameType(frameType, collapseToEmpty);
   return resolved && resolved !== 'normal' ? resolved : undefined;
 }
-function getInitialVisibleFrames(hast, collapseToEmpty = false) {
-  if (!hast) {
-    return collapseToEmpty ? {} : {
-      0: true
-    };
-  }
-
-  // Collapse-to-empty renders an empty collapsed window — no frame is visible while
-  // collapsed, regardless of the precomputed frame types.
-  if (collapseToEmpty) {
-    return {};
-  }
-  const visibleFrames = {};
-  let frameIndex = 0;
-  let hasVisibleEmphasisFrame = false;
-  hast.children.forEach(child => {
-    if (child.type !== 'element' || !isFrameSpan(child)) {
-      return;
-    }
-    const frameType = child.properties.dataFrameType;
-    if (typeof frameType === 'string' && COLLAPSED_VISIBLE_FRAME_TYPES.has(frameType)) {
-      visibleFrames[frameIndex] = true;
-      hasVisibleEmphasisFrame = true;
-    }
-    frameIndex += 1;
-  });
-
-  // Collapse-to-nothing (oversizedFocus: 'hide'): `focusedLines === 0` means
-  // the collapsed window is intentionally empty, so skip the first-frame
-  // fallback and keep every frame hidden when collapsed.
-  if (hast.data?.focusedLines === 0) {
-    return visibleFrames;
-  }
-  if (!hasVisibleEmphasisFrame && frameIndex > 0) {
-    visibleFrames[0] = true;
-  }
-  return visibleFrames;
-}
 
 /**
  * Bounds describing the visible region of a collapsible code block in its
@@ -280,16 +242,32 @@ export function Pre({
   editActivation,
   onActivate
 }) {
+  // Defer the decompressing `decodeHastSource` to a post-paint render ONLY when the
+  // first-paint `.fallback` is ALREADY highlighted — i.e. the promoted highlighted-visible
+  // fallback the server ships for `highlightAt: 'init'`. Then paint that highlighted
+  // fallback first (no decompression on the critical path) and swap in the full decoded
+  // tree after. When the fallback is plain — every other mode, including a late-mounted
+  // `'hydration'` block where `shouldHighlight` is also true on the first render — decode
+  // on mount instead, so we never flash plain → highlighted.
+  const [deferInitialDecode] = React.useState(() => shouldHighlight === true && !!fallback && fallbackIsHighlighted(fallback) && typeof children !== 'string');
+  const [decodeAllowed, setDecodeAllowed] = React.useState(!deferInitialDecode);
+  React.useEffect(() => {
+    if (deferInitialDecode) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- intentional post-paint latch: flip after the first paint so the highlighted fallback shows before the decompressing decode runs
+      setDecodeAllowed(true);
+    }
+  }, [deferInitialDecode]);
+
   // The variant `fallback` is forwarded to `decodeHastSource` so the
   // `hastCompressed` payload is decompressed with the matching DEFLATE
   // dictionary and each frame's `data.fallback` is restored. The decoded
   // tree stays shared (read-only), since `Pre` only reads it.
   const hast = React.useMemo(() => {
-    if (!children || typeof children === 'string') {
+    if (!children || typeof children === 'string' || !decodeAllowed) {
       return null;
     }
     return decodeHastSource(children, fallback);
-  }, [children, fallback]);
+  }, [children, fallback, decodeAllowed]);
 
   // Variant-swap bridge descriptor. While a variant swap is in flight
   // and the partner variant is taller than this one, we render an
@@ -356,6 +334,12 @@ export function Pre({
   // cursor on first paint.
   const [editableReady, setEditableReady] = React.useState(false);
   React.useLayoutEffect(() => {
+    // Deliberate two-pass mount gate: defer engine activation until the
+    // `bindPre` callback ref has committed (see 527-533). Flipping this true
+    // in a layout effect is the documented trigger for the no-flash /
+    // cursor-retention behavior and isn't derivable during render (the ref is
+    // intentionally null in render 1).
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setEditableReady(true);
   }, []);
   const onEditableChange = React.useCallback((text, position, preParsed) => {
@@ -398,6 +382,12 @@ export function Pre({
   // keeping the update outside the render phase while still avoiding a
   // visible flash of un-hydrated emphasis frames.
   React.useLayoutEffect(() => {
+    // Next state unions the new initial-visible set onto `prev` rather than
+    // replacing it (see 564-597): replacing would drop frames already
+    // hydrated by IO/editing on the prior tree, causing the visible flash this
+    // guards against. Depends on both a prop (`hast`) and prior state, so it
+    // can't be derived during render.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setVisibleFrames(prev => {
       const initial = getInitialVisibleFrames(hast, collapseToEmpty);
       let merged;
@@ -976,13 +966,18 @@ export function Pre({
   // FRAMED — the compact `fallback` (the loader's windowed plain-text frames) when one
   // travelled with it, otherwise a single-frame wrap — so the `<code>` is never bare
   // text. The highlighted tree swaps in via `frames` once parsing completes.
-  const stringFramed = React.useMemo(() => {
-    if (typeof children !== 'string') {
+  // The fallback render, used whenever the decoded `hast` isn't in hand: a string
+  // source (highlighted on the client after hydration) or an object source whose
+  // decode is deferred off the first paint (`deferInitialDecode`). For `init` the
+  // server-built `fallback` already carries the initially-visible frames
+  // highlighted, so this first paint is highlighted with no decompression.
+  const framedFallback = React.useMemo(() => {
+    const frameNodes = fallback ?? (typeof children === 'string' ? [['span', 'frame', {
+      dataFrameType: 'focus'
+    }, children]] : null);
+    if (!frameNodes) {
       return null;
     }
-    const frameNodes = fallback ?? [['span', 'frame', {
-      dataFrameType: 'focus'
-    }, children]];
     const root = fallbackToHast(frameNodes);
     if (collapseToEmpty) {
       for (const child of root.children) {
@@ -1020,7 +1015,7 @@ export function Pre({
       "data-collapsible": hasCollapsibleFrames ? '' : undefined,
       "data-total-lines": sourceTotalLines,
       "data-focused-lines": sourceFocusedLines,
-      children: typeof children === 'string' ? stringFramed : frames
+      children: hast ? frames : framedFallback
     })
   });
   if (!isEditable) {

package/useCode/SourceEditingEngine.mjs

@@ -207,20 +207,33 @@ export function shiftComments(comments, lineDelta, position, existingCollapseMap
   // O(1) lookup against the precomputed empty-line set from the old source.
   const oldEmptyLineSet = oldEmptyLines && oldEmptyLines.length > 0 ? new Set(oldEmptyLines) : undefined;
 
-  // For a deletion, find range bases whose BOTH `-start` and `-end` markers fall
-  // inside the deleted block. Such a range is removed entirely — there is nowhere
-  // to shift its markers to — so we stash BOTH ends in the collapseMap and leave
-  // neither visible: the frame disappears now and an undo rebuilds it intact at
-  // its original offsets. (A range whose start survives OUTSIDE the block only
-  // shrinks, so its `-end` keeps the editLine+1 placement below and stays
-  // untracked, matching the expand/contract behavior.)
+  // For a deletion, find range bases that are removed entirely — every line they
+  // highlighted is gone — so the frame must disappear (its `-start`, which is in
+  // the deleted block, is stashed rather than collapsed onto a surviving line
+  // above as a phantom highlight) and an undo can rebuild it.
+  //
+  // Two shapes qualify. Both require the `-start` to fall inside the deleted block
+  // `(editLine, editLine - lineDelta]`:
+  //   1. The `-end` is also inside the block (the selection deleted right through
+  //      it). Both markers are stashed and an undo restores them at their offsets.
+  //   2. The `-end` is on `boundaryLine` — the first SURVIVING line just past the
+  //      block. A range's `-end` is EXCLUSIVE, sitting one line below its last
+  //      highlighted line, so a selection that removes every highlighted line stops
+  //      with the caret on that `-end` line, leaving it intact. The range is still
+  //      empty, so it is fully deleted; the surviving `-end` then shifts up as a
+  //      lone marker (rendering nothing) and is the undo memory that re-pairs with
+  //      the restored `-start`.
+  // (A range whose `-start` survives OUTSIDE the block only shrinks, so its `-end`
+  // keeps the editLine+1 placement below and stays untracked.)
   let fullyDeletedRanges;
   if (lineDelta < 0) {
     const startBases = new Set();
     const endBases = new Set();
+    const boundaryLine = editLine - lineDelta + 1;
     for (const [lineStr, commentArr] of Object.entries(comments ?? {})) {
       const line = Number(lineStr);
-      if (line > editLine && line <= editLine - lineDelta) {
+      const inBlock = line > editLine && line <= editLine - lineDelta;
+      if (inBlock) {
         for (const comment of commentArr) {
           if (comment.endsWith('-end')) {
             endBases.add(comment.slice(0, -'-end'.length));
@@ -228,6 +241,14 @@ export function shiftComments(comments, lineDelta, position, existingCollapseMap
             startBases.add(comment.slice(0, -'-start'.length));
           }
         }
+      } else if (line === boundaryLine) {
+        // Only an exclusive `-end` on the boundary closes a fully-deleted range; a
+        // `-start` here belongs to a surviving line below and must not be paired.
+        for (const comment of commentArr) {
+          if (comment.endsWith('-end')) {
+            endBases.add(comment.slice(0, -'-end'.length));
+          }
+        }
       }
     }
     for (const base of startBases) {