fix(virtual-core): stop a touch fling for a command issued during it on Android too (#1347)

Chrome on Android carries a fling on from a programmatic write, so a
scrollToIndex / scrollToOffset / scrollToEnd issued mid-fling was written
and then overshot (Pixel 6, Android 16, Chrome 156: ~3,200px past the
target, 3 runs of 3). iOS 27 already stops the fling before such a command
(#1332); this does it everywhere a write does not end the fling, which is
everywhere but iOS 26 and earlier.

- IosGesture opens the post-touch tail on every platform. Corrections are
  still deferred through it on iOS only; `_canWriteScroll` and
  `_awaitingCommandReadBack` keep their isIOSWebKit() gates.
- `_startScroll` stops the fling when momentumOverridesWrites():
  !isIOSWebKit() || iosMomentumOverridesWrites().
- `_stopMomentum` puts the overflow back in the same task when hiding it
  changed the element's cross-axis client size: a classic scrollbar (a
  touchscreen laptop) would vanish and reflow the content for two frames.
  The command then waits for the tail, as without a style.

The web trace snapshots move for seeds with touch steps: a command inside
a drag's tail now goes through the stop, which in the simulator (no style)
falls back to the tail, as on ios27.

Author: Kebechet

.changeset/android-fling-stop.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+fix(virtual-core): stop a touch fling for a command issued during it on Android too

packages/virtual-core/src/index.ts

@@ -9,11 +9,7 @@ import {
   flingCaught,
   flingSpedUp,
 } from './scroll-classifier'
-import {
-  IosGesture,
-  iosMomentumOverridesWrites,
-  isIOSWebKit,
-} from './ios-gesture'
+import { IosGesture, isIOSWebKit, momentumOverridesWrites } from './ios-gesture'
 import type { ScrollPhase, ScrollSample } from './scroll-classifier'
 
 export { _resetIOSDetectionForTests } from './ios-gesture'
@@ -2244,13 +2240,13 @@ export class Virtualizer<
     return null
   }
 
-  // Stop a running iOS fling, then call `done`: the momentum does not
-  // survive the element losing its overflow for a frame. Hidden and
-  // restored within one task, iOS never sees the change and the fling
-  // carries on (27.0.1 iPhone); hidden for two frames, it stops at once.
-  // Nothing moves on screen. A second call while one is in progress waits
-  // for the same frames. The app's inline value comes back, unless the app
-  // set a new one meanwhile; `done` is then not called.
+  // Stop a running fling, then call `done`: the momentum does not survive
+  // the element losing its overflow for a frame. Hidden and restored within
+  // one task, iOS never sees the change and the fling carries on (27.0.1
+  // iPhone); hidden for two frames, it stops at once, there and in Chrome on
+  // Android. Nothing moves on screen. A second call while one is in progress
+  // waits for the same frames. The app's inline value comes back, unless the
+  // app set a new one meanwhile; `done` is then not called.
   private _momentumStop: { restore: () => boolean; done: () => void } | null =
     null
   private _stopMomentum = (done: () => void) => {
@@ -2270,7 +2266,17 @@ export class Virtualizer<
     const property = this.options.horizontal ? 'overflow-x' : 'overflow-y'
     const value = style.getPropertyValue(property)
     const priority = style.getPropertyPriority(property)
+    const crossSize = () =>
+      this.options.horizontal ? scroller.clientHeight : scroller.clientWidth
+    const crossSizeBefore = crossSize()
     style.setProperty(property, 'hidden', 'important')
+    // A classic scrollbar takes layout space, so hiding it would reflow the
+    // content for two frames (a touchscreen laptop). Put it back before
+    // anything paints and leave the command to the tail, as without a style.
+    if (crossSize() !== crossSizeBefore) {
+      style.setProperty(property, value, priority)
+      return
+    }
     const stop = {
       // False when the app replaced the hidden value: the fling may not
       // have stopped.
@@ -2490,11 +2496,13 @@ export class Virtualizer<
 
     const tail = this._iosGesture.tail()
     if (kind === 'absolute' && tail !== null) {
-      if (tail === 'fling' && iosMomentumOverridesWrites()) {
-        // iOS 27: a write now shows for one frame and the fling carries on
-        // along its own path, so the command would be lost (#1307, step 3).
-        // Stop the fling and write two frames later. Otherwise (no style to
-        // change, a finger down, a bounce) the tail stays open and
+      if (tail === 'fling' && momentumOverridesWrites()) {
+        // A write now would not end the fling: on iOS 27 it shows for one
+        // frame and the fling carries on along its own path (#1307, step 3);
+        // in Chrome on Android the fling carries on from the written
+        // position. The command would be lost or overshot. Stop the fling
+        // and write two frames later. Otherwise (no style to change, a
+        // classic scrollbar, a finger down, a bounce) the tail stays open and
         // the command is written when it closes, ~150ms after the last
         // fling frame. The user taking over before the write (a drag, a
         // second flick, a finger stopping the fling) cancels the command

packages/virtual-core/src/ios-gesture.ts

@@ -32,6 +32,17 @@ export const iosMomentumOverridesWrites = (): boolean => {
     CSS.supports('overflow-anchor: auto'))
 }
 
+// Whether a touch fling survives a scrollTop write, so a command issued
+// mid-fling has to stop the fling before it writes. Only iOS 26 and earlier
+// stop the momentum on the write itself. Chrome on Android carries the fling
+// on from the written position: on a Pixel 6 (Android 16, Chrome 156) a
+// `scrollToIndex` issued 150ms into a fling wrote its target, then went on
+// ~3,200px past it, 3 runs of 3. Other non-iOS engines are not measured; on
+// one whose write does stop the fling, stopping it first costs the two
+// frames of the stop.
+export const momentumOverridesWrites = (): boolean =>
+  !isIOSWebKit() || iosMomentumOverridesWrites()
+
 // Test hook: reset the iOS detection caches. Not exported.
 export const _resetIOSDetectionForTests = () => {
   _isIOSResult = undefined
@@ -52,9 +63,11 @@ const touchListenerOptions = {
 // the whole gesture: `down` from touchstart to touchend/touchcancel, then
 // `tail` while momentum runs. iOS fires no touch events during momentum, so
 // every scroll event re-arms the tail and it closes ~150ms after the last
-// one. Null between gestures, and after touchend on non-iOS, which arms no
-// tail. The tail record owns its timer: every replacement of the state goes
-// through `end`, which clears it, so a live timer always has its record.
+// one. Null between gestures. The tail is tracked on every platform, but
+// only iOS defers anything through it; elsewhere it only tells a command
+// that a fling may be running (`momentumOverridesWrites`). The tail record
+// owns its timer: every replacement of the state goes through `end`, which
+// clears it, so a live timer always has its record.
 //
 // `moved`: the content moved under or after the finger other than by our
 // own write's read-back. While `down`, a scroll event that changed the
@@ -108,9 +121,9 @@ export class IosGesture {
   // read-back will come. A resting finger does not: the write lands.
   dragging = () => this._touch?.phase === 'down' && this._touch.moved
 
-  // The open tail, if any: after a tap, or after a drag or fling. On iOS 27
-  // a fling's momentum overrides a write within a frame (see
-  // `iosMomentumOverridesWrites`).
+  // The open tail, if any: after a tap, or after a drag or fling. Except on
+  // iOS 26 and earlier, a fling's momentum outlasts a write (see
+  // `momentumOverridesWrites`).
   tail = (): 'tap' | 'fling' | null =>
     this._touch?.phase === 'tail' ? (this._touch.moved ? 'fling' : 'tap') : null
 
@@ -203,10 +216,10 @@ export class IosGesture {
   }
 
   // (Re)open the tail after the finger lifts, closing ~150ms after the last
-  // touchend or momentum frame. On non-iOS there is nothing to protect.
+  // touchend or momentum frame.
   private _openTail = (moved: boolean, awaitingFling: boolean) => {
     const win = this.host.getWindow()
-    if (!isIOSWebKit() || win == null) return
+    if (win == null) return
     this.end()
     const tail = {
       phase: 'tail' as const,