Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

62.3 KB
Raw Blame
import { elementScroll, useVirtualizer } from '@tanstack/react-virtual'
import {
    createContext,
    CSSProperties,
    memo,
    ReactNode,
    useCallback,
    useContext,
    useEffect,
    useLayoutEffect,
    useMemo,
    useRef,
    useState,
} from 'react'

import { cn } from 'lib/utils/css-classes'

import { FlowRows } from './FlowRows'
import { VirtualizedThreadRowContext, type VirtualizedThreadRowContextValue } from './VirtualizedThreadRowContext'

/**
 * Slack the virtualizer core is allowed to treat as "at the end" while the thread is pinned, so its own
 * growth compensation still smooths streaming that lands between our follow writes. Deliberately *not*
 * used to decide whether the reader is at the bottom — see `AT_BOTTOM_EPSILON`.
 */
const BOTTOM_THRESHOLD = 32

/**
 * `scrollEndThreshold` while unpinned. The core compares it against `getVirtualDistanceFromEnd()`, which
 * clamps at 0 — so 0 would still compensate at the exact end. A negative threshold is the only value that
 * distance can never satisfy, which is what "while the reader is away, no measurement may move the view"
 * requires.
 */
const NO_END_COMPENSATION = -1

/**
 * How close to the bottom the reader has to be to count as *there* — subpixel only. A band here would
 * make the bottom sticky: an upward gesture that stops inside it gets re-pinned and yanked back on the
 * next streamed frame, which reads as the view shaking against the gesture. Zero would be stricter still,
 * but fractional layout/zoom leaves the true bottom a half-pixel short, so re-pinning would be unreachable.
 */
const AT_BOTTOM_EPSILON = 1

/** How long a prepend keeps the reader's row in place while the rows put in front measure. */
const PREPEND_HOLD_MS = 1_000
/** The core snaps its own scroll writes to within 1.5px of their target — below that is never the reader. */
const UNPIN_SLACK = 1.5

/**
 * True when the offset moved after the last scroll event `onScroll` handled or the last software write
 * (`lastSeenTop`). The browser dispatches scroll events once per frame, so a timer can run after a reader's
 * scroll and before its event. A timer write there erases the reader's scroll, and `onScroll` then takes the
 * late event for the write's echo. A hidden scroller reads 0 and fires no event, so it never reports a move.
 */
function hasUnseenScroll(el: HTMLElement, lastSeenTop: number): boolean {
    return el.clientHeight > 0 && Math.abs(el.scrollTop - lastSeenTop) > UNPIN_SLACK
}

/**
 * How long a recorded programmatic scroll write explains the scroll event it causes. Events land on the
 * next frame; the window only needs to survive frame jank, and staying short keeps a coincidental user
 * scroll to the same offset from being swallowed for long.
 */
const PROGRAMMATIC_SCROLL_MATCH_MS = 200

/**
 * The settle window after an anchor landing: how often and how many times the landing is re-asserted
 * against the anchor's (re-measured) offset. Needed because the core's scroll reconciler has a blind
 * spot — once its target stops moving, an offset nudge from a late row measurement is rewritten by
 * neither of its branches, so it idles to its timeout and leaves the drift in place. Any reader scroll
 * cancels the window immediately.
 */
const ANCHOR_SETTLE_INTERVAL_MS = 250
const ANCHOR_SETTLE_CHECKS = 8

/** Drift below this is indistinguishable from subpixel rounding — not worth a corrective write. */
const ANCHOR_SETTLE_TOLERANCE_PX = 2

/**
 * How long a bottom arrival is ignored by the re-pin test after a programmatic anchor landing. On the
 * landing commit rows are still estimates, so the scroll clamps against a range that grows as rows
 * measure — the settle touches the exact bottom transiently, and each touch emits a scroll event that is
 * indistinguishable from the reader arriving there. Position-based disambiguation is racy (the settle
 * also emits not-at-bottom events between the touches), so the window is temporal: the reconciler holds
 * a stable anchor target within a few frames, and an explicit downward gesture clears the block early.
 */
const BOTTOM_REPIN_BLOCK_MS = 600

/**
 * How long the thread keeps following after a turn reports done. The turn's last rows land after the
 * flag drops: token usage and cost arrive on their own stream frames, and the footer swaps to them a
 * commit or two later. Without the grace that tail renders just below the fold. Overshooting is harmless —
 * an upward gesture unpins instantly, grace or not.
 */
const FOLLOW_GRACE_MS = 1000

/**
 * Static base for measured rows under `directDomUpdates`: the virtualizer writes each row's `translate3d`
 * (and the container's height) directly to the DOM, so React renders no per-row offset at all — a pure
 * scroll or a measurement settle repositions rows without re-rendering them.
 */
const ROW_BASE_STYLE: CSSProperties = { position: 'absolute', top: 0, left: 0, width: '100%' }

/**
 * Virtual keys for the synthetic header/footer rows — reserved prefixes that never collide with a user item
 * key. The footer key is a prefix, not a constant: `getVirtualItemKey` appends the item count to it.
 */
const HEADER_KEY = '__vt_header__'
const FOOTER_KEY = '__vt_footer__'

const lastReadItems = new Map<string, string>()

interface RootContextValue {
    isFollowing: boolean
    /** Inspecting expanded content should release automatic following, just like scrolling up. */
    pauseFollowing: () => void
    /** The virtualizer's border-box `ResizeObserver` ref — attach to each measured row's outer element. */
    measureElement: (node: Element | null) => void
    /** Inter-row spacing (px), applied as bottom padding on the measured row so heights include it. */
    gap: number
    /** The last row takes no gap: nothing follows it, and an empty footer would otherwise leave a blank strip. */
    lastIndex: number
    maxWidthClassName: string
    /** When false, rows render in document flow (no virtualization) and an ancestor owns scroll. */
    virtualized: boolean
}

const RootContext = createContext<RootContextValue | null>(null)

/**
 * Virtualized row shell: publishes the row index via context and defers content to `renderRow`. Row
 * offsets never pass through React (`directDomUpdates` writes them straight to the DOM), so a mounted row
 * only re-renders when its index or content changes — never on scroll or measurement.
 */
const InternalRow = memo(function InternalRow({
    index,
    renderRow,
}: {
    index: number
    renderRow: (index: number) => ReactNode
}): JSX.Element {
    const value = useMemo<VirtualizedThreadRowContextValue>(() => ({ index }), [index])
    return <VirtualizedThreadRowContext.Provider value={value}>{renderRow(index)}</VirtualizedThreadRowContext.Provider>
})

export interface VirtualizedThreadRootProps<T> {
    items: T[]
    /** Stable key per item — keys the measurement cache (correct reuse on prepend/reorder). */
    getItemKey: (item: T, index: number) => string
    /** Rendered as a measured leading row (e.g. run context). */
    header?: ReactNode
    /** Rendered as a measured trailing row (e.g. thinking indicator, PR card). */
    footer?: ReactNode
    /** Inter-row spacing in px (default 6, matching `gap-1.5`). */
    gap?: number
    /** Height used until a row is measured. */
    defaultRowHeight?: number
    /**
     * Per-item pre-measurement height estimate in px (gap excluded — added internally). The closer the
     * estimate to the real row height, the smaller the scroll-position correction applied when an
     * unmeasured row above the viewport gets its first measurement — which is what makes scrolling up
     * through unvisited history feel like dragging. Falls back to `defaultRowHeight`.
     */
    estimateItemHeight?: (item: T, index: number) => number
    overscanCount?: number
    /** Follow the bottom as rows grow/append; unpins when the user scrolls up. */
    stickToBottom?: boolean
    /**
     * True while the agent is actively working a turn (streaming output into the thread). Gates
     * bottom-following: while active, streamed rows keep pulling the view down — as long as the thread is
     * pinned, which it is whenever the reader is at the bottom — until the user scrolls up, which unpins.
     * Unpinning is absolute: nothing moves the view again (not the follow write, not the virtualizer's own
     * growth compensation) until the reader scrolls all the way back to the bottom, which re-pins. Follow
     * outlasts the flag by a moment so the turn's trailing usage/cost row lands in view. While inactive,
     * streamed rows never move the view.
     */
    turnActive?: boolean
    /**
     * Key of the row the reader's attention anchors to — the last human message, typically. Two behaviors
     * hang off it. Open: when at least a viewport of content follows this row, the thread opens with it
     * at the top of the viewport (the last meaningful turn, its response below), mid-turn included; with
     * less content the scroll clamps and the thread opens at the bottom — no padding is ever reserved to
     * force the row higher. Change to a new non-null value (a fresh send): the thread pins to the bottom
     * and follows the streaming answer; the sent message rides up naturally as the response grows.
     */
    anchorItemKey?: string | null
    scrollRestorationKey?: string
    /**
     * True while `items` are still being assembled (a history replay in flight). Defers the once-only
     * opening scroll and the anchor-key adoption: partial fold commits can carry renderable items —
     * debug/console rows land well before the history's human turns — and spending the open on one of
     * those opens every thread at the bottom instead of its anchor. Cleared-on-error semantics are the
     * caller's job: while true the thread never takes its opening scroll.
     */
    itemsLoading?: boolean
    /**
     * Called when the reader scrolls within a viewport of the top, so the caller can load older rows. Rows the
     * caller then puts in front of `items` never move what the reader sees: the first visible row keeps its
     * place on screen.
     */
    onNearTop?: () => void
    maxWidthClassName?: string
    className?: string
    /**
     * Virtualize and own scroll (default `true` — requires a height-bounded parent). Pass `false` to render
     * rows in document flow and let an ancestor own the scroll (e.g. an external auto-scroller); the wrapper
     * adds no chrome in this mode, so the parent supplies layout (gap, centering, container query).
     */
    virtualized?: boolean
    listClassName?: string
    endInset?: number
    children: (item: T, index: number) => ReactNode
}

/**
 * Embeddable virtualized thread. Fills any height-bounded parent (`h-full`/`flex-1 min-h-0`/fixed),
 * virtualizes rows with TanStack Virtual, measures dynamic heights, owns its own scroll and an optional
 * stick-to-bottom that follows streaming growth. Render rows through the `children` render-prop, each
 * wrapped in `VirtualizedThread.Row`.
 */
function Root<T>({
    items,
    getItemKey,
    header,
    footer,
    gap = 6,
    defaultRowHeight = 56,
    estimateItemHeight,
    overscanCount = 10,
    stickToBottom = true,
    turnActive = false,
    anchorItemKey,
    scrollRestorationKey,
    itemsLoading = false,
    onNearTop,
    maxWidthClassName = 'max-w-180',
    className,
    listClassName,
    endInset = 0,
    virtualized = true,
    children,
}: VirtualizedThreadRootProps<T>): JSX.Element {
    const hasHeader = header != null
    const hasFooter = footer != null
    const rowCount = items.length + (hasHeader ? 1 : 0) + (hasFooter ? 1 : 0)

    const scrollRef = useRef<HTMLDivElement>(null)
    const didInitialScrollRef = useRef(false)
    const savedReadItem = useRef(scrollRestorationKey ? lastReadItems.get(scrollRestorationKey) : undefined)
    // Content growth can move the bottom before the next follow write. Track reader intent separately:
    // the ref updates scroll handlers immediately; state publishes the same mode to activity lists.
    const pinnedRef = useRef(true)
    const [pinned, setPinnedState] = useState(true)
    // Highest offset the reader has reached since the last pin — the yardstick the unpin test measures
    // against. A high-water mark rather than the previous event's offset because a slow drag (scrollbar,
    // touch, a trackpad crawl) moves a couple of px per scroll event and would walk hundreds of px away
    // from the bottom without any single event ever crossing a per-event delta.
    const peakTopRef = useRef(0)
    // Until when bottom arrivals may not re-pin (see `BOTTOM_REPIN_BLOCK_MS`). Armed by programmatic
    // anchor landings; cleared early by an explicit downward gesture.
    const bottomRepinBlockedUntilRef = useRef(0)
    // Recent scroll writes software performed — ours (follow, landings) or the virtualizer core's
    // (`scrollToFn` routes through here). The scroll listener uses them to tell content-driven movement
    // from the reader's: during a fast stream the core writes `scrollTop` many times a frame from its
    // own bookkeeping (measurement compensations, end anchoring), and any of those can move the offset
    // *up* — a lagging internal offset, a row measuring smaller than its estimate — which is byte-for-
    // byte what an upward gesture looks like. The values recorded are the *applied* offsets (read back
    // after the write), so a write the browser clamped still matches its event; a short ring rather
    // than one entry, because a measurement storm can land several writes before their events flush.
    const programmaticScrollsRef = useRef<{ value: number; at: number }[]>([])
    // Item keys of the previous populated commit — how the anchor-change effect tells a fresh send (the
    // key did not exist before) from a replayed anchor (it did). See that effect for why position can't.
    const prevItemKeysRef = useRef<Set<string> | null>(null)
    // When the reader last scrolled (a scroll event no programmatic write explains, or a wheel/touch
    // gesture). The anchor settle loop stands down the moment this passes its start time.
    const lastUserScrollAtRef = useRef(0)
    // The previous scroll event's offset — how the listener recognizes a shrink clamp (see `onScroll`).
    const lastScrollEventTopRef = useRef<number | null>(null)
    // The offset as of the last scroll event or software scroll write (see `hasUnseenScroll`).
    const lastSeenTopRef = useRef(0)
    // Keeps following for a beat after the turn reports done, so the trailing usage/cost row lands in
    // view (see `FOLLOW_GRACE_MS`).
    const [followGrace, setFollowGrace] = useState(false)
    const prevTurnActiveRef = useRef(turnActive)
    const following = turnActive || followGrace
    // Read by the scroll listener without re-subscribing it per render.
    const followingRef = useRef(following)
    followingRef.current = following
    // Read by the open-decision loop without re-arming it per commit.
    const lastItemKeyRef = useRef<string | undefined>(undefined)
    lastItemKeyRef.current = items.length > 0 ? getItemKey(items[items.length - 1], items.length - 1) : undefined
    const onNearTopRef = useRef(onNearTop)
    onNearTopRef.current = onNearTop
    // The first row on screen and its offset from the viewport top, so rows put in front of `items` can keep it
    // in place (see the prepend effect).
    const topRowRef = useRef<{ key: string; offset: number; start: number } | null>(null)
    // Set by the prepend effect for the commit that put rows above the reader, so the anchor effect in the
    // same commit reads a new anchor from that history as history, not as a send.
    const rowsLandedAboveRef = useRef(false)
    // `undefined` means "thread not yet populated" — the anchor-change effect adopts the first real key.
    const prevAnchorKeyRef = useRef<string | null | undefined>(undefined)

    const recordScrollWrite = useCallback((applied: number): void => {
        lastSeenTopRef.current = applied
        const writes = programmaticScrollsRef.current
        writes.push({ value: applied, at: performance.now() })
        if (writes.length > 12) {
            writes.splice(0, writes.length - 12)
        }
    }, [])

    const renderRow = useCallback(
        (index: number): ReactNode => {
            let i = index
            if (hasHeader) {
                if (i === 0) {
                    return header
                }
                i -= 1
            }
            if (i < items.length) {
                return children(items[i], i)
            }
            return footer
        },
        [items, header, footer, hasHeader, children]
    )

    // Wrap the user key with the header/footer offset so measurement is cached by a stable key: prepends and
    // replay-reorders reuse a row's measured height instead of re-measuring by index.
    const getVirtualItemKey = useCallback(
        (index: number): string => {
            let i = index
            if (hasHeader) {
                if (i === 0) {
                    return HEADER_KEY
                }
                i -= 1
            }
            if (i < items.length) {
                return getItemKey(items[i], i)
            }
            // Constant, and it has to be: the core reads an append off the row *count* alone
            // (`didCountChange || edge keys differ`), so appends reach its end-anchoring without the
            // footer key rotating. Rotating it — which an earlier `followOnAppend` config did need, and
            // that option is off now — charged a scroll correction per appended row: a fresh key misses
            // the measurement cache, the always-mounted footer falls back to `defaultRowHeight` for a
            // frame, and the core's at-end compensation applies that estimate error to the scroll offset.
            // Tens of px of shove per streamed row, right where the reader is trying to scroll away.
            return FOOTER_KEY
        },
        [items, getItemKey, hasHeader]
    )

    // Delayed loops read the resolver through this ref: the one a timer captured resolves keys against the items
    // of the render that started it, and older rows loaded since would shift every index.
    const findVirtualIndexForKeyRef = useRef<(key: string) => number>(() => -1)
    const findVirtualIndexForKey = useCallback(
        (key: string): number => {
            // Scan from the end — the anchor (a recent human message) is near the tail in practice.
            for (let i = rowCount - 1; i >= 0; i--) {
                if (getVirtualItemKey(i) === key) {
                    return i
                }
            }
            return -1
        },
        [rowCount, getVirtualItemKey]
    )

    // Measured heights include the gap padding (see `Row`), so estimates must too — otherwise every first
    // measurement carries a built-in error that gets compensated as a scroll-position correction.
    const estimateVirtualRow = useCallback(
        (index: number): number => {
            let i = index
            if (hasHeader) {
                if (i === 0) {
                    return defaultRowHeight + gap
                }
                i -= 1
            }
            if (i < items.length) {
                return (estimateItemHeight?.(items[i], i) ?? defaultRowHeight) + gap
            }
            return defaultRowHeight + gap
        },
        [items, hasHeader, estimateItemHeight, defaultRowHeight, gap]
    )

    findVirtualIndexForKeyRef.current = findVirtualIndexForKey
    const holdTopRowRef = useRef<(itemsChanged: boolean) => void>(() => {})
    // Rows put in front of the items, with the last row unchanged: older history loading above the reader.
    const committedEdgeKeysRef = useRef<{ first: unknown; last: unknown } | null>(null)
    const firstItemKey = items.length > 0 ? getItemKey(items[0], 0) : null
    const lastItemKey = items.length > 0 ? getItemKey(items[items.length - 1], items.length - 1) : null
    const committedEdgeKeys = committedEdgeKeysRef.current
    const prepending =
        committedEdgeKeys !== null &&
        firstItemKey !== null &&
        firstItemKey !== committedEdgeKeys.first &&
        lastItemKey === committedEdgeKeys.last
    useLayoutEffect(() => {
        committedEdgeKeysRef.current = { first: firstItemKey, last: lastItemKey }
    }, [firstItemKey, lastItemKey])
    const virtualizer = useVirtualizer({
        count: rowCount,
        getScrollElement: () => scrollRef.current,
        estimateSize: estimateVirtualRow,
        overscan: overscanCount,
        getItemKey: getVirtualItemKey,
        paddingEnd: endInset,
        onChange: () => holdTopRowRef.current(false),
        // The virtualizer writes container height + row offsets to the DOM itself, in the same tick as each
        // measurement — no stale-offset overlap while rows measure, and React re-renders only on range change.
        directDomUpdates: true,
        // The default `elementScroll`, wrapped so every scroll write the core performs is recorded for
        // the scroll listener's programmatic-vs-reader test (see `programmaticScrollsRef`) and for
        // `hasUnseenScroll` (see `lastSeenTopRef`). Recorded *after* the write, from the element — `scrollTo`
        // applies synchronously, so this is the value the write actually produced, clamping included.
        scrollToFn: (offset, options, instance) => {
            elementScroll(offset, options, instance)
            recordScrollWrite(instance.scrollElement?.scrollTop ?? offset + (options.adjustments ?? 0))
        },
        // No `gap` — inter-row spacing is baked into the measured row height via `paddingBottom` (see `Row`).
        ...(stickToBottom
            ? {
                  // `anchorTo: 'end'` re-anchors on count/edge-key change (append/prepend/reorder) and the
                  // core's resize handling compensates height-only growth (token streaming) while within
                  // `scrollEndThreshold` of the end. Bottom-pinning itself is owned by the explicit
                  // pinned-state effects below, not the core (`followOnAppend` stays off). End-anchoring
                  // is strictly a pinned-state behavior: its key/count anchoring applies on every append
                  // with no threshold check, so with it always on, a reader away from the bottom is glued
                  // back to the end whenever rows land — it overrode the opening anchor scroll within
                  // milliseconds while a history replay was still folding in. Off during `itemsLoading`
                  // too: end-anchoring each partial fold walks the core's *internal* offset to the
                  // bottom, and that internal offset only re-syncs via async scroll events — so the
                  // opening anchor scroll lands, the next measurement batch compensates against the
                  // stale bottom offset, and the landing is yanked straight back down.
                  // A prepend end-anchors too, unpinned: the core then keeps the row under the reader at its offset
                  // before it computes the rendered range, so the visible rows stay mounted (and keep their open
                  // state) instead of unmounting for a frame until the prepend effect below corrects the scroll.
                  anchorTo: itemsLoading || (!pinnedRef.current && !prepending) ? ('start' as const) : ('end' as const),
                  // The core's growth compensation (`resizeItem` re-applying a row's growth to the scroll
                  // offset whenever that offset is within this many px of the end) writes `scrollTop`
                  // synchronously, with no scroll-direction check and no knowledge of our pinned flag. At
                  // 32px that turns the bottom of the thread into flypaper: an upward gesture that stops
                  // inside the band is shoved back down by the next streamed token, the shove arrives as
                  // a downward scroll, and the re-pin test below reads *that* as the reader coming back.
                  // So the band exists only while we consider ourselves pinned, where it does its real
                  // job of smoothing growth that lands between our follow writes; unpinned, nothing but
                  // the reader may move the view — which is also what lets the re-pin test trust downward
                  // motion. Read from the ref, not from state: `useVirtualizer` calls `setOptions` during
                  // render, so the ref applies with no extra render per toggle mid-stream, and `setPinned`
                  // below covers the sub-frame window before that render happens.
                  scrollEndThreshold: pinnedRef.current && !itemsLoading ? BOTTOM_THRESHOLD : NO_END_COMPENSATION,
                  // Seed the virtual offset so the very first render window already emits the right rows
                  // (not a blank top frame): the anchor row's estimated start when opening onto an anchor,
                  // past the end for a plain bottom open. Summing the row estimates keeps this exact
                  // whatever `estimateItemHeight` returns; the pre-paint `scrollToIndex` below lands it.
                  // The seed is the core's *internal* offset only — nothing scrolls the DOM to it — so it
                  // is valid solely when the opening scroll runs in the same commit and converges the two.
                  // Mounting mid-load (the open deferred, the DOM resting at 0) it must be 0: any other
                  // value desyncs internal from DOM, and every first row measurement then "compensates"
                  // the phantom position, deterministically dragging the real scroll toward it.
                  initialOffset: () => {
                      if (itemsLoading) {
                          return 0
                      }
                      const savedIndex = savedReadItem.current ? findVirtualIndexForKey(savedReadItem.current) : -1
                      const anchorIndex =
                          savedIndex >= 0
                              ? savedIndex
                              : anchorItemKey != null
                                ? findVirtualIndexForKey(anchorItemKey)
                                : -1
                      const limit = anchorIndex >= 0 ? anchorIndex : rowCount
                      let total = 0
                      for (let i = 0; i < limit; i++) {
                          total += estimateVirtualRow(i)
                      }
                      return total
                  },
              }
            : {}),
    })

    useEffect(() => {
        const element = scrollRef.current
        if (!scrollRestorationKey || !element || itemsLoading) {
            return
        }
        const rememberPosition = (): void => {
            if (!didInitialScrollRef.current || element.clientHeight === 0 || element.clientWidth === 0) {
                return
            }
            // `item.key`, not a re-derivation from `item.index`: the virtualizer produced that key from
            // its current `getItemKey`, while this listener is only re-bound in the passive phase, so a
            // scroll event arriving after an append can otherwise map a new index through the old `items`.
            const firstVisibleItem = virtualizer.getVirtualItems().find((item) => {
                const itemKey = String(item.key)
                return item.end > element.scrollTop && itemKey !== HEADER_KEY && !itemKey.startsWith(FOOTER_KEY)
            })
            if (firstVisibleItem) {
                lastReadItems.delete(scrollRestorationKey)
                lastReadItems.set(scrollRestorationKey, String(firstVisibleItem.key))
                if (lastReadItems.size > 100) {
                    lastReadItems.delete(lastReadItems.keys().next().value!)
                }
            }
        }
        element.addEventListener('scroll', rememberPosition, { passive: true })
        return () => element.removeEventListener('scroll', rememberPosition)
    }, [scrollRestorationKey, virtualizer, itemsLoading])

    // The only way to flip pinning. Two pins have to move together and in the same tick as the gesture:
    // ours, and the core's at-end growth compensation, which is a second pin we do not otherwise control.
    // Writing the option here is not a duplicate of the render-time value — it is the bridge across one
    // frame. Unpinning originates in a passive wheel/touch/scroll listener, so React schedules the render
    // that would carry the new option for after the current task, while the ResizeObserver that grows the
    // streaming row fires inside it: without this write the core gets one more shove in, on exactly the
    // frame the reader's gesture starts.
    const setPinned = useCallback(
        (next: boolean): void => {
            if (pinnedRef.current === next) {
                return
            }
            pinnedRef.current = next
            setPinnedState(next)
            virtualizer.options.scrollEndThreshold = next ? BOTTOM_THRESHOLD : NO_END_COMPENSATION
            virtualizer.options.anchorTo = next ? 'end' : 'start'
            if (next) {
                peakTopRef.current = scrollRef.current?.scrollTop ?? 0
            }
        },
        [virtualizer]
    )

    // The first item row whose bottom is below the viewport top, from the measurement cache (which covers every
    // row, rendered or not, so it stays right after a programmatic scroll the virtualizer has not seen yet).
    const rememberTopRow = useCallback((): void => {
        const el = scrollRef.current
        if (!el) {
            return
        }
        const top = el.scrollTop
        const rows = virtualizer.measurementsCache
        let low = 0
        let high = rows.length - 1
        let first = rows.length
        while (low <= high) {
            const middle = (low + high) >> 1
            if (rows[middle].end > top) {
                first = middle
                high = middle - 1
            } else {
                low = middle + 1
            }
        }
        // The header and footer never move relative to the items around them, so they cannot hold a place.
        const row = rows.slice(first).find((item) => item.key !== HEADER_KEY && item.key !== FOOTER_KEY)
        topRowRef.current = row ? { key: String(row.key), offset: row.start - top, start: row.start } : null
    }, [virtualizer])

    // Every scroll the component performs itself goes through here. The peak records where the *reader*
    // has been, so a landing we caused — a replayed anchor jumping to a row mid-thread, the initial open,
    // a follow write — has to reset it; otherwise the scroll event our own jump emits reads as the reader
    // walking away and unpins on the spot (the slack is sub-pixel, it forgives nothing).
    const noteProgrammaticScroll = useCallback((): void => {
        const top = scrollRef.current?.scrollTop ?? 0
        peakTopRef.current = top
        recordScrollWrite(top)
        rememberTopRow()
    }, [recordScrollWrite, rememberTopRow])

    // Hold an unpinned anchor landing steady while the thread's measurements settle (see the settle
    // constants). Re-asserts via `scrollToIndex` so the corrective write re-computes the offset from the
    // freshest measurements; stands down permanently the moment the reader scrolls or the thread pins
    // (a pinned thread belongs to the follow effect).
    const scheduleAnchorSettle = useCallback(
        (anchorKey: string): void => {
            const startedAt = performance.now()
            let remaining = ANCHOR_SETTLE_CHECKS
            const tick = (): void => {
                const el = scrollRef.current
                if (!el || lastUserScrollAtRef.current > startedAt || pinnedRef.current) {
                    return
                }
                // Resolved per tick: older rows put in front of the items move the anchor's index.
                const anchorIndex = findVirtualIndexForKeyRef.current(anchorKey)
                if (anchorIndex < 0) {
                    return
                }
                const target = virtualizer.getOffsetForIndex(anchorIndex, 'start')?.[0]
                if (
                    target !== undefined &&
                    !hasUnseenScroll(el, lastSeenTopRef.current) &&
                    Math.abs(el.scrollTop - target) > ANCHOR_SETTLE_TOLERANCE_PX
                ) {
                    virtualizer.scrollToIndex(anchorIndex, { align: 'start' })
                    noteProgrammaticScroll()
                }
                remaining -= 1
                if (remaining > 0) {
                    setTimeout(tick, ANCHOR_SETTLE_INTERVAL_MS)
                }
            }
            setTimeout(tick, ANCHOR_SETTLE_INTERVAL_MS)
        },
        [virtualizer, noteProgrammaticScroll]
    )

    // The open's top-or-bottom verdict, re-taken once real measurements exist. The opening commit only
    // has estimates for the rows under the anchor (they render and measure a few frames later), and the
    // estimates habitually undershoot real markdown — deciding from them alone opens threads with a
    // viewport of response at the bottom instead of on the question. So the open lands on the anchor
    // provisionally (the scroll clamps to the bottom by itself when content is truly short) and this
    // loop settles the verdict: enough content measured below ⇒ the anchor stands; the window ending
    // still short — or the live stream appending before it ends, which makes the open a live-edge open —
    // ⇒ a bottom open, pinned. Stops the moment the reader scrolls: their position, their call.
    const scheduleOpenDecision = useCallback(
        (anchorKey: string): void => {
            const startedAt = performance.now()
            // The tail row, not the row count: older rows put in front change the count without the stream
            // appending anything.
            const tailAtOpen = lastItemKeyRef.current
            let remaining = ANCHOR_SETTLE_CHECKS
            const commitBottomOpen = (el: HTMLElement): void => {
                el.scrollTop = el.scrollHeight
                noteProgrammaticScroll()
                setPinned(true)
            }
            const tick = (): void => {
                const el = scrollRef.current
                if (!el || lastUserScrollAtRef.current > startedAt || pinnedRef.current) {
                    return
                }
                const viewport = el.clientHeight
                const totalSize = virtualizer.getTotalSize()
                const anchorIndex = findVirtualIndexForKeyRef.current(anchorKey)
                const anchorStart = anchorIndex >= 0 ? virtualizer.measurementsCache[anchorIndex]?.start : undefined
                const contentBelow = anchorStart !== undefined ? totalSize - anchorStart : 0
                if (viewport > 0 && contentBelow >= viewport) {
                    return
                }
                remaining -= 1
                const verdictDue = lastItemKeyRef.current !== tailAtOpen || remaining === 0
                if (verdictDue && !hasUnseenScroll(el, lastSeenTopRef.current)) {
                    commitBottomOpen(el)
                } else if (remaining > 0) {
                    setTimeout(tick, ANCHOR_SETTLE_INTERVAL_MS)
                }
            }
            setTimeout(tick, ANCHOR_SETTLE_INTERVAL_MS)
        },
        [virtualizer, noteProgrammaticScroll, setPinned]
    )

    // Rows that land above the reader (a history page loading in front, or the fold placing an older row
    // under the first message) must not move what the reader sees. When the items change and the first row that
    // was on screen has moved, it goes back to the same offset from the viewport top before paint. The rows that
    // landed render at estimated heights and measure a frame or two later, so measured-size changes keep
    // correcting for a short hold; outside it, measurement belongs to the settle loops and the core.
    const totalSize = virtualizer.getTotalSize()
    const previousItemsRef = useRef(items)
    const prependHoldRef = useRef({ from: 0, until: 0 })
    // Also called from the virtualizer's measurement notifications: with direct DOM updates, a row that grows
    // without changing the rendered range skips React, so the layout effect alone would miss it.
    holdTopRowRef.current = (itemsChanged: boolean): void => {
        const el = scrollRef.current
        const topRow = topRowRef.current
        // A thread following a live reply belongs to the follow effect; holding a row would pull it back up.
        if (!virtualized || !el || !topRow || (pinnedRef.current && followingRef.current)) {
            return
        }
        const hold = prependHoldRef.current
        const holding = performance.now() < hold.until && lastUserScrollAtRef.current <= hold.from
        if (!itemsChanged && !holding) {
            return
        }
        const index = findVirtualIndexForKeyRef.current(topRow.key)
        const start = index >= 0 ? virtualizer.measurementsCache[index]?.start : undefined
        if (start === undefined || Math.abs(start - topRow.start) <= UNPIN_SLACK) {
            return
        }
        // A reader's scroll whose event has not dispatched yet still moved the view: the correction keeps that
        // movement, and the hold ends so a later measurement cannot reverse it.
        const pending = hasUnseenScroll(el, lastSeenTopRef.current) ? el.scrollTop - lastSeenTopRef.current : 0
        if (itemsChanged) {
            rowsLandedAboveRef.current = true
        }
        if (pending !== 0) {
            prependHoldRef.current = { from: 0, until: 0 }
        } else if (itemsChanged) {
            prependHoldRef.current = { from: performance.now(), until: performance.now() + PREPEND_HOLD_MS }
        }
        topRowRef.current = { ...topRow, start }
        const target = start - topRow.offset + pending
        if (Math.abs(el.scrollTop - target) > UNPIN_SLACK) {
            el.scrollTop = target
            noteProgrammaticScroll()
        }
    }
    useLayoutEffect(() => {
        const itemsChanged = previousItemsRef.current !== items
        previousItemsRef.current = items
        holdTopRowRef.current(itemsChanged)
    }, [items, totalSize])

    // A thread shorter than its viewport has no scroll to bring the reader near the top, so ask for older
    // rows directly until it fills the viewport or the caller has none left. A reader who scrolled near the
    // top and stays there sends no scroll event when older rows become available again (after a failed
    // load waits and rearms), so that reader asks too.
    useEffect(() => {
        const el = scrollRef.current
        if (!virtualized || !el || el.clientHeight === 0) {
            return
        }
        const short = el.scrollHeight <= el.clientHeight + UNPIN_SLACK
        const readerNearTop = lastUserScrollAtRef.current > 0 && el.scrollTop < el.clientHeight
        if (short || readerNearTop) {
            onNearTopRef.current?.()
        }
    }, [items, onNearTop, virtualized])

    // Initial open (once): land before the browser paints, so a long thread never shows a top-frame
    // flicker or a visible crawl. A thread that already has messages opens on its last meaningful turn —
    // the anchor row (the last human message) at the top of the viewport, its response below — whether or
    // not the agent is still working on it: a reader arriving mid-turn wants the question that was asked,
    // not the tail of the answer to it. That is only possible when at least a viewport of content follows
    // the anchor; with less, the scroll clamps and the open is a plain bottom open — no padding is ever
    // reserved to force the anchor higher, the message just sits wherever the content puts it. No anchor
    // ⇒ bottom open too.
    //
    // Whether the landing starts pinned follows from its kind: an anchor at the top is a reading
    // position, so it unpins and streaming must not steal it; a bottom open pins, following from the
    // first frame whenever a turn is live.
    // Waits for the items to finish assembling, not merely for one to exist: the run-context header and
    // the thinking footer can commit before any message does, and with debug rows enabled the history
    // replay's earliest fold commits carry renderable console items long before the human turns land.
    // Spending the once-only open on such a commit finds no anchor and opens the thread at the bottom.
    useLayoutEffect(() => {
        if (!virtualized || !stickToBottom || didInitialScrollRef.current || itemsLoading || items.length === 0) {
            return
        }
        didInitialScrollRef.current = true
        const savedIndex = savedReadItem.current ? findVirtualIndexForKey(savedReadItem.current) : -1
        const anchorIndex =
            savedIndex >= 0 ? savedIndex : anchorItemKey != null ? findVirtualIndexForKey(anchorItemKey) : -1
        const landingKey = savedIndex >= 0 ? savedReadItem.current : anchorItemKey
        const el = scrollRef.current
        if (anchorIndex >= 0 && landingKey) {
            // Provisional anchor landing — this commit only has estimates for the rows under the anchor,
            // so whether the thread is really "top" or "bottom" shaped is decided by the decision loop
            // once measurements land (see `scheduleOpenDecision`). The scroll itself is safe under
            // either truth: a genuinely short thread clamps to the bottom on its own. The reconciler
            // this arms re-targets a *stable* offset — rows above the anchor don't move when the tail
            // grows — so it settles in a frame or two; the settle loop then covers the drift the
            // reconciler can't (see `scheduleAnchorSettle`).
            virtualizer.scrollToIndex(anchorIndex, { align: 'start' })
            noteProgrammaticScroll()
            setPinned(false)
            bottomRepinBlockedUntilRef.current = performance.now() + BOTTOM_REPIN_BLOCK_MS
            scheduleAnchorSettle(landingKey)
            if (savedIndex < 0) {
                scheduleOpenDecision(landingKey)
            }
            return
        }
        if (turnActive && el) {
            // Deliberately not `scrollToIndex` for a thread that is already streaming: that arms the
            // core's reconciler against a target that never stabilizes — it recomputes the growing end
            // every frame for up to five seconds, with no notion of a user gesture cancelling it, so
            // every upward scroll the reader attempts in that window is undone. The follow effect below
            // owns the landing instead: it holds the bottom as rows measure and yields the moment the
            // reader scrolls away.
            el.scrollTop = el.scrollHeight
        } else {
            // Settled thread: nothing is growing, so the reconciler's target stabilizes within a frame
            // or two, and it is the accurate way to land on the last row's end while rows are
            // unmeasured.
            virtualizer.scrollToIndex(rowCount - 1, { align: 'end' })
        }
        noteProgrammaticScroll()
        setPinned(true)
    }, [
        virtualized,
        stickToBottom,
        rowCount,
        virtualizer,
        turnActive,
        anchorItemKey,
        itemsLoading,
        findVirtualIndexForKey,
        noteProgrammaticScroll,
        setPinned,
        scheduleAnchorSettle,
        scheduleOpenDecision,
        items.length,
    ])

    // Anchor-on-change (see `anchorItemKey`): a key change means a new anchor row landed. An anchor the
    // thread has never held before is a fresh send — pin to the bottom and follow the answer from there;
    // the sent message rides up naturally as the response streams in. An anchor whose key already
    // existed (a replayed turn) just scrolls to it. Novelty, not position: the fold inserts a sent
    // message at the *turn start*, behind any debug/status rows the turn already carries, so on a send
    // the anchor is frequently not the trailing item and any is-it-last test classifies the send by
    // whichever frames happened to land first. The first populated commit only adopts the key: the
    // initial-open effect above owns that scroll.
    // Gated on `itemsLoading` like the initial open — adopting mid-replay would pin the pre-history
    // anchor value (typically null) and misread the full history's anchor as a fresh send.
    useLayoutEffect(() => {
        const rowsLandedAbove = rowsLandedAboveRef.current
        rowsLandedAboveRef.current = false
        if (!virtualized || itemsLoading || items.length === 0) {
            return
        }
        const prevKeys = prevItemKeysRef.current
        prevItemKeysRef.current = new Set(items.map((item, index) => getItemKey(item, index)))
        const prev = prevAnchorKeyRef.current
        if (prev === undefined) {
            prevAnchorKeyRef.current = anchorItemKey ?? null
            return
        }
        if (anchorItemKey == null || anchorItemKey === prev) {
            return
        }
        prevAnchorKeyRef.current = anchorItemKey
        const anchorIndex = findVirtualIndexForKey(anchorItemKey)
        if (anchorIndex < 0) {
            return
        }
        if (rowsLandedAbove) {
            // History that loaded above the reader brought this anchor; the prepend effect already holds the
            // reader's row, so adopting the key is all there is to do.
            return
        }
        const isFreshSend = prevKeys === null || !prevKeys.has(anchorItemKey)
        if (!isFreshSend) {
            virtualizer.scrollToIndex(anchorIndex, { align: 'start' })
            noteProgrammaticScroll()
            // Same estimate-clamp settle as the initial open: the landing may touch the bottom
            // transiently, and those touches must not read as the reader arriving there.
            bottomRepinBlockedUntilRef.current = performance.now() + BOTTOM_REPIN_BLOCK_MS
            scheduleAnchorSettle(anchorItemKey)
            return
        }
        // Sending is an explicit request to follow the answer, wherever the reader had scrolled to
        // while composing — pin and land on the bottom now rather than leaving it to the reader; the
        // follow effect keeps it there as the turn streams.
        setPinned(true)
        const el = scrollRef.current
        if (el) {
            el.scrollTop = el.scrollHeight
            noteProgrammaticScroll()
        }
    }, [
        virtualized,
        items,
        getItemKey,
        anchorItemKey,
        itemsLoading,
        findVirtualIndexForKey,
        virtualizer,
        setPinned,
        noteProgrammaticScroll,
        scheduleAnchorSettle,
    ])

    // Pin/unpin from what the reader did, not from where they ended up. Movement that the scroll range
    // itself doesn't explain is the reader; everything else is content shifting under them. Asymmetric on
    // purpose: leaving takes the smallest upward movement, because a gesture the view fights is the whole
    // complaint, while returning takes an actual arrival at the bottom, because anything looser re-arms
    // the follow while the reader is still reading a few lines up.
    //
    // The wheel and touch listeners catch the *first* frame — they fire before the scroll they cause, and
    // they register even when the offset can't move (already at the top, or the frame's growth cancels the
    // gesture out). The scroll listener catches everything without a gesture event: scrollbar drags,
    // PageUp, momentum.
    useEffect(() => {
        const el = scrollRef.current
        if (!virtualized || !stickToBottom || !el) {
            return
        }
        peakTopRef.current = el.scrollTop
        let touchStartY: number | null = null
        let touchStartX: number | null = null
        const resumeAtBottom = (): void => {
            bottomRepinBlockedUntilRef.current = 0
            // At the end, a downward gesture cannot emit a scroll event. It must still resume following.
            if (el.scrollHeight - el.clientHeight - el.scrollTop <= AT_BOTTOM_EPSILON) {
                setPinned(true)
            }
        }
        const onWheel = (event: WheelEvent): void => {
            if (event.deltaY !== 0) {
                lastUserScrollAtRef.current = performance.now()
            }
            if (event.deltaY < 0) {
                setPinned(false)
            } else if (event.deltaY > 0) {
                // An explicit downward gesture is unambiguous — the reader heading for the bottom must
                // not be told "not yet" by the post-landing block.
                resumeAtBottom()
            }
        }
        const onTouchStart = (event: TouchEvent): void => {
            const touch = event.touches[0]
            touchStartY = touch?.clientY ?? null
            touchStartX = touch?.clientX ?? null
        }
        // A finger moving *down* scrolls the content up. Vertical dominance is required so a horizontal
        // swipe across a wide tool card or code block doesn't read as leaving the bottom.
        const onTouchMove = (event: TouchEvent): void => {
            const touch = event.touches[0]
            if (!touch || touchStartY === null || touchStartX === null) {
                return
            }
            const deltaY = touch.clientY - touchStartY
            if (Math.abs(deltaY) > Math.abs(touch.clientX - touchStartX)) {
                lastUserScrollAtRef.current = performance.now()
                if (deltaY > 0) {
                    setPinned(false)
                } else if (deltaY < 0) {
                    // Finger moving up scrolls the content down — the same explicit "heading for the
                    // bottom" signal as a downward wheel, so it clears the post-landing block too.
                    resumeAtBottom()
                }
            }
        }
        const onScroll = (): void => {
            const top = el.scrollTop
            lastSeenTopRef.current = top
            rememberTopRow()
            if (top < el.clientHeight) {
                onNearTopRef.current?.()
            }
            const maxTop = Math.max(0, el.scrollHeight - el.clientHeight)
            // Content shrinking under the reader — a tool card's accordion collapsing the moment the tool
            // completes, which on this surface is every finished tool — lowers the scroll range, and the
            // browser clamps `scrollTop` down with it. That
            // is an offset decrease nobody asked for, and reading it as a gesture would unpin the thread
            // mid-turn every time a tool finished. A clamp can never pull below the new maximum, so the
            // maximum is the line between "the content moved" and "the reader moved". Growth needs no
            // such correction: it moves `scrollHeight`, never `scrollTop`.
            peakTopRef.current = Math.min(peakTopRef.current, maxTop)
            // An event that lands where software recently wrote is a write echoing back, not the reader
            // (see `programmaticScrollsRef`) — adopt the position and decide nothing from it. A reader
            // gesture racing this window still lands on a different offset (or came in as a wheel/touch
            // event, which unpins before any scroll event fires).
            const now = performance.now()
            const writes = programmaticScrollsRef.current
            while (writes.length > 0 && now - writes[0].at >= PROGRAMMATIC_SCROLL_MATCH_MS) {
                writes.shift()
            }
            const prevEventTop = lastScrollEventTopRef.current
            lastScrollEventTopRef.current = top
            if (writes.some((write) => Math.abs(top - Math.min(Math.max(0, write.value), maxTop)) <= UNPIN_SLACK)) {
                peakTopRef.current = top
                return
            }
            // A downward move that lands exactly on the (new) maximum is the shrink clamp again — no
            // write explains it because the browser performed it, and counting it as the reader would
            // cancel a settle loop the moment a tool card above collapses.
            const isShrinkClamp = prevEventTop !== null && top < prevEventTop && top >= maxTop - UNPIN_SLACK
            if (!isShrinkClamp) {
                lastUserScrollAtRef.current = performance.now()
            }
            if (pinnedRef.current) {
                if (top < peakTopRef.current - UNPIN_SLACK) {
                    setPinned(false)
                } else {
                    peakTopRef.current = Math.max(peakTopRef.current, top)
                }
                return
            }
            if (
                followingRef.current &&
                maxTop - top <= AT_BOTTOM_EPSILON &&
                performance.now() >= bottomRepinBlockedUntilRef.current
            ) {
                setPinned(true)
            }
        }
        el.addEventListener('wheel', onWheel, { passive: true })
        el.addEventListener('touchstart', onTouchStart, { passive: true })
        el.addEventListener('touchmove', onTouchMove, { passive: true })
        // Capture phase, so this listener runs before the virtualizer's own scroll listener on the same
        // element. That listener re-renders this component synchronously when the reader's scroll changes the
        // rendered range, and the follow effect in that re-render would write the bottom back while the
        // thread still counts as pinned.
        el.addEventListener('scroll', onScroll, { passive: true, capture: true })
        return () => {
            el.removeEventListener('wheel', onWheel)
            el.removeEventListener('touchstart', onTouchStart)
            el.removeEventListener('touchmove', onTouchMove)
            el.removeEventListener('scroll', onScroll, { capture: true })
        }
        // Deliberately not keyed on the pinned state: re-subscribing mid-gesture would reset the peak
        // baseline, which is the one thing that has to survive a gesture.
    }, [virtualized, stickToBottom, setPinned, rememberTopRow])

    // The turn's tail arrives after the turn is over — usage and cost come on their own stream frames and
    // the footer swaps to them a commit or two later — so following has to outlast `turnActive` by a beat
    // or that last row renders just below the fold. Timed rather than keyed on the content itself: what
    // lands after a turn ends is open-ended, and the grace costs nothing because an upward gesture unpins
    // through it just the same.
    useEffect(() => {
        const wasActive = prevTurnActiveRef.current
        prevTurnActiveRef.current = turnActive
        if (turnActive || !wasActive) {
            setFollowGrace(false)
            return
        }
        setFollowGrace(true)
        const timeout = setTimeout(() => setFollowGrace(false), FOLLOW_GRACE_MS)
        return () => clearTimeout(timeout)
    }, [turnActive])

    // Runs every commit: while a turn is live (or just ended, see above) and the reader is pinned, keep
    // the bottom in view. Each streamed frame is a commit, so this needs no other trigger; the core's
    // at-end resize compensation smooths growth that lands between commits. Writes `scrollTop` directly
    // instead of `scrollToEnd()`: the latter arms the core's multi-frame scroll reconciler, which
    // re-targets the (growing) end every frame and overrides the user's attempt to scroll away —
    // exactly the gesture that must win here.
    useLayoutEffect(() => {
        // Inert while items are still assembling: following a partial fold would walk the scroll to the
        // bottom of a thread whose open — which owns the landing — hasn't happened yet.
        if (!virtualized || !stickToBottom || itemsLoading || !following || !pinnedRef.current) {
            return
        }
        const el = scrollRef.current
        if (el && el.scrollHeight - el.scrollTop - el.clientHeight > AT_BOTTOM_EPSILON) {
            el.scrollTop = el.scrollHeight
            noteProgrammaticScroll()
        }
    })

    // Mobile Safari: the soft keyboard shrinks the visual (not layout) viewport, so a pinned bottom can slip
    // behind it. Re-assert on visualViewport changes — for a reader who is actually pinned; a proximity
    // check here would be the last place a bottom band could yank back someone who scrolled away.
    useEffect(() => {
        if (!virtualized || !stickToBottom || typeof window === 'undefined' || !window.visualViewport) {
            return
        }
        const viewport = window.visualViewport
        const onViewportChange = (): void => {
            if (!pinnedRef.current) {
                return
            }
            // By hand, not `scrollToEnd()`, for the same reason the follow effect writes `scrollTop`
            // itself: that call arms the core's multi-frame reconciler, which the reader cannot interrupt.
            requestAnimationFrame(() => {
                const el = scrollRef.current
                if (el && el.scrollHeight - el.scrollTop - el.clientHeight > AT_BOTTOM_EPSILON) {
                    el.scrollTop = el.scrollHeight
                    noteProgrammaticScroll()
                }
            })
        }
        viewport.addEventListener('resize', onViewportChange)
        viewport.addEventListener('scroll', onViewportChange)
        return () => {
            viewport.removeEventListener('resize', onViewportChange)
            viewport.removeEventListener('scroll', onViewportChange)
        }
    }, [virtualized, stickToBottom, noteProgrammaticScroll])

    const lastIndex = virtualized ? rowCount - 1 : -1
    const rootValue = useMemo<RootContextValue>(
        () => ({
            measureElement: virtualizer.measureElement,
            gap,
            lastIndex,
            maxWidthClassName,
            virtualized,
            isFollowing: stickToBottom && (!virtualized || pinned),
            pauseFollowing: () => setPinned(false),
        }),
        [virtualizer, gap, lastIndex, maxWidthClassName, virtualized, stickToBottom, pinned, setPinned]
    )

    // Flow mode: render rows directly so an ancestor scroll container (and its auto-scroller) keeps working.
    // No chrome here — the parent supplies gap/centering/container-query context, matching the pre-virtualized
    // layout exactly.
    if (!virtualized) {
        return (
            <RootContext.Provider value={rootValue}>
                <FlowRows
                    items={items}
                    getItemKey={getItemKey}
                    header={hasHeader ? header : null}
                    footer={hasFooter ? footer : null}
                    footerIndex={rowCount - 1}
                    render={children}
                />
            </RootContext.Provider>
        )
    }

    return (
        <RootContext.Provider value={rootValue}>
            <div className={cn('flex flex-col h-full min-h-0 w-full', className)}>
                {/*
                 * `overflow-anchor: none` because the virtualizer already owns every row's position and
                 * compensates content growth itself. Chrome's native scroll anchoring would compensate the
                 * same growth a second time — the rows are absolutely positioned inside the scroller, so
                 * they are anchor candidates, not excluded — and two independent corrections for one
                 * resize is a shake by construction.
                 */}
                <div
                    ref={scrollRef}
                    className={cn(
                        'flex-1 min-h-0 overflow-y-auto overflow-x-hidden overscroll-contain [overflow-anchor:none] [scrollbar-gutter:stable]',
                        listClassName
                    )}
                >
                    {/* Height is written imperatively by the virtualizer (`containerRef` + `directDomUpdates`). */}
                    <div ref={virtualizer.containerRef} style={{ position: 'relative', width: '100%' }}>
                        {virtualizer.getVirtualItems().map((vi) => (
                            <InternalRow key={String(vi.key)} index={vi.index} renderRow={renderRow} />
                        ))}
                    </div>
                </div>
            </div>
        </RootContext.Provider>
    )
}

/**
 * Row shell for content rendered inside `VirtualizedThread.Root`. Registers itself with the virtualizer
 * (which measures it and positions it directly in the DOM), measures its own height (gap included via
 * bottom padding), and centers content with the thread's container-query context.
 */
function Row({ children, className }: { children: ReactNode; className?: string }): JSX.Element {
    const root = useContext(RootContext)
    const row = useContext(VirtualizedThreadRowContext)
    if (!root || !row) {
        throw new Error('VirtualizedThread.Row must be rendered inside VirtualizedThread.Root')
    }
    const { measureElement, gap, lastIndex, maxWidthClassName, virtualized } = root
    const { index } = row

    // Re-registers the node whenever `index` changes: the virtualizer's element cache (which both direct
    // DOM positioning and measurement read) is addressed by the row's *virtual key*, and a row can change
    // key without remounting — the footer's key rotates on every append. Writing `data-index` here (not as
    // a JSX prop) keeps the attribute and the registration in one atomic step, so the virtualizer never
    // reads a stale index off the node.
    const measureRef = useCallback(
        (node: HTMLDivElement | null): void => {
            if (node) {
                node.setAttribute('data-index', String(index))
            }
            measureElement(node)
        },
        [measureElement, index]
    )

    // Flow mode: transparent — the parent container provides spacing and centering.
    if (!virtualized) {
        return <>{children}</>
    }

    // The outer element carries only the static positioning base (never a fixed height or offset — the
    // virtualizer writes `translate3d` to it directly); TanStack's `measureElement` attaches a border-box
    // `ResizeObserver` to it, so the cached height always tracks content growth — tool output
    // expand/collapse, streaming markdown, a late-loading image — and includes the gap padding on the
    // child. Border-box measurement is transform-safe, so the imperative positioning does not distort it.
    return (
        <div ref={measureRef} style={ROW_BASE_STYLE}>
            {/* A row whose content renders nothing (such as the trailing row between turns) takes no space, so the thread does not jump. */}
            <div
                className={cn('w-full mx-auto @container/thread empty:hidden', maxWidthClassName, className)}
                style={{ paddingBottom: index === lastIndex ? 0 : gap }}
            >
                {children}
            </div>
        </div>
    )
}

const noop = (): void => {}

function usePauseFollowing(): () => void {
    return useContext(RootContext)?.pauseFollowing ?? noop
}

function useIsFollowing(): boolean {
    return useContext(RootContext)?.isFollowing ?? false
}

export const VirtualizedThread = { Root, Row, usePauseFollowing, useIsFollowing }