fix(scroll): keep autoscroll to bottom when item sizes settle

useBoundDetection skips the autoscroll check when the content size changes
within 100ms of the last bounds check, so an active scroll is not fought.
The check is dropped rather than deferred, and the taller content then
pushes the bottom out of reach, so the next checkBounds clears the pending
autoscroll and nothing ever brings it back.

Items measuring to their real height a frame after they mount is exactly
that case, which is why a list with dynamic item heights stops sticking to
the bottom: an image finishing its load or a message wrapping onto another
line is enough to lose it.

Defer the check to the moment the scroll goes quiet instead of dropping it,
and run the autoscroll that was owed. The deferred run is cancelled if the
scroll offset moved in the meantime, which is what separates the two cases:
content growing below the viewport leaves the offset untouched, while a
user who takes over changes it and keeps ownership of the position.

The deferred run goes through runAutoScrollToBottomCheck rather than
resurrecting the pending flag, so scrollToEnd stays suppressed while offset
projection is disabled and no stale flag is left behind for a later data
change to fire.

Fixes #1903

Author: dennytosp

.claude/skills/review-and-test/SKILL.md

@@ -338,13 +338,21 @@ Run through relevant entries after any fix or review. This is the single source
 - [ ] `firstItemOffset` after fix — confirm it equals `ListHeaderComponent` height/width
 - [ ] `measureParentSize(view)` returns `x=0, y=0` on RN 0.84 Fabric — the #2017 bug may only manifest on other RN versions
 
+### Autoscroll to bottom (`maintainVisibleContentPosition.autoscrollToBottomThreshold`)
+- [ ] Item heights settling after the row mounts (image loads, text wraps) still keeps the list pinned to the bottom
+- [ ] New content arriving mid-scroll still lands at the bottom once the scroll stops
+- [ ] Scrolling up while content is still growing is NOT yanked back down
+- [ ] `scrollToIndex` in flight is still not hijacked by the autoscroll (`isOffsetProjectionEnabled` guard)
+
 ### Performance
 - [ ] Benchmark screen shows no FPS regression (use `ManualBenchmarkExample`)
 
 ---
 
 ## Common Issues
 
+- **A `not.toHaveBeenCalled()` test can pass without ever reaching the code it names** — negative assertions are vacuous by default. Mutation-test each guard separately (delete one, confirm exactly the test that names it goes red), or drop a temporary `console.log` in the branch to prove the test enters it. A test that stays green when its guard is deleted is testing nothing.
+- **A time-guarded bug hides under `jest.runAllTimers()`** — `runAllTimers` advances the fake clock past every `Date.now()` guard in the code (e.g. `useBoundDetection`'s 100ms quiet window), so a bug that only happens inside that window silently passes. Drive those cases with `jest.advanceTimersByTime(16)` and only drain with `runAllTimers` at the end.
 - **Tests pass but device shows bug** — did you `yarn build` and relaunch? The dist/ folder may be stale
 - **Switched branches but behavior didn't change** — `dist/` is NOT rebuilt on branch switch. You MUST run `yarn build` after every `git checkout`. Verify with `grep` in `dist/` that the expected code is present before testing.
 - **RTL looks wrong but LTR is fine** — did you set `forceRTL(true)` in `index.js` and do a full kill+relaunch?

src/__tests__/RecyclerView.test.tsx

@@ -514,4 +514,137 @@ describe("RecyclerView", () => {
       expect(scrollToEndSpy).toHaveBeenCalled();
     });
   });
+  describe("autoscroll to bottom when item sizes change", () => {
+    const { measureItemLayout } = jest.requireMock(
+      "../recyclerview/utils/measureLayout"
+    ) as { measureItemLayout: jest.Mock };
+
+    // jest.clearAllMocks() keeps implementations, so a grown item size would
+    // otherwise leak in from an earlier test and leave nothing left to grow.
+    beforeEach(() => {
+      measureItemLayout.mockImplementation(() => ({
+        x: 0,
+        y: 0,
+        width: 399,
+        height: 100,
+      }));
+    });
+
+    const itemCount = 30;
+    const itemHeight = 100;
+    const windowHeight = 899;
+    const contentHeight = itemCount * itemHeight;
+    const bottomOffset = contentHeight - windowHeight;
+
+    const scrollTo = (root: ReturnType<typeof render>, y: number) => {
+      const scrollable = root.findWhere((node: any) => node.props.onScroll);
+      if (!scrollable) throw new Error("Could not find scrollable component");
+
+      const onScroll: any = scrollable.prop("onScroll" as never);
+      root.act(() => {
+        onScroll({
+          nativeEvent: {
+            contentOffset: { x: 0, y },
+            contentSize: { width: 399, height: contentHeight },
+            layoutMeasurement: { width: 399, height: windowHeight },
+          },
+        });
+      });
+    };
+
+    // Renders a chat style list, parks it at the given offset and returns a spy
+    // on the scroll the autoscroll would issue.
+    const renderStickyBottomList = (offset: number = bottomOffset) => {
+      const data = Array.from({ length: itemCount }, (_, i) => i);
+      const ref = createRef<FlashListRef<number>>();
+      const result = render(
+        <FlashList
+          ref={ref}
+          data={data}
+          extraData={1}
+          keyExtractor={(item) => String(item)}
+          maintainVisibleContentPosition={{
+            autoscrollToBottomThreshold: 0.2,
+            animateAutoScrollToBottom: false,
+          }}
+          renderItem={({ item }) => <Text>{item}</Text>}
+        />
+      );
+      jest.runAllTimers();
+      scrollTo(result, offset);
+      jest.runAllTimers();
+
+      const scrollToEndSpy = jest.fn();
+      const nativeScrollRef = ref.current?.getNativeScrollRef() as any;
+      expect(nativeScrollRef).toBeTruthy();
+      nativeScrollRef.scrollToEnd = scrollToEndSpy;
+
+      return { result, scrollToEndSpy };
+    };
+
+    // Items settle to their real height with no data change - what an image
+    // finishing its load or a message wrapping onto another line does a frame
+    // after the row mounts.
+    const growItems = (result: ReturnType<typeof render>) => {
+      measureItemLayout.mockImplementation(() => ({
+        x: 0,
+        y: 0,
+        width: 399,
+        height: 300,
+      }));
+      result.setProps({ extraData: 2 });
+    };
+
+    it("still autoscrolls when items grow right after a scroll", () => {
+      const { result, scrollToEndSpy } = renderStickyBottomList();
+
+      // The growth lands inside the window where an active scroll suppresses
+      // the autoscroll check.
+      scrollTo(result, bottomOffset);
+      jest.advanceTimersByTime(16);
+      growItems(result);
+      jest.advanceTimersByTime(16);
+      expect(scrollToEndSpy).not.toHaveBeenCalled();
+
+      // Once the scroll goes quiet the deferred autoscroll runs.
+      jest.runAllTimers();
+      expect(scrollToEndSpy).toHaveBeenCalled();
+    });
+
+    it("autoscrolls right away when items grow well after the last scroll", () => {
+      const { result, scrollToEndSpy } = renderStickyBottomList();
+
+      scrollTo(result, bottomOffset);
+      jest.advanceTimersByTime(200);
+      growItems(result);
+      jest.runAllTimers();
+
+      expect(scrollToEndSpy).toHaveBeenCalled();
+    });
+
+    it("does not autoscroll if the user scrolls away while the growth settles", () => {
+      const { result, scrollToEndSpy } = renderStickyBottomList();
+
+      scrollTo(result, bottomOffset);
+      jest.advanceTimersByTime(16);
+      growItems(result);
+
+      // The user drags up before the deferred autoscroll gets its turn.
+      scrollTo(result, 200);
+      jest.runAllTimers();
+
+      expect(scrollToEndSpy).not.toHaveBeenCalled();
+    });
+
+    it("does not autoscroll when the list was not near the bottom", () => {
+      const { result, scrollToEndSpy } = renderStickyBottomList(0);
+
+      scrollTo(result, 0);
+      jest.advanceTimersByTime(16);
+      growItems(result);
+      jest.runAllTimers();
+
+      expect(scrollToEndSpy).not.toHaveBeenCalled();
+    });
+  });
 });

src/recyclerview/hooks/useBoundDetection.ts

@@ -3,7 +3,25 @@ import { useCallback, useEffect, useMemo, useRef } from "react";
 import { RecyclerViewManager } from "../RecyclerViewManager";
 import { CompatScroller } from "../components/CompatScroller";
 
-import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
+import {
+  useUnmountAwareAnimationFrame,
+  useUnmountAwareTimeout,
+} from "./useUnmountAwareCallbacks";
+
+/**
+ * How long the scroll has to stay quiet before a content size change is allowed
+ * to trigger the autoscroll to bottom. Autoscrolling in the middle of an active
+ * scroll fights the user, so the check waits for this gap instead.
+ */
+const AUTOSCROLL_QUIET_WINDOW = 100;
+
+/**
+ * Scroll offsets can come back off by a sub pixel without anything having
+ * actually moved, so a deferred autoscroll treats a difference this small as
+ * "nobody scrolled". A real drag covers far more than this in
+ * AUTOSCROLL_QUIET_WINDOW.
+ */
+const AUTOSCROLL_OFFSET_TOLERANCE = 1;
 
 /**
  * Hook to detect when the scroll position reaches near the start or end of the list
@@ -28,9 +46,14 @@ export function useBoundDetection<T>(
   const pendingAutoscrollToBottom = useRef(false);
 
   const lastCheckBoundsTime = useRef(Date.now());
+  // Holds an autoscroll that was owed when the content size changed mid scroll,
+  // along with the scroll offset at that moment so a real user scroll during the
+  // wait can cancel it.
+  const deferredAutoscroll = useRef<{ offset: number } | undefined>(undefined);
 
   const { data } = recyclerViewManager.props;
   const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
+  const { setTimeout } = useUnmountAwareTimeout();
 
   const windowHeight = recyclerViewManager.hasLayout()
     ? recyclerViewManager.getWindowSize().height
@@ -140,27 +163,36 @@ export function useBoundDetection<T>(
     }
   }, [recyclerViewManager]);
 
-  const runAutoScrollToBottomCheck = useCallback(() => {
-    // Suppress MVCP autoscroll while a programmatic scrollToIndex is in
-    // flight. FlashList disables offset projection at the start of
-    // scrollToIndex and reenables it ~200-300ms after settling. Without
-    // this guard, the sticky pendingAutoscrollToBottom ref races against
-    // scrollToIndex and fires scrollToEnd mid flight.
-    if (!recyclerViewManager.isOffsetProjectionEnabled) {
-      return;
-    }
-    if (pendingAutoscrollToBottom.current) {
-      pendingAutoscrollToBottom.current = false;
-      requestAnimationFrame(() => {
-        const shouldAnimate =
-          recyclerViewManager.props.maintainVisibleContentPosition
-            ?.animateAutoScrollToBottom ?? true;
-        scrollViewRef.current?.scrollToEnd({
-          animated: shouldAnimate && !recyclerViewManager.ignoreScrollEvents,
+  /**
+   * @param force - run the autoscroll even though checkBounds has since cleared
+   * pendingAutoscrollToBottom. Used by the deferred path, where the content
+   * growing below the viewport is what put the bottom out of reach in the first
+   * place.
+   */
+  const runAutoScrollToBottomCheck = useCallback(
+    (force = false) => {
+      // Suppress MVCP autoscroll while a programmatic scrollToIndex is in
+      // flight. FlashList disables offset projection at the start of
+      // scrollToIndex and reenables it ~200-300ms after settling. Without
+      // this guard, the sticky pendingAutoscrollToBottom ref races against
+      // scrollToIndex and fires scrollToEnd mid flight.
+      if (!recyclerViewManager.isOffsetProjectionEnabled) {
+        return;
+      }
+      if (force || pendingAutoscrollToBottom.current) {
+        pendingAutoscrollToBottom.current = false;
+        requestAnimationFrame(() => {
+          const shouldAnimate =
+            recyclerViewManager.props.maintainVisibleContentPosition
+              ?.animateAutoScrollToBottom ?? true;
+          scrollViewRef.current?.scrollToEnd({
+            animated: shouldAnimate && !recyclerViewManager.ignoreScrollEvents,
+          });
         });
-      });
-    }
-  }, [requestAnimationFrame, scrollViewRef, recyclerViewManager]);
+      }
+    },
+    [requestAnimationFrame, scrollViewRef, recyclerViewManager]
+  );
 
   // Reset end reached state when data changes
   useMemo(() => {
@@ -174,16 +206,60 @@ export function useBoundDetection<T>(
     runAutoScrollToBottomCheck();
   }, [data, runAutoScrollToBottomCheck, windowHeight, windowWidth]);
 
+  /**
+   * Waits out AUTOSCROLL_QUIET_WINDOW and then runs the autoscroll that the
+   * content size change was owed, as long as nothing actually scrolled in the
+   * meantime.
+   */
+  const scheduleAutoScrollRetry = useCallback(() => {
+    if (!pendingAutoscrollToBottom.current || deferredAutoscroll.current) {
+      return;
+    }
+    deferredAutoscroll.current = {
+      offset: recyclerViewManager.getAbsoluteLastScrollOffset(),
+    };
+
+    setTimeout(() => {
+      const deferred = deferredAutoscroll.current;
+      deferredAutoscroll.current = undefined;
+      if (!deferred) {
+        return;
+      }
+      // An offset that moved means the user took over, and checkBounds has
+      // already recorded whether they are still near the bottom - leave the
+      // decision to it rather than yanking them back down. An offset that did
+      // not move means nothing is scrolling, which is both the case autoscroll
+      // exists for and proof that there is no scroll left to fight.
+      if (
+        Math.abs(
+          recyclerViewManager.getAbsoluteLastScrollOffset() - deferred.offset
+        ) > AUTOSCROLL_OFFSET_TOLERANCE
+      ) {
+        return;
+      }
+      runAutoScrollToBottomCheck(true);
+    }, AUTOSCROLL_QUIET_WINDOW);
+  }, [recyclerViewManager, runAutoScrollToBottomCheck, setTimeout]);
+
   // Since content changes frequently, we try and avoid doing the auto scroll during active scrolls
   useEffect(() => {
-    if (Date.now() - lastCheckBoundsTime.current >= 100) {
+    if (Date.now() - lastCheckBoundsTime.current >= AUTOSCROLL_QUIET_WINDOW) {
       runAutoScrollToBottomCheck();
+      return;
     }
+    // The content changed while a scroll was still settling. Giving up here
+    // loses the autoscroll for good: the taller content pushes the bottom out
+    // of reach, so the next checkBounds clears the pending autoscroll and
+    // nothing brings it back. Items measuring to their real height right after
+    // new content arrives is exactly that case, which is why a list with
+    // dynamic item heights stops sticking to the bottom.
+    scheduleAutoScrollRetry();
   }, [
     contentHeight,
     contentWidth,
     recyclerViewManager.firstItemOffset,
     runAutoScrollToBottomCheck,
+    scheduleAutoScrollRetry,
   ]);
 
   return {