Merge pull request Stack-Cairn#108 from Stack-Cairn/features

fix(transcript): stop unwanted auto-scroll while reading during and after streaming

Author: su-fen

crates/agent-gateway/web/src/app/GatewayApp.tsx

@@ -3890,6 +3890,7 @@ export default function GatewayApp() {
                           rows={transcriptRows}
                           liveStartIndex={transcriptLiveStartIndex}
                           activeTurnKey={displayedTranscript.activeTurnKey}
+                          isViewportFollowing={transcriptFollow.isFollowing}
                           error={transcriptError}
                           toolStatus={transcriptToolStatus}
                           toolStatusIsCompaction={transcriptToolStatusIsCompaction}

crates/agent-gateway/web/src/components/GatewayTranscript.tsx

@@ -36,6 +36,7 @@ import {
 import type { GitClient } from "@/lib/git/types";
 import { cn } from "@/lib/shared/utils";
 import { extractLiveRange } from "@/lib/transcript-virtual/liveRangeExtractor";
+import { createLiveRowScrollAdjustPolicy } from "@/lib/transcript-virtual/liveScrollAdjustPolicy";
 import {
   CHECKPOINT_ROW_ESTIMATE_PX,
   estimateAssistantRowHeight,
@@ -77,6 +78,9 @@ type GatewayTranscriptProps = {
   liveStartIndex?: number;
   // Key of the actively streaming turn (caret / live structural state).
   activeTurnKey?: string | null;
+  // Whether the scroll-follow engine is attached to the bottom; gates the
+  // virtualizer's resize-compensation carve-out for live-row growth.
+  isViewportFollowing?: () => boolean;
   error?: string | null;
   toolStatus?: string | null;
   toolStatusIsCompaction?: boolean;
@@ -1088,6 +1092,7 @@ const GatewayTranscriptListRegion = memo(function GatewayTranscriptListRegion(pr
   liveStartIndex: number;
   activeTurnKey?: string | null;
   scrollViewport: HTMLDivElement | null;
+  isViewportFollowing?: () => boolean;
   hasMoreHistory?: boolean;
   isLoadingMoreHistory?: boolean;
   onLoadFullHistory?: () => void;
@@ -1114,6 +1119,7 @@ const GatewayTranscriptListRegion = memo(function GatewayTranscriptListRegion(pr
     liveStartIndex,
     activeTurnKey,
     scrollViewport,
+    isViewportFollowing,
     hasMoreHistory,
     isLoadingMoreHistory,
     onLoadFullHistory,
@@ -1240,6 +1246,15 @@ const GatewayTranscriptListRegion = memo(function GatewayTranscriptListRegion(pr
     enabled: scrollViewport !== null,
     rangeExtractor: (range) => extractLiveRange(range, forceMountStartRef.current),
   });
+
+  // TanStack exposes the resize-compensation predicate as an instance field,
+  // not an option; reassigning per render keeps the closure's inputs current.
+  transcriptVirtualizer.shouldAdjustScrollPositionOnItemSizeChange =
+    createLiveRowScrollAdjustPolicy({
+      getLiveStartIndex: () => forceMountStartRef.current,
+      isFollowing: () => isViewportFollowing?.() ?? false,
+    });
+
   const virtualRows = transcriptVirtualizer.getVirtualItems();
 
   // Prepend anchor: when loading earlier history inserts rows above the
@@ -1248,7 +1263,8 @@ const GatewayTranscriptListRegion = memo(function GatewayTranscriptListRegion(pr
   // getOffsetForIndex(_, "start") is the public offset accessor; the anchor
   // and the restore read through the same function, so the delta is exact.
   const prependAnchorRef = useRef<{ key: string; start: number } | null>(null);
-  // biome-ignore lint/correctness/useExhaustiveDependencies: runs per commit by design
+  // Intentionally no dependency array: the anchor must re-read on every
+  // commit, since any render can be the one that prepends rows.
   useLayoutEffect(() => {
     const firstRowKey = virtualItems[leadingOffset]?.key ?? null;
     const startOf = (index: number) => transcriptVirtualizer.getOffsetForIndex(index, "start")?.[0];
@@ -1458,6 +1474,7 @@ export function GatewayTranscript({
   rows,
   liveStartIndex = -1,
   activeTurnKey = null,
+  isViewportFollowing,
   error,
   toolStatus,
   toolStatusIsCompaction = false,
@@ -1531,6 +1548,7 @@ export function GatewayTranscript({
           liveStartIndex={liveStartIndex}
           activeTurnKey={activeTurnKey}
           scrollViewport={transcriptScrollViewport}
+          isViewportFollowing={isViewportFollowing}
           hasMoreHistory={hasMoreHistory}
           isLoadingMoreHistory={isLoadingMoreHistory}
           onLoadFullHistory={onLoadFullHistory}

crates/agent-gateway/web/src/lib/chat-scroll/scrollFollowCore.ts

@@ -14,11 +14,16 @@
 //   after a programmatic pin (the abort lands with the next main-thread
 //   commit); those frames carry no input and no drag, so they can never
 //   detach.
-// - ATTACH is position-driven: landing at the physical clamp always attaches;
-//   a gesture-latched downward arrival inside the reattach zone attaches; a
-//   pointer released inside the zone after downward movement attaches. The
-//   gesture latch is the only timing heuristic left and it gates attach only —
-//   a false positive re-pins, it can never tear follow down.
+// - ATTACH is position-driven and intent-gated: landing at the physical clamp
+//   attaches while following (our own pin write echoing back) or inside an
+//   active gesture latch; a gesture-latched downward arrival inside the
+//   reattach zone attaches; a pointer released inside the zone after downward
+//   movement attaches. Content shrinking under a detached reader (a reply
+//   settling out of the row list, a collapsing block) also clamps scrollTop
+//   to the bottom with no input — that arrival carries no latch, so it can
+//   never re-engage follow and the next growth cannot yank the reader down.
+//   The gesture latch is the only timing heuristic left and it gates attach
+//   only — a false positive re-pins, it can never tear follow down.
 // - While following, a scroll event that leaves a gap open is corrected by
 //   re-pinning rather than classified.
 // - ResizeObserver deliveries (contentGrowth) never change follow state; they
@@ -194,11 +199,17 @@ export function reduceFollowEvent(
       const next = { ...state, lastGap: gap };
 
       if (isAtBottom(gap, config)) {
-        // At the physical clamp — attaching is always safe, whether the user
-        // landed here or our own pin write echoed back. Also counts as
-        // downward movement for the pointer-release re-check.
-        next.following = true;
+        // At the physical clamp. Counts as downward movement for the
+        // pointer-release re-check, but attaching needs evidence of intent:
+        // our own pin write echoing back (still following) or an arrival
+        // inside an active gesture latch. Content shrinking under a detached
+        // reader (a reply settling out of the row list, a collapsing block)
+        // also clamps scrollTop here with no input — attaching on that would
+        // let the next growth yank the reader to the bottom.
         next.dragTowardBottom = true;
+        if (state.following || now <= state.latchUntil) {
+          next.following = true;
+        }
         return { state: next, pin: false };
       }
 

crates/agent-gateway/web/src/lib/transcript-virtual/liveScrollAdjustPolicy.ts

@@ -0,0 +1,74 @@
+import type { VirtualItem, Virtualizer } from "@tanstack/react-virtual";
+
+// Resize-compensation policy for the transcript virtualizer.
+//
+// virtual-core's default shouldAdjustScrollPositionOnItemSizeChange treats any
+// resize of a row whose START sits above the viewport top as "content above
+// the reader changed" and shifts scrollTop by the delta. That is correct for
+// rows entirely above the viewport, but wrong for the live streaming row once
+// it grows taller than the viewport: a reader scrolled up into that row has
+// the row's start above the viewport top while the stream appends at the
+// row's BOTTOM edge, below everything visible. The default then drags
+// scrollTop down by exactly the growth delta on every stream flush — the
+// view creeps toward the bottom and the transcript is unreadable.
+//
+// This policy replicates the upstream default and carves out exactly that
+// case: growth (delta > 0) of a live row that still extends past the viewport
+// top never adjusts while the user is detached from the bottom. Everything
+// else keeps the default:
+// - rows entirely above the viewport compensate as before (estimate→measured
+//   corrections must not jump the view);
+// - while following, the compensation cooperates with the scroll-follow pin,
+//   so it stays on;
+// - live-row shrinks (delta < 0, e.g. a thinking block collapsing near the
+//   row's top) keep compensating so content under the reader stays put.
+export type LiveRowScrollAdjustPolicyArgs = {
+  // Index of the first live (streaming) row in the virtualizer's item list,
+  // -1 while idle. Read per call — the boundary moves between renders.
+  getLiveStartIndex: () => number;
+  // Whether the scroll-follow engine is attached to the bottom.
+  isFollowing: () => boolean;
+};
+
+export function createLiveRowScrollAdjustPolicy<
+  TScrollElement extends Element | Window,
+  TItemElement extends Element,
+>(
+  args: LiveRowScrollAdjustPolicyArgs,
+): (
+  item: VirtualItem,
+  delta: number,
+  instance: Virtualizer<TScrollElement, TItemElement>,
+) => boolean {
+  const { getLiveStartIndex, isFollowing } = args;
+  return (item, delta, instance) => {
+    // Un-echoed scroll writes accumulate in a private field until the next
+    // scroll event; the upstream default folds them into the comparison, so
+    // mirror that (fall back to 0 if the field ever disappears).
+    const pendingAdjustments =
+      (instance as unknown as { scrollAdjustments?: number }).scrollAdjustments ?? 0;
+    const viewportTop = (instance.scrollOffset ?? 0) + pendingAdjustments;
+
+    // Upstream default: only above-viewport resizes may shift scrollTop, and
+    // never while the user is actively scrolling backward.
+    if (item.start >= viewportTop || instance.scrollDirection === "backward") {
+      return false;
+    }
+
+    // The carve-out. `item` carries the pre-resize measurement, so
+    // `item.end > viewportTop` means the row straddles the viewport top and
+    // its bottom-appended growth lands below the reading line.
+    const liveStartIndex = getLiveStartIndex();
+    if (
+      liveStartIndex >= 0 &&
+      item.index >= liveStartIndex &&
+      delta > 0 &&
+      item.end > viewportTop &&
+      !isFollowing()
+    ) {
+      return false;
+    }
+
+    return true;
+  };
+}

crates/agent-gateway/web/test/live-scroll-adjust-policy.test.mjs

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { createWebModuleLoader } from "../../test/helpers/load-web-module.mjs";
+
+const loader = createWebModuleLoader({
+  rootDir: fileURLToPath(new URL("../", import.meta.url)),
+});
+
+const { createLiveRowScrollAdjustPolicy } = loader.loadModule(
+  "src/lib/transcript-virtual/liveScrollAdjustPolicy.ts",
+);
+
+const makeItem = ({ index = 5, start, size }) => ({
+  index,
+  key: index,
+  start,
+  size,
+  end: start + size,
+  lane: 0,
+});
+
+const makeInstance = ({ scrollOffset = 1000, scrollDirection = null, scrollAdjustments = 0 } = {}) => ({
+  scrollOffset,
+  scrollDirection,
+  scrollAdjustments,
+});
+
+const makePolicy = ({ liveStartIndex = -1, following = false } = {}) =>
+  createLiveRowScrollAdjustPolicy({
+    getLiveStartIndex: () => liveStartIndex,
+    isFollowing: () => following,
+  });
+
+test("row entirely above the viewport keeps the default compensation", () => {
+  const policy = makePolicy();
+  const item = makeItem({ index: 1, start: 100, size: 200 });
+  assert.equal(policy(item, 40, makeInstance()), true);
+  assert.equal(policy(item, -40, makeInstance()), true);
+});
+
+test("row starting at or below the viewport top never adjusts", () => {
+  const policy = makePolicy();
+  assert.equal(policy(makeItem({ start: 1000, size: 200 }), 40, makeInstance()), false);
+  assert.equal(policy(makeItem({ start: 1200, size: 200 }), 40, makeInstance()), false);
+});
+
+test("active backward scrolling suppresses compensation (upstream default)", () => {
+  const policy = makePolicy();
+  const item = makeItem({ index: 1, start: 100, size: 200 });
+  assert.equal(policy(item, 40, makeInstance({ scrollDirection: "backward" })), false);
+  assert.equal(policy(item, 40, makeInstance({ scrollDirection: "forward" })), true);
+});
+
+test("detached reader inside the growing live row is left alone (streaming creep)", () => {
+  const policy = makePolicy({ liveStartIndex: 5, following: false });
+  // Live row spans 400..5400, viewport top at 3000: the reader scrolled up
+  // into the streaming reply. Growth appends below the reading line.
+  const item = makeItem({ index: 5, start: 400, size: 5000 });
+  assert.equal(policy(item, 60, makeInstance({ scrollOffset: 3000 })), false);
+});
+
+test("the same live-row growth while following keeps compensating (pin assist)", () => {
+  const policy = makePolicy({ liveStartIndex: 5, following: true });
+  const item = makeItem({ index: 5, start: 400, size: 5000 });
+  assert.equal(policy(item, 60, makeInstance({ scrollOffset: 3000 })), true);
+});
+
+test("live-row shrink keeps compensating so content under the reader stays put", () => {
+  const policy = makePolicy({ liveStartIndex: 5, following: false });
+  const item = makeItem({ index: 5, start: 400, size: 5000 });
+  assert.equal(policy(item, -80, makeInstance({ scrollOffset: 3000 })), true);
+});
+
+test("settled row straddling the viewport keeps the default", () => {
+  const policy = makePolicy({ liveStartIndex: 5, following: false });
+  const item = makeItem({ index: 2, start: 400, size: 5000 });
+  assert.equal(policy(item, 60, makeInstance({ scrollOffset: 3000 })), true);
+});
+
+test("idle transcript (liveStartIndex -1) keeps the default everywhere", () => {
+  const policy = makePolicy({ liveStartIndex: -1, following: false });
+  const item = makeItem({ index: 5, start: 400, size: 5000 });
+  assert.equal(policy(item, 60, makeInstance({ scrollOffset: 3000 })), true);
+});
+
+test("live row entirely above the viewport still compensates", () => {
+  const policy = makePolicy({ liveStartIndex: 5, following: false });
+  // end (300) <= viewport top (1000): the growth lands above the reader.
+  const item = makeItem({ index: 5, start: 100, size: 200 });
+  assert.equal(policy(item, 40, makeInstance({ scrollOffset: 1000 })), true);
+});
+
+test("pending scroll adjustments fold into the viewport-top comparison", () => {
+  const policy = makePolicy();
+  const item = makeItem({ index: 1, start: 1040, size: 5 });
+  // Without pending adjustments the row start sits below the viewport top…
+  assert.equal(policy(item, 40, makeInstance({ scrollOffset: 1000 })), false);
+  // …with 50px of un-echoed writes it counts as above, like upstream.
+  assert.equal(policy(item, 40, makeInstance({ scrollOffset: 1000, scrollAdjustments: 50 })), true);
+});
+
+test("missing private scrollAdjustments field falls back to zero", () => {
+  const policy = makePolicy();
+  const item = makeItem({ index: 1, start: 100, size: 200 });
+  assert.equal(policy(item, 40, { scrollOffset: 1000, scrollDirection: null }), true);
+});

crates/agent-gateway/web/test/scroll-follow-core.test.mjs

@@ -50,10 +50,39 @@ test("constants coupling: reserve band and DPR tolerance", () => {
   assert.ok(BOTTOM_ATTACH_THRESHOLD_PX >= 4);
 });
 
-test("fractional-DPR clamp shortfall still attaches (c4d6471)", () => {
+test("fractional-DPR clamp shortfall attaches inside the latch (c4d6471)", () => {
   // Windows 125%/150% scaling clamps scrollTop 1-3px short of the physical
-  // bottom; landing there must attach with no latch and no pointer.
-  const { state } = run([wheelUp(), growth(500), scroll(3, 10_000)]);
+  // bottom; a latched downward arrival landing there must still attach (the
+  // attach threshold covers the shortfall).
+  const { state } = run([
+    wheelUp({ now: 0 }),
+    growth(500),
+    wheelDown({ now: 9_800 }), // latch until 10_300
+    scroll(3, 10_000),
+  ]);
+  assert.equal(state.following, true);
+});
+
+test("content shrink clamping a detached reader never re-attaches", () => {
+  // A reply settling out of the row list (or a collapsing block) shrinks
+  // scrollHeight; the browser clamps scrollTop and emits a scroll event at
+  // the bottom with no input and no latch. Follow must stay off, and the
+  // regrowth that lands right after must not pin — this was the "jump to
+  // the bottom when the reply finishes" bug.
+  const clamped = run([wheelUp({ now: 0 }), growth(2000), scroll(0, 10_000)]);
+  assert.equal(clamped.state.following, false);
+  // The clamp still counts as downward movement for a later release check.
+  assert.equal(clamped.state.dragTowardBottom, true);
+
+  const regrown = run([growth(1800)], { state: clamped.state });
+  assert.equal(regrown.state.following, false);
+  assert.equal(regrown.pin, false);
+});
+
+test("pin echo at the clamp keeps following without a latch", () => {
+  // While following, our own pin write echoes back as a scroll event at the
+  // clamp long after any input; it must keep follow engaged.
+  const { state } = run([growth(0), scroll(2, 10_000)]);
   assert.equal(state.following, true);
 });
 

crates/agent-gui/src/lib/chat-scroll/scrollFollowCore.ts

@@ -14,11 +14,16 @@
 //   after a programmatic pin (the abort lands with the next main-thread
 //   commit); those frames carry no input and no drag, so they can never
 //   detach.
-// - ATTACH is position-driven: landing at the physical clamp always attaches;
-//   a gesture-latched downward arrival inside the reattach zone attaches; a
-//   pointer released inside the zone after downward movement attaches. The
-//   gesture latch is the only timing heuristic left and it gates attach only —
-//   a false positive re-pins, it can never tear follow down.
+// - ATTACH is position-driven and intent-gated: landing at the physical clamp
+//   attaches while following (our own pin write echoing back) or inside an
+//   active gesture latch; a gesture-latched downward arrival inside the
+//   reattach zone attaches; a pointer released inside the zone after downward
+//   movement attaches. Content shrinking under a detached reader (a reply
+//   settling out of the row list, a collapsing block) also clamps scrollTop
+//   to the bottom with no input — that arrival carries no latch, so it can
+//   never re-engage follow and the next growth cannot yank the reader down.
+//   The gesture latch is the only timing heuristic left and it gates attach
+//   only — a false positive re-pins, it can never tear follow down.
 // - While following, a scroll event that leaves a gap open is corrected by
 //   re-pinning rather than classified.
 // - ResizeObserver deliveries (contentGrowth) never change follow state; they
@@ -194,11 +199,17 @@ export function reduceFollowEvent(
       const next = { ...state, lastGap: gap };
 
       if (isAtBottom(gap, config)) {
-        // At the physical clamp — attaching is always safe, whether the user
-        // landed here or our own pin write echoed back. Also counts as
-        // downward movement for the pointer-release re-check.
-        next.following = true;
+        // At the physical clamp. Counts as downward movement for the
+        // pointer-release re-check, but attaching needs evidence of intent:
+        // our own pin write echoing back (still following) or an arrival
+        // inside an active gesture latch. Content shrinking under a detached
+        // reader (a reply settling out of the row list, a collapsing block)
+        // also clamps scrollTop here with no input — attaching on that would
+        // let the next growth yank the reader to the bottom.
         next.dragTowardBottom = true;
+        if (state.following || now <= state.latchUntil) {
+          next.following = true;
+        }
         return { state: next, pin: false };
       }