Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
66.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file ChatVirtualizer.tsx
 * @input Uses React, Core's scrollable-area hook, finger-scroll watch and
 *   scroll-anchoring writer; attaches to a caller-owned scroll container
 *   that runs no follow of its own, or renders its own
 * @output Exports ChatVirtualizer component, ChatVirtualizerProps and
 *   ChatVirtualizerHandle
 * @position Experimental windowing participant for ChatMessageList children:
 *   keeps thousands-of-messages transcripts at a bounded DOM size while
 *   owning follow-at-end and read-position stability
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/Chat/index.ts (exports)
 */

import * as React from 'react';
import * as stylex from '@stylexjs/stylex';
import {useScrollableArea} from '@astryxdesign/core/hooks';
import {observeResize} from '@astryxdesign/core/utils';
import {useTranslator} from '@astryxdesign/core/i18n';
import {setScrollAnchoringOff} from '@astryxdesign/core/internal/scroll-anchoring';
import {useFingerScroll} from '@astryxdesign/core/internal/touch';

// "Did the declarative target land?" — a convergence tolerance, deliberately
// NOT the same knob as `endThreshold` (which is a user-intent question).
const CONVERGE_EPSILON_PX = 4;

const GLOBAL_BUCKET = '\u0000global';
// Prior strength for shrinkage in effectiveAvg: at this many real samples
// the bucket's own data and the inherited baseline carry equal weight.
const PRIOR_SAMPLES = 5;

// The block that holds the spacers and the windowed rows, in both modes.
// Its `min-height` is the scroll extent's FLOOR and is written imperatively
// (writeSpacers), never through this object, so React's style diffing
// cannot touch it. React applies a parent's own style only after every
// child mutation of the commit, and this component writes the floor only in
// its own layout effect — after its children's — so from the first row
// removal until the pass re-derives the geometry, the floor is the previous
// extent. The extent then cannot collapse under a forced layout in that
// window (a row's layout cleanup, a ref callback, a child's layout effect),
// and the browser has nothing to clamp scrollTop against.
//
// flow-root keeps row margins inside the block, as the own scroller did
// before this block existed. flexShrink: 0 / alignSelf: stretch — in a
// column-flex host scroller (attach mode) the block is a
// flex item and would otherwise be compressed to fit (default shrink 1),
// silently corrupting the whole geometry.
const styles = stylex.create({
  content: {
    display: 'flow-root',
    flexShrink: 0,
    alignSelf: 'stretch',
  },
  // The own scroller positions nothing itself; `relative` keeps a row's
  // absolutely positioned parts inside it.
  scroller: {
    position: 'relative',
  },
});

// While a finger scroll ends in an elastic overscroll, a write would snap the
// bounce onto the clamp; the flush waits a frame at a time until it is over.
const isBouncing = (vp: ViewportRead): boolean =>
  vp.scrollTop < 0 ||
  vp.scrollTop > Math.max(0, vp.scrollHeight - vp.clientHeight) + 1;

/**
 * The scroller's position and size, read together in one batch. A scroll
 * event reads these once and writes nothing. A correction pass reads them
 * once, after its first spacer write, and forces at most two layouts.
 */
type ViewportRead = {
  scrollTop: number;
  scrollHeight: number;
  clientHeight: number;
};
const readViewport = (el: HTMLElement): ViewportRead => ({
  scrollTop: el.scrollTop,
  scrollHeight: el.scrollHeight,
  clientHeight: el.clientHeight,
});

/** Imperative surface — both methods are declarations, not scroll actions. */
export interface ChatVirtualizerHandle {
  /** Declare "be N px above the bottom edge" (0 = follow-at-end). */
  scrollToDistanceFromBottomPx: (px?: number) => void;
  /**
   * Hold one row at a fixed viewport offset (0 = its top edge at the
   * viewport top — the "pin the new prompt to the top" pattern). Same
   * declaration semantics; the reference frame becomes a row identity
   * instead of the bottom edge, so rows resizing above it are absorbed.
   * The position clamps to the scrollable range, and the key must exist in
   * the CURRENT data: a missing key falls back to follow-at-end on the next
   * pass, so declare after the data commit, not ahead of it.
   */
  anchorToKey: (key: string, viewportOffset?: number) => void;
}

export interface ChatVirtualizerProps<T> {
  /** Row data. Changes are detected by REFERENCE — replace, don't mutate. */
  data: readonly T[];
  /**
   * Stable string identity per row (coerced with String() internally).
   * Never derive keys from indices: the size cache and the running size
   * averages are keyed by identity.
   */
  getRowKey: (item: T, index: number) => string;
  renderItem: (info: {item: T; index: number}) => React.ReactNode;
  /**
   * Static estimate (px) for unmeasured rows, or a function — a function is
   * authoritative and never overridden by the running averages.
   *
   * Bias it LOW. The two directions are not symmetric: an estimate that is too
   * small makes content grow as it measures, which extends the scroll range
   * below you and leaves your position valid; one that is too large makes it
   * shrink, and the browser then clamps scrollTop into a range that just got
   * smaller — a position loss nothing can undo. The default errs small on
   * purpose, and raising it past typical row height is the one setting that
   * can make a drag look broken.
   *
   * Pass a stable function: a new one each render reprices every row.
   */
  estimatedItemSize?: number | ((item: T, index: number) => number);
  /** Imperative declarations (see ChatVirtualizerHandle). */
  handleRef?: React.Ref<ChatVirtualizerHandle>;
  /**
   * Optional item classifier: measured sizes feed a running average PER
   * TYPE, so a corpus mixing tool-call stubs with long markdown converges
   * to honest per-shape prices instead of one blended number.
   *
   * Pass a stable function: a new one each render reprices every row.
   */
  getItemType?: (item: T, index: number) => string;
  /**
   * ATTACH MODE. By default the list renders its own scroll container. Pass
   * the caller's scroll element instead — a scroller that runs no follow of
   * its own, such as a page shell's content area — and it renders one
   * content block (spacers + windowed rows) into the container the caller
   * already owns: the layout component keeps the scroller, the virtualizer
   * is one participant in it. Not ChatLayout's: ChatLayout runs its own
   * follow on that element with no way to turn it off, so attaching there
   * puts two writers on one position. It cannot host attach mode until it
   * exposes a seam to disable that follow.
   *
   * Pass the ELEMENT, not a ref: a parent's ref attaches after its
   * children's layout effects, so a ref would still read null on the commit
   * that matters, while state holding the element re-renders with it
   * available. Pass null (not undefined) while the
   * element is pending: absent = own-container mode, null = attach mode
   * waiting — falling back to the own container for even one commit mounts
   * EVERY row (unbounded clientHeight) and tears it back down (measured:
   * 10s boot at 2000 messages).
   *
   * CONTRACT: row spacing must live INSIDE the rows (padding), never as
   * flex `gap` or margins on the container — offsetHeight cannot see
   * either, so the geometry would drift by one gap per row. Nest inside
   * ChatMessageList with gap=0.
   */
  scrollElement?: HTMLElement | null;
  /**
   * How close to the bottom (px) a user scroll must land to re-engage
   * follow-at-end. This is the RE-ENGAGE condition only — disengaging is
   * upward movement past it. Default 24 matches the value shipped by a
   * production chat transcript; TanStack Virtual's chat mode uses 1px and
   * Legend List 10% of the viewport, so the useful range is wide. Too tight
   * and a user who stops "visually at the bottom" (trackpad inertia,
   * fractional row heights, page zoom) silently stops following while
   * output grows below them.
   */
  endThreshold?: number;
  overscanTop?: number;
  overscanBottom?: number;
  /**
   * Own-container mode only: the accessible name of the scroll container,
   * which keyboard users can focus and scroll. Defaults to the translated
   * "Messages".
   */
  label?: string;
  /** Own-container mode only. */
  style?: React.CSSProperties;
  /** Own-container mode only. */
  className?: string;
}

type AnchorMode = {kind: 'anchor'; key: string; viewportOffset: number};

type Mode = {kind: 'end'; distance: number} | AnchorMode;

type Win = {start: number; end: number};

type Geo = {
  offsets: number[];
  total: number;
  keys: string[];
  index: Map<string, number>;
};

type Bucket = {sum: number; count: number; eff: number};

export function ChatVirtualizer<T>(
  props: ChatVirtualizerProps<T>,
): React.ReactNode {
  const {
    data,
    getRowKey,
    renderItem,
    estimatedItemSize = 120,
    handleRef,
    getItemType,
    scrollElement,
    endThreshold = 24,
    overscanTop = 1600,
    overscanBottom = 600,
    label,
    style,
    className,
  } = props;
  const t = useTranslator();
  // Own-container mode: keyboard users reach and scroll the scroller, a
  // `group` named by this list. It is always a scroll container, so the
  // machinery's scrollTop writes land before the content first overflows.
  const {getViewportProps, getContentProps} = useScrollableArea({
    axis: 'block',
    stickyContainment: 'always',
    keyboardAccess: {
      owner: 'viewport',
      label: label ?? t('@astryx.chatVirtualizer.label'),
    },
  });

  const ownScrollerRef = React.useRef<HTMLDivElement | null>(null);
  const attachMode = scrollElement !== undefined;
  // CLOSURE DISCIPLINE (canonical statement): the machinery is plain
  // render-scope functions, so same-commit callers always see live props;
  // everything created ONCE and outliving renders — the ResizeObserver
  // callback, the imperative handle, the rAF retry — must go through a
  // live ref (syncRef and the prop mirrors below) instead of its birth
  // closure. A violation froze attach mode for a memoized consumer on the
  // first render's null scroller (geometry stuck on estimates forever).
  const scrollElementRef = React.useRef(scrollElement);
  scrollElementRef.current = scrollElement;
  const overscanTopRef = React.useRef(overscanTop);
  overscanTopRef.current = overscanTop;
  const overscanBottomRef = React.useRef(overscanBottom);
  overscanBottomRef.current = overscanBottom;
  // Single accessor so every pass reads the live element in either mode.
  // In attach mode a pending (null) element makes every pass bail rather
  // than falling back to the own container.
  const getScroller = (): HTMLElement | null =>
    scrollElementRef.current !== undefined
      ? scrollElementRef.current
      : ownScrollerRef.current;
  // The live scroller as a ref, for Core's finger-scroll watch, which reads
  // it after each commit and moves to a replaced element.
  const liveScrollerRef = React.useRef<React.RefObject<HTMLElement | null>>({
    get current(): HTMLElement | null {
      return scrollElementRef.current !== undefined
        ? scrollElementRef.current
        : ownScrollerRef.current;
    },
  }).current;
  const contentRef = React.useRef<HTMLDivElement | null>(null);
  const spacerTopRef = React.useRef<HTMLDivElement | null>(null);
  const spacerBottomRef = React.useRef<HTMLDivElement | null>(null);
  // While a focused row sits outside the window it stays mounted (a keyboard
  // user's focus must not fall to the page), with a gap spacer between it and
  // the window so the geometry is unchanged.
  const gapTopRef = React.useRef<HTMLDivElement | null>(null);
  const gapBottomRef = React.useRef<HTMLDivElement | null>(null);
  const [focusedKey, setFocusedKey] = React.useState<string | null>(null);
  // The focused row this render keeps outside the window, read by the passes.
  const pinnedKeyRef = React.useRef<string | null>(null);
  // Rows a commit mounts that are not new messages (the window moving over
  // history, or history loading above) must not reach the transcript's
  // polite log as news: the content block is marked busy for that commit
  // and the next frame. A message appended at the tail mounts unmarked.
  const renderedKeysRef = React.useRef<ReadonlySet<string>>(new Set());
  // The messages the last data change appended at the tail that have not
  // mounted yet: the only rows that mount as news.
  const newsKeysRef = React.useRef(new Set<string>());
  // The first row of the arrived tail run this render mounts (see
  // `arrival`), for the spacers.
  const tailKeyRef = React.useRef<string | null>(null);
  // The commit the last correction pass ran for, so a commit that changes
  // nothing the pass reads skips it.
  const passedRenderRef = React.useRef<{
    keys: string;
    scroller: HTMLElement | null;
    sizing: readonly unknown[];
  } | null>(null);
  const pendingRenderKeysRef = React.useRef('');
  const gapTailRef = React.useRef<HTMLDivElement | null>(null);
  // This render's rows, and whether they mount history, for its commit.
  const pendingRenderedRef = React.useRef<ReadonlySet<string>>(new Set());
  const pendingBusyRef = React.useRef(false);
  const busyClearRef = React.useRef<number | null>(null);
  const rowEls = React.useRef(new Map<string, HTMLDivElement>());
  const sizes = React.useRef(new Map<string, number>());
  const geo = React.useRef<Geo>({
    offsets: [],
    total: 0,
    keys: [],
    index: new Map(),
  });
  const mode = React.useRef<Mode>({kind: 'end', distance: 0});
  // Echo-matching instead of a time window: we record the exact value we
  // wrote; a scroll event only counts as "ours" if scrollTop matches it.
  // A time gate would swallow real user scrolls arriving within the window,
  // leaving a stale anchor that the next restore then fights (double-writer).
  const progTarget = React.useRef<number | null>(null);
  // Which regime scrollTop is in: USER-DRIVEN (a non-echo scroll event was
  // the latest movement — the live-anchor refresh may re-derive identity
  // from scrollTop every pass, covering the events-lag-rAF staleness) or
  // MACHINE-DRIVEN (a declaration was issued and the user has not scrolled
  // since — the stored identity is the truth and refresh must hold off).
  // A regime, not a one-shot: at high scroll speeds several correction
  // passes run between two scroll events, and clearing per pass re-created
  // the staleness class mid-gesture (measured: 5.2% jitter at 60px steps).
  const userScrolledRef = React.useRef(false);
  // Last scrollTop observed by a scroll event, and the px the user has moved
  // away from where the machinery last placed them — the end→anchor decision
  // runs on the latter (see onScroll).
  const lastEventST = React.useRef<number | null>(null);
  const lastUserEventT = React.useRef(0);
  const userAway = React.useRef(0);
  const geoChanged = React.useRef(false);
  const rafRetry = React.useRef<number | null>(null);
  const prevScrollerRef = React.useRef<HTMLElement | null>(null);
  // ---- Touch write-gate --------------------------------------------------
  // While a finger scrolls the viewport (from its first scroll until that
  // scroll ends, momentum included, as Core's finger-scroll watch reports)
  // the machinery writes no scrollTop at all: near the bottom, per-event
  // restores erase a slow drag's displacement faster than it accumulates,
  // and a write during momentum cancels the fling. Nothing is queued as a
  // ledger — the reference frame is declarative, so the flush is one
  // ordinary syncAndRestore from the re-stated mode, when the finger's
  // scroll ends.
  const gestureActive = React.useRef(false);
  // The flush's retry while the scroll ends in an elastic overscroll.
  const flushRetry = React.useRef<number | null>(null);
  // Did the USER move the viewport this gesture? Only non-echo scrolls count.
  // Kept apart from the clock above because a browser clamp (a spacer shrink
  // near the bottom) is movement for settling purposes but is NOT intent:
  // treating it as such let a plain tap mid-stream re-judge follow against a
  // distance the stream itself had grown, and silently disengage.
  const gestureMoved = React.useRef(false);
  const gestureHeld = (): boolean => gestureActive.current;
  // Spacer-side compensation while the gate holds. Rows measuring in during a
  // drag land their (real - estimate) deltas in the geometry, and with
  // scrollTop untouchable the content would crawl under the finger. Document
  // flow gives a second knob a transform-positioned virtualizer lacks: the TOP
  // SPACER absorbs the delta instead — each pass re-anchors the row at the
  // viewport top across the recompute and rolls the difference in here, so
  // on-screen positions stay invariant with zero scrollTop writes. The flush
  // folds it into the adopted anchor and zeroes it in the same atomic pass.
  const gestureAdj = React.useRef(0);
  // Convergence protection (generalized from a one-shot landing flag):
  // whenever a declarative target is set (mount landing, or any imperative
  // scrollTo*), the list is "converging" — scroll events may not flip the
  // mode (bootstrap writes and transient clamps would otherwise read as
  // user scrolls and hijack the target mid-flight), and every pass keeps
  // retrying until the target is reached. Only INTENT signals (wheel/touch,
  // not scroll effects — those mix in our own writes) break it early.
  const converging = React.useRef(true);
  // Prices hold still while a declared target is in flight: the destination is
  // an offset in the geometry, and repricing mid-flight moves it out from under
  // the target. The release gets a rAF pass of its own, so whatever the
  // averages then owe is derived from a settled geometry rather than appended
  // to the pass that just landed. (LegendList snapshots the averages for the
  // duration of a programmatic scroll; virtua reprices once and returns the
  // displacement for the caller to apply as a jump. The invariant all of them
  // hold is that a price move and its position correction are one step.)
  const priceFreeze = React.useRef(true);
  const rafRelease = React.useRef<number | null>(null);
  const [win, setWin] = React.useState<Win>({start: 0, end: -1});
  const winRef = React.useRef(win);
  winRef.current = win;
  const dataRef = React.useRef(data);
  dataRef.current = data;
  const endThresholdRef = React.useRef(endThreshold);
  endThresholdRef.current = endThreshold;

  // Running average of everything measured so far. A static estimate that
  // undershoots makes the bottom RECEDE while scrolling toward it: each cold
  // row that mounts adds (real - est) px of newly discovered distance, faster
  // than a mouse wheel can close it. Once samples exist they price unmeasured
  // rows, so mounting a cold row discovers ~nothing. An estimatedItemSize
  // FUNCTION is authoritative and never overridden — the consumer knows more
  // than an average does. Averages accumulate per item type when getItemType
  // is given, plus a global cold-start bucket, but the EFFECTIVE price is
  // gated: hysteresis, never while converging, only in scroll-quiet, and every
  // move marks the geometry dirty (see effectiveAvg).
  const bucketsRef = React.useRef(new Map<string, Bucket>());
  const typeByKey = React.useRef(new Map<string, string>());
  const bucket = (t: string): Bucket => {
    let b = bucketsRef.current.get(t);
    if (!b) {
      bucketsRef.current.set(t, (b = {sum: 0, count: 0, eff: 0}));
    }
    return b;
  };
  const noteMeasured = (
    key: string,
    prev: number | undefined,
    px: number,
  ): void => {
    for (const t of [GLOBAL_BUCKET, typeByKey.current.get(key)]) {
      if (t === undefined) {
        continue;
      }
      const b = bucket(t);
      if (prev === undefined) {
        b.sum += px;
        b.count += 1;
      } else {
        b.sum += px - prev;
      }
    }
  };
  // A bucket's effective price INITIALIZES from the inherited baseline (the
  // global average, or the static estimate), so a type first encountered
  // mid-scroll is not a cliff — zero-initialized buckets made the first
  // per-type pricing a mass repricing event.
  // READ ONLY. Whether a price MOVES is decided once per pass, in
  // repriceBuckets — never here, which runs per row.
  const effectiveAvg = (t: string, baseline: number): number => {
    const b = bucketsRef.current.get(t);
    return !b || b.count === 0 || b.eff === 0 ? baseline : b.eff;
  };

  // Decide repricing once per pass, before the rebuild. A clock gate inside
  // the row loop can reprice part of the list.
  const repriceBuckets = (): void => {
    if (typeof estimatedItemSize === 'function') {
      return; // a function estimate is authoritative — nothing to reprice
    }
    if (converging.current || priceFreeze.current) {
      return;
    }
    // Sampled ONCE per pass, and only while scrolling is QUIET: a repricing
    // event moves every unmeasured offset at once, so landing it mid-scroll
    // costs a frame of up-to-step-size deviation. A quarter second of silence
    // defers the same correction into frames nobody is watching. (Streams
    // reprice freely — machinery echoes are not user events.)
    const quiet = performance.now() - lastUserEventT.current > 250;
    // Shrinkage toward the inherited baseline: the baseline counts as
    // PRIOR_SAMPLES virtual samples, so a young bucket's mean is mostly
    // baseline and the data takes over smoothly as samples accumulate.
    const settle = (b: Bucket | undefined, baseline: number): number => {
      if (!b || b.count === 0) {
        return baseline;
      }
      const raw =
        (b.sum + PRIOR_SAMPLES * baseline) / (b.count + PRIOR_SAMPLES);
      if (b.eff === 0) {
        b.eff = baseline > 0 ? baseline : raw;
      }
      if (quiet && Math.abs(raw - b.eff) > b.eff * 0.1) {
        b.eff = raw;
        geoChanged.current = true;
      }
      return b.eff;
    };
    // Global first: it is the baseline every type bucket shrinks toward, so it
    // has to settle before they read it.
    const global = settle(
      bucketsRef.current.get(GLOBAL_BUCKET),
      estimatedItemSize,
    );
    if (getItemType) {
      for (const [t, b] of bucketsRef.current) {
        if (t !== GLOBAL_BUCKET) {
          settle(b, global);
        }
      }
    }
  };
  const estOf = (item: T, i: number): number => {
    if (typeof estimatedItemSize === 'function') {
      return estimatedItemSize(item, i);
    }
    const global = effectiveAvg(GLOBAL_BUCKET, estimatedItemSize);
    return getItemType ? effectiveAvg(getItemType(item, i), global) : global;
  };

  const recompute = (): void => {
    const d = dataRef.current;
    const offsets = new Array<number>(d.length);
    const keys = new Array<string>(d.length);
    let y = 0;
    const index = new Map<string, number>();
    for (let i = 0; i < d.length; i++) {
      // String coercion is part of the key contract: the RO pipeline reads
      // keys back from dataset.pkey (always a string), so a number key would
      // split the size cache in two — the RO copy under the string, the sync
      // copy under the number — and every RO re-measure would feed the
      // averages as a fresh sample. Coercing at both derivation points keeps
      // every internal map keyed consistently.
      keys[i] = String(getRowKey(d[i], i));
      index.set(keys[i], i);
      offsets[i] = y;
      y += sizes.current.get(keys[i]) ?? estOf(d[i], i);
    }
    geo.current = {offsets, total: y, keys, index};
  };

  // index of the last row whose offset <= y
  const indexAt = (y: number): number => {
    const {offsets} = geo.current;
    let lo = 0;
    let hi = offsets.length - 1;
    while (lo < hi) {
      const mid = (lo + hi + 1) >> 1;
      if (offsets[mid] <= y) {
        lo = mid;
      } else {
        hi = mid - 1;
      }
    }
    return lo;
  };

  const computeWindow = (vp: ViewportRead, desiredTop?: number): Win => {
    const g = geo.current;
    if (g.keys.length === 0) {
      return {start: 0, end: -1};
    }
    const top = (desiredTop ?? vp.scrollTop) - paintOrigin();
    const start = indexAt(Math.max(0, top - overscanTopRef.current));
    const bottomEdge = top + vp.clientHeight + overscanBottomRef.current;
    // When the query reaches past the content, include the last row by
    // construction instead of by binary search: a zero-height final row sits
    // AT total, which the search (offsets[i] <= total - 1) can never select.
    const end = bottomEdge >= g.total ? g.keys.length - 1 : indexAt(bottomEdge);
    return {start, end};
  };

  const setWindowIfChanged = (next: Win): void => {
    const cur = winRef.current;
    if (next.start !== cur.start || next.end !== cur.end) {
      geoChanged.current = true;
      setWin(next);
    }
  };

  // Size both spacers so the mounted window occupies its true place in the
  // scroll range, under whatever geometry is current, and move the content
  // block's floor (styles.content) to the extent that geometry describes.
  const writeSpacers = (w: Win): void => {
    const g = geo.current;
    const empty = w.end < w.start || g.offsets.length === 0;
    const offsetAfter = (i: number): number =>
      i + 1 < g.offsets.length ? g.offsets[i + 1] : g.total;
    const pinnedKey = pinnedKeyRef.current;
    const pinned =
      empty || pinnedKey === null ? undefined : g.index.get(pinnedKey);
    const pinnedAbove = pinned !== undefined && pinned < w.start;
    const pinnedBelow = pinned !== undefined && pinned > w.end;
    // The arrived tail run: from its first row to the last row.
    const tailKey = tailKeyRef.current;
    const tailIndex =
      empty || tailKey === null ? undefined : g.index.get(tailKey);
    const tail =
      tailIndex !== undefined && tailIndex > w.end ? tailIndex : undefined;
    const first = pinnedAbove ? pinned : w.start;
    const last =
      tail !== undefined ? g.keys.length - 1 : pinnedBelow ? pinned : w.end;
    // gestureAdj shifts the whole rendered block without touching scrollTop
    // (0 outside a touch gesture). Clamped at the very top of the list —
    // there is no spacer left to absorb into there.
    const top = empty ? 0 : Math.max(0, g.offsets[first] + gestureAdj.current);
    const belowEnd = empty ? 0 : offsetAfter(last);
    const write = (
      ref: React.RefObject<HTMLDivElement | null>,
      prop: 'height' | 'minHeight',
      px: number,
    ): void => {
      if (ref.current) {
        ref.current.style[prop] = `${px}px`;
      }
    };
    write(spacerTopRef, 'height', top);
    write(
      gapTopRef,
      'height',
      pinnedAbove ? Math.max(0, g.offsets[w.start] - offsetAfter(pinned)) : 0,
    );
    write(
      gapBottomRef,
      'height',
      pinnedBelow
        ? Math.max(0, g.offsets[pinned] - offsetAfter(w.end))
        : tail !== undefined
          ? Math.max(0, g.offsets[tail] - offsetAfter(w.end))
          : 0,
    );
    write(
      gapTailRef,
      'height',
      pinnedBelow && tail !== undefined
        ? Math.max(0, g.offsets[tail] - offsetAfter(pinned))
        : 0,
    );
    write(spacerBottomRef, 'height', Math.max(0, g.total - belowEnd));
    // The extent these spacers describe: the model total, plus whatever the
    // top spacer carries beyond its model offset (the gesture adjustment,
    // after the clamp at the very top).
    write(
      contentRef,
      'minHeight',
      empty ? g.total : g.total + top - g.offsets[first],
    );
  };

  // Where a row identity + viewport offset puts scrollTop under the current
  // geometry, and the reverse: the anchor for whatever is at a scroll offset.
  const anchorAt = (scrollTop: number): Mode => {
    const g = geo.current;
    const y = scrollTop - paintOrigin();
    const idx = indexAt(y);
    return {
      kind: 'anchor',
      key: g.keys[idx],
      viewportOffset: g.offsets[idx] - y,
    };
  };

  // The same reference frame, MEASURED instead of derived. anchorAt's
  // `offsets[idx] - y` IS the anchored row's painted top, but only while
  // painted == model + gestureAdj holds — and the top spacer clamps at 0 when
  // there is nothing above to absorb into, leaving every derived position
  // wrong by the difference. Reading the row's real rect skips the broken map.
  // Same row anchorAt would pick; null when nothing is rendered.
  const anchorFromPaint = (el: HTMLElement, h: number): AnchorMode | null => {
    const g = geo.current;
    const box = el.getBoundingClientRect();
    let best: AnchorMode | null = null;
    for (const [key, rowEl] of rowEls.current) {
      if (!rowEl.isConnected || !g.index.has(key)) {
        continue;
      }
      const r = rowEl.getBoundingClientRect();
      const top = r.top - box.top;
      if (r.bottom - box.top <= 0 || top >= h) {
        continue;
      }
      if (best === null || top < best.viewportOffset) {
        best = {kind: 'anchor', key, viewportOffset: top};
      }
    }
    return best;
  };

  // Scroll offset at which our content starts. Zero when we own the scroller;
  // in attach mode the caller's container can put padding, a header or a
  // sticky region above us, and every offset in `geo` is relative to our first
  // spacer rather than to the scroll box.
  const originRef = React.useRef(0);
  // Content the caller renders BELOW our block (a docked composer's
  // overflow, say: a scroller that deliberately overflows by the composer
  // height so the tail can scroll clear of it). End mode must scroll past
  // it, or the last message parks underneath the overlay (measured:
  // constant 174px).
  const belowRef = React.useRef(0);
  const measureOrigin = (el: HTMLElement, vp: ViewportRead): number => {
    if (scrollElementRef.current == null) {
      // Own container: the content starts at the scroll box and nothing
      // follows it. Stated rather than skipped — a list switched back from
      // attach mode would otherwise keep the host's header and dock offsets
      // and aim every target past the end of its own scroller.
      originRef.current = 0;
      belowRef.current = 0;
      return 0;
    }
    const top = spacerTopRef.current;
    if (!top) {
      return originRef.current;
    }
    originRef.current =
      top.getBoundingClientRect().top -
      el.getBoundingClientRect().top +
      vp.scrollTop;
    belowRef.current = Math.max(
      0,
      vp.scrollHeight - originRef.current - geo.current.total,
    );
    return originRef.current;
  };
  // Where the model's zero sits ON SCREEN. Identical to the origin except
  // while the touch write-gate holds, when the top spacer carries an extra
  // offset (gestureAdj) that shifts every painted position. Converting
  // through this one function keeps painted space and model space from ever
  // being mixed: anchors read scrollTop through it, targets write back
  // through it.
  const paintOrigin = (): number => originRef.current + gestureAdj.current;

  // Desired scrollTop for a reference frame, clamped to the scrollable range.
  // null when the anchored row no longer exists in the data.
  const targetFor = (m: Mode, clientHeight: number): number | null => {
    const g = geo.current;
    const origin = paintOrigin();
    let raw;
    const below = belowRef.current;
    if (m.kind === 'end') {
      raw = origin + g.total + below - clientHeight - m.distance;
    } else {
      const idx = g.index.get(m.key) ?? -1;
      if (idx < 0) {
        return null;
      }
      raw = origin + g.offsets[idx] - m.viewportOffset;
    }
    return Math.max(0, Math.min(raw, origin + g.total + below - clientHeight));
  };

  // The single correction pass: spacers(old geo) -> measure -> recompute ->
  // spacers(new geo) -> restore.
  const syncAndRestore = (): void => {
    const el = getScroller();
    if (!el) {
      return;
    }
    // Phase 0 — spacers FIRST, from the pre-measure geometry: a window-shift
    // commit swaps rows before the layout effect runs, so the first forced
    // layout below would otherwise place the new rows against stale spacers
    // — every origin and anchor read off it wrong by the swapped rows'
    // height. (The extent itself cannot collapse meanwhile: the content
    // block's floor holds it, see styles.content.) Style writes don't force
    // layout, so the spacers are consistent BEFORE the first read.
    writeSpacers(winRef.current);
    // The pass's one batch of reads, before its next write: position, size,
    // where the content starts, and rows not measured yet (below).
    const vp = readViewport(el);
    const entryScrollTop = vp.scrollTop;
    measureOrigin(el, vp);
    // Refresh the anchor from the LIVE scrollTop against the pre-measure
    // geometry (= what's currently painted). scroll events lag rAF-driven
    // scrolls by a frame; scrollTop itself is ground truth, so deriving the
    // anchor here removes that staleness class entirely.
    if (
      mode.current.kind === 'anchor' &&
      // Re-derive the anchor from the live scrollTop ONLY when scrollTop's
      // latest movement was user-authored. That is the staleness this refresh
      // exists for (scroll events lag rAF scrolls by a frame). When the
      // machinery moved last — a declared anchorToKey landing, a restore, an
      // average repricing — the stored identity is the truth and scrollTop
      // may be mid-correction: re-deriving from it replaced a declared
      // {key, 0} with the neighbouring row at the repricing delta
      // (measured: deterministic 44px landing error).
      userScrolledRef.current &&
      !converging.current &&
      geo.current.keys.length > 0
    ) {
      mode.current = anchorAt(entryScrollTop);
    }
    // Only rows never seen are measured here — the first-mount backstop: an
    // UNMEASURED row is
    // about to paint at its real height while the geometry still carries its
    // estimate, and in document flow that displaces everything below it (the
    // whole viewport) by (real - est) for one frame, then snaps back when RO
    // delivers. Measuring ONCE at mount closes that; growth and reflow of
    // known rows stay on the RO pipeline, so steady-state commits force no
    // layout at all.
    for (const [key, rowEl] of rowEls.current) {
      if (sizes.current.has(key)) {
        continue;
      }
      const px = rowEl.offsetHeight;
      // Never record 0: a row measured while transiently EMPTY (a streaming
      // reply's first commit) would otherwise pin offsets[last] == total,
      // which no bottom-edge query can reach — the row is evicted from the
      // window and, unmounted, can never be re-measured. Deadlock, measured:
      // the streamed reply never rendered at all. Keeping the estimate keeps
      // the row reachable until it has real height.
      if (px === 0) {
        continue;
      }
      const prev = sizes.current.get(key);
      if (prev !== px) {
        noteMeasured(key, prev, px);
        sizes.current.set(key, px);
        geoChanged.current = true;
      }
    }
    // While the write-gate holds, the correction this pass would have written
    // to scrollTop goes into the spacer instead. Anchor to whatever is at the
    // viewport top BEFORE the recompute (identity, so a long momentum keeps
    // re-anchoring to what is on screen now), then absorb the resulting
    // target delta: painted positions come out bit-identical, with no
    // scrollTop write to cancel momentum or fight the finger.
    const heldAnchor =
      gestureHeld() && geo.current.keys.length > 0
        ? anchorAt(entryScrollTop)
        : null;
    repriceBuckets();
    recompute();
    if (heldAnchor !== null) {
      const t = targetFor(heldAnchor, vp.clientHeight);
      if (t !== null) {
        gestureAdj.current -= t - entryScrollTop;
      }
    }
    writeSpacers(winRef.current);

    // restore scrollTop from the stored reference frame
    if (converging.current) {
      geoChanged.current = true;
    }
    let target = targetFor(mode.current, vp.clientHeight);
    // Dead-anchor fallback: a null target means the anchored key is not in
    // the data — an anchorToKey to a missing key, or the anchored row left
    // with a thread switch / history replacement. Convergence could never
    // exit (it only exits by reaching a target, and its gate keeps ignoring
    // scroll events — scrollbar and keyboard could not recover), and a
    // parked dead anchor would neither follow nor restore until the next
    // gesture. Fall back to follow-at-end, the chat default.
    if (target === null) {
      converging.current = false;
      if (dataRef.current.length > 0) {
        mode.current = {kind: 'end', distance: 0};
        userAway.current = 0;
        geoChanged.current = true;
        target = targetFor(mode.current, vp.clientHeight);
      }
    }
    let wroteTarget: number | null = null;
    if (target !== null && geoChanged.current && !gestureHeld()) {
      geoChanged.current = false;
      if (Math.abs(entryScrollTop - target) > 0.5) {
        el.scrollTop = target;
        wroteTarget = target;
      }
    }
    // The pass's one read after its writes: where scrollTop actually is. The
    // browser may clamp our write if the spacer resize hasn't reached layout
    // yet, or clamp on its own when the spacers shrank; either move is ours to
    // claim (below).
    const actual = el.scrollTop;
    if (wroteTarget !== null) {
      // The echo target must be the ACTUAL landing value (otherwise our
      // own clamped write is misread as a user scroll and flips the mode),
      // and a clamp marks the geometry dirty again with a next-frame retry
      // until the write sticks.
      progTarget.current = actual;
      if (Math.abs(actual - wroteTarget) > 1) {
        geoChanged.current = true;
        // One retry slot: consecutive clamped writes coalesce, and unmount
        // cancels it (a post-unmount pass would setWin on a dead tree).
        if (rafRetry.current !== null) {
          cancelAnimationFrame(rafRetry.current);
        }
        rafRetry.current = requestAnimationFrame(() => {
          rafRetry.current = null;
          syncRef.current();
        });
      }
    }
    if (
      converging.current &&
      target !== null &&
      dataRef.current.length > 0 &&
      Math.abs(actual - target) <= CONVERGE_EPSILON_PX
    ) {
      // Reaching the target does not end a HEAD-CHANGE convergence: the rows
      // that arrived above are still measuring in, so the prices and the
      // offsets keep moving for several more passes. Both halves of the
      // protection therefore lift on the SAME later pass — one that sees the
      // settled numbers. Releasing the anchor half here instead let the
      // live-anchor refresh re-derive from a scrollTop still mid-settle and
      // freeze that intermediate position as the new reference frame
      // (measured: a 300-row prepend read at the top moved the reader 33-53px
      // and kept it, every time).
      if (priceFreeze.current) {
        if (rafRelease.current !== null) {
          cancelAnimationFrame(rafRelease.current);
        }
        rafRelease.current = requestAnimationFrame(() => {
          rafRelease.current = null;
          converging.current = false;
          priceFreeze.current = false;
          geoChanged.current = true;
          syncRef.current();
        });
      } else {
        converging.current = false;
      }
    }
    // The window must cover the DESIRED position, not the stale scrollTop:
    // in end mode a newly appended tail row would otherwise never enter the
    // window and its growth stay invisible to the geometry; for a declared
    // anchor it is what renders the destination before the position lands.
    // While the write-gate holds, the viewport belongs to the finger — the
    // desired target is not going to be written, so the window tracks the
    // ACTUAL position (rows must keep mounting under the drag).
    setWindowIfChanged(
      computeWindow(vp, target === null || gestureHeld() ? actual : target),
    );
    // Entry/exit claim: if scrollTop moved during this pass — by our write OR
    // by a SILENT BROWSER CLAMP during a transient layout (spacers not yet
    // caught up with a window shift, an estimate replaced by a smaller
    // measured size) — the movement is machinery-induced, and the coalesced
    // scroll event that dispatches next frame will carry the CURRENT value.
    // Claim it, or that event is misread as a user scroll and hijacks the
    // mode. User input cannot move scrollTop inside synchronous JS
    // (compositor scrolls land at frame boundaries), so this never swallows
    // a real gesture.
    if (actual !== entryScrollTop) {
      progTarget.current = actual;
    }
  };
  // Latest-pass ref for once-created callers (see CLOSURE DISCIPLINE).
  const syncRef = React.useRef(syncAndRestore);
  syncRef.current = syncAndRestore;

  // Data identity change (append / chunk growth) also invalidates geometry.
  const prevData = React.useRef(data);
  if (prevData.current !== data) {
    prevData.current = data;
    geoChanged.current = true;
    // The rows past the last row the previous data had are this change's
    // news, but only for a tail append: the walk must stop at a row the
    // previous data held. A thread loaded into an empty list, or one that
    // replaces the rows, is history, so the log does not read it out. The
    // geometry still indexes the previous data here.
    const previous = geo.current.index;
    const appended = new Set<string>();
    let isTailAppend = false;
    for (let i = data.length - 1; i >= 0; i--) {
      const key = String(getRowKey(data[i], i));
      if (previous.has(key)) {
        isTailAppend = true;
        break;
      }
      appended.add(key);
    }
    // The first message of a new conversation (one row into an empty list)
    // is news too; a larger load into an empty list stays history.
    const isFirstMessage = previous.size === 0 && appended.size === 1;
    newsKeysRef.current = isTailAppend || isFirstMessage ? appended : new Set();
    // HEAD CHANGE (loading older history, or trimming it). Rows arrived above
    // everything placed, so the restore owes a correction the size of the whole
    // page, paid across several passes as those rows measure in. That is a
    // CONVERGENCE, and treating it as one stops the live-anchor refresh from
    // re-deriving the anchor from a scrollTop still mid-flight — which
    // otherwise freezes the intermediate position as the new anchor, for good.
    // Cannot wedge: every gesture path already clears `converging`.
    const head = data.length > 0 ? String(getRowKey(data[0], 0)) : null;
    if (
      head !== null &&
      geo.current.keys.length > 0 &&
      geo.current.keys[0] !== head
    ) {
      converging.current = true;
      priceFreeze.current = true;
    }
  }

  // The pre-paint correction slot. (No separate initial-landing effect: this
  // pass computes the window from the declared target on the same commits,
  // attach arrival included.) A commit that changes none of what the pass
  // reads — the geometry, the rows mounted, the scroller, the sizing props —
  // skips it: a parent re-render with the same data, a label change.
  React.useLayoutEffect(() => {
    const scroller = getScroller();
    const keys = pendingRenderKeysRef.current;
    const sizing = [
      overscanTop,
      overscanBottom,
      estimatedItemSize,
      getItemType,
    ];
    const passed = passedRenderRef.current;
    if (
      !geoChanged.current &&
      passed !== null &&
      passed.keys === keys &&
      passed.scroller === scroller &&
      passed.sizing.every((value, i) => Object.is(value, sizing[i]))
    ) {
      return;
    }
    passedRenderRef.current = {keys, scroller, sizing};
    syncAndRestore();
  });

  // Marks the content block busy for a commit that mounts history, until
  // the frame after it, so the log does not read those rows out as new.
  React.useLayoutEffect(function markHistoryMountsBusy() {
    // News is news once: a message that has mounted is history after.
    for (const key of pendingRenderedRef.current) {
      newsKeysRef.current.delete(key);
    }
    renderedKeysRef.current = pendingRenderedRef.current;
    const block = contentRef.current;
    if (!pendingBusyRef.current || block === null) {
      return;
    }
    block.setAttribute('aria-busy', 'true');
    if (busyClearRef.current !== null) {
      cancelAnimationFrame(busyClearRef.current);
    }
    busyClearRef.current = requestAnimationFrame(() => {
      busyClearRef.current = requestAnimationFrame(() => {
        busyClearRef.current = null;
        block.removeAttribute('aria-busy');
      });
    });
  });

  // The RO is the measurement pipeline: sizes come from the observed
  // border-box (no forced layout anywhere).
  // Sizes come through Core's shared resize observer, one callback per entry;
  // the sync they trigger runs once per batch, after the last entry.
  const syncQueued = React.useRef(false);
  const onResizeRef = React.useRef<
    ((entry: ResizeObserverEntry) => void) | null
  >(null);
  if (onResizeRef.current === null) {
    onResizeRef.current = entry => {
      // The registration's own synchronous call carries no box: the observer's
      // first real entry follows, so reading the size here would only force a
      // layout.
      if (
        entry.borderBoxSize === undefined &&
        entry.contentRect === undefined
      ) {
        return;
      }
      // One sync for the whole batch: the microtask runs after the shared
      // observer has delivered its last entry.
      if (!syncQueued.current) {
        syncQueued.current = true;
        queueMicrotask(() => {
          syncQueued.current = false;
          syncRef.current();
        });
      }
      const key = (entry.target as HTMLElement).dataset.pkey;
      if (key === undefined) {
        // The scroll CONTAINER (observed in the listener effect): its
        // resize changes clientHeight, which moves the end-mode target and
        // the window coverage with zero row-size changes — without marking
        // the geometry dirty here, a window resize or a growing composer
        // would leave the pinned bottom stranded.
        geoChanged.current = true;
        return;
      }
      // Border box, the same box the sync path reads with offsetHeight —
      // one cache, one definition of a row's size. contentRect is NOT that
      // box (it drops padding and border), so a padded row would be cached
      // short for as long as the fallback is the writer.
      const px =
        entry.borderBoxSize?.[0]?.blockSize ??
        (entry.target as HTMLElement).offsetHeight;
      const prev = sizes.current.get(key);
      if (px > 0 && prev !== px) {
        noteMeasured(key, prev, px);
        sizes.current.set(key, px);
        geoChanged.current = true;
      }
    };
  }
  const unobserveByEl = React.useRef(new Map<Element, () => void>());
  const observeSize = (el: Element): void => {
    if (!unobserveByEl.current.has(el)) {
      unobserveByEl.current.set(el, observeResize(el, onResizeRef.current!));
    }
  };
  const unobserveSize = (el: Element): void => {
    unobserveByEl.current.get(el)?.();
    unobserveByEl.current.delete(el);
  };
  React.useEffect(
    () => () => {
      for (const unobserve of unobserveByEl.current.values()) {
        unobserve();
      }
      unobserveByEl.current.clear();
      if (rafRetry.current !== null) {
        cancelAnimationFrame(rafRetry.current);
      }
      if (rafRelease.current !== null) {
        cancelAnimationFrame(rafRelease.current);
      }
      if (busyClearRef.current !== null) {
        cancelAnimationFrame(busyClearRef.current);
      }
    },
    [],
  );

  // A DECLARATION re-points the reference frame and lets the restore loop
  // converge: machine-driven regime, displacement cleared, protected from
  // mode flips until reached. The window is computed from the declared
  // target first, so the destination renders before the position lands
  // (committed semantics; no blank flash on long jumps).
  const declare = (m: Mode): void => {
    mode.current = m;
    priceFreeze.current = true;
    userScrolledRef.current = false;
    userAway.current = 0;
    converging.current = true;
    geoChanged.current = true;
    syncRef.current(); // captured by the once-created handle: live ref
  };

  // Imperative API — both methods are declarations, not scroll actions.
  // useImperativeHandle so a discarded concurrent render cannot repoint the
  // handle; created once, reads only refs (see CLOSURE DISCIPLINE).
  React.useImperativeHandle(
    handleRef,
    () => ({
      scrollToDistanceFromBottomPx: (px = 0) =>
        declare({kind: 'end', distance: px}),
      anchorToKey: (key, viewportOffset = 0) =>
        declare({kind: 'anchor', key: String(key), viewportOffset}),
    }),
    [],
  );

  // The finger's scroll is over (its scrollend after the lift, momentum
  // included, or the watch's quiet fallback): hand the gesture back.
  const flushGesture = (): void => {
    flushRetry.current = null;
    const el = getScroller();
    if (!el || !gestureActive.current) {
      return;
    }
    // Inside an elastic overscroll a write snaps the bounce onto the clamp
    // and discards where the user let go: wait until it is over.
    // One batch of reads for the gesture's end, before the pass it starts.
    const vp = readViewport(el);
    if (isBouncing(vp)) {
      flushRetry.current = requestAnimationFrame(flushGesture);
      return;
    }
    gestureActive.current = false;
    // Engines report scrollHeight as at least clientHeight, so this is
    // never negative in practice — clamped anyway to hold the same
    // invariant targetFor does.
    const max = Math.max(0, vp.scrollHeight - vp.clientHeight);
    // Re-state the reference frame from the resting position. Whether the
    // gesture MOVED decides the semantics only: a real scroll re-judges
    // follow against the bottom edge, while a scroll that was only our own
    // echo under a resting finger keeps the mode it had — re-judging would
    // read machinery growth as a user pushing away.
    //
    // The re-statement is UNCONDITIONAL, because it is also what hands the
    // gesture adjustment back: the stored viewportOffset is where the
    // anchored row actually IS, so zeroing the adjustment below leaves the
    // sync one balancing scrollTop write, spacers and position moving in the
    // same task. The offset comes from the DOM (anchorFromPaint) rather than
    // being derived, so a clamped spacer cannot make the two disagree.
    if (!converging.current) {
      const atEnd = gestureMoved.current
        ? max - vp.scrollTop <= endThresholdRef.current
        : mode.current.kind === 'end';
      mode.current = atEnd
        ? {kind: 'end', distance: 0}
        : (anchorFromPaint(el, vp.clientHeight) ?? anchorAt(vp.scrollTop));
      userAway.current = 0;
      // The fold is a MACHINE repositioning: the adjustment now lives only
      // in the folded viewportOffset, and the live-anchor refresh — which
      // re-derives from scrollTop once the adjustment is gone — would
      // erase it, dropping the balancing write while the spacers revert
      // (measured: +148px). Machine-driven regime holds the fold until the
      // user actually scrolls again.
      userScrolledRef.current = false;
    }
    gestureAdj.current = 0;
    geoChanged.current = true;
    syncRef.current();
  };
  const flushGestureRef = React.useRef(flushGesture);
  flushGestureRef.current = flushGesture;
  // Core's finger-scroll watch: whether the scroller's scroll is a finger's
  // (only under a coarse primary pointer), and when it ends.
  const isFingerScroll = useFingerScroll(liveScrollerRef, {
    onEnd: () => flushGestureRef.current(),
  });

  const onScroll = (): void => {
    const el = getScroller();
    if (!el) {
      return;
    }
    // The handler's one batch of reads; it writes nothing to the DOM.
    const vp = readViewport(el);
    // The position the machinery last WROTE, kept before the echo slot is
    // cleared below: the user's displacement is measured from there, not
    // from the last event seen. A wheel that lands between two of our
    // writes coalesces with the next write into one event carrying the net,
    // and against the previous event's value that net can still read as
    // "moved down" — the user's own upward step erased by the re-pin.
    const lastWrite = progTarget.current;
    const isEcho =
      lastWrite !== null && Math.abs(vp.scrollTop - lastWrite) <= 1;
    // STICKY echo: k offset changes within one frame queue up to k scroll
    // events, dispatched across successive frames, EACH reading the same
    // final scrollTop. A consume-once slot matches the first and misreads
    // every duplicate as a user scroll. Keep the expectation while events
    // match; only a NON-matching event (a real user scroll) clears it.
    if (!isEcho) {
      progTarget.current = null;
      userScrolledRef.current = true;
      lastUserEventT.current = performance.now();
    }
    const prevEventST = lastEventST.current;
    lastEventST.current = vp.scrollTop;
    if (isFingerScroll()) {
      if (!gestureActive.current) {
        // A finger's scroll begins: an INTENT signal, like a wheel, so it
        // breaks convergence.
        gestureActive.current = true;
        gestureMoved.current = false;
        converging.current = false;
        priceFreeze.current = false;
      }
      // A new finger scroll during a held flush continues the gesture.
      if (flushRetry.current !== null) {
        cancelAnimationFrame(flushRetry.current);
        flushRetry.current = null;
      }
    }
    if (gestureHeld() && !isEcho) {
      gestureMoved.current = true;
    }
    if (!isEcho && !converging.current) {
      const g = geo.current;
      const dist = vp.scrollHeight - vp.clientHeight - vp.scrollTop;
      // With native anchoring off, the one move the browser still makes on
      // its own is the clamp onto a new, smaller bottom (a row shrinking in
      // a way no commit announced — an image, a font). It lands exactly on
      // the bottom, where a user scrolling up never lands, so it is not
      // displacement.
      const landedAtBottom = dist < 1;
      const anchorHere = (): void => {
        mode.current = anchorAt(vp.scrollTop);
        userAway.current = 0;
      };
      if (g.keys.length === 0) {
        mode.current = {kind: 'end', distance: 0};
        userAway.current = 0;
      } else if (mode.current.kind === 'end') {
        // DISENGAGE is judged on the user's own displacement, never on the
        // absolute distance to the bottom: while following, the tail grows
        // between corrections, so the live distance carries machinery
        // movement the user did not make (measured: 6-24px nudges reading as
        // 25-59px, flipping to anchor and stranding the reader mid-stream).
        // Accumulating means a slow, persistent upward scroll still wins even
        // when each individual step is erased by a re-pin.
        const from = lastWrite ?? prevEventST;
        if (from !== null && !landedAtBottom) {
          userAway.current = Math.max(
            0,
            userAway.current + (from - vp.scrollTop),
          );
        }
        if (userAway.current > endThresholdRef.current) {
          anchorHere();
        }
      } else if (dist <= endThresholdRef.current) {
        // RE-ENGAGE is judged on the absolute distance, which IS honest in
        // anchor mode: nothing is pulling the viewport, so reaching the
        // bottom is the user's own doing.
        mode.current = {kind: 'end', distance: 0};
        userAway.current = 0;
      } else {
        anchorHere();
      }
    }
    setWindowIfChanged(computeWindow(vp));
  };

  // The listener is attached once per scroll element but the handler is read
  // live, so it never closes over a stale render's props.
  const onScrollRef = React.useRef(onScroll);
  onScrollRef.current = onScroll;

  // Listeners are attached imperatively rather than through JSX so both modes
  // take the same path, and so attach mode can also turn OFF the browser's own
  // scroll anchoring on a container it does not render: native anchoring picks
  // its own anchor node and adjusts scrollTop underneath us, which is exactly
  // the job this list is doing from its own reference frame.
  React.useEffect(() => {
    const el = getScroller();
    if (!el) {
      return;
    }
    // A REPLACED scroller (not the first arrival) carries none of the old
    // one's scroll state: a stale lastEventST would difference two unrelated
    // scrollTops into a phantom user displacement (instant spurious unpin),
    // and a stale echo expectation could swallow the first real event.
    if (prevScrollerRef.current !== null && prevScrollerRef.current !== el) {
      lastEventST.current = null;
      userAway.current = 0;
      progTarget.current = null;
    }
    prevScrollerRef.current = el;
    // Intent signals break convergence early: a wheel, or the start of a
    // finger's scroll (see onScroll), is USER INPUT, unlike scroll events,
    // which mix in our own writes and clamps.
    //
    // A wheel does NOT unpin by itself. One this scroller never consumes —
    // over a nested scroller with room above, over one with
    // `overscroll-behavior: contain`, an overscroll at the bottom — moves
    // nothing here, and unpinning on it strands the reader off the tail.
    // Whether the container moved is what onScroll measures, against the
    // position the machinery last wrote, so a wheel the next write outruns
    // still shows there.
    const onWheel = (): void => {
      converging.current = false;
      priceFreeze.current = false;
    };
    setScrollAnchoringOff(el, true);
    const scrollHandler = (): void => onScrollRef.current();
    el.addEventListener('scroll', scrollHandler, {passive: true});
    el.addEventListener('wheel', onWheel, {passive: true});
    // Observe the CONTAINER too (rows alone miss clientHeight changes): a
    // window resize or a growing composer moves the end-mode target and the
    // window coverage without any row changing size. Container entries have
    // no data-pkey — the RO callback marks the geometry dirty for them.
    observeSize(el);
    return () => {
      setScrollAnchoringOff(el, false);
      el.removeEventListener('scroll', scrollHandler);
      el.removeEventListener('wheel', onWheel);
      // A replaced or unmounted scroller ends the gesture with it: the
      // finger-scroll watch moves to the new element and reports no end for
      // the old one. The adjustment is dropped rather than folded — the
      // element carrying it in its spacer is going away, and the replacement
      // re-derives its own frame from the mode on its first pass.
      if (flushRetry.current !== null) {
        cancelAnimationFrame(flushRetry.current);
        flushRetry.current = null;
      }
      gestureActive.current = false;
      gestureMoved.current = false;
      gestureAdj.current = 0;
      unobserveSize(el);
    };
  }, [scrollElement]);

  // Stable per-key ref callbacks: an inline `(el) => …` would be a new
  // identity every render, making React detach + reattach EVERY row's ref on
  // EVERY commit — and each re-observe() fires an initial ResizeObserver
  // callback, so steady-state commits would trigger a full-window RO batch
  // of pure noise.
  const rowRefCbs = React.useRef(
    new Map<string, (el: HTMLDivElement | null) => void>(),
  );
  const rowRef = (key: string): ((el: HTMLDivElement | null) => void) => {
    let cb = rowRefCbs.current.get(key);
    if (!cb) {
      cb = el => {
        if (el) {
          rowEls.current.set(key, el);
          observeSize(el);
        } else {
          const prev = rowEls.current.get(key);
          if (prev) {
            unobserveSize(prev);
          }
          rowEls.current.delete(key);
          rowRefCbs.current.delete(key);
        }
      };
      rowRefCbs.current.set(key, cb);
    }
    return cb;
  };

  // Tail messages the window has not reached. They mount on arrival, after a
  // gap spacer below the window, so the log can deliver them while the reader
  // is in history. State, not a ref: it decides what renders. Only a tail
  // append adds to it, so a replaced thread mounts nothing extra. A row
  // leaves once the window reaches it or it is gone from the data.
  const [arrival, setArrival] = React.useState<{
    data: readonly T[];
    win: Win;
    keys: ReadonlySet<string>;
  }>(() => ({data, win, keys: new Set()}));
  let arrivedKeys = arrival.keys;
  if (arrival.data !== data || arrival.win !== win) {
    const next = new Set<string>();
    const indexOf = new Map<string, number>();
    for (let i = 0; i < data.length; i++) {
      indexOf.set(String(getRowKey(data[i], i)), i);
    }
    const reached = (key: string): boolean =>
      win.end >= win.start && (indexOf.get(key) ?? -1) <= win.end;
    for (const key of arrival.keys) {
      if (indexOf.has(key) && !reached(key)) {
        next.add(key);
      }
    }
    if (arrival.data !== data) {
      const previous = new Set<string>();
      for (let i = 0; i < arrival.data.length; i++) {
        previous.add(String(getRowKey(arrival.data[i], i)));
      }
      const run: string[] = [];
      let isTailAppend = false;
      for (let i = data.length - 1; i >= 0; i--) {
        const key = String(getRowKey(data[i], i));
        if (previous.has(key)) {
          isTailAppend = true;
          break;
        }
        run.push(key);
      }
      // Only while the reader is away from the tail: a window that reached
      // the previous last row follows the append itself.
      const wasAtTail =
        win.end >= win.start && win.end >= arrival.data.length - 1;
      if (isTailAppend && !wasAtTail) {
        for (const key of run) {
          if (!reached(key)) {
            next.add(key);
          }
        }
      }
    }
    // At most one window's worth of the newest arrivals stays mounted, across
    // every batch and single arrival while the reader stays in history. They
    // are the newest rows, so the run they start is that long too.
    const room = Math.max(1, win.end - win.start + 1);
    if (next.size > room) {
      const newest = [...next]
        .sort((a, b) => (indexOf.get(b) ?? -1) - (indexOf.get(a) ?? -1))
        .slice(0, room);
      next.clear();
      for (const key of newest) {
        next.add(key);
      }
    }
    arrivedKeys = next;
    setArrival({data, win, keys: next});
  }

  // A focused row outside the window stays mounted beside it. It keeps its
  // place among its siblings as rows mount and unmount around it, so React
  // never moves its node (a moved node loses focus).
  let pinnedIndex = -1;
  if (focusedKey !== null && win.end >= win.start) {
    pinnedIndex = data.findIndex(
      (item, i) => String(getRowKey(item, i)) === focusedKey,
    );
    if (pinnedIndex >= win.start && pinnedIndex <= win.end) {
      pinnedIndex = -1;
    }
  }
  // The arrived tail run starts at the first arrived row past the window and
  // runs to the last row.
  let tailIndex = -1;
  if (arrivedKeys.size > 0 && win.end >= win.start) {
    for (let i = data.length - 1; i > win.end; i--) {
      if (arrivedKeys.has(String(getRowKey(data[i], i)))) {
        tailIndex = i;
      }
    }
  }
  tailKeyRef.current =
    tailIndex < 0 ? null : String(getRowKey(data[tailIndex], tailIndex));
  // A focused row inside the tail run is drawn by the run.
  if (tailIndex >= 0 && pinnedIndex >= tailIndex) {
    pinnedIndex = -1;
  }
  pinnedKeyRef.current = pinnedIndex < 0 ? null : focusedKey;
  const renderRow = (i: number): React.ReactNode => {
    const key = String(getRowKey(data[i], i));
    if (getItemType) {
      typeByKey.current.set(key, getItemType(data[i], i));
    }
    return (
      <div key={key} ref={rowRef(key)} data-pkey={key}>
        {renderItem({item: data[i], index: i})}
      </div>
    );
  };
  const children: React.ReactNode[] = [
    <div key="__top" ref={spacerTopRef} aria-hidden />,
  ];
  if (pinnedIndex >= 0 && pinnedIndex < win.start) {
    children.push(
      renderRow(pinnedIndex),
      <div key="__gapTop" ref={gapTopRef} aria-hidden />,
    );
  }
  if (win.end >= win.start) {
    for (let i = win.start; i <= Math.min(win.end, data.length - 1); i++) {
      children.push(renderRow(i));
    }
  }
  if (pinnedIndex > win.end) {
    children.push(
      <div key="__gapBottom" ref={gapBottomRef} aria-hidden />,
      renderRow(pinnedIndex),
    );
  }
  if (tailIndex >= 0) {
    children.push(
      pinnedIndex > win.end ? (
        <div key="__gapTail" ref={gapTailRef} aria-hidden />
      ) : (
        <div key="__gapBottom" ref={gapBottomRef} aria-hidden />
      ),
    );
    for (let i = tailIndex; i < data.length; i++) {
      children.push(renderRow(i));
    }
  }
  children.push(<div key="__bottom" ref={spacerBottomRef} aria-hidden />);

  // Busy when this render mounts a row that is not news: the window moving
  // over history, or history loading above.
  const renderedKeys = new Set<string>();
  for (const child of children) {
    const key = (child as React.ReactElement).key;
    if (key !== null && !key.startsWith('__')) {
      renderedKeys.add(key);
    }
  }
  let mountsHistory = false;
  for (const key of renderedKeys) {
    if (!renderedKeysRef.current.has(key) && !newsKeysRef.current.has(key)) {
      mountsHistory = true;
      break;
    }
  }
  pendingRenderedRef.current = renderedKeys;
  pendingRenderKeysRef.current = [...renderedKeys].join('\n');
  pendingBusyRef.current = mountsHistory;

  // Which row holds focus, for the pinning above.
  const onContentFocus = (event: React.FocusEvent<HTMLDivElement>): void => {
    const row = (event.target as Element).closest<HTMLElement>('[data-pkey]');
    const key =
      row != null && event.currentTarget.contains(row)
        ? (row.dataset.pkey ?? null)
        : null;
    setFocusedKey(key);
  };
  const onContentBlur = (event: React.FocusEvent<HTMLDivElement>): void => {
    const next = event.relatedTarget as Node | null;
    if (next != null) {
      if (!event.currentTarget.contains(next)) {
        setFocusedKey(null);
      }
      return;
    }
    // A blur with no next target can come while the row still holds focus
    // (the window switching around it): drop the pin only once focus has
    // really left the list.
    const block = event.currentTarget;
    queueMicrotask(() => {
      if (!block.contains(block.ownerDocument.activeElement)) {
        setFocusedKey(null);
      }
    });
  };

  const contentProps = {
    ref: contentRef,
    onFocus: onContentFocus,
    onBlur: onContentBlur,
    xstyle: styles.content,
  };
  // In own-container mode the scrollable area measures this block's overflow
  // to decide whether keyboard users can scroll.
  const {xstyle: contentXstyle, ...contentDomProps} = attachMode
    ? contentProps
    : getContentProps<HTMLDivElement>(contentProps);
  const content = (
    <div {...contentDomProps} {...stylex.props(contentXstyle)}>
      {children}
    </div>
  );

  if (attachMode) {
    return content;
  }

  return (
    <div
      {...getViewportProps<HTMLDivElement>({
        ref: ownScrollerRef,
        className,
        style,
        xstyle: styles.scroller,
      })}>
      {content}
    </div>
  );
}