Skip to content

The agent that grows with you

68.4 KB
Raw Blame
import { ThreadPrimitive, useAuiEvent, useAuiState } from '@assistant-ui/react'
import { useStore } from '@nanostores/react'
import { atom } from 'nanostores'
import {
  type ComponentProps,
  type CSSProperties,
  type FC,
  memo,
  type ReactNode,
  startTransition,
  useCallback,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useState
} from 'react'
import { type GetTargetScrollTop, useStickToBottom } from 'use-stick-to-bottom'

import { useComposerSurfaceId } from '@/app/chat/composer/scope'
import { usePaneLifecycle, usePaneVisible } from '@/components/pane-shell/pane-visibility'
import { useI18n } from '@/i18n'
import { messagePaintWeight } from '@/lib/render-weight'
import { cn } from '@/lib/utils'
import {
  COMPOSER_CLEARANCE_SLOT,
  getThreadScrollPosition,
  onScrollToBottomRequest,
  onThreadEditClose,
  onThreadEditOpen,
  onThreadPageScrollRequest,
  planThreadScrollRestore,
  publishThreadAtBottom,
  readThreadScrollResizeMetrics,
  resetPublishedThreadScroll,
  saveThreadScrollPosition,
  shouldReapplyFrozenThreadScrollOffset,
  THREAD_SCROLL_BOTTOM,
  type ThreadScrollState,
  threadScrollStateFromMetrics,
  threadScrollStorageKey,
  threadScrollTargetTop
} from '@/store/thread-scroll'
import { isSecondaryWindow } from '@/store/windows'

import { MessageRenderBoundary } from '../message-render-boundary'
import { PendingApprovalStack } from '../tool/approval'

import { responseMessageRole, ResponseMessages } from './response-group'
import { holdSessionSwitching } from './session-switching'
import { resolveShowEarlierAction, shouldAutoShowEarlier, useTranscriptWindow } from './transcript-window'
import { useMessagesBelow } from './use-messages-below'
import { useStickyPromptClip } from './use-sticky-prompt-clip'
import { useTimelineReveal } from './use-timeline-reveal'

type ThreadMessageComponents = ComponentProps<typeof ThreadPrimitive.MessageByIndex>['components']

export type MessageGroup = { id: string; weight: number } & (
  { index: number; kind: 'standalone' } | { indices: number[]; kind: 'turn' }
)

// DOM is bounded by a render-cost budget, not a message/turn count. The
// currency is `messagePaintWeight`: what a turn actually MOUNTS, which is what
// the grouping decides rather than what the payload weighs. A settled run of
// twelve reads is one grey summary line, a thought is one collapsed
// disclosure, a hoisted `todo` is nothing — while a diff, an image card or a
// wall of markdown really does build DOM and is charged for it.
//
// Pricing by payload instead had the budget counting work that never mounts:
// one tool-heavy turn measured 84-281 units of tool JSON that painted as a
// dozen one-line summaries, so a session spent the whole page in two or three
// turns and offered "Show earlier" over a screen and a half of transcript.
//
// "Show earlier" prepends another page; whole turns stay intact so the sticky
// human bubble never loses its turn. This is the long-session perf lever WITHOUT
// a virtualizer — pure rendering, never touches scrollTop, so it can't fight
// use-stick-to-bottom (the single scroll owner).
//
// 600 units ≈ 10-20 agentic turns on measured real sessions (a tool-heavy turn
// prices at 30-90, a plain exchange at 5-10), and a whole session of ordinary
// work now fits one page instead of paging three times to reach its start.
// What the DOM can hold is bounded above by the store window regardless
// (TRANSCRIPT_WINDOW_BUDGET), so this cannot admit more than one window's
// content.
const RENDER_BUDGET = 600
// Every mounted transcript list registers here (see the mount effect). The
// budget above is sized for ONE full-height pane; a grid split shows several
// panes at once, each a fraction of the screen — yet each was still mounting
// the full budget. Four visible panes meant 4x the mounted message fibers,
// and every streaming flush pays selector re-runs and React commit traversal
// over ALL of them — measured as the 4-zone collapse in the long-session
// matrix (worst-second 8fps while 1-2 zones held 50+). Sharing the budget
// keeps "screens of scrollback" constant instead of "turns per pane": a pane
// gets its proportional share of the page (MIN_VISIBLE_GROUPS still floors the
// turn count regardless of weight).
// Panes that already backfilled keep their mounted content when the count
// changes — the share only caps where NEW backfills stop.
const $mountedTranscriptPanes = atom(0)
// Never offer "Show earlier" over fewer turns than this, however heavy they
// are. A weight-only cut on a session of enormous turns put the button two
// turns from the bottom, where it reads as broken rather than as paging — the
// user has not been given enough transcript to have gone looking for more. The
// store window caps what the DOM can reach at all, so a floor here stays
// bounded.
const MIN_VISIBLE_GROUPS = 8
// On session switch, paint a small budget first (enough for the bottom turn(s)
// the user actually sees after scroll-to-bottom), then bump to the full budget
// in a requestAnimationFrame — defers the heavy markdown+syntax-highlight render
// past the initial commit, so the switch feels instant.
//
// 20, down from 60: the first-paint commit is synchronous and uninterruptible,
// and at 60 cost units it measured 627ms on a real session (LoAF: block=575ms, no
// attributed script — pure commit). A viewport after scroll-to-bottom shows
// 1-2 normal turns ≈ 10-20 units; the transition backfill below fills the rest
// interruptibly, so the only thing a smaller budget changes is how much work
// blocks the click-to-paint path.
const FIRST_PAINT_BUDGET = 20
// A hot-hidden transcript is retained for instant tab return, but keeping its
// full scrollback mounted defeats the bounded pane cache. Preserve only the
// live tail while hidden; revealing it resumes stepped backfill.
export const HIDDEN_TRANSCRIPT_RENDER_BUDGET = 40

export const transcriptPaneBudget = (mountedPanes: number, hidden: boolean): number =>
  hidden ? HIDDEN_TRANSCRIPT_RENDER_BUDGET : Math.ceil(RENDER_BUDGET / Math.max(1, mountedPanes))

// "Show earlier" raises renderBudget ABOVE paneBudget (one pane page per click).
// The render-phase cap must only snap a hot-hidden pane down to its retention
// budget — a visible pane's growth has to survive the next render or the click
// is a no-op. Parked panes are unmounted, so they never hit this path.
export const shouldClampTranscriptBudget = (hidden: boolean, renderBudget: number, paneBudget: number): boolean =>
  hidden && renderBudget > paneBudget

// Whether a backfill step may record its distance-from-bottom anchor. A
// settled load has a position the user chose. An UNSETTLED load only has one
// when it is pinned to the bottom: the settle loop rewrites scrollTop to the
// bottom every frame, so the measured distance is the truth and the restore
// effect re-pins in the same commit the taller tree lands in. An unsettled
// OFFSET load is still being applied — recording it would clobber the
// remembered offset with a way-point (#99920 regressed exactly this way).
export const shouldAnchorBeforePrepend = (settled: boolean, target: ThreadScrollState): boolean =>
  settled || target.kind === 'bottom'
// Units the backfill adds per committed step (see the backfill effect). A
// 60-unit step produced ~10 visible prepend frames after FIRST_PAINT_BUDGET
// retune (#83681). 290 fills a 600-unit page in two interruptible commits —
// still well under the measured 780ms single-jump freeze.
const BACKFILL_STEP = 290

// Auto-spent budget pages while a parked reading offset waits for the tree
// to cover it (see the grow effect). The real bound is the transcript
// itself; this only stops a truncated-window fetch that never lands from
// re-arming forever.
const PARKED_OFFSET_MAX_PAGES = 96

// A reader parked this long has stopped scrolling past the composer; bring it back.
const COMPOSER_UNDIM_AFTER_STALL_MS = 5000

export const transcriptBackfillFrameCount = (
  firstPaint = FIRST_PAINT_BUDGET,
  step = BACKFILL_STEP,
  budget = RENDER_BUDGET
): number => Math.ceil(Math.max(0, budget - firstPaint) / step)

// Browsers may quantize a requested scrollTop to a nearby device-pixel
// boundary. use-stick-to-bottom otherwise compares the lower actual value to
// the integer target forever, re-requesting the same instant scroll every
// frame. Treat a subpixel remainder as achieved; larger gaps still follow new
// streamed content normally.
const SCROLL_TARGET_EPSILON_PX = 0.5

// True while the user holds a non-collapsed text selection inside the
// transcript. use-stick-to-bottom only pauses for a selection while the mouse
// button is still down — a selection that persists after mouse-up must also
// pin the viewport, or streaming growth yanks it out from under the user
// (#115464). A collapsed caret (or a selection outside the transcript, e.g.
// in the composer) never pins.
export function hasTranscriptTextSelection(scrollElement?: Element | null): boolean {
  if (typeof document === 'undefined') {
    return false
  }

  const selection = document.getSelection()

  if (!selection || selection.isCollapsed || selection.rangeCount === 0) {
    return false
  }

  if (!scrollElement) {
    return true
  }

  const { anchorNode, focusNode } = selection

  return Boolean((anchorNode && scrollElement.contains(anchorNode)) || (focusNode && scrollElement.contains(focusNode)))
}

export const resolveThreadScrollTarget: GetTargetScrollTop = (targetScrollTop, { scrollElement }) => {
  if (hasTranscriptTextSelection(scrollElement)) {
    return scrollElement.scrollTop
  }

  const currentScrollTop = scrollElement.scrollTop
  const remaining = targetScrollTop - currentScrollTop

  return remaining >= 0 && remaining <= SCROLL_TARGET_EPSILON_PX ? currentScrollTop : targetScrollTop
}

/** Near-bottom slack for a run-start snap. Wider than the subpixel epsilon
 *  use-stick-to-bottom uses for resize follow — a follow-up sent a line or two
 *  off the bottom should still track, but a reader in history must not yank. */
export const RUN_START_SNAP_THRESHOLD_PX = 64

export function shouldSnapOnRunStart(remainingPx: number, thresholdPx = RUN_START_SNAP_THRESHOLD_PX): boolean {
  return remainingPx < thresholdPx
}

// True when the pin-to-bottom settle should re-arm. A same-session refresh
// (transcript briefly emptied and repopulated under the same key) must keep
// the reader's position; only a session switch or a cold-load arrival re-pins.
export function shouldRePinOnTranscriptReload(opts: { sessionSwitched: boolean; settledNonEmpty: boolean }): boolean {
  return opts.sessionSwitched || !opts.settledNonEmpty
}

export function subscribeToThreadForeground(shouldReanchor: () => boolean, onReanchor: () => void): () => void {
  let frameId: number | null = null
  let framePending = false

  const onForeground = () => {
    if (framePending || document.visibilityState !== 'visible' || !shouldReanchor()) {
      return
    }

    framePending = true

    const scheduledId = requestAnimationFrame(() => {
      frameId = null
      framePending = false

      if (document.visibilityState === 'visible' && shouldReanchor()) {
        onReanchor()
      }
    })

    // Browser callbacks are asynchronous; the guard also keeps synchronous
    // requestAnimationFrame test doubles from leaving a completed frame pending.
    if (framePending) {
      frameId = scheduledId
    }
  }

  document.addEventListener('visibilitychange', onForeground)
  window.addEventListener('focus', onForeground)

  return () => {
    document.removeEventListener('visibilitychange', onForeground)
    window.removeEventListener('focus', onForeground)

    if (frameId !== null) {
      cancelAnimationFrame(frameId)
    }

    frameId = null
    framePending = false
  }
}

interface ThreadMessageListProps {
  clampToComposer: boolean
  components: ThreadMessageComponents
  emptyPlaceholder?: ReactNode
  loadingIndicator?: ReactNode
  sessionId?: string | null
  sessionKey?: string | null
  /** A routed session is still loading into this surface (the thread spinner
   *  is up). Holds `data-session-switching` for that phase. */
  sessionLoading?: boolean
  scrollProfile?: string
}

// Group each user message with the assistant turn(s) that follow it so the
// human bubble can `position: sticky` against the scroller across its whole
// turn (see StickyHumanMessageContainer in thread.tsx).
export function buildGroups(signature: string): MessageGroup[] {
  if (!signature) {
    return []
  }

  const messages = signature.split('\n').map(row => {
    const [index, id, role, weight] = row.split(':')

    return { id, index: Number(index), role, weight: Number(weight) || 1 }
  })

  const groups: MessageGroup[] = []

  for (let i = 0; i < messages.length; i++) {
    const message = messages[i]

    if (message.role !== 'user') {
      groups.push({ id: message.id, index: message.index, kind: 'standalone', weight: message.weight })

      continue
    }

    const indices = [message.index]
    let weight = message.weight

    while (i + 1 < messages.length && messages[i + 1].role !== 'user') {
      weight += messages[++i].weight
      indices.push(messages[i].index)
    }

    groups.push({ id: message.id, indices, kind: 'turn', weight })
  }

  return groups
}

// Walk turns newest-first, summing their render weights until the budget is met;
// everything before the first kept turn is hidden. `minVisible` turns are kept
// regardless of weight (the exempt newest turn counts as one of them). With
// `exemptNewest` the newest turn is kept AND left out of the sum, so a turn
// whose weight is still changing cannot move the cut. Returns the index of that
// first visible group.
export function firstVisibleGroupIndex(
  groups: readonly MessageGroup[],
  budget: number,
  minVisible = 0,
  exemptNewest = false
): number {
  const budgetedEnd = exemptNewest ? Math.max(0, groups.length - 1) : groups.length
  let firstVisible = budgetedEnd

  for (let i = budgetedEnd - 1, weight = 0; i >= 0; i--) {
    weight += groups[i].weight
    firstVisible = i

    if (weight >= budget) {
      break
    }
  }

  return Math.min(firstVisible, Math.max(0, groups.length - minVisible))
}

// content-visibility:auto skips off-screen turns for perf, but with
// contain-intrinsic-size:auto the browser only remembers a turn's size AFTER
// it has rendered. A turn that finishes streaming near the bottom may have had
// its (smaller) mid-stream size remembered; when it scrolls just off the top
// edge and gets skipped, it snaps back to that stale height, shifting content
// down. With overflow-anchor:none (the viewport can't self-correct) the
// stick-to-bottom lock drifts and the view creeps up over older turns — the
// "long session eventually shows old responses" glitch.
//
// Keep the newest turns always-rendered so a turn is only ever virtualized
// once its layout has settled at its final size (remembered == real → skipping
// it changes no height). Off-screen OLDER turns still skip, so the dialog/popover
// recalc win on long transcripts is preserved.
//
// The tail is budgeted in render-cost units, not turns, because that is what the
// cost actually scales with — the same currency as RENDER_BUDGET /
// FIRST_PAINT_BUDGET.
// A turn-count tail silently defeats itself on agent transcripts: one tool-heavy
// turn is 50-200 units, so a 6-TURN tail exempted the entire visible transcript
// and nothing virtualized at all. Measured on a 5-tile window (7/3/5/3/2 groups
// per tile): zero content-visibility containers were active, and every Radix
// overlay open paid the full ~610ms whole-document recalc that #66470 fixed.
//
// 40 units ≈ the 1-2 turns a viewport shows after scroll-to-bottom (the same
// reasoning as FIRST_PAINT_BUDGET=20, doubled so a turn that grows mid-stream
// doesn't fall out of the tail as it settles).
export const LIVE_TAIL_PARTS = 40
// Floor: always exempt at least this many turns regardless of weight, so a
// transcript of very heavy turns still keeps the streaming one unvirtualized.
export const LIVE_TAIL_MIN_GROUPS = 2
// Ceiling: never exempt more than this many turns, however light they are. On a
// long transcript of tiny turns a weight-only budget would walk back further
// than the old turn-count tail did and virtualize LESS — this keeps the new
// policy a strict improvement on every shape.
export const LIVE_TAIL_MAX_GROUPS = 6

/**
 * Index of the newest group that still virtualizes — everything at or after it
 * is the live tail and stays rendered. Walks newest-first accumulating weight,
 * so the tail covers a viewport's worth of content rather than a fixed number
 * of turns, clamped to [MIN, MAX] turns. Computed once per render, not per row.
 */
export function liveTailStart(
  groups: readonly MessageGroup[],
  tailWeight = LIVE_TAIL_PARTS,
  minGroups = LIVE_TAIL_MIN_GROUPS,
  maxGroups = LIVE_TAIL_MAX_GROUPS
): number {
  let weight = 0
  let start = groups.length

  for (let i = groups.length - 1; i >= 0; i--) {
    weight += groups[i]?.weight ?? 1
    start = i

    if (weight > tailWeight) {
      break
    }
  }

  // Clamp the tail to [minGroups, maxGroups] turns: the floor keeps the live
  // turn rendered when turns are huge, the ceiling stops a tail of tiny turns
  // from sprawling past what the old turn-count policy rendered.
  const floor = Math.max(0, groups.length - minGroups)
  const ceiling = Math.max(0, groups.length - maxGroups)

  return Math.min(floor, Math.max(ceiling, start))
}

/**
 * React identity of the row a message opens. A stored row's renderer id is
 * built from its position in the page it was read from, so every newest-page
 * re-read that slides the window hands every row in it a new id. Keyed by
 * that id, each settled turn remounted the whole page: a remounted row is a
 * new element with no remembered size, so an off-screen one drops to the
 * contain-intrinsic-size placeholder, the transcript height jumps, and the
 * scrollTop clamp reads as a scroll-up to use-stick-to-bottom (the view stops
 * following). The durable row id is the same row in every page.
 */
export function transcriptRowKey(message: { id: string; metadata?: { custom?: Record<string, unknown> } }): string {
  const rowId = message.metadata?.custom?.rowId

  return typeof rowId === 'number' ? `row:${rowId}` : message.id
}

/**
 * Per-message React keys, indexed like thread.messages. Two rendered messages
 * can carry one durable row (hydration splits a stored row it renders in
 * parts); the later copy keeps its own renderer id as its key.
 */
export function turnRowKeys(rowKeySignature: string, structuralSignature: string): string[] {
  const seen = new Set<string>()
  const ids = structuralSignature.split('\n').map(row => row.split(':')[1])

  return rowKeySignature.split('\n').map((key, index) => {
    const unique = seen.has(key) ? (ids[index] ?? key) : key
    seen.add(unique)

    return unique
  })
}

interface TurnRowProps {
  components: ThreadMessageComponents
  group: MessageGroup
  resetKey: string
  virtualized: boolean
}

// One turn (or standalone message) of the transcript. memo() is the point:
// the rows array below is REBUILT whenever the DOM budget's cut advances
// (hiddenCount changes its slice), and without per-row bail-out that rebuild
// re-rendered every mounted turn — markdown, code cards, tool blocks — in one
// synchronous frame, a 100-800ms stall once a second on a streaming long
// session. With memo, a rebuild re-renders only rows whose props changed:
// the dropped head row unmounts, the virtualization boundary rows flip their
// flag, and everything else bails on identical group/resetKey identity.
//
// content-visibility:auto (virtualized rows) — off-screen turns skip style
// recalc, layout, and paint. On a long transcript this is what keeps
// UNRELATED UI fast: any dialog/popover mount (Radix Presence reads
// getComputedStyle) forces a whole-document style recalc, measured
// ~650-730ms per open on a 1300-message session and ~100-200ms with this
// on. contain-intrinsic-size keeps a placeholder height for never-rendered
// turns (auto: remembered real size once rendered), so scrollbar/anchoring
// stay stable. It sits on EVERY row, not only virtualized ones: the browser
// records a remembered size only while the declaration is present, so a row
// that gained it together with content-visibility (leaving the live tail
// off screen) dropped to the 37.5rem placeholder, and the height change
// clamped scrollTop into a scroll-up that stopped the follow. Sticky human
// bubbles are unaffected — their turn is rendered whenever any part of it
// intersects the viewport.
//
// The live tail (newest turns) is exempt: virtualizing a turn whose final
// size hasn't been remembered yet snaps it to a stale height when it scrolls
// off, drifting stick-to-bottom up over old turns. See liveTailStart.
const TurnRow = memo(function TurnRow({ components, group, resetKey, virtualized }: TurnRowProps) {
  return (
    <div
      className={cn(
        'flex min-w-0 flex-col gap-(--conversation-turn-gap) pb-(--conversation-turn-gap) [contain-intrinsic-size:auto_37.5rem]',
        virtualized && '[content-visibility:auto]'
      )}
      data-slot="aui_message-group"
    >
      <MessageRenderBoundary resetKey={resetKey}>
        {group.kind === 'turn' ? (
          <div
            className="composer-human-ai-pair-container relative flex min-w-0 flex-col gap-(--conversation-turn-gap)"
            data-slot="aui_turn-pair"
          >
            <ResponseMessages components={components} indices={group.indices} />
          </div>
        ) : (
          <ThreadPrimitive.MessageByIndex components={components} index={group.index} />
        )}
      </MessageRenderBoundary>
    </div>
  )
})

const ThreadMessageListInner: FC<ThreadMessageListProps> = ({
  clampToComposer,
  components,
  emptyPlaceholder,
  loadingIndicator,
  sessionId = null,
  scrollProfile,
  sessionKey,
  sessionLoading = false
}) => {
  // TWO signatures, deliberately split. The STRUCTURAL one (ids/roles/count)
  // changes only when messages are added/removed/swapped — it keys the error
  // boundaries and the row identity. The WEIGHT one (parts + character cost)
  // ticks while a streaming turn appends content — it feeds only the render
  // budget. Folding weights into the structural key handed every boundary a
  // new resetKey per appended part, which reconciled every turn's subtree on
  // every tick (measured: 540 wasted Block renders per explain() sample with
  // two threads streaming).
  const structuralSignature = useAuiState(s =>
    s.thread.messages.map((message, index) => `${index}:${message.id}:${responseMessageRole(message)}`).join('\n')
  )

  const weightSignature = useAuiState(s =>
    s.thread.messages.map(message => messagePaintWeight(message.content)).join(',')
  )

  const { t } = useI18n()
  // Row structure is memoized on the STRUCTURAL signature only, so streaming
  // part-appends can't churn group identity (that would defeat the rows memo
  // below on every tick). Weights are folded in separately for the budget.
  const groups = useMemo(() => buildGroups(structuralSignature), [structuralSignature])
  const rowKeySignature = useAuiState(s => s.thread.messages.map(transcriptRowKey).join('\n'))
  const renderEmpty = groups.length === 0 && Boolean(emptyPlaceholder)

  // use-stick-to-bottom owns scrollTop (single writer): follow while locked,
  // escape on user scroll-up, re-lock at bottom. Snap instantly, not spring — a
  // spring can't tell live-token growth from a session-switch bulk relayout, and
  // chasing the latter reads as the view scrolling to random spots before
  // settling. Its refs hang off our own DOM so the sticky human bubbles survive.
  const { scrollRef, contentRef, isAtBottom, scrollToBottom, stopScroll } = useStickToBottom({
    initial: 'instant',
    resize: 'instant',
    targetScrollTop: resolveThreadScrollTarget
  })

  // #115464: explicit snaps go through the same selection pin as the resize
  // follow above — without this a snap still flips isAtBottom and kicks an
  // animation while the user is selecting transcript text.
  const scrollToBottomUnlessSelecting = useCallback(
    (...args: Parameters<typeof scrollToBottom>) => {
      if (hasTranscriptTextSelection(scrollRef.current)) {
        return undefined
      }

      return scrollToBottom(...args)
    },
    [scrollRef, scrollToBottom]
  )

  const { olderAvailable, expandWindow, isHistorical, returnToLatest } = useTranscriptWindow()

  useEffect(() => {
    $mountedTranscriptPanes.set($mountedTranscriptPanes.get() + 1)

    return () => $mountedTranscriptPanes.set($mountedTranscriptPanes.get() - 1)
  }, [])

  const mountedPanes = useStore($mountedTranscriptPanes)
  const paneLifecycle = usePaneLifecycle()
  const paneVisible = usePaneVisible()
  // Hidden panes retain only a live-tail budget. Visible panes share the normal
  // screen budget; a reveal backfills older rows in bounded transition steps.
  const paneBudget = transcriptPaneBudget(mountedPanes, paneLifecycle === 'hot-hidden')

  const [renderBudget, setRenderBudget] = useState(FIRST_PAINT_BUDGET)

  // Cut the budget during RENDER, not in the post-commit layout effect. An
  // effect-time cut is too late: React would first build the whole tree with
  // the full budget (up to 600 cost units of markdown + syntax highlighting),
  // commit it, and only then re-render at the small budget. The render-phase
  // state adjustment restarts this component immediately — before any child
  // renders — so the heavy commit never happens.
  //
  // Two triggers, because the transcript swap arrives differently per path:
  // a WARM switch publishes sessionKey + messages in one commit (the key
  // branch), while a COLD switch changes sessionKey with an empty transcript
  // and the prefetched messages land hundreds of ms later under the SAME key
  // (the empty→non-empty branch).
  const hasGroups = groups.length > 0
  const [budgetSessionKey, setBudgetSessionKey] = useState(sessionKey)
  const [hadGroups, setHadGroups] = useState(hasGroups)

  if (budgetSessionKey !== sessionKey) {
    setBudgetSessionKey(sessionKey)
    setHadGroups(hasGroups)
    setRenderBudget(FIRST_PAINT_BUDGET)
  } else if (shouldClampTranscriptBudget(paneLifecycle === 'hot-hidden', renderBudget, paneBudget)) {
    // Apply the hidden budget during render so React never first commits the
    // stale full transcript after this pane moves to the background.
    setRenderBudget(paneBudget)
  } else if (hadGroups !== hasGroups) {
    setHadGroups(hasGroups)

    if (hasGroups) {
      setRenderBudget(FIRST_PAINT_BUDGET)
    }
  }

  // Where to land after a prepend, in distance-from-bottom (survives the
  // height change). Shared by "Show earlier" and the budget backfill below.
  const restoreFromBottomRef = useRef<number | null>(null)
  // scrollHeight when the anchor was recorded. The restore effect below also
  // runs on commits that do not grow the content (the transcript arriving
  // under the first-paint budget; a "Show earlier" whose page comes from the
  // store a commit later); consuming the anchor there spends it as a no-op and
  // leaves the real prepend unanchored. Only a taller tree is the prepend.
  const anchorHeightRef = useRef<number | null>(null)
  // False from a session switch until the settle loop below parks the
  // transcript at its true bottom. While false, scrollTop is a way-point of a
  // load in progress, not a reading position anyone chose — never anchor to it.
  const loadSettledRef = useRef(false)
  // What the in-flight load is steering toward; decides whether a backfill
  // step may anchor while the load is still unsettled.
  const loadTargetRef = useRef<ThreadScrollState>(THREAD_SCROLL_BOTTOM)
  const cancelRestoreRef = useRef<(() => void) | null>(null)
  const applyRestoreRef = useRef<(() => void) | null>(null)
  // Pages auto-spent toward the current parked offset; reset at each park.
  const autoGrowPagesRef = useRef(0)
  // Bumped when the settle loop parks an offset, so the grow effect below
  // re-runs with fresh state even when no other dependency changed.
  const [restoreGrowTick, setRestoreGrowTick] = useState(0)
  const windowRequestRef = useRef<object | null>(null)
  const windowCommitRef = useRef<string | null>(null)
  const jumpRestoreRef = useRef<(() => void) | null>(null)
  const isRunning = useAuiState(s => s.thread.isRunning)
  // Read by the resize-pin callback so a turn boundary doesn't rebuild its
  // scroll listener and ResizeObserver.
  const isRunningRef = useRef(isRunning)
  isRunningRef.current = isRunning
  const clearanceRef = useRef<HTMLDivElement>(null)
  // Session the settle loop last armed for, so a re-arm within the same load
  // is distinguishable from a switch to a different transcript.
  const settleKeyRef = useRef(sessionKey)

  // Record where the view should land once a prepend has grown the content,
  // measured from the BOTTOM so the added height doesn't invalidate it. A
  // bottom-pinned load anchors even before it settles: the settle loop hands
  // back at the FIRST-PAINT height, before the backfill transition commits, so
  // without an anchor that commit prepends thousands of px with nothing
  // re-pinning the view until use-stick-to-bottom's ResizeObserver catches up
  // frames later — the full-viewport lurch of #99920. An unsettled OFFSET load
  // never anchors: the settle loop is still applying the remembered offset,
  // and parks it itself on a clamped exit.
  const anchorBeforePrepend = useCallback(() => {
    const el = scrollRef.current

    if (!el || !shouldAnchorBeforePrepend(loadSettledRef.current, loadTargetRef.current)) {
      return
    }

    // Preserve bottom intent rather than a temporary gap before resize-follow.
    restoreFromBottomRef.current =
      liveScrollStateRef.current.kind === 'bottom' ? el.clientHeight : el.scrollHeight - el.scrollTop
    anchorHeightRef.current = el.scrollHeight
  }, [scrollRef])

  // Weights (part count + visible character cost) fold into the BUDGET only.
  // Group identity stays structural, so a streaming append re-runs this cheap
  // sum — not the row JSX. Settled content hits messagePaintWeight's WeakMap.
  const weightedGroups = useMemo(() => {
    const weights = weightSignature.split(',').map(w => Number(w) || 1)

    return groups.map(group => ({
      ...group,
      weight:
        group.kind === 'turn'
          ? group.indices.reduce((sum, index) => sum + (weights[index] ?? 1), 0)
          : (weights[group.index] ?? 1)
    }))
  }, [groups, weightSignature])

  // The turn floor and the newest-turn exemption apply to a real page only.
  // During the first-paint budget the point is a small synchronous commit;
  // forcing 8 turns into it — or a whole extra turn behind an unbudgeted
  // newest one — would put back exactly the freeze FIRST_PAINT_BUDGET exists
  // to avoid, and the rAF backfill a frame later fills them in anyway.
  //
  // On a real page the newest turn is exempt from the history budget so its
  // growing — then completed — weight never advances the cut boundary. A
  // moving cut unmounts older rows, shrinks scrollHeight, and the browser
  // clamp looks like a user scroll-up to use-stick-to-bottom.
  const fullPage = renderBudget >= paneBudget

  const hiddenCount = firstVisibleGroupIndex(weightedGroups, renderBudget, fullPage ? MIN_VISIBLE_GROUPS : 0, fullPage)

  // Memoized for IDENTITY, not to save the slice: `rows` below keys off this
  // array, and an inline slice handed it a fresh array every render — so the
  // moment a transcript outgrew the render budget (hiddenCount > 0), every
  // streamed token rebuilt every visible row's JSX and re-rendered the whole
  // mounted transcript. Under the budget the raw `groups` identity made the
  // memo hold; heavy sessions lost it exactly when they could least afford to.
  const visibleGroups = useMemo(() => (hiddenCount > 0 ? groups.slice(hiddenCount) : groups), [groups, hiddenCount])

  // Backfill from FIRST_PAINT_BUDGET to the full budget after the small
  // commit painted — as a TRANSITION, so the heavy markdown + syntax
  // highlight render of the older turns is interruptible instead of one long
  // synchronous commit that freezes input right after the switch. Route
  // changes stay urgent (main.tsx disables router transitions); it's exactly
  // this backfill that belongs at background priority. "Show earlier" pages
  // (budget > paneBudget) never re-enter here.
  //
  // In BOUNDED STEPS, not one jump to the full budget. A transition render is
  // interruptible but its COMMIT is not, and one 20→600 step commits every
  // backfilled turn at once — measured as a 780ms uninterruptible frame when
  // the session was revealed while other tiles streamed (the flushes kept
  // interrupting the transition, which finally landed whole, seconds later,
  // mid-stream). Each step commits at most BACKFILL_STEP units; the effect
  // re-arms off the committed budget, so steps pace one per frame.
  //
  // Nothing to backfill while the transcript is still empty (a COLD switch);
  // an anchor measured against the empty viewport would be consumed by the
  // first-paint commit and leave the real prepend unanchored.
  useEffect(() => {
    if (!hasGroups || renderBudget >= paneBudget) {
      return
    }

    const rafId = requestAnimationFrame(() => {
      // The backfill PREPENDS older turns, so everything on screen slides down
      // by their height. Anchor first and let the restore effect below re-apply
      // it in the same commit the taller tree lands in — otherwise the view is
      // stranded near the TOP until use-stick-to-bottom's ResizeObserver
      // catches up a frame or two later (measured: an 11.5k px jump showing
      // ~160ms of unrelated old turns, on every session load). A step with
      // nothing left hidden prepends nothing: an anchor recorded for it would
      // never be consumed and would re-pin a later append instead.
      if (hiddenCount > 0) {
        anchorBeforePrepend()
      }

      // Functional max, not a plain set: an urgent "Show earlier" click can
      // land between scheduling and committing this transition, and a plain
      // set would rebase over it and shrink the budget back down.
      startTransition(() => setRenderBudget(budget => Math.max(budget, Math.min(budget + BACKFILL_STEP, paneBudget))))
    })

    return () => cancelAnimationFrame(rafId)
  }, [anchorBeforePrepend, hasGroups, hiddenCount, paneBudget, renderBudget])

  // Where the always-rendered live tail begins. Derived from the WEIGHTED
  // groups (render cost, not turns) so the tail is a viewport's worth of content —
  // see liveTailStart. Computed once here rather than per row.
  const tailStart = useMemo(
    () => liveTailStart(hiddenCount > 0 ? weightedGroups.slice(hiddenCount) : weightedGroups),
    [weightedGroups, hiddenCount]
  )

  // Secondary windows (new-session scratch, subagent watch, cmd-click pop-out)
  // hide the titlebar tool cluster + session header, but the OS traffic lights
  // still sit in the top-left, so reserve the titlebar gap above the transcript.
  const secondaryWindow = isSecondaryWindow()
  // NB: CSS calc() requires whitespace around the +/- operator. This string is
  // assigned verbatim to the --sticky-human-top inline style below (it does not
  // go through Tailwind, which would auto-space it), so the spaces are load-
  // bearing — without them the declaration is invalid, gets dropped, and the
  // sticky user bubble falls back to its ~4px default and slides under the OS
  // traffic lights.
  const secondaryTitlebarGap = 'calc(var(--titlebar-height) + 0.75rem)'

  const threadContentTopPad = secondaryWindow
    ? 'pt-[calc(var(--titlebar-height)+0.75rem)]'
    : 'pt-[calc(var(--titlebar-height)-0.5rem)]'

  const surfaceId = useComposerSurfaceId()
  const scrollSessionId = sessionId ?? surfaceId
  useEffect(() => {
    const atBottom = isAtBottom && !isHistorical
    const publisher = { paneVisible, sessionId: scrollSessionId }
    const el = scrollRef.current

    publishThreadAtBottom(atBottom, publisher)

    if (atBottom || !el) {
      return
    }

    let timer = 0

    const arm = () => {
      publishThreadAtBottom(false, publisher)
      clearTimeout(timer)
      timer = window.setTimeout(() => publishThreadAtBottom(false, publisher, false), COMPOSER_UNDIM_AFTER_STALL_MS)
    }

    arm()
    el.addEventListener('scroll', arm, { passive: true })

    return () => {
      clearTimeout(timer)
      el.removeEventListener('scroll', arm)
    }
  }, [isAtBottom, isHistorical, paneVisible, scrollRef, scrollSessionId])
  useEffect(
    () => () => resetPublishedThreadScroll({ paneVisible, sessionId: scrollSessionId }),
    [paneVisible, scrollSessionId]
  )

  // Floating jump button (outside this subtree) → return to the bottom.
  useEffect(
    () =>
      onScrollToBottomRequest(() => {
        if (isHistorical) {
          returnToLatest?.()
        }

        if (jumpRestoreRef.current) {
          jumpRestoreRef.current()
        } else {
          void scrollToBottomUnlessSelecting()
        }
      }, scrollSessionId),
    [scrollToBottomUnlessSelecting, scrollSessionId, isHistorical, returnToLatest]
  )

  // Waking from display: hidden (HUD mode hides the main window; OS hide does
  // the same to any window): rAF and ResizeObserver may have been frozen, so
  // the virtualizer's measurements — and scrollTop itself — are stale. Active
  // turns disable Chromium's background throttling, which can keep visibility
  // pinned at `visible`; window focus is then the only foreground edge. If the
  // user was following the bottom, re-anchor on either signal. Consult this
  // thread's local state rather than the composer-facing global mirror, which
  // can be overwritten by another mounted pane; leave a scrolled-up reader
  // exactly where they were.
  useEffect(
    () =>
      subscribeToThreadForeground(
        () => isAtBottom,
        () => void scrollToBottomUnlessSelecting()
      ),
    [isAtBottom, scrollToBottomUnlessSelecting]
  )

  const endEditHold = useCallback(() => {
    scrollRef.current?.removeAttribute('data-editing')
  }, [scrollRef])

  // Inline edit grows a sticky bubble. Escape before focus/layout so the
  // resize-follow can't snap scrollTop; native anchoring holds the viewport.
  const beginEditHold = useCallback(() => {
    const el = scrollRef.current

    if (!el) {
      return
    }

    endEditHold()
    stopScroll()
    el.setAttribute('data-editing', 'true')
  }, [endEditHold, scrollRef, stopScroll])

  useEffect(() => onThreadEditOpen(beginEditHold), [beginEditHold])
  useEffect(() => onThreadEditClose(endEditHold), [endEditHold])
  useEffect(() => () => endEditHold(), [endEditHold])
  // New run → snap to the latest turn only when already near the bottom.
  useAuiEvent('thread.runStart', () => {
    cancelRestoreRef.current?.()
    const el = scrollRef.current

    if (el && shouldSnapOnRunStart(el.scrollHeight - el.scrollTop - el.clientHeight)) {
      scrollToBottomUnlessSelecting()
    }
  })

  // Live scroll state of the CURRENT session, updated on every scroll event
  // AND on content height changes (ResizeObserver). The RO leg is what keeps
  // the recorded distance-from-bottom honest: async relayout (images,
  // highlight, the budget backfill) changes scrollHeight WITHOUT a scroll
  // event, so a scroll-only cache records a stale offset (the gap #70478's
  // review threads flagged). Both legs write stateFromMetrics(el).
  // Bind persistence to this transcript, not whichever Bot most recently
  // changed the global profile. Visibility changes do not transfer ownership.
  const [scrollOwner, setScrollOwner] = useState(() => ({
    sessionKey,
    profile: scrollProfile,
    storageKey: threadScrollStorageKey(scrollProfile)
  }))

  if (scrollOwner.sessionKey !== sessionKey || scrollOwner.profile !== scrollProfile) {
    setScrollOwner({ sessionKey, profile: scrollProfile, storageKey: threadScrollStorageKey(scrollProfile) })
  }

  const scrollStorageKey = scrollOwner.storageKey
  const restoredStorageKeyRef = useRef(scrollStorageKey)

  const liveScrollStateRef = useRef<ThreadScrollState>(THREAD_SCROLL_BOTTOM)
  // Key the restore loop has already applied to the current transcript — the
  // record gate: an instance records only the state it actually showed under
  // its own key (an empty-transcript instance still holds the PREVIOUS
  // session's live state and must not file it under the new key).
  const restoredContentKeyRef = useRef<string | null | undefined>(undefined)

  // eslint-disable-next-line no-restricted-syntax -- DOM-event cache (scroll/ResizeObserver callbacks), not an atom mirror
  useEffect(() => {
    const el = scrollRef.current
    const content = contentRef.current

    if (!el || !content || !paneVisible) {
      return
    }

    // use-stick-to-bottom follows a content resize on the next animation frame,
    // so a busy streamed turn can grow the content before that callback runs:
    // the viewport paints at the stale scrollTop, visibly drifting up before
    // the re-pin (#118482). The RO leg closes that frame, synchronously before
    // paint.
    const resizeMetrics = () => readThreadScrollResizeMetrics(el, clearanceRef.current)

    // ponytail: previous-metrics precision is load-bearing — the predicate must
    // see the frame BEFORE the growth, so a scroll event (which also writes it)
    // can't leave a stale gap that makes a mid-stream resize look like growth.
    let previousResizeMetrics = resizeMetrics()

    const update = () => {
      previousResizeMetrics = resizeMetrics()
      liveScrollStateRef.current = threadScrollStateFromMetrics(el)
    }

    const onResize = () => {
      const nextResizeMetrics = resizeMetrics()

      // Same transcript-only metric as the restore loop: a composer-only resize
      // (every keystroke) grows the clearance spacer, not the rows, so it is
      // distinguishable from streamed content. The pre-growth metrics hold the
      // reader's position, so a reader who scrolled up is never yanked back
      // (#108941); use-stick-to-bottom stays the single scroll owner otherwise.
      // An open inline edit holds the viewport (beginEditHold), so its growing
      // bubble is never followed.
      if (
        isRunningRef.current &&
        !el.hasAttribute('data-editing') &&
        shouldReapplyFrozenThreadScrollOffset(THREAD_SCROLL_BOTTOM, true, previousResizeMetrics, nextResizeMetrics) &&
        threadScrollStateFromMetrics({ ...previousResizeMetrics, scrollTop: el.scrollTop }).kind === 'bottom' &&
        !hasTranscriptTextSelection(el)
      ) {
        el.scrollTop = threadScrollTargetTop(THREAD_SCROLL_BOTTOM, nextResizeMetrics)
      }

      previousResizeMetrics = nextResizeMetrics
      liveScrollStateRef.current = threadScrollStateFromMetrics(el)
    }

    el.addEventListener('scroll', update, { passive: true })
    const observer = new ResizeObserver(onResize)
    observer.observe(content)

    return () => {
      el.removeEventListener('scroll', update)
      observer.disconnect()
    }
  }, [contentRef, paneVisible, scrollRef])

  // Persist the live position on app close, so a reading position survives a
  // quit without a session switch (the switch cleanup below only runs on
  // committed switches). Guarded by the same restored-content gate AND the
  // settled gate — a close mid-settle must not persist transient clamped
  // metrics.
  useEffect(() => {
    const storageKey = scrollStorageKey

    const flush = () => {
      if (sessionKey && loadSettledRef.current && restoredContentKeyRef.current === sessionKey) {
        saveThreadScrollPosition(sessionKey, liveScrollStateRef.current, storageKey)
      }
    }

    window.addEventListener('beforeunload', flush)

    return () => window.removeEventListener('beforeunload', flush)
  }, [scrollStorageKey, sessionKey])

  // Reset the cap and restore the remembered scroll state on mount + every
  // session switch (messages swap in place on a long-lived runtime, so
  // sessionKey is the only signal). Sessions the user left mid-read reapply
  // their exact distance-from-bottom; sticky-bottom sessions pin to the bottom.
  // The swap is multi-step and lays out over many frames; letting the library
  // follow re-pins every frame to a moving target — visible as ~10 scroll
  // jumps. Instead: quiet it, glue to the remembered target until the height
  // holds steady, then hand back (locked at the bottom, escaped at an offset).
  // Live streaming afterward uses the normal resize follow.
  //
  // `hasGroups` joins sessionKey as a dep because a COLD load changes the key
  // while the transcript is still empty and publishes messages hundreds of ms
  // later. Keyed on the switch alone the loop measured an EMPTY viewport, saw
  // a stable height in two frames, and handed back "settled" before the
  // transcript existed — so the turns painted at scrollTop 0 and only snapped
  // down once use-stick-to-bottom's ResizeObserver noticed, a full-viewport
  // lurch on every cold load. The empty→non-empty flip re-arms for the
  // transcript that actually arrived; being a boolean, it cannot re-fire on a
  // streaming append. The restore must re-run at first content too — that is
  // what `restoredContentKeyRef` gates: one restore per key AFTER its
  // transcript exists. The effect cleanup is the record point: it runs with
  // the OLD session's closure, synchronously in the commit that swaps
  // transcripts.
  useLayoutEffect(() => {
    const el = scrollRef.current

    if (!el) {
      return
    }

    // A kept-alive Bot pane can shrink its render budget or refresh messages
    // while hidden. Preserve its last visible position, not that background
    // layout, and re-arm the normal restore loop when the pane is revealed.
    // The outgoing visible effect's cleanup has already saved its position.
    if (!paneVisible) {
      loadSettledRef.current = false
      restoredContentKeyRef.current = null
      restoreFromBottomRef.current = null

      return
    }

    // Cleanup belongs to the subscription owner, not the newly active globals.
    const storageKey = scrollStorageKey
    const sessionSwitched = settleKeyRef.current !== sessionKey || restoredStorageKeyRef.current !== storageKey
    restoredStorageKeyRef.current = storageKey

    const plan = planThreadScrollRestore(
      sessionSwitched ? undefined : restoredContentKeyRef.current,
      sessionKey,
      hasGroups,
      loadSettledRef.current
    )

    restoredContentKeyRef.current = plan.gate

    // Record only states that were actually shown under this key: the gate
    // equals this closure's sessionKey exactly when this instance restored
    // content (cleanups run before the next instance's effect, so a later
    // cold-switch instance clearing the ref can't spoof it). An
    // empty-transcript instance still holds the PREVIOUS session's live state,
    // which must not be filed under this key. And only SETTLED states: mid-
    // settle the ref holds transient clamped metrics (the loop writing targets
    // into a still-arriving transcript), and persisting those would corrupt
    // the session's real reading position.
    const record = () => {
      if (sessionKey && loadSettledRef.current && restoredContentKeyRef.current === sessionKey) {
        saveThreadScrollPosition(sessionKey, liveScrollStateRef.current, storageKey)
      }
    }

    if (plan.cold) {
      // Cold switch: transcript not landed yet (or emptied for a reload). The
      // DOM collapse clamps scrollTop to garbage, so forget the restore gate —
      // when content (re)arrives, reapply from memory. The previous session's
      // real state was already recorded by its own cleanup just before this.
      // Whatever anchor exists was measured against the tree that just
      // collapsed (the OUTGOING transcript, or stale rows shown under this key
      // before the swap) and would re-pin the arriving one to garbage. The
      // re-arm below restores from the remembered position instead.
      loadSettledRef.current = false
      settleKeyRef.current = sessionKey
      restoreFromBottomRef.current = null

      return record
    }

    if (!plan.restore) {
      // Same key, already settled: the restore is done, keep recording only.
      return record
    }

    const remembered = sessionKey ? getThreadScrollPosition(sessionKey, storageKey) : undefined
    let target = remembered ?? THREAD_SCROLL_BOTTOM

    // The previous session's parting state must not leak into this one: from
    // here every scroll/RO event describes the restored session.
    liveScrollStateRef.current = target
    loadTargetRef.current = target

    stopScroll()

    // Every scrollTop this effect writes is read back here, so the `scroll`
    // event it fires is recognised as ours below and cannot cancel the restore.
    let ownScrollTop: number | null = null

    const applyTarget = (node: HTMLElement) => {
      node.scrollTop = threadScrollTargetTop(target, node)
      ownScrollTop = node.scrollTop
    }

    applyRestoreRef.current = () => {
      applyTarget(el)
    }

    applyRestoreRef.current()
    loadSettledRef.current = false
    // The rows are in and about to be glued to their target: theme CSS may
    // hide this phase (data-session-switching) so the jump never paints.
    const releaseSwitching = holdSessionSwitching(el)

    // An anchor captured for the OUTGOING transcript must not be applied to
    // this one — a switch owns the position outright. The empty→non-empty
    // re-arm is the SAME load, whose in-flight anchor is still correct.
    if (sessionSwitched) {
      settleKeyRef.current = sessionKey
      restoreFromBottomRef.current = null
    }

    let frame = 0
    let stableFrames = 0
    let lastHeight = el.scrollHeight

    const settle = () => {
      const node = scrollRef.current

      if (!node) {
        return
      }

      const height = node.scrollHeight

      // An offset deeper than the current scroll range means content is still
      // arriving (the budget backfill prepends older turns) — a quiet frame in
      // that state is not stability, keep waiting for the height.
      const clamped = target.kind === 'offset' && target.fromBottom > Math.max(0, height - node.clientHeight)

      stableFrames = height === lastHeight && !clamped ? stableFrames + 1 : 0
      lastHeight = height
      applyTarget(node)

      // Most session switches are synchronous and stabilize within 2 frames;
      // the old 90-frame ceiling was for slow async image loads. Cap at 15
      // frames to minimize the settle-loop racing markdown paint on every switch.
      if (stableFrames >= 2 || ++frame > 15) {
        releaseSwitching()

        if (target.kind === 'bottom') {
          // Hand back to use-stick-to-bottom locked, so late async growth
          // (images, highlight) keeps following the bottom.
          void scrollToBottomUnlessSelecting('instant')
          loadSettledRef.current = true
        } else if (clamped) {
          // Content hasn't finished arriving (the backfill transition is still
          // rendering). Park the offset in the anchor so the restore effect
          // re-applies it the moment the taller tree lands — otherwise the
          // view is stranded at the clamped position. Keep loadSettled false:
          // anchorBeforePrepend skips while unsettled, so the parked offset
          // can't be overwritten by a mid-load anchor measurement. The restore
          // effect flips settled once it consumes the parked value.
          restoreFromBottomRef.current = target.fromBottom + node.clientHeight
          anchorHeightRef.current = height
          // Wake paging even when the current render budget has stopped growing.
          autoGrowPagesRef.current = 0
          setRestoreGrowTick(tick => tick + 1)
        } else {
          loadSettledRef.current = true
        }

        return
      }

      rafId = requestAnimationFrame(settle)
    }

    let rafId = requestAnimationFrame(settle)

    // Quiet frames are not layout completion: deferred Markdown and intrinsic
    // row measurements can change height after the initial settle. Retain the
    // restored target through those resizes until input or a live run takes over.
    // Bottom needs the same protection: the library follows on the next frame,
    // but a switch in this frame would otherwise persist the temporary gap.
    const restoreResizeMetrics = () => readThreadScrollResizeMetrics(el, clearanceRef.current)

    let lastRestoreMetrics = restoreResizeMetrics()

    const resizeObserver = new ResizeObserver(() => {
      const next = restoreResizeMetrics()
      const previous = lastRestoreMetrics
      lastRestoreMetrics = next

      // ResizeObserver runs before paint; waiting for the next settle rAF
      // exposes a frame at the old offset when deferred markdown grows.
      // Once settled, only a transcript-row height change may re-pin — for a
      // bottom target too: a composer-only resize (every keystroke) used to
      // yank a view the user had moved away from the bottom back down.
      if (!loadSettledRef.current || shouldReapplyFrozenThreadScrollOffset(target, true, previous, next)) {
        applyTarget(el)
        liveScrollStateRef.current = threadScrollStateFromMetrics(el)
      }
    })

    if (contentRef.current) {
      resizeObserver.observe(contentRef.current)
    }

    const cancelRestore = () => {
      applyRestoreRef.current = null
      resizeObserver.disconnect()
      cancelAnimationFrame(rafId)
      releaseSwitching()

      if (loadSettledRef.current) {
        return
      }

      // Input wins even at a clamped top, where no scroll event fires.
      stopScroll()
      loadSettledRef.current = true
      liveScrollStateRef.current = threadScrollStateFromMetrics(el)
      restoreFromBottomRef.current = el.scrollHeight - el.scrollTop
    }

    cancelRestoreRef.current = target.kind === 'offset' ? cancelRestore : () => resizeObserver.disconnect()

    const onWheel = (event: WheelEvent) => {
      resizeObserver.disconnect()

      // A wheel/trackpad scroll-up is explicit reading intent. Break the
      // bottom-follow synchronously, before a same-frame content resize can
      // ask use-stick-to-bottom to re-pin while its delayed scroll handler
      // still considers the thread locked.
      if (event.deltaY < 0) {
        stopScroll()
      }

      if (event.deltaY !== 0) {
        cancelRestore()
      }
    }

    // A position neither this effect nor use-stick-to-bottom produced is the
    // user's (scrollbar drag, rail jump, find-in-page reveal) and ends the
    // restore like wheel input does — otherwise the next ResizeObserver tick
    // would rewrite scrollTop over a genuine scroll.
    const onScroll = () => {
      if (el.scrollTop === ownScrollTop || el.scrollTop === threadScrollTargetTop(target, el)) {
        return
      }

      cancelRestore()
    }

    jumpRestoreRef.current = () => {
      cancelRestore()
      // A jump replaces reading intent, including an in-flight prepend anchor.
      // Re-arm resize protection: deferred markdown may grow after this click.
      target = THREAD_SCROLL_BOTTOM
      restoreFromBottomRef.current = null
      liveScrollStateRef.current = target

      applyRestoreRef.current = () => {
        applyTarget(el)
      }

      loadSettledRef.current = true
      applyTarget(el)

      if (contentRef.current) {
        resizeObserver.observe(contentRef.current)
      }

      void scrollToBottomUnlessSelecting('instant')
    }

    el.addEventListener('wheel', onWheel, { passive: true })
    el.addEventListener('scroll', onScroll, { passive: true })
    el.addEventListener('pointerdown', cancelRestore, { passive: true })
    el.addEventListener('keydown', cancelRestore)

    return () => {
      cancelRestoreRef.current = null
      applyRestoreRef.current = null
      resizeObserver.disconnect()
      jumpRestoreRef.current = null
      el.removeEventListener('wheel', onWheel)
      el.removeEventListener('scroll', onScroll)
      el.removeEventListener('pointerdown', cancelRestore)
      el.removeEventListener('keydown', cancelRestore)
      cancelAnimationFrame(rafId)
      releaseSwitching()
      record()
    }
  }, [
    contentRef,
    hasGroups,
    paneVisible,
    scrollRef,
    scrollStorageKey,
    scrollToBottomUnlessSelecting,
    sessionKey,
    stopScroll
  ])

  // The load phase of a switch: the route names a session whose transcript
  // has not arrived. The restore loop above takes over the marker when it does.
  useLayoutEffect(() => {
    if (!sessionLoading || !paneVisible) {
      return
    }

    return holdSessionSwitching(scrollRef.current)
  }, [paneVisible, scrollRef, sessionLoading])

  // A thread can mount with a run already active, without a runStart event.
  useEffect(() => {
    if (isRunning) {
      cancelRestoreRef.current?.()
    }
  }, [hasGroups, isRunning, sessionKey])

  // A window request owns no position while in flight. Capture at application
  // time, when the reader may be somewhere else. A session/visibility change
  // invalidates the callback, including an old promise resolving after reveal.
  useLayoutEffect(
    () => () => {
      windowRequestRef.current = null
      windowCommitRef.current = null
    },
    [paneVisible, scrollStorageKey, sessionKey]
  )

  const releaseParkedRestore = useCallback(() => {
    if (!loadSettledRef.current && restoreFromBottomRef.current != null) {
      cancelRestoreRef.current?.()
      restoreFromBottomRef.current = null
    }
  }, [])

  const growWindow = useCallback(async () => {
    if (!paneVisible || windowRequestRef.current || windowCommitRef.current != null) {
      return
    }

    const request = {}
    windowRequestRef.current = request
    let captured = false

    try {
      const applied = await expandWindow(() => {
        if (windowRequestRef.current !== request) {
          return
        }

        captured = true
        windowCommitRef.current = structuralSignature
        anchorBeforePrepend()
        setRenderBudget(budget => budget + paneBudget)
      })

      if (windowRequestRef.current === request) {
        if (applied === false || !captured) {
          windowCommitRef.current = null
          releaseParkedRestore()
        } else {
          autoGrowPagesRef.current += 1
        }
      }
    } catch {
      // The existing Show earlier button remains the explicit retry path.
      if (windowRequestRef.current === request) {
        windowCommitRef.current = null
        releaseParkedRestore()
      }
    } finally {
      if (windowRequestRef.current === request) {
        windowRequestRef.current = null
        setRestoreGrowTick(tick => tick + 1)
      }
    }
  }, [anchorBeforePrepend, expandWindow, paneBudget, paneVisible, releaseParkedRestore, structuralSignature])

  // Prepend an older page while preserving the on-screen position. The user is
  // scrolled up (reading history) so the stick-to-bottom lock is escaped and
  // won't fight this manual restore. Spend the already-materialized DOM page
  // first; only when that is exhausted pull more messages out of the session
  // store (#55191).
  const showEarlier = useCallback(() => {
    const action = resolveShowEarlierAction(hiddenCount, olderAvailable)

    if (!action) {
      return
    }

    if (action === 'window') {
      void growWindow()
    } else {
      anchorBeforePrepend()
      setRenderBudget(budget => budget + paneBudget)
    }
  }, [anchorBeforePrepend, growWindow, hiddenCount, olderAvailable, paneBudget])

  useTimelineReveal({
    viewport: scrollRef,
    groups: weightedGroups,
    hiddenCount,
    renderBudget,
    olderAvailable,
    expandWindow,
    sessionKey,
    revealBudget: budget => setRenderBudget(current => Math.max(current, budget)),
    prepare: () => {
      cancelRestoreRef.current?.()
      applyRestoreRef.current = null
      restoreFromBottomRef.current = null
      loadSettledRef.current = true
      stopScroll()
    }
  })

  // Page the focused transcript explicitly. Browser-default PageUp/PageDown
  // targets whichever ancestor happens to own focus, which is unreliable in
  // the nested desktop layout. Keep the movement here with the thread's sole
  // scroll owner, and key the request so split/kept-alive threads stay put.
  useEffect(
    () =>
      onThreadPageScrollRequest(direction => {
        const el = scrollRef.current

        if (!el) {
          return
        }

        // A no-op PageDown at the bottom must not escape sticky follow: the
        // browser will clamp the write and emit no scroll event to re-lock it.
        if (direction > 0 && threadScrollStateFromMetrics(el).kind === 'bottom') {
          return
        }

        cancelRestoreRef.current?.()
        stopScroll()

        // At the clamped top there will be no native scroll event to trigger
        // the existing automatic "Show earlier" path. Treat PageUp there like
        // an upward wheel notch before moving the viewport.
        if (
          direction < 0 &&
          shouldAutoShowEarlier({
            action: resolveShowEarlierAction(hiddenCount, olderAvailable),
            isAtBottom,
            loadSettled: loadSettledRef.current,
            restorePending: restoreFromBottomRef.current != null,
            scrollTop: el.scrollTop,
            wheelDeltaY: direction
          })
        ) {
          showEarlier()

          return
        }

        el.scrollTop += direction * el.clientHeight
      }, sessionKey ?? null),
    [hiddenCount, isAtBottom, olderAvailable, scrollRef, sessionKey, showEarlier, stopScroll]
  )

  // Scroll/wheel at the top edge pages older turns through the same showEarlier
  // path as the button. Wheel is required because browsers emit no `scroll`
  // once scrollTop is already 0 — exactly where the reader who wants more is.
  useEffect(() => {
    const el = scrollRef.current

    if (!el) {
      return
    }

    const tryShowEarlier = (wheelDeltaY?: number) => {
      if (
        shouldAutoShowEarlier({
          action: resolveShowEarlierAction(hiddenCount, olderAvailable),
          isAtBottom,
          loadSettled: loadSettledRef.current,
          restorePending: restoreFromBottomRef.current != null,
          scrollTop: el.scrollTop,
          wheelDeltaY
        })
      ) {
        showEarlier()
      }
    }

    const onScroll = () => tryShowEarlier()
    const onWheel = (event: WheelEvent) => tryShowEarlier(event.deltaY)

    el.addEventListener('scroll', onScroll, { passive: true })
    el.addEventListener('wheel', onWheel, { passive: true })

    return () => {
      el.removeEventListener('scroll', onScroll)
      el.removeEventListener('wheel', onWheel)
    }
  }, [hiddenCount, isAtBottom, olderAvailable, scrollRef, showEarlier])

  useLayoutEffect(() => {
    const el = scrollRef.current
    const restoreFromBottom = restoreFromBottomRef.current

    if (windowCommitRef.current === structuralSignature) {
      return
    }

    windowCommitRef.current = null

    // Apply load intent in the commit, without spending an unchanged anchor.
    if (paneVisible && (restoreFromBottom == null || liveScrollStateRef.current.kind === 'bottom')) {
      applyRestoreRef.current?.()
    }

    if (
      el &&
      restoreFromBottom != null &&
      el.scrollHeight > (anchorHeightRef.current ?? 0) &&
      el.scrollHeight >= restoreFromBottom
    ) {
      el.scrollTop = el.scrollHeight - restoreFromBottom
      restoreFromBottomRef.current = null
      // Consuming a parked offset (clamped-exit) means the view just landed at
      // its real reading position — the load is settled from here on.
      loadSettledRef.current = true
    }
    // renderBudget covers DOM pages; groups.length covers store-window expands.
  }, [scrollRef, renderBudget, structuralSignature, paneVisible])

  // Regrow toward a parked reading offset through the existing paging path.
  // Keep its target intact until reachable; exhaustion releases it at the
  // nearest available position rather than leaving restoration stuck forever.
  useLayoutEffect(() => {
    const el = scrollRef.current
    const restoreFromBottom = restoreFromBottomRef.current

    if (!el || restoreFromBottom == null || el.scrollHeight >= restoreFromBottom) {
      return
    }

    // Wait for the stepped backfill to top out first: while it is still
    // climbing the tree may cover the offset on its own, and racing it would
    // only hoard pages. A hidden pane stays put entirely — its budget is
    // clamped to the live tail and the reveal re-runs this effect.
    if (renderBudget < paneBudget || !paneVisible) {
      return
    }

    const action = resolveShowEarlierAction(hiddenCount, olderAvailable)

    if (!action || autoGrowPagesRef.current >= PARKED_OFFSET_MAX_PAGES) {
      releaseParkedRestore()

      return
    }

    if (windowRequestRef.current) {
      return
    }

    if (action === 'window') {
      void growWindow()
    } else {
      autoGrowPagesRef.current += 1
      startTransition(() => setRenderBudget(budget => budget + paneBudget))
    }
  }, [
    restoreGrowTick,
    scrollRef,
    renderBudget,
    groups.length,
    hiddenCount,
    olderAvailable,
    paneBudget,
    growWindow,
    paneVisible,
    releaseParkedRestore
  ])

  // The row array is memoized on the inputs the rows actually read. This
  // component re-renders on every isAtBottom flip — and use-stick-to-bottom
  // flips it from a ResizeObserver, so a sidebar DRAG re-renders this list per
  // frame. Without the memo, the inline .map() rebuilt every row's JSX each
  // time, and rebuilt children re-render their whole subtree even when nothing
  // changed (measured live: 865 wasted Block renders in one drag, walked to
  // "MessageRenderBoundary (children only)" by explain()). With it, React
  // bails out on element identity and a scroll flip re-renders nothing below.
  const rows = useMemo(() => {
    const rowKeys = turnRowKeys(rowKeySignature, structuralSignature)

    return visibleGroups.map((group, indexInVisible) => (
      <TurnRow
        components={components}
        group={group}
        key={rowKeys[group.kind === 'turn' ? group.indices[0] : group.index] ?? group.id}
        resetKey={structuralSignature}
        virtualized={indexInVisible < tailStart}
      />
    ))
  }, [visibleGroups, components, rowKeySignature, structuralSignature, tailStart])

  useMessagesBelow({ contentRef, scrollRef, isAtBottom, paneVisible, rows, sessionKey, sessionId: scrollSessionId })
  useStickyPromptClip({ contentRef, scrollRef, paneVisible, rows })

  return (
    <div
      className="relative min-h-0 max-w-full overflow-hidden contain-[layout_paint]"
      style={
        {
          height: clampToComposer ? 'var(--thread-viewport-height)' : '100%',
          ...(secondaryWindow ? { '--sticky-human-top': secondaryTitlebarGap } : {})
        } as CSSProperties
      }
    >
      {secondaryWindow && (
        // Secondary windows hide the titlebar chrome, so the scroller runs to
        // the window's top edge and streamed text slides up under the OS
        // traffic lights. Content padding alone scrolls away with the text — a
        // fixed opaque strip (the titlebar's drag region) masks anything behind
        // it and keeps the window draggable, matching the main window's header.
        <div
          aria-hidden="true"
          className="absolute inset-x-0 top-0 z-10 h-(--titlebar-height) bg-background [-webkit-app-region:drag]"
        />
      )}
      <div
        className="size-full overflow-x-hidden overflow-y-auto overscroll-contain"
        data-following={isAtBottom ? 'true' : 'false'}
        data-slot="aui_thread-viewport"
        ref={scrollRef as React.RefCallback<HTMLDivElement>}
      >
        <div
          className={cn(
            'mx-auto flex min-h-full w-full max-w-(--composer-width) min-w-0 flex-col px-6',
            renderEmpty ? 'py-8' : threadContentTopPad
          )}
          data-slot="aui_thread-content"
          ref={contentRef as React.RefCallback<HTMLDivElement>}
        >
          {!renderEmpty && (hiddenCount > 0 || olderAvailable) && (
            <button
              className="mx-auto mb-(--conversation-turn-gap) rounded-full border border-border/65 bg-(--composer-fill) px-3 py-1 text-xs text-muted-foreground hover:text-foreground"
              onClick={showEarlier}
              type="button"
            >
              {t.assistant.thread.showEarlier}
            </button>
          )}
          {renderEmpty ? (
            <div className="grid flex-1 grid-rows-[minmax(0,1fr)_auto] gap-(--conversation-turn-gap)">
              {emptyPlaceholder}
            </div>
          ) : (
            rows
          )}
          <PendingApprovalStack />
          {!renderEmpty && loadingIndicator}
          {!renderEmpty && clampToComposer && (
            <div
              aria-hidden="true"
              className="shrink-0"
              data-slot={COMPOSER_CLEARANCE_SLOT}
              ref={clearanceRef}
              style={{ height: 'var(--thread-last-message-clearance)' }}
            />
          )}
        </div>
      </div>
    </div>
  )
}

export const ThreadMessageList = memo(ThreadMessageListInner)