Chat screen maintainVisibleContentPosition jump/glitch

Description

When using FlashList maintainVisibleContentPosition to create a chat app, when adding item to the top of the list might jump more or less.
It happens when

• the rendered items have a variable height.
• the timing isn't "right" for insertions.

Current behavior

https://github.com/user-attachments/assets/9c3c735e-bff9-4fe8-85f7-e49fca99e3e4

In this video we can see that when we scroll to top, the list scroll smoothly, but there is almost always a frame where a it jump to another position.

Expected behavior

It shouldn't jump

Reproduction

I forked flashlist and updated the Chat screen so that it reflect the issue
You can find the fork here

• Some message now display a "preview" block, which in a real chat app could be a preview message for a reply.
• The loading of new items is done in a setTimeout to reflect async network or cache call. (Note that if the setTimeout is big enough, the bug disapears, with my test setup for instance, 50ms of timeout cause the bug, but 500ms is ok)
• I set bounces={false} and onStartReachedThreshold={0.01} so that the behavior is more easily visible/reproductible.

(In a real app it might not be realistic to use onStartReachedThreshold={0.01} and a constant 50ms delay for a network call to load datas, but what matter is the duration between the moment the list stop scrolling and the moment it is updated with new items, in a real app we might use a bigger onStartReachedThreshold to load data sooner, but we might wait longer for the data to arrives, so by the time the data arrives the scroll might have stopped, I think that is what matter to reproduce the bug. )

Expo Snack or minimal reproduction link:

https://github.com/ACHP/flash-list/commit/2f67582f9e94e4a24769b7e2667e773fe1e2eb65

Platform

• iOS
• Android
• Web (if applicable)

Environment

info Fetching system and libraries information...
System:
  OS: macOS 15.5
  CPU: (12) arm64 Apple M3 Pro
  Memory: 137.88 MB / 18.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 20.19.5
    path: ~/.nvm/versions/node/v20.19.5/bin/node
  Yarn:
    version: 1.22.22
    path: /opt/homebrew/bin/yarn
  npm:
    version: 10.8.2
    path: ~/.nvm/versions/node/v20.19.5/bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /var/folders/12/_ffy101j76zccg89mklrbbdw0000gn/T/frum_46154_1764954422874/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 24.2
      - iOS 18.2
      - macOS 15.2
      - tvOS 18.2
      - visionOS 2.2
      - watchOS 11.2
  Android SDK:
    API Levels:
      - "23"
      - "25"
      - "28"
      - "29"
      - "30"
      - "31"
      - "33"
      - "34"
      - "35"
      - "36"
    Build Tools:
      - 28.0.3
      - 29.0.2
      - 30.0.2
      - 30.0.3
      - 31.0.0
      - 32.0.0
      - 33.0.0
      - 33.0.1
      - 34.0.0
      - 35.0.0
      - 35.0.1
      - 36.0.0
    System Images:
      - android-24 | ARM 64 v8a
      - android-28 | ARM 64 v8a
      - android-29 | Google APIs ARM 64 v8a
      - android-30 | Google APIs ARM 64 v8a
      - android-30 | Google Play ARM 64 v8a
      - android-31 | Google APIs ARM 64 v8a
      - android-31 | Google Play Intel x86_64 Atom
      - android-32 | Google APIs ARM 64 v8a
      - android-33-ext5 | Google Play ARM 64 v8a
      - android-34 | Google APIs ARM 64 v8a
      - android-35 | ARM 64 v8a
    Android NDK: Not Found
IDEs:
  Android Studio: 2025.1 AI-251.27812.49.2514.14085407
  Xcode:
    version: 16.2/16C5032a
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.10
    path: /Users/alexischappron/.asdf/shims/javac
  Ruby:
    version: 3.4.5
    path: /var/folders/12/_ffy101j76zccg89mklrbbdw0000gn/T/frum_46154_1764954422874/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 18.0.1
    wanted: 18.0.1
  react:
    installed: 19.0.0
    wanted: 19.0.0
  react-native:
    installed: 0.79.1
    wanted: 0.79.1
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

FlashList version:

Additional context

Checklist

• I've searched existing issues and couldn't find a duplicate
  (I've seen similar issues already, but none of them provide reproduction example, and we can't be sure it's the same bug)
• I've provided a minimal reproduction (Expo Snack preferred)
• I'm using the latest version of @shopify/flash-list
• I've included all required information above

Possible pragmatic alternative

While I think it's a technical problem that needs to be solved, it could make sense from a product point of view to say : when the list is at the very top and we're loading data, then we display a loader, and we stop/delay data insertion for x ms.
that way we wait for long enough that the bug doesn't appear, we're telling the user we need more time to load the data, and the loader does not blink.

Start with the updated Chat screen in the linked reproduction commit and reproduce the jump while loading variable-height items at the top with maintainVisibleContentPosition. Compare the timing around onStartReached and the 50ms delayed insertion on iOS and Android. Done means the list no longer visibly jumps in this reproduction.