perf(desktop): fix "Enter jumps up" on long threads

User reported: after pressing Enter on a long thread, the view jumps up
— the just-submitted message disappears below the fold. Confirmed via
apps/desktop/scripts/measure-jump.mjs:

  before:  distFromBottom 0 → 49.5px, sticks there permanently
  after:   distFromBottom 0 → ~0 (worst case 4px for one frame)

Root cause in useThreadScrollAnchor (thread-virtualizer.tsx):

1. The sticky-bottom logic disarmed on any scroll event where
   `scrollTop < lastTopRef.current`. That check can't distinguish a
   user scrolling up from a programmatic `pinToBottom` write that
   the browser clamped short of bottom (because content also grew in
   the same frame, so `scrollTop = scrollHeight` lands at
   `scrollHeight - clientHeight` for the OLD scrollHeight, which is
   now below the NEW scrollHeight). Result: sticky-bottom disarmed
   permanently on the user's first submit.

2. There was no synchronous pin tied to React's commit phase. By the
   time the ResizeObserver fired and re-pinned, the user had already
   seen ~50ms of "message below the fold" — visually that reads as the
   view jumping up.

Fix:

- `programmaticScrollPendingRef` counter tracks scroll events we
  expect to be ours (one per `pinToBottom` write). The scroll handler
  skips the disarm check when consuming a pending tick, keeps the
  arm bit true, and re-pins synchronously if the browser clamped us
  short of bottom. A depth cap (8) breaks runaway loops in
  pathological streaming-burst layouts.

- `useLayoutEffect` on `groupCount` increase pins BEFORE the browser
  paints, eliminating the visible ~50ms window between optimistic
  user-message insert and the RO/scroll-event chain firing.

Verified on the long Cloud Shadows thread (7-8 turns, ~11k px tall):
all three repro runs now hold within 0–4 px of bottom across the
post-Enter transition. Submit latency unchanged (paint 77–107 ms),
streaming-typing latency unchanged.

Also adds three debug harnesses:
  - measure-jump.mjs   — sample thread scroll across Enter
  - probe-thread.mjs   — dump current thread / scroll state
  - diag-jump.mjs      — intercept scrollTop + RO + mutations across Enter
This commit is contained in:
Brooklyn Nicholson
2026-05-21 17:45:55 -05:00
parent e18c233c1e
commit a7e6a4fc0b
4 changed files with 339 additions and 1 deletions
@@ -1,6 +1,6 @@
import { ThreadPrimitive, useAuiEvent, useAuiState } from '@assistant-ui/react'
import { useVirtualizer, type Virtualizer } from '@tanstack/react-virtual'
import { type ComponentProps, type FC, type ReactNode, useCallback, useEffect, useMemo, useRef } from 'react'
import { type ComponentProps, type FC, type ReactNode, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
import { cn } from '@/lib/utils'
import { setThreadScrolledUp } from '@/store/thread-scroll'
@@ -182,9 +182,25 @@ function useThreadScrollAnchor({ enabled, groupCount, scrollerRef, sessionKey, v
// user-driven upward scroll; re-armed when they reach bottom again.
const armedRef = useRef(true)
const lastTopRef = useRef(0)
// Counter that tracks how many scroll events we expect to be ours rather
// than the user's. `pinToBottom` writes `el.scrollTop`, which fires an
// async `scroll` event; without this guard the on-scroll handler can race
// with the programmatic write (because content also grew, the *resulting*
// scrollTop can be lower than `lastTopRef` from the previous frame) and
// misread the programmatic pin as the user scrolling up — which disarms
// sticky-bottom and the user's just-submitted message slides above the
// fold. See `apps/desktop/scripts/measure-jump.mjs` for the repro
// (distFromBottom 0 → 49 within one frame, sticking forever).
const programmaticScrollPendingRef = useRef(0)
const prevSessionKeyRef = useRef(sessionKey)
const prevGroupCountRef = useRef(0)
// Track repins-in-a-row to break runaway loops during rapid layout churn.
// In healthy paths this drains to zero between frames; we only need the
// ceiling for pathological streaming bursts where content height keeps
// growing every frame.
const inFlightPinDepthRef = useRef(0)
const pinToBottom = useCallback(() => {
const el = scrollerRef.current
@@ -192,6 +208,8 @@ function useThreadScrollAnchor({ enabled, groupCount, scrollerRef, sessionKey, v
return
}
// Hold the disarm gate across the scroll event the next line will fire.
programmaticScrollPendingRef.current += 1
el.scrollTop = el.scrollHeight
lastTopRef.current = el.scrollTop
}, [scrollerRef])
@@ -228,6 +246,45 @@ function useThreadScrollAnchor({ enabled, groupCount, scrollerRef, sessionKey, v
const onScroll = () => {
const top = el.scrollTop
// If this scroll event is the consequence of `pinToBottom` writing
// `el.scrollTop`, treat it as ours: never disarm, just consume the
// gate. If we landed short of bottom (because content also grew in
// the same frame and the browser clamped our scrollTop = scrollHeight
// write to the now-stale scrollHeight - clientHeight), schedule
// another pin on the next frame. Without this the post-pin scrollTop
// gets misread as the user scrolling up, disarming sticky-bottom
// permanently and leaving the just-submitted message below the fold.
if (programmaticScrollPendingRef.current > 0) {
programmaticScrollPendingRef.current -= 1
lastTopRef.current = top
// Stay armed regardless — sticky-bottom should hold through clamp
// races.
armedRef.current = true
const atBottom = el.scrollHeight - (top + el.clientHeight) <= AT_BOTTOM_THRESHOLD
setThreadScrolledUp(!atBottom)
if (atBottom) {
inFlightPinDepthRef.current = 0
} else if (inFlightPinDepthRef.current < 8) {
// Re-pin synchronously: the browser already laid out for this
// scroll event, so reading scrollHeight now gives us the up-to-date
// value and writing scrollTop lands us at the actual bottom in the
// same frame. Doing this in a rAF causes a 1-frame visual flicker
// (distFromBottom briefly nonzero), so we accept one extra
// synchronous pin cycle (which goes back through this very
// handler with the counter incremented and arm preserved). The
// depth guard prevents pathological runaway loops if content
// height keeps growing every frame; 8 is generous for any
// realistic rendering pattern.
inFlightPinDepthRef.current += 1
pinToBottom()
} else {
inFlightPinDepthRef.current = 0
}
return
}
if (top + 1 < lastTopRef.current) {
armedRef.current = false
}
@@ -302,5 +359,23 @@ function useThreadScrollAnchor({ enabled, groupCount, scrollerRef, sessionKey, v
}
}, [enabled, groupCount, jumpToBottom, sessionKey])
// Pre-paint pin: when groupCount increases while armed (optimistic user
// message insert, streaming assistant turn arriving, etc.), pin BEFORE
// the browser commits the layout to screen. Using useLayoutEffect rather
// than useEffect so this runs synchronously after React commits the DOM
// mutation but before the browser paints. Without this, there's a ~50ms
// visual window where the new message sits below the fold while we wait
// for the ResizeObserver / scroll event chain to fire and re-pin.
const prevGroupCountForLayoutRef = useRef(groupCount)
useLayoutEffect(() => {
if (!enabled) {
return
}
if (groupCount > prevGroupCountForLayoutRef.current && armedRef.current) {
pinToBottom()
}
prevGroupCountForLayoutRef.current = groupCount
}, [enabled, groupCount, pinToBottom])
useAuiEvent('thread.runStart', jumpToBottom)
}