fix(chat): keep a sent message pinned while the list settles

Sending the second or a later message sometimes left it where it was
appended instead of pinned below the header, forcing a manual scroll.

The pin was a single `scrollToEnd` fired from `onContentSizeChange`, but the
list's maximum offset keeps moving for a few hundred milliseconds afterwards:
`blankSpace` is applied as the scroll view's bottom contentInset and Reanimated
commits it on the UI thread a frame later, the inset is recomputed once the new
rows report their heights, and keyboard-controller drives its own per-frame
scrollTo while the keyboard dismissed by the send animates out. Whichever
lands last wins, so a lone scroll aims at a stale end and falls short.

`useScrollSettler` re-asserts the position across that window (animated while
the send transition is still running, instant afterwards), `recomputeBlankSpace`
re-snaps whenever it moves the inset, a drag cancels the pin so the user is
never fought, and the keyboard-dismiss snap no longer skips a send in flight
just because the list was scrolled up when the message was written.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: kfaracik

__tests__/useScrollSettler.test.ts

@@ -0,0 +1,139 @@
+import { act, renderHook } from '@testing-library/react-native';
+import {
+  SCROLL_SETTLE_STEPS,
+  useScrollSettler,
+} from '../components/chat-screen/useScrollSettler';
+
+const LAST_STEP = SCROLL_SETTLE_STEPS[SCROLL_SETTLE_STEPS.length - 1];
+
+const setup = () => {
+  const snap = jest.fn();
+  const { result, unmount } = renderHook(() => useScrollSettler(snap));
+  return { snap, result, unmount };
+};
+
+beforeEach(() => {
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+describe('useScrollSettler', () => {
+  it('snaps immediately, then re-snaps at every step', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.start());
+    expect(snap).toHaveBeenCalledTimes(1);
+    expect(snap).toHaveBeenLastCalledWith(true);
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay));
+
+    expect(snap).toHaveBeenCalledTimes(1 + SCROLL_SETTLE_STEPS.length);
+    expect(snap.mock.calls.slice(1)).toEqual(
+      SCROLL_SETTLE_STEPS.map((step) => [step.animated])
+    );
+  });
+
+  it('keeps the send transition animated, then corrects instantly', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.start());
+    act(() => jest.advanceTimersByTime(220));
+    expect(snap.mock.calls.every(([animated]) => animated === true)).toBe(true);
+
+    snap.mockClear();
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay - 220));
+    expect(snap).toHaveBeenCalled();
+    expect(snap.mock.calls.every(([animated]) => animated === false)).toBe(
+      true
+    );
+  });
+
+  it('keeps re-snapping past the keyboard-dismiss animation', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.start());
+    act(() => jest.advanceTimersByTime(300));
+    const beforeTail = snap.mock.calls.length;
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay - 300));
+
+    expect(snap.mock.calls.length).toBeGreaterThan(beforeTail);
+  });
+
+  it('stops re-snapping once cancelled', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.start());
+    snap.mockClear();
+    act(() => result.current.cancel());
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay * 2));
+
+    expect(snap).not.toHaveBeenCalled();
+    expect(result.current.isSettling()).toBe(false);
+  });
+
+  it('reports settling only inside the window', () => {
+    const { result } = setup();
+
+    expect(result.current.isSettling()).toBe(false);
+
+    act(() => result.current.start());
+    expect(result.current.isSettling()).toBe(true);
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay));
+    expect(result.current.isSettling()).toBe(false);
+  });
+
+  it('resettles only while a pin is in flight', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.resettle());
+    expect(snap).not.toHaveBeenCalled();
+
+    act(() => result.current.start());
+    snap.mockClear();
+    act(() => result.current.resettle());
+    expect(snap).toHaveBeenLastCalledWith(true);
+
+    act(() => jest.advanceTimersByTime(340));
+    snap.mockClear();
+    act(() => result.current.resettle());
+    expect(snap).toHaveBeenLastCalledWith(false);
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay));
+    snap.mockClear();
+    act(() => result.current.resettle());
+    expect(snap).not.toHaveBeenCalled();
+  });
+
+  it('restarts cleanly when a second message is sent mid-window', () => {
+    const { snap, result } = setup();
+
+    act(() => result.current.start());
+    act(() => jest.advanceTimersByTime(SCROLL_SETTLE_STEPS[0].delay));
+    snap.mockClear();
+
+    act(() => result.current.start());
+    expect(snap).toHaveBeenLastCalledWith(true);
+
+    snap.mockClear();
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay));
+    expect(snap).toHaveBeenCalledTimes(SCROLL_SETTLE_STEPS.length);
+  });
+
+  it('drops pending timers on unmount', () => {
+    const { snap, result, unmount } = setup();
+
+    act(() => result.current.start());
+    snap.mockClear();
+    unmount();
+
+    act(() => jest.advanceTimersByTime(LAST_STEP.delay * 2));
+
+    expect(snap).not.toHaveBeenCalled();
+  });
+});

components/chat-screen/Messages.tsx

@@ -49,6 +49,7 @@ import BranchMarker from './BranchMarker';
 import Toast from 'react-native-toast-message';
 import { SUPPORTS_USER_ACTION_MENU } from '../../constants/chat-screen';
 import { useKeyboardLift } from './useKeyboardLift';
+import { useScrollSettler } from './useScrollSettler';
 import { visibleMessageText } from '../../utils/messageText';
 
 /**
@@ -68,6 +69,8 @@ const GENERATION_ERROR_MEASUREMENT_KEY = 'generation-error';
 
 const MESSAGE_PIN_OFFSET = 8;
 
+const PIN_FALLBACK_MS = 300;
+
 export interface MessagesHandle {
   onMessageSent: () => void;
   scrollToEnd: () => void;
@@ -227,6 +230,17 @@ const Messages = ({
     scrollRef.current?.scrollToEnd({ animated: false });
   }, []);
 
+  const {
+    start: startPin,
+    cancel: cancelPin,
+    resettle: resettlePin,
+    isSettling: isPinSettling,
+  } = useScrollSettler(
+    useCallback((animated: boolean) => {
+      scrollRef.current?.scrollToEnd({ animated });
+    }, [])
+  );
+
   const scheduleInitialScrollToEnd = useCallback(() => {
     clearInitialScrollTimers();
     snapToEnd();
@@ -306,9 +320,10 @@ const Messages = ({
       opacity.set(0);
       pinActive.current = false;
       blankSpace.set(0);
+      cancelPin();
     }
     prevChatLengthRef.current = chatHistory.length;
-  }, [chatHistory.length, opacity, blankSpace]);
+  }, [chatHistory.length, opacity, blankSpace, cancelPin]);
 
   useLayoutEffect(() => clearInitialScrollTimers, [clearInitialScrollTimers]);
 
@@ -372,8 +387,9 @@ const Messages = ({
       };
 
       if (
-        wasAtBottomDuringKeyboard.current &&
-        !userScrolledDuringKeyboard.current
+        (wasAtBottomDuringKeyboard.current &&
+          !userScrolledDuringKeyboard.current) ||
+        isPinSettling()
       ) {
         clearPendingSnap();
         firstFrame = requestAnimationFrame(() => {
@@ -397,7 +413,7 @@ const Messages = ({
       showSub.remove();
       hideSub.remove();
     };
-  }, [closeUserActionMenu]);
+  }, [closeUserActionMenu, isPinSettling]);
 
   // Armed from onMessageSent until the chat is cleared; gates recomputeBlankSpace.
   // Stays armed past end-of-stream so the final layout (once the stats row and
@@ -420,7 +436,29 @@ const Messages = ({
       listBottomPadding +
       MESSAGE_PIN_OFFSET;
     blankSpace.set(Math.max(0, raw));
-  }, [blankSpace, listBottomPadding, listTopPadding]);
+    resettlePin();
+  }, [blankSpace, listBottomPadding, listTopPadding, resettlePin]);
+
+  const pinFallbackTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const clearPinFallback = useCallback(() => {
+    if (pinFallbackTimer.current) {
+      clearTimeout(pinFallbackTimer.current);
+      pinFallbackTimer.current = null;
+    }
+  }, []);
+
+  const runPendingPin = useCallback(() => {
+    if (!pendingPinRef.current) return;
+    pendingPinRef.current = false;
+    clearPinFallback();
+    closeUserActionMenu();
+    if (Platform.OS !== 'ios' && containerHeight.current > 0) {
+      blankSpace.set(containerHeight.current - topInset + MESSAGE_PIN_OFFSET);
+    }
+    startPin();
+  }, [blankSpace, clearPinFallback, closeUserActionMenu, startPin, topInset]);
+
+  useLayoutEffect(() => clearPinFallback, [clearPinFallback]);
 
   useImperativeHandle(
     ref,
@@ -453,9 +491,18 @@ const Messages = ({
           }
         }
         pendingPinRef.current = true;
+        clearPinFallback();
+        pinFallbackTimer.current = setTimeout(runPendingPin, PIN_FALLBACK_MS);
       },
     }),
-    [blankSpace, closeUserActionMenu, opacity, topInset]
+    [
+      blankSpace,
+      clearPinFallback,
+      closeUserActionMenu,
+      opacity,
+      runPendingPin,
+      topInset,
+    ]
   );
 
   const handleContainerLayout = useCallback(
@@ -596,7 +643,8 @@ const Messages = ({
     if (keyboardOpenRef.current) {
       userScrolledDuringKeyboard.current = true;
     }
-  }, []);
+    cancelPin();
+  }, [cancelPin]);
 
   const handleForkMessage = useCallback(
     (message: Message) => {
@@ -620,28 +668,7 @@ const Messages = ({
         return;
       }
 
-      // After send: now that the new chat row has rendered, seed
-      // blankSpace and scroll to end. Doing this here (instead of
-      // synchronously in onMessageSent) avoids a 1-frame flick where
-      // the old content gets lifted by the new inset before the new
-      // DOM commits.
-      // Android: defer the pin here (not in onMessageSent) so the new
-      // row has committed before we expand blankSpace. Animate both
-      // blankSpace and scrollToEnd for a smooth transition.
-      if (pendingPinRef.current) {
-        pendingPinRef.current = false;
-        closeUserActionMenu();
-        if (Platform.OS !== 'ios' && containerHeight.current > 0) {
-          blankSpace.set(
-            containerHeight.current - topInset + MESSAGE_PIN_OFFSET
-          );
-        }
-        requestAnimationFrame(() => {
-          requestAnimationFrame(() => {
-            scrollRef.current?.scrollToEnd({ animated: true });
-          });
-        });
-      }
+      runPendingPin();
 
       // During streaming, check if content has grown past the viewport
       // so the scroll-to-bottom button can appear without the user
@@ -662,12 +689,10 @@ const Messages = ({
       }
     },
     [
-      blankSpace,
-      closeUserActionMenu,
       listBottomPadding,
       listTopPadding,
+      runPendingPin,
       scheduleInitialScrollToEnd,
-      topInset,
     ]
   );
 

components/chat-screen/useScrollSettler.ts

@@ -0,0 +1,65 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+export const SCROLL_SETTLE_STEPS = [
+  { delay: 60, animated: true },
+  { delay: 130, animated: true },
+  { delay: 220, animated: true },
+  { delay: 340, animated: false },
+  { delay: 480, animated: false },
+];
+
+const SETTLE_WINDOW_MS =
+  SCROLL_SETTLE_STEPS[SCROLL_SETTLE_STEPS.length - 1].delay;
+
+const ANIMATED_WINDOW_MS = 300;
+
+export interface ScrollSettler {
+  start: () => void;
+  cancel: () => void;
+  resettle: () => void;
+  isSettling: () => boolean;
+}
+
+export const useScrollSettler = (
+  snapToEnd: (animated: boolean) => void
+): ScrollSettler => {
+  const snapRef = useRef(snapToEnd);
+  useEffect(() => {
+    snapRef.current = snapToEnd;
+  }, [snapToEnd]);
+
+  const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
+  const startedAt = useRef(0);
+  const settlingUntil = useRef(0);
+
+  const cancel = useCallback(() => {
+    timers.current.forEach(clearTimeout);
+    timers.current = [];
+    settlingUntil.current = 0;
+  }, []);
+
+  const isSettling = useCallback(() => Date.now() < settlingUntil.current, []);
+
+  const start = useCallback(() => {
+    cancel();
+    startedAt.current = Date.now();
+    settlingUntil.current = startedAt.current + SETTLE_WINDOW_MS;
+    snapRef.current(true);
+    SCROLL_SETTLE_STEPS.forEach(({ delay, animated }) => {
+      timers.current.push(
+        setTimeout(() => {
+          snapRef.current(animated);
+        }, delay)
+      );
+    });
+  }, [cancel]);
+
+  const resettle = useCallback(() => {
+    if (!isSettling()) return;
+    snapRef.current(Date.now() - startedAt.current < ANIMATED_WINDOW_MS);
+  }, [isSettling]);
+
+  useEffect(() => cancel, [cancel]);
+
+  return { start, cancel, resettle, isSettling };
+};