@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/useCode/useCode.mjs

@@ -9,17 +9,25 @@ import { useFileNavigation } from "./useFileNavigation.mjs";
 import { useUIState } from "./useUIState.mjs";
 import { useCopyFunctionality } from "./useCopyFunctionality.mjs";
 import { useSourceEditing } from "./useSourceEditing.mjs";
+import { findCollapseInFocusTransforms, shouldHighlightForRender } from "./useCodeUtils.mjs";
+import { findVariantFocusedLinesMismatches } from "./sourceLineCounts.mjs";
 export function useCode(contentProps, opts) {
   const {
     copy: copyOpts,
-    defaultOpen = false,
     initialVariant,
     initialTransform,
     preClassName,
     fileHashMode = 'remove-hash',
     saveHashVariantToLocalStorage = 'on-interaction',
     sourceEnhancers,
-    disabled
+    disabled,
+    onExpand,
+    transformDelay,
+    transformLayoutShift = 'selected',
+    strictCollapseInFocus = false,
+    variantLayoutShift = 'selected',
+    variantSwapDelay,
+    strictMatchingVariantFocusedLines = false
   } = opts || {};
 
   // Safely try to get context values - will be undefined if not in context
@@ -34,25 +42,68 @@ 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(() => {
     return context?.code || contentProps.code || {};
   }, [context?.code, contentProps.code]);
-  const shouldHighlight = !context?.deferHighlight;
+
+  // Opt-in development-time assertion: throw if any transform's
+  // `.collapse` placeholder would land inside the focus region. The
+  // check is purely a lookup against precomputed manifest flags (no
+  // tree walking) so it is cheap to run on every render; the memo
+  // ensures the actual scan only re-runs when `effectiveCode` changes.
+  // Fail-fast in render so demo authors notice the problem the first
+  // time they load the page instead of debugging a missing animation.
+  const collapseInFocusOffenders = React.useMemo(() => strictCollapseInFocus ? findCollapseInFocusTransforms(effectiveCode) : null, [strictCollapseInFocus, effectiveCode]);
+  if (collapseInFocusOffenders && collapseInFocusOffenders.length > 0) {
+    const first = collapseInFocusOffenders[0];
+    const extraCount = collapseInFocusOffenders.length - 1;
+    const suffix = extraCount > 0 ? ` (${extraCount} more offender(s) suppressed).` : `.`;
+    throw new Error(`[useCode] strictCollapseInFocus is enabled and transform "${first.transformKey}" on variant "${first.variantName}" file "${first.fileName}" introduces a .collapse placeholder inside the visible focus region. Narrow the focused area (e.g. tighten @focus/@padding markers or shrink the transform's edit range) so the placeholder lands outside the initially-visible window${suffix}`);
+  }
+
+  // Opt-in development-time assertion: throw if any two variants
+  // declare a file with the same name but disagree on
+  // `focusedLines`. Cheap precomputed-metadata lookup — the memo
+  // ensures the actual scan only re-runs when `effectiveCode`
+  // changes. Fail-fast in render so demo authors notice the problem
+  // the first time they load the page.
+  const variantFocusedLinesMismatches = React.useMemo(() => strictMatchingVariantFocusedLines ? findVariantFocusedLinesMismatches(effectiveCode) : null, [strictMatchingVariantFocusedLines, effectiveCode]);
+  if (variantFocusedLinesMismatches && variantFocusedLinesMismatches.length > 0) {
+    const first = variantFocusedLinesMismatches[0];
+    const extraCount = variantFocusedLinesMismatches.length - 1;
+    const suffix = extraCount > 0 ? ` (${extraCount} more mismatch(es) suppressed).` : `.`;
+    throw new Error(`[useCode] strictMatchingVariantFocusedLines is enabled and file "${first.fileName}" has ${first.focusedLinesA} focused line(s) in variant "${first.variantA}" but ${first.focusedLinesB} focused line(s) in variant "${first.variantB}". Align the @focus/@padding markers across variants so the collapsed window matches${suffix}`);
+  }
+
+  // Dev-only sanity check: `strictMatchingVariantFocusedLines` only
+  // protects against coordinated-barrier risk while the block is
+  // collapsed under `variantLayoutShift: 'focus'`. Enabling it in
+  // any other mode produces throws that don't correspond to a real
+  // layout-shift hazard, so warn the author once per render.
+  if (process.env.NODE_ENV !== 'production' && strictMatchingVariantFocusedLines && variantLayoutShift !== 'focus') {
+    console.warn(`[useCode] strictMatchingVariantFocusedLines is enabled but variantLayoutShift is "${variantLayoutShift}". The strict check only guards coordinated-barrier swaps under 'focus' mode; consider setting variantLayoutShift: 'focus' or disabling strictMatchingVariantFocusedLines.`);
+  }
 
   // Memoize userProps with auto-generated name and slug if missing
   const userProps = React.useMemo(() => {
@@ -63,6 +114,11 @@ export function useCode(contentProps, opts) {
       code,
       components,
       url: contentUrl,
+      // `collapseToEmpty` / `initialExpanded` are render-time display flags, not
+      // user-facing props — strip them (rest siblings) so they don't leak into
+      // the demo's props.
+      collapseToEmpty: collapseToEmptyContentProp,
+      initialExpanded: initialExpandedContentProp,
       ...userDefinedProps
     } = contentProps;
     // Get URL from context first, then fall back to contentProps
@@ -86,66 +142,238 @@ export function useCode(contentProps, opts) {
     };
   }, [contentProps, context?.url]);
 
+  // Resolve the render-time display flags. They must come from `contentProps`
+  // (threaded by the demo factory / `CodeHighlighter` / code transforms) rather
+  // than `useCode` opts: the loading fallback derives its own copy from the same
+  // `contentProps`, so a per-call opt would let the live render and the fallback
+  // disagree.
+  const collapseToEmpty = contentProps.collapseToEmpty === true;
+  const initialExpanded = contentProps.initialExpanded === true;
+
   // Sub-hook: UI State Management (needs slug to check for relevant hash)
   const uiState = useUIState({
-    defaultOpen,
+    initialExpanded,
     mainSlug: userProps.slug
   });
 
+  // Lift `selectedFileName` state out of `useFileNavigation` so
+  // `useTransformManagement` *and* `useVariantSelection` can read it
+  // (selected-file-scoped `transformLayoutShift` /
+  // `variantLayoutShift` modes). `useFileNavigation` consumes the
+  // value + setter as controlled props. Initial value is resolved
+  // below once `useVariantSelection` has reported the initial
+  // variant.
+  const [selectedFileNameState, setSelectedFileNameState] = React.useState(undefined);
+
   // Sub-hook: Variant Selection
   const variantSelection = useVariantSelection({
     effectiveCode,
     initialVariant,
     variantType: contentProps.variantType,
     mainSlug: userProps.slug,
-    saveHashVariantToLocalStorage
+    saveHashVariantToLocalStorage,
+    variantLayoutShift,
+    selectedFileName: selectedFileNameState,
+    expanded: uiState.expanded,
+    variantSwapDelay,
+    deferHighlight: context?.deferHighlight
+  });
+
+  // Seed the selected file name from the variant's main file the
+  // first time the variant resolves. Subsequent file selections come
+  // through `useFileNavigation`'s controlled setter. Set-state during
+  // render triggers one extra render on first mount; we accept that
+  // cost because the alternative (lazy `useState` initializer)
+  // requires resolving the variant key here, which depends on
+  // `useUrlHashState` / `usePreference` hooks that already live
+  // inside `useVariantSelection`. Duplicating them at this level
+  // would be worse than the extra render.
+  if (selectedFileNameState === undefined && variantSelection.selectedVariant?.fileName) {
+    setSelectedFileNameState(variantSelection.selectedVariant.fileName);
+  }
+
+  // Defer the outgoing `<Pre>` from rendering highlighted spans while
+  // a stored-preference bootstrap swap is known to be coming. See
+  // `shouldHighlightForRender` for the full rationale, including the
+  // `highlightAfter === 'init'` bypass that prevents a visible flash
+  // of unhighlighted code on first-paint variant swaps.
+  const shouldHighlight = shouldHighlightForRender({
+    deferHighlight: context?.deferHighlight,
+    highlightReady: context?.highlightReady,
+    pendingBootstrap: variantSelection.pendingBootstrap,
+    highlightAfter: context?.highlightAfter
   });
 
+  // The rendered tree should reflect the *committed* variant so the
+  // outgoing `<Pre>` stays put during `variantSwapDelay`. When no
+  // delay is configured these are always equal to `selectedVariant` /
+  // `selectedVariantKey`. Falling back to the pending value (rather
+  // than `null`) keeps the boot path — before the coordinator has
+  // committed for the first time — rendering the freshly-resolved
+  // variant instead of nothing.
+  const renderedVariant = variantSelection.committedVariant ?? variantSelection.selectedVariant;
+  const renderedVariantKey = variantSelection.committedVariantKey || variantSelection.selectedVariantKey;
+
   // Sub-hook: Transform Management
   const transformManagement = useTransformManagement({
     context,
     effectiveCode,
-    selectedVariantKey: variantSelection.selectedVariantKey,
-    selectedVariant: variantSelection.selectedVariant,
-    initialTransform
+    selectedVariantKey: renderedVariantKey,
+    selectedVariant: renderedVariant,
+    initialTransform,
+    transformDelay,
+    transformLayoutShift,
+    selectedFileName: selectedFileNameState,
+    expanded: uiState.expanded
   });
 
   // Sub-hook: Source Editing
   const sourceEditing = useSourceEditing({
     context,
-    selectedVariantKey: variantSelection.selectedVariantKey,
+    selectedVariantKey: renderedVariantKey,
     effectiveCode,
-    selectedVariant: variantSelection.selectedVariant,
+    selectedVariant: renderedVariant,
     disabled
   });
 
+  // Combine the two animation phases into a single `transforming`
+  // attribute for `<Pre>`. Both phases share the `data-transforming`
+  // attribute and the `.collapse` placeholder bridge — the only
+  // difference is which delta drives the bridge. When both are
+  // simultaneously eligible (rare — a transform swap mid-variant-swap
+  // window) the variant phase takes precedence because the rendered
+  // tree just swapped variants and that's the larger visual change.
+  const transforming = variantSelection.variantSwappingPhase ?? transformManagement.transformingPhase;
+
+  // Route `<Pre>`'s readiness callback to whichever phase source owns
+  // the current animation window. Each source flips its own paused →
+  // active transition independently; we just forward the signal.
+  const variantPhaseActive = variantSelection.variantSwappingPhase !== null;
+  const notifyVariantTransitionReady = variantSelection.notifyVariantTransitionReady;
+  const notifyTransformTransitionReady = transformManagement.notifyTransformTransitionReady;
+  const onPreTransitionReady = React.useCallback(() => {
+    if (variantPhaseActive) {
+      notifyVariantTransitionReady();
+    } else {
+      notifyTransformTransitionReady();
+    }
+  }, [variantPhaseActive, notifyVariantTransitionReady, notifyTransformTransitionReady]);
+
+  // Defer `expand()` while a variant or transform swap is in flight,
+  // or while the currently-displayed variant's source is still being
+  // highlighted. Callers that pair `selectVariant(...)` /
+  // `selectTransform(...)` with `expand()` in the same tick (e.g.
+  // "show source of variant X" or "switch to JS then expand"
+  // affordances) would otherwise flip `expanded` mid-animation: the
+  // bridge `.collapse` placeholder switches metric (`focus` →
+  // `total`) and the previously-hidden rows pop in before the swap
+  // commits, producing a visible jump. When no `variantSwapDelay`
+  // is configured the swap commits synchronously, but the new
+  // variant's `parsedCode` is still computed asynchronously — the
+  // `deferHighlight` flag published by `CodeHighlighterClient`
+  // (true while `waitingForParsedCode`) keeps the gate engaged
+  // through that window too.
+  //
+  // `expand()` always queues through a `pendingExpand` state flag;
+  // a passive effect resolves it on every render where the composed
+  // `transforming` phase is `null` and `deferHighlight` is falsy
+  // (i.e. neither a variant/transform swap nor an async re-highlight
+  // is in flight). Using state (not a ref) keeps the drain reactive:
+  // a synchronous `expand()` triggers a render, the effect runs, and
+  // `setExpanded(true)` flushes in the same React batch — preserving
+  // the "expand is synchronous" semantics for the common case while
+  // naturally waiting on in-flight swaps. `setExpanded` stays direct
+  // so explicit controlled-state writes remain synchronous regardless
+  // of swap phase.
+  const setExpanded = uiState.setExpanded;
+  const swapInFlight = transforming !== null || !!context?.deferHighlight;
+  const [pendingExpand, setPendingExpand] = React.useState(false);
+  // Keep the latest `onExpand` in a ref so the stable `expand` callback below
+  // can call it without changing identity (it is forwarded down to `<Pre>`).
+  const onExpandRef = React.useRef(onExpand);
+  React.useLayoutEffect(() => {
+    onExpandRef.current = onExpand;
+  });
+  const expand = React.useCallback(() => {
+    // Notify the host synchronously, while the block is still collapsed, so it
+    // can capture the pre-expansion layout and engage a scroll anchor (the
+    // expansion itself is deferred below via `pendingExpand`). This mirrors the
+    // timing of clicking the expand toggle, where the host anchors the scroll
+    // before the layout changes.
+    onExpandRef.current?.();
+    setPendingExpand(true);
+  }, []);
+  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]);
+
+  // Partner variant whose per-file line counts feed `<Pre>`'s bridge
+  // computation. `null` when no variant swap is in flight (the bridge
+  // collapses to a no-op inside `<Pre>` either way; this lookup is a
+  // performance shortcut so we don't read the entire variant on every
+  // render).
+  const swapPartnerVariant = React.useMemo(() => {
+    if (!variantSelection.swapPartnerVariantKey) {
+      return null;
+    }
+    const variant = effectiveCode[variantSelection.swapPartnerVariantKey];
+    if (variant && typeof variant === 'object' && 'source' in variant) {
+      return variant;
+    }
+    return null;
+  }, [effectiveCode, variantSelection.swapPartnerVariantKey]);
+
+  // Bridge line-count metric should mirror variant layout-shift mode:
+  // only `'focus'` compares focused lines while collapsed; every other
+  // mode always compares total lines.
+  const variantBridgeLineMode = variantLayoutShift === 'focus' ? 'focus' : 'total';
+
   // Sub-hook: File Navigation
   const fileNavigation = useFileNavigation({
-    selectedVariant: variantSelection.selectedVariant,
+    selectedVariant: renderedVariant,
     transformedFiles: transformManagement.transformedFiles,
     selectedTransform: transformManagement.selectedTransform,
     mainSlug: userProps.slug,
-    selectedVariantKey: variantSelection.selectedVariantKey,
+    selectedVariantKey: renderedVariantKey,
     selectVariant: variantSelection.selectVariantProgrammatic,
     variantKeys: variantSelection.variantKeys,
     shouldHighlight,
     preClassName,
     setSource: sourceEditing.setSource,
+    editActivation: context?.editActivation,
+    onActivate: context?.onEditingActivated,
     effectiveCode,
     fileHashMode,
     saveHashVariantToLocalStorage,
     saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
     hashVariant: variantSelection.hashVariant,
     sourceEnhancers: mergedEnhancers,
+    fallbacks: context?.fallbacks,
     expanded: uiState.expanded,
-    expand: uiState.expand
+    collapseToEmpty,
+    expand,
+    transforming,
+    onPreTransitionReady,
+    variantBridgeLineMode,
+    swapPartnerVariant,
+    selectedFileName: selectedFileNameState,
+    setSelectedFileName: setSelectedFileNameState
   });
 
   // Sub-hook: Copy Functionality
   const copyFunctionality = useCopyFunctionality({
     selectedFile: fileNavigation.selectedFile,
-    selectedVariant: variantSelection.selectedVariant,
+    selectedVariant: renderedVariant,
     transformedFiles: transformManagement.transformedFiles,
+    // Per-file dictionaries for the active variant (decodes `hastCompressed`
+    // sources back to text); `selectedFileFallback` covers the single-file copy.
+    fallbacks: context?.fallbacks,
+    selectedFileFallback: fileNavigation.selectedFileFallback,
     title: userProps.name,
     copyOpts
   });
@@ -158,18 +386,21 @@ export function useCode(contentProps, opts) {
     selectedFileLines: fileNavigation.selectedFileLines,
     selectedFileName: fileNavigation.selectedFileName,
     selectedFileUrl: fileNavigation.selectedFileUrl,
+    selectedFileSlug: fileNavigation.selectedFileSlug,
     selectFileName: fileNavigation.selectFileName,
     allFilesSlugs: fileNavigation.allFilesSlugs,
     expanded: uiState.expanded,
-    expand: uiState.expand,
-    setExpanded: uiState.setExpanded,
+    expand,
+    setExpanded,
     copy: copyFunctionality.copy,
     copyMarkdown: copyFunctionality.copyMarkdown,
     availableTransforms: transformManagement.availableTransforms,
     selectedTransform: transformManagement.selectedTransform,
     selectTransform: transformManagement.selectTransform,
+    pendingTransform: transformManagement.pendingTransform,
     setSource: sourceEditing.setSource,
     reset: sourceEditing.reset,
+    refresh: context?.refresh,
     userProps
   };
 }

package/useCode/useCodeUtils.d.mts

@@ -1,8 +1,14 @@
-import type { VariantSource, VariantCode, Code, Transforms } from "../CodeHighlighter/types.mjs";
-interface TransformedFile {
+import type { VariantSource, VariantCode, Code, SourceComments } from "../CodeHighlighter/types.mjs";
+export interface TransformedFile {
   name: string;
   originalName: string;
   source: VariantSource;
+  /**
+   * Comments map shifted onto the transformed source's line numbering.
+   * Set only when the variant supplied a `comments` map for this file;
+   * entries whose source line was wiped by the transform are dropped.
+   */
+  comments?: SourceComments;
 }
 export interface TransformedFiles {
   files: TransformedFile[];
@@ -12,32 +18,137 @@ export interface TransformedFiles {
 }
 /**
  * Pure function to get available transforms from effective code data.
- * Only includes transforms that have actual deltas (file changes), not just filename changes.
+ *
+ * Variant-level `transforms` is a manifest produced by `splitTransformsForEmbed`
+ * (or by the legacy `Transforms` shape with deltas, for back-compat). Only
+ * entries that produced a real source delta are reported here — rename-only
+ * entries (manifest entries with `hasDelta: false`, kept around so the
+ * runtime can still apply the rename based on user preference) are filtered
+ * out so the transform toggle stays hidden when nothing meaningful changes.
  *
  * @param effectiveCode - The effective code object containing all variants
  * @param selectedVariantKey - The currently selected variant key
- * @returns Array of available transform keys that have deltas
+ * @returns Array of available transform keys (toggle-visible only)
  */
 export declare function getAvailableTransforms(effectiveCode: Code, selectedVariantKey: string): string[];
 /**
- * Pure helper function to apply transform to a source file.
+ * Like `getAvailableTransforms` but also includes rename-only entries
+ * (manifest entries with `hasDelta: false`). Used by the transform
+ * resolution path so a stored preference can still apply a rename even
+ * when its toggle is hidden because no actual delta exists.
  *
- * @param source - The source code to transform
- * @param fileName - The filename for the source
- * @param transforms - Available transforms for this source
- * @param selectedTransform - The transform to apply
- * @returns Object with transformed source and name
+ * @param effectiveCode - The effective code object containing all variants
+ * @param selectedVariantKey - The currently selected variant key
+ * @returns Array of all applicable transform keys
  */
-export declare function applyTransformToSource(source: VariantSource, fileName: string, transforms: Transforms | undefined, selectedTransform: string): {
-  transformedSource: VariantSource;
-  transformedName: string;
-};
+export declare function getApplicableTransforms(effectiveCode: Code, selectedVariantKey: string): string[];
 /**
- * Pure function to create transformed files from a variant and selected transform.
+ * Determines whether applying `transformKey` to `variant` would introduce
+ * `.collapse` placeholders into the rendered hast tree — i.e. whether the
+ * swap is layout-affecting and must run through the coordinated barrier.
+ *
+ * Reads the precomputed `hasCollapse` / `hasCollapseInFocus` flags
+ * stored on each transform entry by the pipeline (`diffHast` sets them
+ * directly, `splitTransformsForEmbed` propagates them onto the
+ * manifest). No tree walking or delta decompression happens at runtime.
+ *
+ * The `mode` option controls *which* file's transform entry is consulted:
+ *
+ *   - `'selected'` (default) — Consults only the transform map for the
+ *     file identified by `selectedFileName` (or `variant.transforms`
+ *     when `selectedFileName === variant.fileName`). When
+ *     `selectedFileName` is omitted, treats the variant's main file
+ *     (`variant.fileName`) as the selection.
+ *   - `'all'` — Iterates every transform map on the variant
+ *     (`variant.transforms` + each `extraFiles[*].transforms`) and
+ *     returns `true` if any one has `hasCollapse: true`. Useful for
+ *     callers that render multiple files simultaneously and need to
+ *     coordinate a swap whenever *any* file would shift.
+ *   - `'focus'` — Like `'selected'`, but consults
+ *     `hasCollapseInFocus` instead of `hasCollapse` whenever
+ *     `expanded === false`. Lets consumers skip the coordinated
+ *     barrier for transforms whose `.collapse` insertion lands
+ *     outside the initially-visible region of a collapsed code block.
+ *
+ * Falls back to a conservative phase 1 classification for legacy
+ * payloads that carry `hasDelta: true` without the precomputed flag —
+ * i.e. transforms produced by an older build that predates
+ * `hasCollapse`, or constructed by a direct caller bypassing the
+ * pipeline. For `hasCollapseInFocus`, entries that lack the field fall
+ * back to the value of `hasCollapse` (matching the embed-side default).
+ *
+ * Returns `false` when every consulted entry has `hasCollapse: false`
+ * (or `hasCollapseInFocus: false` in focus mode while collapsed), is
+ * rename-only, is absent, or the variant is `null`.
+ *
+ * @param variant - The variant whose transforms to inspect.
+ * @param transformKey - The transform key to classify, or `null`.
+ * @param opts - Optional mode + selected-file + expanded context.
+ */
+export declare function transformHasCollapsePlaceholder(variant: VariantCode | null, transformKey: string | null, opts?: {
+  mode?: 'all' | 'selected' | 'focus';
+  selectedFileName?: string | undefined;
+  expanded?: boolean;
+}): boolean;
+/**
+ * Description of a single transform entry that carries
+ * `hasCollapseInFocus: true`. Returned by
+ * `findCollapseInFocusTransforms` so callers can produce actionable
+ * error messages without re-walking the variant tree.
+ */
+export interface CollapseInFocusOffender {
+  variantName: string;
+  fileName: string;
+  transformKey: string;
+}
+/**
+ * Walk every variant on `effectiveCode` and collect transform entries
+ * whose precomputed `hasCollapseInFocus` flag is `true` — i.e. the
+ * collapse placeholder introduced by the transform lands inside the
+ * focus region that is visible while the surrounding code block is
+ * un-expanded.
+ *
+ * Used by `useCode`'s `strictCollapseInFocus` option to throw with a
+ * pointer to the offending variant/file/transform so the demo author
+ * can narrow the `@focus` region (or the transform's edit range) until
+ * the placeholder lands outside the visible window.
+ *
+ * Walks main files (`variant.transforms`) and `extraFiles[*].transforms`.
+ * Returns an empty array when no entry has the flag set.
+ */
+export declare function findCollapseInFocusTransforms(effectiveCode: Code): CollapseInFocusOffender[];
+/**
+ * Decide whether the rendered `<Pre>` should emit highlighted spans on
+ * this render. Three gates compose:
+ *
+ * 1. `highlightReady` — the render-side readiness gate published by
+ *    `CodeHighlighterClient`. `false` while the highlight trigger
+ *    (`hydration` / `idle` / `visible`) hasn't fired yet *or* the
+ *    sync `parseCode` pass hasn't resolved. The precomputed HAST on
+ *    the published `code` would render highlighted spans on first
+ *    paint otherwise — defeating the deferred trigger. Treated as
+ *    `true` when undefined so legacy/test consumers without a
+ *    surrounding context default to rendering highlighted.
+ * 2. `deferHighlight` — the narrower pipeline-level signal published
+ *    while the incoming variant's parse / transform deltas are still
+ *    in flight. Always wins: if the tree isn't ready, highlighting
+ *    can't happen.
+ * 3. `pendingBootstrap` — set while a stored-preference variant swap
+ *    is queued behind the initial mount. Suppresses the *outgoing*
+ *    tree's highlighting so we don't burn cycles painting spans the
+ *    user is about to swap away from.
  *
- * @param selectedVariant - The currently selected variant
- * @param selectedTransform - The transform to apply
- * @returns Object with transformed files and filename mapping, or undefined if no transform
+ * The bootstrap gate is skipped when `highlightAfter === 'init'`:
+ * - the precomputed HAST already carries the spans (no "wasted work"),
+ *   and
+ * - leaving it on causes the *incoming* variant to render as plain
+ *   text for the render between `pendingBootstrap` flipping and the
+ *   bootstrap commit landing, producing a visible flash of unhighlighted
+ *   code on first-paint variant swaps.
  */
-export declare function createTransformedFiles(selectedVariant: VariantCode | null, selectedTransform: string | null): TransformedFiles | undefined;
-export {};
+export declare function shouldHighlightForRender(args: {
+  deferHighlight: boolean | undefined;
+  highlightReady?: boolean | undefined;
+  pendingBootstrap: boolean;
+  highlightAfter: 'init' | 'hydration' | 'idle' | undefined;
+}): boolean;