Stop auto-follow from fighting touch scrolls

A touch drag registers scroll intent after 4px, but a scroll position
counts as at-end until 24px, so the first frames of every upward drag
landed in the gap: the scroll handler re-armed bottom sticking and
cleared the user-scroll lock, snapping the timeline back under the
finger. Wheel devices clear the tolerance in one notch and never saw it.

- Only re-arm from a scroll event once the user-scroll lock has expired
- Hold off the lock-expiry re-check while a finger is still on the glass,
  and re-check on touch end instead
- Skip the viewport-resize re-stick mid-gesture, since mobile browsers
  collapse the URL bar as the user scrolls
- Cover the drag-inside-tolerance case in the timeline browser tests

Author: badcuban

apps/web/src/components/chat/MessagesTimeline.browser.tsx

@@ -13,6 +13,23 @@ import { __resetClientSettingsPersistenceForTests } from "../../hooks/useSetting
 const scrollToEndSpy = vi.fn();
 const getStateSpy = vi.fn(() => ({ isAtEnd: true }));
 
+// Viewport 100 / content 200 at offset 0 — a full viewport away from the end.
+const AWAY_FROM_END_SCROLL_METRICS = {
+  layoutMeasurement: { height: 100 },
+  contentSize: { height: 200 },
+  contentOffset: { y: 0 },
+  contentInset: { bottom: 0 },
+};
+// 10px from the end: past the touch intent threshold, still inside the 24px
+// at-end tolerance — the window a mobile drag has to cross.
+const NEAR_END_SCROLL_METRICS = {
+  layoutMeasurement: { height: 100 },
+  contentSize: { height: 210 },
+  contentOffset: { y: 100 },
+  contentInset: { bottom: 0 },
+};
+let timelineScrollMetrics: typeof AWAY_FROM_END_SCROLL_METRICS = AWAY_FROM_END_SCROLL_METRICS;
+
 vi.mock("@legendapp/list/react", async () => {
   const React = await import("react");
 
@@ -32,6 +49,9 @@ vi.mock("@legendapp/list/react", async () => {
       };
     }) => void;
     onWheelCapture?: React.WheelEventHandler<HTMLDivElement>;
+    onTouchStartCapture?: React.TouchEventHandler<HTMLDivElement>;
+    onTouchMoveCapture?: React.TouchEventHandler<HTMLDivElement>;
+    onTouchEndCapture?: React.TouchEventHandler<HTMLDivElement>;
     ref?: React.Ref<LegendListRef>;
   }) {
     React.useImperativeHandle(
@@ -48,16 +68,12 @@ vi.mock("@legendapp/list/react", async () => {
         data-testid="legend-list"
         data-maintain-scroll-at-end={props.maintainScrollAtEnd ? "true" : "false"}
         onScroll={() => {
-          props.onScroll?.({
-            nativeEvent: {
-              layoutMeasurement: { height: 100 },
-              contentSize: { height: 200 },
-              contentOffset: { y: 0 },
-              contentInset: { bottom: 0 },
-            },
-          });
+          props.onScroll?.({ nativeEvent: timelineScrollMetrics });
         }}
         onWheelCapture={props.onWheelCapture}
+        onTouchStartCapture={props.onTouchStartCapture}
+        onTouchMoveCapture={props.onTouchMoveCapture}
+        onTouchEndCapture={props.onTouchEndCapture}
       >
         {props.ListHeaderComponent}
         {props.data.map((item) => (
@@ -114,6 +130,30 @@ function buildProps() {
   };
 }
 
+function dispatchTouch(
+  target: HTMLElement,
+  type: "touchstart" | "touchmove" | "touchend",
+  clientY: number,
+) {
+  const touch = new Touch({ identifier: 1, target, clientY, clientX: 0 });
+  target.dispatchEvent(
+    new TouchEvent(type, {
+      bubbles: true,
+      touches: type === "touchend" ? [] : [touch],
+      changedTouches: [touch],
+    }),
+  );
+}
+
+// Native events dispatched outside React's act() flush their state updates on a
+// later task, so settle them before asserting a render *didn't* happen. Stays
+// well under USER_SCROLL_STICK_LOCK_MS so the lock is still held on the far side.
+function flushPendingRenders() {
+  return new Promise<void>((resolve) => {
+    window.setTimeout(resolve, 100);
+  });
+}
+
 async function resetBrowserHoverState() {
   const resetTarget = document.createElement("button");
   resetTarget.type = "button";
@@ -189,6 +229,7 @@ describe("MessagesTimeline", () => {
   afterEach(() => {
     scrollToEndSpy.mockReset();
     getStateSpy.mockClear();
+    timelineScrollMetrics = AWAY_FROM_END_SCROLL_METRICS;
     useUiStateStore.setState({ threadChangedFilesExpandedById: {} });
     __resetClientSettingsPersistenceForTests();
     vi.restoreAllMocks();
@@ -708,6 +749,67 @@ describe("MessagesTimeline", () => {
     }
   });
 
+  it("keeps a touch drag disarmed while it is still inside the at-end tolerance", async () => {
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation(
+      (callback: FrameRequestCallback) => {
+        callback(0);
+        return 1;
+      },
+    );
+    vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => undefined);
+
+    const props = buildProps();
+    const screen = await renderTimeline(
+      <MessagesTimeline
+        {...props}
+        activeTurnInProgress
+        isWorking
+        timelineEntries={[buildUserTimelineEntry("Streaming reply in progress.")]}
+      />,
+    );
+
+    try {
+      const legendList = document.querySelector<HTMLElement>('[data-testid="legend-list"]');
+      expect(legendList).not.toBeNull();
+      expect(legendList?.getAttribute("data-maintain-scroll-at-end")).toBe("true");
+
+      dispatchTouch(legendList!, "touchstart", 400);
+      dispatchTouch(legendList!, "touchmove", 412);
+
+      await vi.waitFor(() => {
+        const list = document.querySelector<HTMLElement>('[data-testid="legend-list"]');
+        expect(list?.getAttribute("data-maintain-scroll-at-end")).toBe("false");
+      });
+
+      // The drag has moved further than the intent threshold but is still
+      // within the at-end tolerance, so the list keeps reporting itself at the
+      // end. Re-arming on those scroll events is what snapped the timeline back
+      // under the finger.
+      timelineScrollMetrics = NEAR_END_SCROLL_METRICS;
+      scrollToEndSpy.mockClear();
+      legendList?.dispatchEvent(new Event("scroll", { bubbles: true }));
+      dispatchTouch(legendList!, "touchmove", 424);
+      legendList?.dispatchEvent(new Event("scroll", { bubbles: true }));
+      await flushPendingRenders();
+
+      expect(
+        document
+          .querySelector<HTMLElement>('[data-testid="legend-list"]')
+          ?.getAttribute("data-maintain-scroll-at-end"),
+      ).toBe("false");
+      expect(scrollToEndSpy).not.toHaveBeenCalled();
+
+      // Lifting the finger at the bottom re-arms once the gesture settles.
+      dispatchTouch(legendList!, "touchend", 424);
+      await vi.waitFor(() => {
+        const list = document.querySelector<HTMLElement>('[data-testid="legend-list"]');
+        expect(list?.getAttribute("data-maintain-scroll-at-end")).toBe("true");
+      });
+    } finally {
+      await screen.unmount();
+    }
+  });
+
   it("exposes an edit-and-branch action on user messages", async () => {
     const onContinueInNewThread = vi.fn();
     const screen = await renderTimeline(

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -872,26 +872,34 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   }, [clearUserScrollLockTimer, listRef, onIsAtEndChange, setAutoStickToBottomState]);
 
   const enableAutoStickIfAtEnd = useCallback(() => {
-    if (!isTimelineListAtEnd(listRef.current)) {
+    // A finger still on the glass is mid-gesture even when it pauses, and a
+    // paused drag that has only just left the bottom is still inside the at-end
+    // tolerance. Re-arming here would yank the list back under the touch.
+    // `handleTouchEndCapture` re-checks once the gesture lifts.
+    if (touchStartYRef.current !== null || !isTimelineListAtEnd(listRef.current)) {
       return;
     }
     setAutoStickToBottomState(true);
     onIsAtEndChange(true);
   }, [listRef, onIsAtEndChange, setAutoStickToBottomState]);
 
+  const scheduleStickReArmCheck = useCallback(() => {
+    clearUserScrollLockTimer();
+    userScrollLockTimerRef.current = window.setTimeout(() => {
+      userScrollLockTimerRef.current = null;
+      enableAutoStickIfAtEnd();
+    }, USER_SCROLL_STICK_LOCK_MS);
+  }, [clearUserScrollLockTimer, enableAutoStickIfAtEnd]);
+
   const markUserScrollIntent = useCallback(
     (options?: { notifyAwayFromEnd?: boolean }) => {
-      clearUserScrollLockTimer();
       setAutoStickToBottomState(false);
       if (options?.notifyAwayFromEnd) {
         onIsAtEndChange(false);
       }
-      userScrollLockTimerRef.current = window.setTimeout(() => {
-        userScrollLockTimerRef.current = null;
-        enableAutoStickIfAtEnd();
-      }, USER_SCROLL_STICK_LOCK_MS);
+      scheduleStickReArmCheck();
     },
-    [clearUserScrollLockTimer, enableAutoStickIfAtEnd, onIsAtEndChange, setAutoStickToBottomState],
+    [onIsAtEndChange, scheduleStickReArmCheck, setAutoStickToBottomState],
   );
 
   const stickToBottomRequestPending =
@@ -917,14 +925,19 @@ export const MessagesTimeline = memo(function MessagesTimeline({
         onIsAtEndChange(true);
         return;
       }
-      if (nextIsAtEnd) {
-        clearUserScrollLockTimer();
+      // Only re-arm from a scroll event once the user-scroll lock has expired.
+      // A touch drag clears the intent threshold (a few px) long before it
+      // clears the at-end tolerance (24px), so re-arming here would stick the
+      // list back to the bottom under the moving finger, report at-end on the
+      // next frame, and stick again — the list flickers instead of scrolling.
+      // Pointer devices never hit this because one wheel notch clears the
+      // tolerance outright. The lock timer re-checks once scrolling settles.
+      if (nextIsAtEnd && userScrollLockTimerRef.current === null) {
         setAutoStickToBottomState(true);
       }
       onIsAtEndChange(nextIsAtEnd);
     },
     [
-      clearUserScrollLockTimer,
       listRef,
       onIsAtEndChange,
       refreshTranscriptNoteHighlightRects,
@@ -1042,7 +1055,13 @@ export const MessagesTimeline = memo(function MessagesTimeline({
 
   const handleTouchEndCapture = useCallback(() => {
     touchStartYRef.current = null;
-  }, []);
+    if (autoStickToBottomRef.current) {
+      return;
+    }
+    // The gesture may have ended at the bottom, or momentum may still be
+    // running. Re-check after it settles rather than mid-flick.
+    scheduleStickReArmCheck();
+  }, [scheduleStickReArmCheck]);
 
   const handleKeyDownCapture = useCallback(
     (event: ReactKeyboardEvent) => {
@@ -1093,7 +1112,10 @@ export const MessagesTimeline = memo(function MessagesTimeline({
 
     let cancelStickFrames: (() => void) | null = null;
     const restickIfArmed = () => {
-      if (!autoStickToBottomRef.current) {
+      // Mobile browsers collapse and expand the URL bar as the user scrolls,
+      // which resizes the visual viewport mid-gesture. Never re-stick under a
+      // finger that is on the glass — the touch handlers own the scroll then.
+      if (!autoStickToBottomRef.current || touchStartYRef.current !== null) {
         return;
       }
       cancelStickFrames?.();