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

package/useCoordinated/useCoordinated.d.mts

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { type ChannelKey, type PeerId } from "./coordinatePreference.mjs";
+/**
+ * Options for {@link useCoordinated}. See `coordinatePreference` for
+ * the underlying semantics; only React-specific behaviors are
+ * documented here.
+ */
+export interface UseCoordinatedOptions<TValue, TPreload> {
+  /**
+   * Coordination scope. All peers (component instances) that share a
+   * `channelKey` participate in the same layout-shift barrier. Pass
+   * `null` to opt out of coordination entirely (the hook becomes a
+   * plain pass-through of the underlying `[value, setValue]`).
+   */
+  channelKey: ChannelKey | null;
+  /**
+   * Stable identifier for *this* peer within the channel. Defaults to
+   * a freshly generated id on mount. Override when stable cross-mount
+   * identity matters (e.g. for analytics / debugging).
+   */
+  peerId?: PeerId;
+  /**
+   * Return `true` when applying this target would visibly shift
+   * layout — the peer joins the channel-wide barrier so all such
+   * peers commit together. Return `false` for non-disruptive changes
+   * — the peer commits lazily on its own self-serial chain. See
+   * `coordinatePreference` for the full semantics.
+   */
+  causesLayoutShift: (target: TValue) => boolean;
+  /**
+   * Optional async work to run before the barrier commits (for
+   * `causesLayoutShift === true`) or before a lazy commit (for
+   * `false`). The resolved value is handed to `onCommit`.
+   */
+  preload?: (target: TValue, signal: AbortSignal) => TPreload | Promise<TPreload>;
+  /**
+   * Hook fired inside the coordinated commit, before the visible
+   * value flips. Useful for installing precomputed payloads into
+   * neighboring state. The visible `value` returned from this hook
+   * always lags `pendingValue` until coordination settles, so this
+   * runs *with* the value flip, not before it.
+   *
+   * Also fires once on first mount, with the initial preloaded
+   * payload, so consumers can install precomputed state on hydration
+   * without a separate code path.
+   *
+   * Under normal conditions `preloaded` is whatever this peer's
+   * `preload` resolved to. It may still be `undefined` when:
+   *  - the barrier force-resolved at `ultimateTimeoutMs` (a sibling
+   *    peer crashed / hung; accompanied by a console warning),
+   *  - `preload` threw (logged via `console.error`, treated as a
+   *    no-op so the rest of the channel still commits), or
+   *  - `preload` explicitly returned `undefined`.
+   *
+   * Handlers should tolerate the undefined case and fall back to a
+   * synchronous render path rather than throwing.
+   */
+  onCommit?: (target: TValue, preloaded: TPreload | undefined) => void;
+  /**
+   * See {@link AnnounceOptions.minWaitMs}.
+   */
+  minWaitMs?: number;
+  /**
+   * See {@link AnnounceOptions.multiPeerExtraMinWaitMs}.
+   */
+  multiPeerExtraMinWaitMs?: number;
+  /**
+   * See {@link AnnounceOptions.lazyMinWaitMs}.
+   */
+  lazyMinWaitMs?: number;
+  /**
+   * See {@link AnnounceOptions.gracePeriodMs}.
+   */
+  gracePeriodMs?: number;
+  /**
+   * See {@link AnnounceOptions.ultimateTimeoutMs}.
+   */
+  ultimateTimeoutMs?: number;
+  /**
+   * Controls whether `isCoordinating` flips *during* the preload
+   * or *after* it. `pendingValue` (the user-facing "intent"
+   * signal) always flips synchronously regardless of this flag —
+   * toolbars and other affordances stay responsive on click.
+   *
+   * - `false` (default) — defer `isCoordinating` until the
+   *   originator's `preload` settles. Use this when the preload
+   *   is CPU-bound (parsing, syntax highlighting, layout
+   *   measurement, etc.) and the consumer drives a visible
+   *   animation off `isCoordinating`. Running the animation
+   *   concurrently with the preload would steal main-thread time
+   *   from the compositor and produce a janky transition; with
+   *   the flip deferred the animation only starts once the heavy
+   *   work is done.
+   * - `true` — flip `isCoordinating` synchronously on the
+   *   originating setter call, so the animation runs in parallel
+   *   with the preload. Use this when the preload is I/O-bound
+   *   (network fetches, `localStorage` reads, etc.) so the
+   *   animation and the I/O roundtrip overlap.
+   *
+   * The coordinator always yields to the browser (via
+   * `scheduler.yield()` when available, otherwise a `setTimeout`
+   * macrotask) before invoking `preload`, so even synchronous
+   * preloads settle one macrotask after the originating setter
+   * call. This lets the intermediate loading state paint before
+   * the (potentially CPU-bound) preload monopolizes the main
+   * thread. This flag has no effect when `preload` is omitted;
+   * the flip is synchronous either way.
+   *
+   * Only the originator's flip is affected. Sibling peers picked
+   * up via `notifySiblings` still observe the receiver flow's
+   * synchronous flip, because their `isCoordinating` is driven
+   * by the originator's broadcast rather than a local click.
+   */
+  animateDuringPreload?: boolean;
+  /**
+   * Scheduling priority for lazy-path commits.
+   *
+   * - `'idle'` (default) — lazy-path commits are deferred via
+   *   `requestIdleCallback` so the browser can yield to in-flight
+   *   paints and input. Use when the lazy peer's commit itself is
+   *   main-thread heavy (DOM reconciliation of a freshly
+   *   transformed tree, etc.).
+   * - `'normal'` — the commit lands as soon as the preload
+   *   resolves. Use for I/O-bound `preload`s where the commit is
+   *   cheap and you want each peer's swap to surface immediately;
+   *   otherwise idle scheduling can cluster commits together near
+   *   the slowest peer's settle.
+   *
+   * Has no effect when this peer takes the barrier path — barrier
+   * commits are batched synchronously inside the barrier's resolve
+   * microtask regardless.
+   */
+  lazyCommitPriority?: 'idle' | 'normal';
+}
+export interface UseCoordinatedExtras<TValue> {
+  /**
+   * The most recently announced target value. Equals the committed
+   * `value` when no coordination is in flight. Useful for showing an
+   * optimistic preview UI (toolbar selection, etc.) that should react
+   * instantly to a click even when the visible content has a pending
+   * barrier.
+   */
+  pendingValue: TValue;
+  /**
+   * `true` while a coordination is in flight that this peer can drive
+   * an animation off of. For receivers and barrier joiners that lands
+   * synchronously with the announce. For originators the flip is
+   * controlled by `animateDuringPreload`: with the default
+   * `animateDuringPreload: false`, `isCoordinating` stays `false`
+   * until the originator's `preload` settles, then flips `true` for
+   * the remainder of the barrier; with `animateDuringPreload: true`,
+   * it flips synchronously on the originating setter call so the
+   * animation overlaps with an I/O-bound preload. Use
+   * {@link pendingValue} to drive intent-based affordances (toolbar
+   * selection, etc.) that should react instantly to a click
+   * regardless of this flag. Surfaces as `data-coordinating` on
+   * consumers.
+   */
+  isCoordinating: boolean;
+  /**
+   * `true` once the grace period has elapsed with the barrier still
+   * unresolved. Only set on the originating peer. Surface as a
+   * "waiting" affordance to the user.
+   */
+  isWaitingForPeers: boolean;
+}
+/**
+ * Coordinate a piece of state across sibling component instances on
+ * the same channel, so that visually disruptive value changes commit
+ * in a single layout pass rather than independently. Designed as a
+ * thin wrapper around any `useState`-shaped primitive (e.g.
+ * `useLocalStorageState`, `usePreference`, plain `useState`).
+ *
+ * **Originator flow** — calling the returned `setValue`:
+ *   1. `pendingValue` updates synchronously to the requested target
+ *   2. The coordinator runs `preload` (per phase rules) and waits for
+ *      sibling peers (phase 1 only)
+ *   3. When the barrier resolves, the underlying `setValue` is called
+ *      and this hook's visible `value` flips, so the swap is
+ *      consistent with the optional `onCommit` side-effect
+ *
+ * **Receiver flow** — when the underlying `value` changes from outside
+ * (e.g. a storage event from another tab):
+ *   1. `pendingValue` updates to match
+ *   2. Coordination runs locally (this tab's peers run their own
+ *      phase-1 barrier)
+ *   3. The visible `value` returned by this hook is held at the
+ *      previous value until the barrier resolves, then flips
+ *
+ * Pass `channelKey: null` to disable coordination — the hook becomes
+ * a transparent pass-through of the underlying tuple.
+ */
+export declare function useCoordinated<TValue, TPreload = void>(underlying: [TValue, (next: TValue) => void], options: UseCoordinatedOptions<TValue, TPreload>): [TValue, React.Dispatch<React.SetStateAction<TValue>>, UseCoordinatedExtras<TValue>];

package/useCoordinated/useCoordinated.mjs

@@ -0,0 +1,469 @@
+'use client';
+
+import * as React from 'react';
+import { registerPeer, reportValue, announceTarget, getBarrierAnnounceTime } from "./coordinatePreference.mjs";
+import { whenLayoutShiftsSettled, layoutShiftsSettled } from "./layoutShiftGate.mjs";
+
+/**
+ * Options for {@link useCoordinated}. See `coordinatePreference` for
+ * the underlying semantics; only React-specific behaviors are
+ * documented here.
+ */
+
+let nextAutoPeerId = 0;
+function generatePeerId() {
+  nextAutoPeerId += 1;
+  return `peer-${nextAutoPeerId}`;
+}
+
+/**
+ * Coordinate a piece of state across sibling component instances on
+ * the same channel, so that visually disruptive value changes commit
+ * in a single layout pass rather than independently. Designed as a
+ * thin wrapper around any `useState`-shaped primitive (e.g.
+ * `useLocalStorageState`, `usePreference`, plain `useState`).
+ *
+ * **Originator flow** — calling the returned `setValue`:
+ *   1. `pendingValue` updates synchronously to the requested target
+ *   2. The coordinator runs `preload` (per phase rules) and waits for
+ *      sibling peers (phase 1 only)
+ *   3. When the barrier resolves, the underlying `setValue` is called
+ *      and this hook's visible `value` flips, so the swap is
+ *      consistent with the optional `onCommit` side-effect
+ *
+ * **Receiver flow** — when the underlying `value` changes from outside
+ * (e.g. a storage event from another tab):
+ *   1. `pendingValue` updates to match
+ *   2. Coordination runs locally (this tab's peers run their own
+ *      phase-1 barrier)
+ *   3. The visible `value` returned by this hook is held at the
+ *      previous value until the barrier resolves, then flips
+ *
+ * Pass `channelKey: null` to disable coordination — the hook becomes
+ * a transparent pass-through of the underlying tuple.
+ */
+export function useCoordinated(underlying, options) {
+  const [underlyingValue, setUnderlyingValue] = underlying;
+  const {
+    channelKey,
+    peerId: explicitPeerId,
+    causesLayoutShift,
+    preload,
+    onCommit,
+    minWaitMs,
+    multiPeerExtraMinWaitMs,
+    lazyMinWaitMs,
+    gracePeriodMs,
+    ultimateTimeoutMs,
+    animateDuringPreload = false,
+    lazyCommitPriority = 'idle'
+  } = options;
+
+  // Stable peer id for the lifetime of the mounted component. Held in a ref so an
+  // auto-generated fallback stays stable across renders, an explicit `peerId` prop
+  // wins and resyncs on change, and an explicit id later removed keeps the last
+  // explicit value. The registration effect keys off [channelKey, peerId].
+  /* eslint-disable react-hooks/refs -- deliberate stable-id ref: lazy init + explicit-prop resync during render; the ref is identity memory, never read for rendering output */
+  const peerIdRef = React.useRef(null);
+  if (peerIdRef.current === null) {
+    peerIdRef.current = explicitPeerId ?? generatePeerId();
+  } else if (explicitPeerId !== undefined && explicitPeerId !== peerIdRef.current) {
+    peerIdRef.current = explicitPeerId;
+  }
+  const peerId = peerIdRef.current;
+  /* eslint-enable react-hooks/refs */
+
+  // The visible (committed) value. Lags `underlyingValue` while a
+  // phase-1 barrier is open in the receiver flow.
+  const [committedValue, setCommittedValue] = React.useState(underlyingValue);
+  // The latest target value (originator click or external change).
+  const [pendingValue, setPendingValue] = React.useState(underlyingValue);
+  const [isCoordinating, setIsCoordinating] = React.useState(false);
+  const [isWaitingForPeers, setIsWaitingForPeers] = React.useState(false);
+
+  // Keep latest callbacks in a ref so we don't re-register the peer
+  // when the consumer passes inline functions.
+  const callbacksRef = React.useRef({
+    causesLayoutShift,
+    preload,
+    onCommit,
+    setUnderlyingValue
+  });
+  /* eslint-disable react-hooks/refs -- latest-ref pattern: cache current callbacks for the once-registered peer and long-lived runCoordination closure; intentionally excluded from effect/useCallback deps to avoid re-registering on inline-function identity churn */
+  callbacksRef.current.causesLayoutShift = causesLayoutShift;
+  callbacksRef.current.preload = preload;
+  callbacksRef.current.onCommit = onCommit;
+  callbacksRef.current.setUnderlyingValue = setUnderlyingValue;
+  /* eslint-enable react-hooks/refs */
+
+  const timingRef = React.useRef({
+    minWaitMs,
+    multiPeerExtraMinWaitMs,
+    lazyMinWaitMs,
+    gracePeriodMs,
+    ultimateTimeoutMs,
+    animateDuringPreload,
+    lazyCommitPriority
+  });
+  /* eslint-disable react-hooks/refs -- latest-ref pattern: cache current timing options for the once-registered peer and long-lived runCoordination closure; intentionally excluded from effect/useCallback deps to avoid re-registering on option identity churn */
+  timingRef.current.minWaitMs = minWaitMs;
+  timingRef.current.multiPeerExtraMinWaitMs = multiPeerExtraMinWaitMs;
+  timingRef.current.lazyMinWaitMs = lazyMinWaitMs;
+  timingRef.current.gracePeriodMs = gracePeriodMs;
+  timingRef.current.ultimateTimeoutMs = ultimateTimeoutMs;
+  timingRef.current.animateDuringPreload = animateDuringPreload;
+  timingRef.current.lazyCommitPriority = lazyCommitPriority;
+  /* eslint-enable react-hooks/refs */
+
+  // In-flight handle so we can cancel/supersede.
+  const handleRef = React.useRef(null);
+  // Track the value we last asked the underlying primitive to take —
+  // when we see it echoed back via `underlyingValue` we skip the
+  // receiver flow so we don't double-coordinate our own writes.
+  const lastWrittenRef = React.useRef({
+    has: false
+  });
+  // The latest target the coordinator is working on; used to dedupe
+  // re-entrant effect runs when `underlyingValue` changes mid-flight.
+  const inFlightTargetRef = React.useRef({
+    has: false
+  });
+
+  // Forward-declared ref so the peer registration's `onSiblingAnnounce`
+  // can call the latest `runCoordination` without re-registering the
+  // peer every time the callback identity changes.
+  const runCoordinationRef = React.useRef(null);
+  // Register / unregister this peer with the channel.
+  React.useInsertionEffect(() => {
+    if (channelKey === null) {
+      return undefined;
+    }
+    const unregister = registerPeer(channelKey, peerId, target => {
+      runCoordinationRef.current?.(target, false);
+    });
+    reportValue(channelKey, peerId, committedValue);
+    return () => {
+      const handle = handleRef.current;
+      handleRef.current = null;
+      if (handle) {
+        handle.cancel();
+      }
+      inFlightTargetRef.current = {
+        has: false
+      };
+      unregister();
+    };
+  }, [channelKey, peerId]);
+
+  // Tell the coordinator our latest committed value so it can skip
+  // already-at-target peers when classifying barrier expectations.
+  React.useInsertionEffect(() => {
+    if (channelKey === null) {
+      return;
+    }
+    reportValue(channelKey, peerId, committedValue);
+  }, [channelKey, peerId, committedValue]);
+  const runCoordination = React.useCallback((target, isOriginator) => {
+    if (channelKey === null) {
+      // Keep `inFlightTargetRef` in sync so two synchronous calls
+      // like `setValue(p => p + 1); setValue(p => p + 1)` see the
+      // freshest base — `setPendingValue` is async, so the second
+      // updater would otherwise read the pre-render value and
+      // collapse to a single increment. The receiver-flow effect
+      // resets the ref on every external `underlyingValue` change,
+      // and `runCoordination` overwrites it on every subsequent
+      // call, so this won't leak across coordination cycles.
+      inFlightTargetRef.current = {
+        has: true,
+        value: target
+      };
+      setPendingValue(target);
+      setCommittedValue(target);
+      if (isOriginator) {
+        lastWrittenRef.current = {
+          has: true,
+          value: target
+        };
+        callbacksRef.current.setUnderlyingValue(target);
+      }
+      callbacksRef.current.onCommit?.(target, undefined);
+      return;
+    }
+    // Dedupe: if we're already coordinating exactly this target
+    // (e.g. a sibling-announce notification arrived after we
+    // already kicked off our own receiver-flow announce, our own
+    // originator-flow `announceTarget` call is still on the stack,
+    // or the user clicked the same value twice in quick
+    // succession), skip restarting the announcement. Without this
+    // the second call would cancel our in-flight handle and we'd
+    // lose our place in the barrier — or, when the dedupe also
+    // fires re-entrantly mid-announce, we'd recurse forever.
+    if (inFlightTargetRef.current.has && Object.is(inFlightTargetRef.current.value, target)) {
+      return;
+    }
+    // Supersede any in-flight announcement.
+    const previousHandle = handleRef.current;
+    if (previousHandle) {
+      previousHandle.cancel();
+    }
+    inFlightTargetRef.current = {
+      has: true,
+      value: target
+    };
+    // `pendingValue` is the user-facing "intent" signal and
+    // always flips synchronously so toolbars / pickers stay
+    // responsive on click. `isCoordinating` is what consumers
+    // typically gate an animation on — when
+    // `animateDuringPreload === false` we hold it until the
+    // originator's preload settles so a CPU-bound preload
+    // doesn't steal main-thread time from the animation that
+    // follows. The coordinator yields to the browser before
+    // invoking `preload`, so even sync preloads settle one
+    // macrotask later; receivers flip in the same tick
+    // regardless of the flag.
+    setPendingValue(target);
+    // Always clear stale waiting state from any previous
+    // coordination cycle synchronously — otherwise a later
+    // `onWaitingForPeers` (which fires from a timer relative to
+    // the announce) could be overwritten when we flip
+    // `isCoordinating`.
+    setIsWaitingForPeers(false);
+    const deferFlipForPreload = isOriginator && !timingRef.current.animateDuringPreload && callbacksRef.current.preload !== undefined;
+    let coordinatingFlipped = false;
+    const flipCoordinating = () => {
+      if (coordinatingFlipped) {
+        return;
+      }
+      coordinatingFlipped = true;
+      setIsCoordinating(true);
+    };
+    if (!deferFlipForPreload) {
+      flipCoordinating();
+    }
+    const userPreload = callbacksRef.current.preload;
+    const flipWrappedPreload = deferFlipForPreload ? (preloadTarget, signal) => {
+      // Wrap the user's preload so we flip `isCoordinating`
+      // the instant it settles — whether sync or async —
+      // but not before. Errors still flip; the engine logs
+      // them and treats the result as `undefined`, and the
+      // consumer expects the signal to converge regardless
+      // of the preload outcome.
+      let result;
+      let threw;
+      let didThrow = false;
+      try {
+        result = userPreload(preloadTarget, signal);
+      } catch (err) {
+        didThrow = true;
+        threw = err;
+      }
+      const isThenable = !didThrow && result !== null && result !== undefined && typeof result.then === 'function';
+      if (!isThenable) {
+        if (!signal.aborted) {
+          flipCoordinating();
+        }
+        if (didThrow) {
+          throw threw;
+        }
+        return result;
+      }
+      return result.then(value => {
+        if (!signal.aborted) {
+          flipCoordinating();
+        }
+        return value;
+      }, err => {
+        if (!signal.aborted) {
+          flipCoordinating();
+        }
+        throw err;
+      });
+    } : userPreload;
+
+    // Automatically hold the *commit* until the page's initial layout-shift
+    // sources have settled (see `layoutShiftGate`), for layout-shifting
+    // targets only. The consumer's preload still starts immediately and flips
+    // `isCoordinating` on its own settle — the gate wait runs in parallel and
+    // only delays the commit, so the first page-wide transform/variant change
+    // lands as one unified update. A no-op when nothing has registered with
+    // the gate (`whenLayoutShiftsSettled` returns `null`), so plain
+    // `useCoordinated` consumers are unaffected.
+    let wrappedPreload;
+    if (userPreload) {
+      wrappedPreload = (preloadTarget, signal) => {
+        const inner = flipWrappedPreload(preloadTarget, signal);
+        const gateWait = callbacksRef.current.causesLayoutShift(preloadTarget) ? whenLayoutShiftsSettled(signal) : null;
+        if (gateWait === null) {
+          return inner;
+        }
+        return Promise.all([gateWait, Promise.resolve(inner)]).then(([, result]) => result);
+      };
+    } else if (!layoutShiftsSettled() && callbacksRef.current.causesLayoutShift(target)) {
+      // No user preload, but the target shifts layout and the gate is still
+      // closed: synthesize a preload that only awaits the gate so the commit
+      // still holds until the page settles (the gate is otherwise consulted
+      // only inside the user-preload wrapper, so without this branch a
+      // layout-shifting peer with no preload would skip coordination entirely).
+      // Once the gate has opened
+      // this branch is skipped, so steady-state layout-shifting commits keep
+      // the synchronous fast path. The gate wait rejects `AbortError` on
+      // supersede, which propagates into the engine's `await preload(...)`
+      // and is swallowed there because the signal is aborted — exactly like
+      // the user-preload path above.
+      wrappedPreload = (preloadTarget, signal) => {
+        const gateWait = callbacksRef.current.causesLayoutShift(preloadTarget) ? whenLayoutShiftsSettled(signal) : null;
+        if (gateWait === null) {
+          return undefined;
+        }
+        return gateWait.then(() => undefined);
+      };
+    }
+    const handle = announceTarget(channelKey, peerId, target, {
+      causesLayoutShift: callbacksRef.current.causesLayoutShift,
+      preload: wrappedPreload,
+      onCommit: (committedTarget, preloaded) => {
+        // Side-effect first so consumers can install precomputed
+        // payloads before the value flip becomes visible.
+        callbacksRef.current.onCommit?.(committedTarget, preloaded);
+        // If the engine force-resolved the barrier while our
+        // deferred preload was still in flight (e.g. at
+        // `ultimateTimeoutMs`), `flipCoordinating` may not have
+        // run — flush it now so `isCoordinating` reaches the
+        // true → false transition consumers expect at least
+        // once per cycle.
+        flipCoordinating();
+        if (isOriginator) {
+          lastWrittenRef.current = {
+            has: true,
+            value: committedTarget
+          };
+          callbacksRef.current.setUnderlyingValue(committedTarget);
+        }
+        setCommittedValue(committedTarget);
+        // Clear coordination flags synchronously alongside the
+        // value flip so the next render reflects both at once.
+        setIsCoordinating(false);
+        setIsWaitingForPeers(false);
+      },
+      minWaitMs: timingRef.current.minWaitMs,
+      multiPeerExtraMinWaitMs: timingRef.current.multiPeerExtraMinWaitMs,
+      lazyMinWaitMs: timingRef.current.lazyMinWaitMs,
+      gracePeriodMs: timingRef.current.gracePeriodMs,
+      ultimateTimeoutMs: timingRef.current.ultimateTimeoutMs,
+      lazyCommitPriority: timingRef.current.lazyCommitPriority,
+      onWaitingForPeers: () => {
+        setIsWaitingForPeers(true);
+      },
+      isOriginator,
+      // Non-originators (e.g. storage echoes) anchor to the
+      // originator's announce time if a barrier is already open
+      // so late joiners share the same wall-clock deadline.
+      announceTime: !isOriginator && getBarrierAnnounceTime(channelKey, target) || Date.now()
+    });
+    handleRef.current = handle;
+    handle.settled.then(() => {
+      if (handleRef.current === handle) {
+        handleRef.current = null;
+        inFlightTargetRef.current = {
+          has: false
+        };
+        setIsCoordinating(false);
+        setIsWaitingForPeers(false);
+      }
+    });
+  }, [channelKey, peerId]);
+
+  // Keep the ref pointed at the latest `runCoordination` so the
+  // peer-registration callback (set once at mount) always invokes
+  // the current closure.
+  // eslint-disable-next-line react-hooks/refs -- forward-declared latest-ref: the once-registered peer callback must invoke the current runCoordination closure without re-registering
+  runCoordinationRef.current = runCoordination;
+
+  // Receiver flow: external `underlyingValue` change that we did not
+  // originate. Trigger a local coordination so this tab's peers commit
+  // together. Uses `useLayoutEffect` so the announcement lands in the
+  // same synchronous flush as the originator's broadcast — otherwise
+  // a sibling peer's `runCoordination` would slip past whatever
+  // `setTimeout` cadence the test (or browser) is driving and miss
+  // the originator's barrier window.
+  React.useLayoutEffect(() => {
+    if (channelKey === null) {
+      // Coordination disabled: the hook is a transparent pass-through,
+      // so the visible value / pending value are derived directly from
+      // `underlyingValue` at the return rather than mirrored into state.
+      // Only reset the in-flight ref here.
+      inFlightTargetRef.current = {
+        has: false
+      };
+      return;
+    }
+    if (lastWrittenRef.current.has) {
+      if (Object.is(lastWrittenRef.current.value, underlyingValue)) {
+        // Echo of our own write — already coordinated. Treat the
+        // sentinel as one-shot: consume it here so a *subsequent*
+        // external write that happens to round-trip to the same
+        // value (e.g. local→`b`, external→`c`, external→`b`) is
+        // recognized as a genuine external change rather than
+        // misclassified as another echo.
+        lastWrittenRef.current = {
+          has: false
+        };
+        return;
+      }
+      // Sentinel is stale: the underlying moved to something other
+      // than what we last wrote, so an earlier no-op originator
+      // write (which produced no echo) must have left the sentinel
+      // armed. Clear it now so a later external round-trip back to
+      // that value isn't suppressed.
+      lastWrittenRef.current = {
+        has: false
+      };
+    }
+    if (handleRef.current && inFlightTargetRef.current.has && Object.is(inFlightTargetRef.current.value, underlyingValue) && Object.is(pendingValue, underlyingValue)) {
+      // Already coordinating this target.
+      return;
+    }
+    if (Object.is(committedValue, underlyingValue)) {
+      // No external change to react to. We deliberately skip running
+      // `preload` on mount when the underlying value already matches
+      // our committed value: preload only needs to run when the value
+      // changes out from under us without the consumer calling the
+      // setter (e.g. a hydration write from `localStorage` or a
+      // parent state update). After the consumer interacts with the
+      // setter, the originator flow drives every cycle.
+      return;
+    }
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- receiver flow: runCoordination drives the coordination state machine in response to an external underlyingValue change; this is the genuine effect side-effect, not derivable during render
+    runCoordination(underlyingValue, false);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [channelKey, underlyingValue, runCoordination]);
+  const coordinatedSetValue = React.useCallback(action => {
+    // Functional updaters need to see the latest target — even
+    // before React has re-rendered with the new `pendingValue` —
+    // so that bursts like `setValue(p => p + 1); setValue(p => p +
+    // 1)` compose to +2 instead of +1. `inFlightTargetRef` is
+    // updated synchronously inside `runCoordination` before
+    // `announceTarget` runs, so it's the freshest source.
+    const base = inFlightTargetRef.current.has ? inFlightTargetRef.current.value : pendingValue;
+    const next = typeof action === 'function' ? action(base) : action;
+    runCoordination(next, true);
+  }, [pendingValue, runCoordination]);
+  const extras = React.useMemo(() => ({
+    pendingValue,
+    isCoordinating,
+    isWaitingForPeers
+  }), [pendingValue, isCoordinating, isWaitingForPeers]);
+
+  // When coordination is disabled the hook is a transparent
+  // pass-through: derive the visible value, pending value, and inert
+  // coordination flags straight from `underlyingValue` rather than
+  // mirroring it into `committedValue` / `pendingValue` state.
+  if (channelKey === null) {
+    return [underlyingValue, coordinatedSetValue, {
+      pendingValue: underlyingValue,
+      isCoordinating: false,
+      isWaitingForPeers: false
+    }];
+  }
+  return [committedValue, coordinatedSetValue, extras];
+}

package/useCoordinated/useCoordinatedLazy.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Declares the calling component as a source of an initial, post-hydration
+ * layout shift — e.g. a code block that swaps from its plain fallback to
+ * highlighted (and focus-collapsed) output once it hydrates.
+ *
+ * While any registered source is unsettled, {@link useCoordinated} holds its
+ * layout-shifting commits, so a page-wide transform/variant change lands as a
+ * single unified update instead of a cascade as blocks swap in at staggered
+ * idle times. The host doesn't wire anything into its coordinated hooks — this
+ * registration is the only opt-in.
+ *
+ * Pass `settled: true` once the component has reached its stable
+ * post-hydration layout. Registration happens on mount and is released on
+ * unmount, so a component that unmounts before it settles can't hold the gate
+ * open for the rest of the page.
+ */
+export declare function useCoordinatedLazy(settled: boolean): void;