Streaming follow scheduled a two-frame animation-frame chain per content
growth and then went through the list's programmatic scrollToEnd, whose
scroll bookkeeping schedules further frames. Together they roughly
doubled frame production for the whole stream (16 -> 35 frames/s in a
profiled streaming session), with the matching style recalc and layout
cost per frame.
In following-end mode, correct synchronously in the totalSize listener by
writing scrollTop directly — the same write path a user gesture takes —
and keep the animation-frame chain only for the anchored-turn glide.
Profiled streaming frame production returns to the previous engine's
range and peak heap drops from 164 MB to 90 MB.
The streaming status and the scroll-to-bottom pill now hand off to each
other in one place above the composer: same anchor, same input-aligned
column, both in the popover glass (ring and soft shadow stay pill-only
as the interactivity cue, with the shadow on a wrapper so the glass
backdrop-filter cannot drop it after hide/show cycles). The pill is a
single full-surface button, moves to the left edge, and while the
session streams it carries a compact one-line status label instead of
the status row's animation machinery, which did not survive a 32px
chip.
Behavioral fixes along the way: a gesture shows the pill immediately
(no debounce) and hides the status in the same frame; gestures register
whenever the viewport can actually move up — an anchored short turn
kept live-follow armed and suppressed the pill entirely; the status
row sheds its in-list morph offsets (mb-6, message column) and its
inline-size container gets the glass on an inner row, since a query
container cannot shrink-wrap; its working text uses full
muted-foreground to match the pill.
The animated glide trails its target between corrections, so the
distance-based at-end signal flapped during streaming and the pill and
the status row crossfaded into overlapping half-transparent mush. The
pill now shows only in free-scrolling (a real gesture), which also
keeps the status row's visibility stable; a gesture taken after our own
movement already left the end offers the pill immediately.
The phase-2 reveal correction now scrolls animated; successive
corrections restart the smooth scroll from the current position, so
streaming follows as one continuous motion. User gestures interrupt the
native smooth scroll, so free-scrolling is unaffected.
Phase 2 of the anchored turn (following the live edge once the reply
outgrows the viewport) never ran: the reveal correction was triggered
only by entries-array changes, and the streaming tail grows inside a
single row without touching the array. The hook now also subscribes to
LegendList's totalSize and re-runs the same guarded correction on every
content growth.
Six reported defects, one root theme — our port diverged from the
reference semantics:
- a user gesture no longer collapses the reserved anchored end space
(that snap-to-bottom was the 'anchoring vanishes on a micro-scroll');
it only disarms the follow/anchor machinery, and anchor remeasures
after the user takes over can no longer re-position the viewport
- the anchor arms synchronously BEFORE the send reaches the store, and
the claim compares against the arm-time baseline — arming a frame
after the optimistic row committed is why anchoring 'rarely worked'
and sending from mid-history did nothing
- gestures are selective (wheel up, touch/pointer away from the end,
PageUp/Home/ArrowUp), so scrolling toward the end or clicking a row
at the live edge no longer kills follow
- 'at end' is a tight 40px band against the full content length instead
of the list's half-viewport isNearEnd, so the scroll-to-bottom pill
appears when the viewport actually leaves the end
- reaching the end re-arms follow without knocking an anchored turn out
of its mode, and the overlay scrollbar suppression follows scroll
ownership rather than the anchor's mere existence
- the status/working row moved out of the list footer to a fixed spot
above the composer: inside the list it walked down with every
streamed line, and its unmount was part of the end-of-stream jerk
Sending a message now parks that message near the top of the viewport
and streams the reply into reserved end space below it, instead of
jumping to the bottom and chasing it.
- swap @tanstack/react-virtual for @legendapp/list in the chat timeline; the
streaming tail becomes a normal list row rather than a separately rendered
block, so one component owns the scroll position
- add timelineScrollAnchoring: pure anchored-turn geometry plus the three
scroll modes (following-end / anchoring-new-turn / free-scrolling)
- replace useChatAutoFollow with useChatTimelineScroll, which opts out of
automatic movement on real gestures via a generation counter instead of the
timer windows the old implementation needed to recognise its own writes
- move the load-older button, question/permission cards, recap, status row and
bottom spacer into the list header/footer, since the list owns its container
- extract useScrollShadow so the shadows can attach to that container
maintainScrollAtEnd and maintainVisibleContentPosition replace the manual
prepend anchor-hold and the mobile quiet-window prepend deferral.
Validated: workspace type-check, lint, web build, ui tests per file.
Scroll behaviour itself is unverified and needs manual testing on web, desktop
and iOS.
Bohdan Triapitsyn