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

package/useCode/useVariantSelection.mjs

@@ -1,8 +1,12 @@
 import * as React from 'react';
 import { usePreference } from "../usePreference/index.mjs";
 import { useUrlHashState } from "../useUrlHashState/index.mjs";
+import { useCoordinated } from "../useCoordinated/index.mjs";
+import { useHighlightGate } from "./useHighlightGate.mjs";
+import { useTransitionPhase } from "./useTransitionPhase.mjs";
 import { isHashRelevantToDemo } from "./useFileNavigation.mjs";
 import { toKebabCase } from "../pipeline/loaderUtils/toKebabCase.mjs";
+import { variantHasLayoutShift } from "./sourceLineCounts.mjs";
 
 /**
  * Parses the variant name from a URL hash
@@ -49,17 +53,63 @@ function parseVariantFromHash(urlHash, mainSlug, variantKeys) {
   }
   return null;
 }
+/**
+ * Resolve a stored / hash / initial preference into a valid variant
+ * key. Priority: URL hash > localStorage > initialVariant > first
+ * variant. Returns an empty string only when no variants are
+ * available — callers should treat that as "no selection".
+ */
+function resolveVariantKey(hashVariant, storedValue, initialVariant, variantKeys) {
+  if (hashVariant && variantKeys.includes(hashVariant)) {
+    return hashVariant;
+  }
+  if (storedValue && variantKeys.includes(storedValue)) {
+    return storedValue;
+  }
+  if (initialVariant && variantKeys.includes(initialVariant)) {
+    return initialVariant;
+  }
+  return variantKeys[0] || '';
+}
+
 /**
  * Hook for managing variant selection and providing variant-related data
  * Priority: URL hash > localStorage > initialVariant > first variant
  * When hash has a variant, it overrides localStorage and is saved to localStorage
+ *
+ * Wraps the selection in `useCoordinated` so sibling demos that share
+ * the same variant set commit variant swaps together — preventing
+ * staggered layout shifts when multiple demos on the page react to
+ * the same preference change.
+ */
+/**
+ * Minimum coordinator barrier wait used when `variantSwapDelay` is
+ * unset or zero but a layout-shift-prone swap still needs to land on
+ * the same frame as peer demos. One animation frame at ~60fps so the
+ * coordinated paint feels instantaneous but every peer commits
+ * together. Mirrors the same constant in `useTransformManagement`.
  */
+const MIN_VARIANT_WAIT_MS = 16;
+
+/**
+ * Time after an originator's announce by which all peers should have
+ * acked. Beyond this, the barrier surfaces `pendingVariantKey` so
+ * consumers can render a transient loading indicator while continuing
+ * to wait up to `ultimateTimeoutMs` (10s). Mirrors
+ * `TRANSFORM_GRACE_PERIOD_MS`.
+ */
+const VARIANT_GRACE_PERIOD_MS = 300;
 export function useVariantSelection({
   effectiveCode,
   initialVariant,
   variantType,
   mainSlug,
-  saveHashVariantToLocalStorage = 'on-interaction'
+  saveHashVariantToLocalStorage = 'on-interaction',
+  variantLayoutShift = 'selected',
+  selectedFileName,
+  expanded,
+  variantSwapDelay,
+  deferHighlight
 }) {
   // Get variant keys from effective code
   const variantKeys = React.useMemo(() => {
@@ -78,102 +128,374 @@ export function useVariantSelection({
     return null;
   });
 
-  // Track if the last change was user-initiated (to prevent hash from overriding)
-  const isUserInitiatedChange = React.useRef(false);
-  // Track previous hash variant to detect hash changes
-  const prevHashVariant = React.useRef(hashVariant);
-  // Track previous storedValue to detect localStorage changes
-  const prevStoredValue = React.useRef(storedValue);
-
-  // Determine initial variant: hash > localStorage > initialVariant > first variant
-  const [selectedVariantKey, setSelectedVariantKeyState] = React.useState(() => {
-    // Priority 1: Hash variant
-    if (hashVariant && variantKeys.includes(hashVariant)) {
-      return hashVariant;
-    }
-    // Priority 2: localStorage
-    if (storedValue && variantKeys.includes(storedValue)) {
-      return storedValue;
-    }
-    // Priority 3: initialVariant prop
-    if (initialVariant && variantKeys.includes(initialVariant)) {
-      return initialVariant;
-    }
-    // Priority 4: First available variant
-    return variantKeys[0] || '';
+  // When a delay is configured, start from the boot-time value
+  // (initialVariant or first variant), then adopt the stored value on
+  // a later tick as a normal coordinated receiver swap. This allows
+  // the initial→stored transition to open `data-transforming` windows
+  // instead of resolving to the stored variant before first paint —
+  // most visibly when the full content component replaces a loading
+  // skeleton and needs to animate from the default variant to the
+  // user's saved preference.
+  //
+  // The bootstrap is gated on the *stored* variant's source being
+  // available as HAST (not a raw string). On a fresh mount, only the
+  // default variant typically has source data; non-default variants
+  // are lazy-loaded as URL refs and then parsed into HAST by the
+  // highlighter pipeline. Firing the bootstrap before that lands
+  // commits a swap to a variant whose `<Pre>` has no HAST to render,
+  // producing the user-visible sequence: unhighlighted initial paint
+  // → swap-and-animate against still-unhighlighted content → content
+  // snaps to highlighted text mid-animation. Waiting for the stored
+  // variant's HAST guarantees the receiver-flow animation plays once,
+  // against a fully-highlighted target tree, so the visible order is
+  // swap → highlight → animate.
+  //
+  // We also gate on the parent's `deferHighlight` flipping to `false`.
+  // `deferHighlight` reflects the current variant's highlight pipeline
+  // state (parsing + transforms). Without this wait the combobox
+  // pending value flips to the stored variant as soon as its HAST is
+  // available, but the receiver flow's `preload` then blocks on
+  // `awaitHighlight` (which tracks the *current* variant's
+  // `deferHighlight`). The visible result is a large gap where the
+  // combo says "Tailwind" but the content is still CSS Modules with
+  // `data-transforming` running against the stale tree. Waiting for
+  // `deferHighlight=false` before flipping `allowStoredBootstrap`
+  // keeps the combo and the content swap in lockstep — and, paired
+  // with the unconditional `storedValueForResolve` gate below, means
+  // the swap commit lands on an already-highlighted destination
+  // instead of flashing the stored variant through its raw-source
+  // fallback while its parse completes.
+  const storedVariantSourceLoaded = React.useMemo(() => {
+    // When there's no stored preference (or it's not a valid variant key),
+    // the bootstrap doesn't change the resolved variant, so no wait needed.
+    if (!storedValue || !variantKeys.includes(storedValue)) {
+      return true;
+    }
+    const variantEntry = effectiveCode[storedValue];
+    if (!variantEntry || typeof variantEntry === 'string') {
+      return false;
+    }
+    // Require HAST (not a raw string source) so the receiver-flow
+    // animation runs against the already-highlighted target tree.
+    return variantEntry.source != null && typeof variantEntry.source !== 'string';
+  }, [storedValue, variantKeys, effectiveCode]);
+  // One-way latch: opens after the stored variant's HAST is
+  // available and the parent highlighter is no longer deferring
+  // highlights. Driven by an effect (not a render-time set-state)
+  // so the first render always resolves to `initialVariant`; the
+  // effect then flips the latch on a later tick, the resolved value
+  // swings to `storedValue`, and the change drives the coordinated
+  // receiver-flow swap (with its `data-transforming` animation).
+  // Adopting the stored value synchronously on the first render
+  // would skip the swap entirely — no animation, and
+  // `pendingBootstrap` would never latch so `useCode` wouldn't
+  // suppress highlight on the outgoing initial variant.
+  const [allowStoredBootstrap, setAllowStoredBootstrap] = React.useState(false);
+  React.useEffect(() => {
+    if (!storedVariantSourceLoaded) {
+      return;
+    }
+    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]);
+
+  // Barrier wait length. Falls back to one frame when
+  // `variantSwapDelay` isn't configured so peers still align on the
+  // same paint without making the click feel sluggish.
+  const hasDelay = typeof variantSwapDelay === 'number' && variantSwapDelay > 0;
+  const effectiveSwapWindowMs = hasDelay ? variantSwapDelay : MIN_VARIANT_WAIT_MS;
+
+  // Hold the resolved value on the initial variant until the
+  // bootstrap gate (`allowStoredBootstrap`) releases whenever there
+  // is a highlight pipeline to wait for — either because a
+  // `variantSwapDelay` is configured (delayed swaps must always
+  // settle on HAST) or because a `CodeHighlighter` parent is
+  // publishing a `deferHighlight` signal (in which case the stored
+  // variant's parse hasn't necessarily completed even though the
+  // coordinator's `minWaitMs` is zero). Without this second clause,
+  // the no-delay path would commit the swap on the very first
+  // render and the stored variant would flash through its raw-source
+  // fallback while its parse completed. When neither condition
+  // applies (bare `useCode` consumers in tests / non-highlighted
+  // contexts) we skip the gate so raw-string sources continue to
+  // bootstrap synchronously.
+  const shouldGateBootstrap = hasDelay || deferHighlight !== undefined;
+  const storedValueForResolve = shouldGateBootstrap && !allowStoredBootstrap ? null : storedValue;
+
+  // Resolved underlying value combining hash and localStorage (and
+  // the initial/first-variant fallbacks). This is what `useCoordinated`
+  // observes as its external source of truth — any change to hash or
+  // storage opens a receiver-flow barrier so peer demos commit
+  // together.
+  const resolvedValue = React.useMemo(() => resolveVariantKey(hashVariant, storedValueForResolve, initialVariant, variantKeys), [hashVariant, storedValueForResolve, initialVariant, variantKeys]);
+
+  // Stable underlying tuple. The setter is intentionally a no-op:
+  // localStorage writes are performed *eagerly* by
+  // `setSelectedVariantAsUser` (so user intent is persisted and
+  // broadcast to peer demos on the same tick as the click), not
+  // lazily on barrier commit. The engine sees the eager write echo
+  // back through `usePreference` and dedupes it via its
+  // `inFlightTargetRef` guard so the receiver flow doesn't double-fire.
+  const underlying = React.useMemo(() => [resolvedValue, () => {}], [resolvedValue]);
+
+  // Coordinator key. Demos sharing the same variant set belong to the
+  // same coordination group. Use the variant-type bucket when set so
+  // unrelated variant sets that share a type (e.g. Yarn/Npm/Pnpm
+  // installs) still coordinate even if their key list differs.
+  const channelKey = React.useMemo(() => {
+    // Single-variant demos have nothing to coordinate (no choice to
+    // swap to) — skip the coordinator entirely so we don't trigger
+    // its localStorage reads. Mirrors `usePreference`'s
+    // single-element-array short-circuit.
+    if (variantKeys.length < 2) {
+      return null;
+    }
+    if (variantType) {
+      return `variant:${variantType}`;
+    }
+    return `variant:${[...variantKeys].sort().join(':')}`;
+  }, [variantKeys, variantType]);
+
+  // Stable per-hook identity used by the coordinator to track which
+  // demos have acked the current barrier. `React.useId` gives us a
+  // unique-per-mount string without the impure `Math.random()` /
+  // `Date.now()` dance, and stays stable across re-renders.
+  const demoId = React.useId();
+
+  // Latest props read by the engine's `causesLayoutShift` callback.
+  // Kept in a ref so the callback itself can be referentially stable.
+  const layoutShiftPropsRef = React.useRef({
+    effectiveCode,
+    variantLayoutShift,
+    selectedFileName,
+    expanded
   });
+  // eslint-disable-next-line react-hooks/refs
+  layoutShiftPropsRef.current = {
+    effectiveCode,
+    variantLayoutShift,
+    selectedFileName,
+    expanded
+  };
 
-  // Track selected variant key in a ref for use in effect without causing re-runs
-  const selectedVariantKeyRef = React.useRef(selectedVariantKey);
-  React.useEffect(() => {
-    selectedVariantKeyRef.current = selectedVariantKey;
+  // Latest committed variant key — read by `causesLayoutShift` to
+  // compare against the swap target. Initialized to `''` (rather than
+  // `resolvedValue`) because the post-`useCoordinated` assignment
+  // below is the single source of truth: relying on the init argument
+  // would leave the ref stale if `resolvedValue` later changed
+  // outside of a commit. The empty string is a sentinel —
+  // `variantHasLayoutShift` treats a falsy `from` key as "no shift".
+  const committedRef = React.useRef('');
+  const causesLayoutShift = React.useCallback(target => {
+    const props = layoutShiftPropsRef.current;
+    return variantHasLayoutShift(props.effectiveCode, committedRef.current, target, {
+      mode: props.variantLayoutShift,
+      selectedFileName: props.selectedFileName,
+      expanded: props.expanded
+    });
+  }, []);
+
+  // Track whether the most recent commit landed on `hashVariant` so
+  // we can opt-in save to localStorage under `'on-load'` semantics.
+  const lastStoredValueRef = React.useRef(storedValue);
+  // eslint-disable-next-line react-hooks/refs
+  lastStoredValueRef.current = storedValue;
+  const lastHashVariantRef = React.useRef(hashVariant);
+  // eslint-disable-next-line react-hooks/refs
+  lastHashVariantRef.current = hashVariant;
+  const onCommit = React.useCallback(target => {
+    // Mirror the historical `'on-load'` behavior: when a swap
+    // commits to whatever the hash currently points at, persist
+    // that variant to localStorage so a subsequent visit without a
+    // hash still lands on the same variant.
+    if (saveHashVariantToLocalStorage === 'on-load' && lastHashVariantRef.current && lastHashVariantRef.current === target && target !== lastStoredValueRef.current) {
+      setStoredValue(target);
+    }
+  }, [saveHashVariantToLocalStorage, setStoredValue]);
+
+  // Tracks the previous render's committed variant so we can decide
+  // the originator's `minWaitMs` synchronously inside
+  // `selectVariantDispatch`: leaving a non-empty variant needs the
+  // pre-swap expand window. Initialised to the resolved boot value
+  // (mirroring `useTransformManagement`'s `prevCommittedTransformRef`)
+  // so the very first user-driven dispatch already sees a non-empty
+  // ref and applies `variantSwapDelay`. The empty-string sentinel is
+  // kept as a fallback for the (rare) case where the variant list
+  // resolves empty during boot.
+  const prevCommittedVariantKeyRef = React.useRef(resolvedValue);
+
+  // Hold the originator's coordinator barrier open while the
+  // highlighter pipeline is still working on the incoming variant.
+  // Without this, an interactive variant swap can commit after
+  // `variantSwapDelay` even when the new variant's `parseCode` /
+  // `computeHastDeltas` hasn't landed — the incoming `<Pre>` paints
+  // from raw source then snaps to highlighted text a frame later.
+  // See `useHighlightGate` for the gate plumbing.
+  const awaitHighlight = useHighlightGate(!!deferHighlight);
+  const preload = React.useCallback((_target, signal) => {
+    const wait = awaitHighlight(signal);
+    if (wait === null) {
+      return undefined;
+    }
+    return wait;
+  }, [awaitHighlight]);
+  const [committedVariantKey, selectVariantDispatch, coordinationExtras] = useCoordinated(underlying, {
+    channelKey,
+    peerId: demoId,
+    causesLayoutShift,
+    preload,
+    onCommit,
+    // eslint-disable-next-line react-hooks/refs
+    minWaitMs: hasDelay && prevCommittedVariantKeyRef.current !== '' ? variantSwapDelay : 0,
+    multiPeerExtraMinWaitMs: hasDelay ? 0 : MIN_VARIANT_WAIT_MS,
+    lazyMinWaitMs: hasDelay ? variantSwapDelay : 0,
+    gracePeriodMs: VARIANT_GRACE_PERIOD_MS
   });
 
-  // When hash changes and has a variant, override current selection
-  // When hash is removed, fall back to localStorage
+  // eslint-disable-next-line react-hooks/refs
+  prevCommittedVariantKeyRef.current = committedVariantKey;
+
+  // Keep the outgoing-tree probe in sync with whatever the engine
+  // just committed. Mutating a ref during render is safe — React
+  // tolerates it as long as the value derives deterministically from
+  // inputs of the current render.
+  // eslint-disable-next-line react-hooks/refs
+  committedRef.current = committedVariantKey;
+
+  // User-facing selected variant key. Prefer the pending value so UI
+  // controls (tabs, dropdowns) react immediately to a click, even if
+  // the engine is briefly holding the visible value back for a
+  // coordinated barrier.
+  const selectedVariantKey = coordinationExtras.pendingValue;
+
+  // Track the initial committed variant so we can detect the very
+  // first commit (whether driven by bootstrap or a user click that
+  // races bootstrap). `pendingBootstrap` derives from this so callers
+  // can suppress highlighting of the outgoing initial variant when a
+  // stored-preference swap is known to be in flight — without it,
+  // the initial variant briefly paints fully highlighted right at
+  // the moment the combobox flips to the stored value, then flashes
+  // through the animation against stale content before the incoming
+  // tree commits. Latching on first commit (not on
+  // `committedVariantKey === storedValue`) keeps the gate honest if
+  // the user clicks during the bootstrap window: their click commits
+  // a different variant and `pendingBootstrap` releases so the new
+  // selection lights up normally.
+  const [initialCommittedVariantKey, setInitialCommittedVariantKey] = React.useState(null);
+  const [hasCommittedPastInitial, setHasCommittedPastInitial] = React.useState(false);
   React.useEffect(() => {
-    // Skip if this was a user-initiated change
-    if (isUserInitiatedChange.current) {
-      // Only reset the flag once the hash has actually been cleared
-      if (hashVariant === null && urlHash === null) {
-        isUserInitiatedChange.current = false;
-      }
-      prevHashVariant.current = hashVariant;
+    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
+  // identity changes (the consumer swaps in a new lesson with a
+  // different variant set, or `variantType` switches the
+  // `usePreference` bucket). Without this, a second payload
+  // inherits the first payload's "already bootstrapped" state and
+  // its newly resolved stored preference is never adopted.
+  //
+  // The identity is derived from the bucket coordinates — the same
+  // values `usePreference` keys off — rather than `effectiveCode`'s
+  // object identity. `CodeHighlighterClient` rebuilds and republishes
+  // the code object during ordinary parse / transform progress, so
+  // keying on `effectiveCode` would re-arm the bootstrap path in
+  // the middle of a user-driven swap (whose stored value is
+  // persisted eagerly by `setSelectedVariantAsUser`), making an
+  // interactive variant change look like an initial-mount stored
+  // bootstrap and replaying it again.
+  //
+  // Tracking the previous identity in state (rather than a ref)
+  // follows React's "adjusting state when a prop changes" pattern
+  // so the reset stays a synchronous render-time decision without
+  // violating the refs-during-render rule.
+  const bootstrapIdentity = React.useMemo(() => `${variantType ?? ''}\u0000${[...variantKeys].sort().join('\u0001')}`, [variantType, variantKeys]);
+  const [prevBootstrapIdentity, setPrevBootstrapIdentity] = React.useState(bootstrapIdentity);
+  if (prevBootstrapIdentity !== bootstrapIdentity) {
+    setPrevBootstrapIdentity(bootstrapIdentity);
+    // Reset to `false` so the effect re-runs and the resolved value
+    // swings from initial → stored on a later tick. Setting it true
+    // synchronously here would skip the receiver-flow swap animation
+    // for the new bucket — same regression class as bootstrapping
+    // synchronously on first render.
+    setAllowStoredBootstrap(false);
+    setHasCommittedPastInitial(false);
+    setInitialCommittedVariantKey(null);
+  }
+  // A stored-preference bootstrap is only actually pending when no
+  // higher-precedence source (the URL hash) is already winning. When
+  // the hash takes precedence, the resolved value matches the hash
+  // forever and no bootstrap swap will ever fire — gating only on
+  // `storedValue !== committedVariantKey` here would leave
+  // `pendingBootstrap` latched forever, which `useCode` translates
+  // into "never highlight". The hash precedence guard keeps
+  // permalinked / hash-selected demos highlighting normally even when
+  // the user's saved preference points at a different variant.
+  const hashOverridesStorage = !!hashVariant && variantKeys.includes(hashVariant);
+  const pendingBootstrap = !hasCommittedPastInitial && !hashOverridesStorage && !!storedValue && variantKeys.includes(storedValue) && storedValue !== committedVariantKey;
+
+  // User setter: persists to localStorage (and clears any relevant
+  // URL hash) before dispatching the coordinator so peer demos
+  // observe the new preference on the same tick as the click.
+  // Validation differs from `resolveVariantKey`: an explicit `null`
+  // means "fall back to the first variant" — never re-resolved to
+  // `initialVariant` (which is only consulted for the
+  // never-set-storage hydration path).
+  const setSelectedVariantAsUser = React.useCallback(value => {
+    const resolved = typeof value === 'function' ? value(selectedVariantKey) : value;
+    const effectiveValue = resolved ?? variantKeys[0];
+    if (!effectiveValue || !variantKeys.includes(effectiveValue)) {
+      return;
+    }
+    if (effectiveValue === selectedVariantKey && effectiveValue === committedVariantKey) {
       return;
     }
+    // Clear hash first so the receiver flow doesn't observe a
+    // stale hash → variant mapping after the storage write echoes
+    // back through `usePreference`. Only clear when the current
+    // hash is one this demo cares about.
+    if (urlHash && mainSlug && isHashRelevantToDemo(urlHash, mainSlug)) {
+      setUrlHash(null);
+    }
+    // Start local coordination from the user action first so this
+    // demo is always treated as the originator (matching the
+    // pattern in `useTransformManagement`), then persist.
+    selectVariantDispatch(effectiveValue);
+    setStoredValue(effectiveValue);
+  }, [selectedVariantKey, committedVariantKey, variantKeys, urlHash, mainSlug, setUrlHash, selectVariantDispatch, setStoredValue]);
 
-    // Only apply hash if it actually changed (not just a re-render with same hash)
-    const hashChanged = prevHashVariant.current !== hashVariant;
-    const storedValueChanged = prevStoredValue.current !== storedValue;
-    prevHashVariant.current = hashVariant;
-    prevStoredValue.current = storedValue;
-    if (!hashChanged && !storedValueChanged) {
+  // Programmatic setter: doesn't save to localStorage and doesn't
+  // clear the hash. Used for hash-driven changes routed through
+  // `useFileNavigation`.
+  const setSelectedVariantProgrammatic = React.useCallback(value => {
+    const resolved = typeof value === 'function' ? value(selectedVariantKey) : value;
+    if (!variantKeys.includes(resolved)) {
       return;
     }
-    if (hashVariant && variantKeys.includes(hashVariant) && hashVariant !== selectedVariantKeyRef.current) {
-      // Hash has a variant - use it
-      setSelectedVariantKeyState(hashVariant);
-      // Save hash variant to localStorage based on configuration
-      if (saveHashVariantToLocalStorage === 'on-load' && hashVariant !== storedValue) {
-        setStoredValue(hashVariant);
-      }
-    } else if (!hashVariant && !urlHash &&
-    // Only fall back to localStorage when hash is truly empty
-    storedValue && variantKeys.includes(storedValue) && storedValue !== selectedVariantKeyRef.current) {
-      // Hash is empty but localStorage has a variant - use it
-      setSelectedVariantKeyState(storedValue);
-    }
-  }, [hashVariant, urlHash, variantKeys,
-  // Note: selectedVariantKey is intentionally NOT in dependencies
-  // to avoid effect running when user manually changes variant
-  storedValue, setStoredValue, saveHashVariantToLocalStorage]);
-
-  // Programmatic setter: doesn't save to localStorage (used for hash-driven changes)
-  const setSelectedVariantKeyProgrammatic = React.useCallback(value => {
-    const resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
-    if (variantKeys.includes(resolvedValue)) {
-      setSelectedVariantKeyState(resolvedValue);
-    }
-  }, [selectedVariantKey, variantKeys]);
-
-  // User setter: saves to localStorage (used for user-initiated changes like dropdown)
-  const setSelectedVariantKeyAsUser = React.useCallback(value => {
-    const resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
-    // If value is null, select the first variant (default)
-    const effectiveValue = resolvedValue ?? variantKeys[0];
-    if (effectiveValue && variantKeys.includes(effectiveValue)) {
-      // Mark as user-initiated to prevent hash effect from overriding
-      isUserInitiatedChange.current = true;
-      // Clear hash if it exists and is relevant to this demo
-      if (urlHash && mainSlug && isHashRelevantToDemo(urlHash, mainSlug)) {
-        setUrlHash(null);
-        // Update prevHashVariant to reflect that hash is now null
-        prevHashVariant.current = null;
-      }
-      setSelectedVariantKeyState(effectiveValue);
-      setStoredValue(effectiveValue);
-    }
-  }, [setStoredValue, selectedVariantKey, variantKeys, urlHash, mainSlug, setUrlHash]);
+    if (resolved === selectedVariantKey && resolved === committedVariantKey) {
+      return;
+    }
+    selectVariantDispatch(resolved);
+  }, [selectedVariantKey, committedVariantKey, variantKeys, selectVariantDispatch]);
   const selectedVariant = React.useMemo(() => {
     const variant = effectiveCode[selectedVariantKey];
     if (variant && typeof variant === 'object' && 'source' in variant) {
@@ -182,12 +504,119 @@ export function useVariantSelection({
     return null;
   }, [effectiveCode, selectedVariantKey]);
 
-  // Safety check: if selectedVariant doesn't exist, fall back to first variant
+  // Variant resolved from the *committed* key — lags `selectedVariant`
+  // by `variantSwapDelay` ms when a delay is configured. Used by the
+  // renderer so the outgoing tree stays put for the pre-swap window.
+  const committedVariant = React.useMemo(() => {
+    if (committedVariantKey === selectedVariantKey) {
+      return selectedVariant;
+    }
+    const variant = effectiveCode[committedVariantKey];
+    if (variant && typeof variant === 'object' && 'source' in variant) {
+      return variant;
+    }
+    return null;
+  }, [effectiveCode, committedVariantKey, selectedVariantKey, selectedVariant]);
+
+  // Post-swap `data-transforming="expanded"`/`"collapsing"` window. Mirrors the
+  // equivalent in `useTransformManagement`: fires after the engine
+  // commits a swap so the incoming tree has a chance to enter-animate
+  // any bridge `.collapse` placeholder appended by `<Pre>`. Only
+  // armed when `variantSwapDelay` is configured.
+  //
+  // `collapseSourceVariantKey` captures the variant we just left at
+  // the moment of commit so the post-swap window has a stable bridge
+  // target even if `selectedVariantKey` keeps changing.
+  const [postSwapWindowActive, setPostSwapWindowActive] = React.useState(false);
+  const [collapseSourceVariantKey, setCollapseSourceVariantKey] = React.useState(null);
+  const [prevAppliedVariant, setPrevAppliedVariant] = React.useState(committedVariantKey);
+  if (prevAppliedVariant !== committedVariantKey) {
+    if (hasDelay && prevAppliedVariant !== '') {
+      setPostSwapWindowActive(true);
+      setCollapseSourceVariantKey(prevAppliedVariant);
+    }
+    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;
+    }
+    const timerId = setTimeout(() => {
+      setPostSwapWindowActive(false);
+      setCollapseSourceVariantKey(null);
+    }, effectiveSwapWindowMs);
+    return () => clearTimeout(timerId);
+  }, [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
+  // needs to expand out for the next swap. When `variantSwapDelay`
+  // isn't configured, no animation window is opening (the coordinator
+  // wait is the one-frame `MIN_VARIANT_WAIT_MS`, too short to
+  // animate) so the phase stays `null`.
+  //
+  // Each phase enters a "paused" value first (`'collapsed'` for the
+  // pre-swap window, `'expanded'` for the post-swap window). The
+  // rendered `<Pre>` calls `notifyVariantTransitionReady` once it has
+  // painted the new tree at that paused value, flipping
+  // `variantTransitionReady` to `true` which advances the phase to
+  // the matching active value (`'expanding'` / `'collapsing'`). The
+  // readiness flag is keyed on `(committedVariantKey,
+  // selectedVariantKey)` so each new paused window starts with a
+  // fresh wait.
+  const variantTransitionWindowKey = `${committedVariantKey}|${selectedVariantKey}|${postSwapWindowActive ? '1' : '0'}`;
+  const {
+    ready: variantTransitionReady,
+    notify: notifyVariantTransitionReady
+  } = useTransitionPhase(variantTransitionWindowKey);
+  const variantSwappingPhase = (() => {
+    if (!hasDelay) {
+      return null;
+    }
+    if (committedVariantKey !== selectedVariantKey) {
+      return variantTransitionReady ? 'expanding' : 'collapsed';
+    }
+    if (postSwapWindowActive) {
+      return variantTransitionReady ? 'collapsing' : 'expanded';
+    }
+    return null;
+  })();
+  const swapPartnerVariantKey = (() => {
+    if (variantSwappingPhase === 'collapsed' || variantSwappingPhase === 'expanding') {
+      return selectedVariantKey || null;
+    }
+    if (variantSwappingPhase === 'expanded' || variantSwappingPhase === 'collapsing') {
+      return collapseSourceVariantKey;
+    }
+    return null;
+  })();
+  const pendingVariantKey = coordinationExtras.isWaitingForPeers ? coordinationExtras.pendingValue : undefined;
+
+  // Safety check: if the selected variant truly disappears from the
+  // code map (e.g. variant keys re-resolved), fall back to the first
+  // variant. We deliberately *don't* trip on a key whose entry exists
+  // but is still a lazy placeholder (string / partial object without
+  // `source`): during incremental loading the variant key is valid,
+  // the source just hasn't arrived yet, and bouncing through the
+  // coordinator here would round-trip the selection
+  // stored → first-variant → stored (the receiver flow re-resolves
+  // back to the underlying value the moment the placeholder swaps
+  // for a real `VariantCode`). `variantKeys` itself only includes
+  // fully-loaded variants, so it's not a reliable signal here.
+  const keyExistsInCode = selectedVariantKey ? Object.prototype.hasOwnProperty.call(effectiveCode, selectedVariantKey) : false;
   React.useEffect(() => {
-    if (!selectedVariant && variantKeys.length > 0) {
-      setSelectedVariantKeyProgrammatic(variantKeys[0]);
+    if (!keyExistsInCode && variantKeys.length > 0) {
+      setSelectedVariantProgrammatic(variantKeys[0]);
     }
-  }, [selectedVariant, variantKeys, setSelectedVariantKeyProgrammatic]);
+  }, [keyExistsInCode, variantKeys, setSelectedVariantProgrammatic]);
 
   // Function to save variant to localStorage (used for on-interaction mode)
   const saveVariantToLocalStorage = React.useCallback(variant => {
@@ -199,8 +628,15 @@ export function useVariantSelection({
     variantKeys,
     selectedVariantKey,
     selectedVariant,
-    selectVariant: setSelectedVariantKeyAsUser,
-    selectVariantProgrammatic: setSelectedVariantKeyProgrammatic,
+    committedVariantKey,
+    committedVariant,
+    variantSwappingPhase,
+    swapPartnerVariantKey,
+    pendingVariantKey,
+    pendingBootstrap,
+    notifyVariantTransitionReady,
+    selectVariant: setSelectedVariantAsUser,
+    selectVariantProgrammatic: setSelectedVariantProgrammatic,
     saveVariantToLocalStorage,
     hashVariant
   };