Description

This PR fixes a race between imperative scrollToIndex and the MVCP autoscroll to bottom mechanism in v2. When autoscrollToBottomThreshold is set and the user is near the bottom of the list, calling scrollToIndex imperatively can be hijacked by the autoscroll to bottom path mid scroll animation. The list briefly lands at the target index, then snaps back to the bottom.

This typically reproduces when list items are not fully stable, i.e they need to be remeasured/corrected often. In other words, something that would actually falsely trigger autoscrolling.

I've found this to be reliably reproducible in any chat style list with an actual autoscrollToBottomThreshold set to its MVCP that also has unstable items (i.e images or GIFs, but also items which might require additional correction internally so basically anything that would trigger any type of change in contentSize):

1. Open the list (lands at bottom)
2. Scroll up far enough that the target index has rendered and been measured at least once
3. Scroll back down to the bottom and sit still for >=100ms
4. Trigger listRef.current?.scrollToIndex({ index: targetIndex, animated: true, viewPosition: 0.5 }) - typically from an effect or setTimeout(0) callback that's downstream of an unrelated state update (e.g., tapping a quoted message that first dispatches a "targeted message" state change)
5. List animates to targetIndex, then snaps back to the bottom

The race fires reliably only on the first attempt after step 3. Subsequent calls behave correctly: the race fired scrollToEnd refreshes the tracked anchor (via computeFirstVisibleIndexForOffsetCorrection), so subsequent applyOffsetCorrection diff calculations evaluate to ~0 and don't emit the stray scrollBy. A long enough wait at the bottom can make the snapshot stale again however, via background remeasurement and reproduce on a later attempt.

After a ton of debugging, I've found the root cause of this to actually be the two MVCP related subsystems interacting without coordinating:

1. Autoscroll-to-bottom lives in useBoundDetection.ts. It maintains a sticky ref pendingAutoscrollToBottom, set true by checkBounds whenever the user is within autoscrollToBottomThreshold viewports of the bottom. runAutoScrollToBottomCheck fires scrollToEnd via requestAnimationFrame, driven by two effects:

• The data change effect, keyed on [data, runAutoScrollToBottomCheck, windowHeight, windowWidth].
• The content geometry effect, keyed on [contentHeight, contentWidth, recyclerViewManager.firstItemOffset, …], gated by a 100ms lastCheckBoundsTime guard that I'm guessing is there to avoid firing during finger scroll.

2. Anchor MVCP lives in applyOffsetCorrection, runs on every layout commit and applies a compensating scrollBy(diff) when its tracked anchor item's cached layout snapshot diverges from the live layout. Gated by pauseOffsetCorrection.current. The anchor snapshot is refreshed at the end of each applyOffsetCorrection run via computeFirstVisibleIndexForOffsetCorrection and at scroll momentumend via the same function.

So, the timeline of events looks something like this from my analysis:

• User is at the bottom; pendingAutoscrollToBottom.current === true. The user has been sitting still long enough that background remeasurement of items (async images, font metric resolution, estimates resolving into real measurements as items leave/enter the render window) has drifted some items' cached layouts relative to the snapshot captured by computeFirstVisibleIndexForOffsetCorrection at the last momentum end.
• An unrelated rerender commits typically from a state update in the integrating app (e.g., highlighting the targeted message). pauseOffsetCorrection.current is still false because scrollToIndex hasn't run yet - it lives downstream in a setTimeout(0) / effect / event-handler tick.
• During that commit, applyOffsetCorrection evaluates with the stale anchor snapshot, computes a nonzero diff and fires scrollAnchorRef.current?.scrollBy(diff)
• The stray scroll mutates contentHeight / firstItemOffset over the next render, triggering the content change useEffect in useBoundDetection. pendingAutoscrollToBottom.current is still true (the >100ms lastCheckBoundsTime guard passes), then runAutoScrollToBottomCheck fires, then scrollToEnd queued via requestAnimationFrame
• A tick later, scrollToIndex finally runs and sets setOffsetProjectionEnabled(false) + pauseOffsetCorrection.current = true. Two scroll animations are now in flight; scrollToEnd typically wins.

Fix

A single early return at the top of runAutoScrollToBottomCheck: bail when a programmatic scrollToIndex is in flight, signalled by FlashList's own recyclerViewManager.isOffsetProjectionEnabled getter, backed by engagedIndicesTracker.enableOffsetProjection (default true).

const runAutoScrollToBottomCheck = useCallback(() => {
+ 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,
      });
    });
  }
}, [requestAnimationFrame, scrollViewRef, recyclerViewManager]);

isOffsetProjectionEnabled is already toggled false at the start of scrollToIndex and back to true ~200–300ms after the scroll settles (here). That window covers the entire scrollToIndex operation and its settling tail, during which applyOffsetCorrection can continue to emit corrective scrolls. If it fits the usecase better I can possibly introduce a separate ref that is going to have purely this as its responsibility.

The autoscroll to bottom contract should be "if the user is at the bottom and new content arrives, stay at the bottom." When an imperative scroll has explicitly reassigned the scroll position, "stay at the bottom" no longer applies for the duration of that operation. Suppressing autoscroll while imperative scrolling owns the position should be the correct semantic in my opinion.

I've also included a new fixture that reproduces this consistently (just load all of the items up until the middle and try scrolling to bottom and then to the item using the buttons. Needed to do this because of how stable the example is and it wouldn't reproduce on items that don't particularly drift at any point.

Reviewers’ hat-rack 🎩

• The guard predicate (!recyclerViewManager.isOffsetProjectionEnabled) is the right signal vs. alternatives like pauseOffsetCorrection.current or a new dedicated flag
• No other call site of runAutoScrollToBottomCheck or path into autoscroll is unintentionally suppressed by this guard. isOffsetProjectionEnabled is only flipped inside scrollToIndex, so the window is precisely the imperative scroll lifetime + settle
• Confirm the "stay at bottom on new content arriving during a programmatic scroll" behavior change is acceptable - during the 200-300ms settling tail of a scrollToIndex, newly arrived data won't trigger autoscroll. Autoscroll resumes when the flag flips back
• Confirm the issue is reproducible through the fixture screen

Screenshots or videos (if needed)

Before:

(I forgot to add feedback on clicking the buttons but essentially I'm just pressing on the scrollToIndex button and it succeeds only once)

After:

(same drill, except it succeeds all times)