Viewport Auto-Scroll#

useThreadViewportAutoScroll is the central hook powering scroll management inside ThreadPrimitive.Viewport. It attaches to the scrollable container DOM element via a composed ref and coordinates three concerns: when to scroll to bottom, how to detect user intent, and how to coexist with the top-anchor reserve system.

Entry point: useThreadViewportAutoScroll.ts

Scroll Triggers#

The hook exposes four independent triggers, each defaulting to true 1:

autoScroll determines whether content-resize events continue scrolling the viewport to bottom while the user is already at bottom (i.e., the streaming "follow" behavior). It defaults to false when turnAnchor="top" 2.

Pending Intent (scrollingToBottomBehaviorRef)#

A single ref, scrollingToBottomBehaviorRef, carries a pending scroll-to-bottom intent as a ScrollBehavior | null 3. It is planted by any of the triggers above and cleared by one of three conditions 4:

1. Reached bottom with overflow — handleScroll confirms scrollHeight > clientHeight + 1 and the difference is ≤ 1px (at-bottom). Clears intent. The overflow guard prevents false-positive clearance when content hasn't grown yet.
2. User scrolls up with stable content — handleScroll detects upward scroll (lastScrollTop > div.scrollTop) and unchanged scrollHeight. Clears intent so future content growth won't re-snap the viewport. This was fixed in PR #4141 after content-driven mutations (markdown re-renders, lazy images) were re-triggering scrollToBottom even after users scrolled away.
3. User pointer-down — A pointerdown listener immediately nulls the intent 5. Prevents an intent kept alive by a non-overflowing thread from hijacking the next content growth (e.g., expanding a tool call result).

While intent is set and content resizes, useOnResizeContent re-invokes scrollToBottom(behavior) on each layout change, continuously following new content during streaming.

In-flight smooth scroll guard: handleScroll suppresses intermediate events during a smooth animation — it no-ops if scrollTop is increasing but hasn't reached bottom yet, preventing isAtBottom flicker 6.

At-Bottom Detection#

isAtBottom is stored in ThreadViewportStore and updated by handleScroll. The check uses a ≤ 1px threshold 7:

Math.abs(scrollHeight - scrollTop - clientHeight) <= 1 || scrollHeight <= clientHeight

The <= 1 (not < 1) threshold was introduced in PR #4141 to absorb sub-pixel clipping on high-DPR (Retina) displays, where Chrome macOS clips scrollTop 1px short of its target.

Top-Anchor Conflict Resolution#

When turnAnchor="top" is active, the viewport uses a top-anchor reserve to keep new user messages visible at the top of the scroll area. This system (introduced in PR #3908) lives under packages/react/src/primitives/thread/topAnchor/ and manages a stable DOM reserve element owned by the viewport.

The auto-scroll hook detects an active top-anchor via hasActiveTopAnchor() 8, which checks turnAnchor === "top", the viewport element identity, and that an anchor element is registered. When a resize event fires with a pending bottom-scroll intent and a top-anchor is active, the intent is surrendered 9:

if (scrollBehavior && hasActiveTopAnchor()) {
  // Let the top-anchor reserve own scrolling — avoid a bottom-scroll race
  scrollingToBottomBehaviorRef.current = null;
}

Additionally, thread.runStart skips planting intent entirely when turnAnchor="top" 10.

The mountTopAnchorReserve.ts module handles the reserve element's scroll correction using behavior: "instant" — changed in PR #4110 from "smooth" to eliminate the one-frame jitter that appeared before the correction landed.

Key Files#