fix(virtual-core): recognize the virtualizer's own write when it is reported again at rest

.changeset/scrollend-own-write.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+With `useScrollendEvent: true`, `scrollToIndex` and `scrollToEnd` no longer stop short of a target that moved while they settled: the `scrollend` that reports the virtualizer's own write again (a size correction, or a write the browser clamped) is no longer read as the user scrolling away. With `anchorTo: 'end'`, rows prepended once a `scrollToIndex` has landed end the command in either mode, so the view stays on the rows it showed rather than moving to the row the index names in the new list.

packages/react-virtual/e2e/app/command-retire/main.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
+import { flushSync } from 'react-dom'
 import { useVirtualizer } from '@tanstack/react-virtual'
 
 // Scroll commands that must finish without the user's help (#1307 step 5,
@@ -12,6 +13,14 @@ import { useVirtualizer } from '@tanstack/react-virtual'
 //   from the spec through `window.__v`). The compensation moves the element
 //   past the target; the command must retire rather than reconcile until the
 //   5s safety valve.
+// - scrollToIndex, then one ResizeObserver batch measures a row above the
+//   fold (compensated) and one between the fold and the target (not): the
+//   target moves further than the correction (rows resized from the spec
+//   through `window.__resize`). The command must land on the fresh target.
+// With `?scrollend=1` (`useScrollendEvent`) the browser also reports each
+// write by `scrollend`, before reconcile; every command must finish the same.
+
+const params = new URLSearchParams(window.location.search)
 
 const COUNT = 100
 const EST = 50
@@ -27,8 +36,12 @@ const App = () => {
     getScrollElement: () => parentRef.current,
     estimateSize: () => EST,
     overscan: 2,
+    useScrollendEvent: params.get('scrollend') === '1',
   })
   ;(window as any).__v = virtualizer
+  // Commits in the caller's task, so the rows are measured in this frame.
+  ;(window as any).__resize = (next: Record<number, number>) =>
+    flushSync(() => setSizes((s) => s.map((size, i) => next[i] ?? size)))
 
   return (
     <div>

packages/react-virtual/e2e/app/test/command-retire.spec.ts

@@ -14,41 +14,73 @@ const state = (page: Page) =>
     }
   })
 
-test.beforeEach(async ({ page }) => {
-  await page.goto('/command-retire/')
-  await page.waitForFunction(() => (window as any).__v != null)
-})
+for (const scrollend of [false, true]) {
+  test.describe(`useScrollendEvent=${scrollend}`, () => {
+    test.beforeEach(async ({ page }) => {
+      await page.goto(`/command-retire/${scrollend ? '?scrollend=1' : ''}`)
+      await page.waitForFunction(() => (window as any).__v != null)
+    })
 
-test('scrollToIndex lands on the fresh target when rows above shrink in the same handler', async ({
-  page,
-}) => {
-  await page.click('[data-testid="index-shrink"]')
-  // Rows 0–19 lost 30px each: row 90 moved from 4500 to 3900, and the max
-  // from 4600 to 4000, under the 4500 written first.
-  // Retired on its own; the safety valve would take 5s.
-  await expect
-    .poll(async () => (await state(page)).command, { timeout: 1000 })
-    .toBe(false)
-  const { scrollTop, row90 } = await state(page)
-  expect(row90).toBe(3900)
-  expect(scrollTop).toBe(3900)
-})
+    test('scrollToIndex lands on the fresh target when rows above shrink in the same handler', async ({
+      page,
+    }) => {
+      await page.click('[data-testid="index-shrink"]')
+      // Rows 0–19 lost 30px each: row 90 moved from 4500 to 3900, and the max
+      // from 4600 to 4000, under the 4500 written first.
+      // Retired on its own; the safety valve would take 5s.
+      await expect
+        .poll(async () => (await state(page)).command, { timeout: 1000 })
+        .toBe(false)
+      const { scrollTop, row90 } = await state(page)
+      expect(row90).toBe(3900)
+      expect(scrollTop).toBe(3900)
+    })
 
-test('scrollToOffset retires after a row above grows, without waiting for the safety valve', async ({
-  page,
-}) => {
-  await page.evaluate(() => {
-    const v = (window as any).__v
-    const el = document.querySelector('[data-testid="scroll-container"]')!
-    // Row 10 is measured larger as the write's read-back arrives, before
-    // reconcile has seen the target reached.
-    el.addEventListener('scroll', () => v.resizeItem(10, 100), { once: true })
-    v.scrollToOffset(2000)
+    test('scrollToOffset retires after a row above grows, without waiting for the safety valve', async ({
+      page,
+    }) => {
+      await page.evaluate(() => {
+        const v = (window as any).__v
+        const el = document.querySelector('[data-testid="scroll-container"]')!
+        // Row 10 is measured larger as the write's read-back arrives, before
+        // reconcile has seen the target reached.
+        el.addEventListener('scroll', () => v.resizeItem(10, 100), {
+          once: true,
+        })
+        v.scrollToOffset(2000)
+      })
+      // The compensation keeps the content in place.
+      await expect.poll(async () => (await state(page)).scrollTop).toBe(2050)
+      // Retired within a few frames; the safety valve would take 5s.
+      await expect
+        .poll(async () => (await state(page)).command, { timeout: 1000 })
+        .toBe(false)
+    })
+
+    test('scrollToIndex lands on the fresh target when it moves further than a correction', async ({
+      page,
+    }) => {
+      await page.evaluate(() => {
+        const v = (window as any).__v
+        const el = document.querySelector('[data-testid="scroll-container"]')!
+        // Row 60 centred: 2825, rows 54–66 rendered. At the read-back, after
+        // this frame's reconcile, row 55 (above the fold, compensated) grows
+        // by 50 and row 58 (in view, above the target) by 100.
+        el.addEventListener(
+          'scroll',
+          () =>
+            requestAnimationFrame(() =>
+              (window as any).__resize({ 55: 100, 58: 150 }),
+            ),
+          { once: true },
+        )
+        v.scrollToIndex(60, { align: 'center' })
+      })
+      await expect
+        .poll(async () => (await state(page)).command, { timeout: 1000 })
+        .toBe(false)
+      // Row 60 starts at 3150: centred at 2975, not at the correction's 2875.
+      expect((await state(page)).scrollTop).toBe(2975)
+    })
   })
-  // The compensation keeps the content in place.
-  await expect.poll(async () => (await state(page)).scrollTop).toBe(2050)
-  // Retired within a few frames; the safety valve would take 5s.
-  await expect
-    .poll(async () => (await state(page)).command, { timeout: 1000 })
-    .toBe(false)
-})
+}

packages/virtual-core/src/index.ts

@@ -633,6 +633,10 @@ export class Virtualizer<
     smooth: boolean
     lowMaxes?: Array<number>
   } | null = null
+  // Where the last scroll event reported our own write, until a report
+  // anywhere else. The browser reports the write again when the element
+  // comes to rest (`restEcho`).
+  private _ownWriteAt: number | null = null
   // A compensation write from `applyScrollAdjustment` whose target exceeded
   // the element's scroll max at the moment of the write. The browser clamps
   // such a write because the consumer's sizer has not grown yet: an
@@ -956,7 +960,7 @@ export class Virtualizer<
         // the rows and the total shifted back by it, so the reader's row
         // stays put, and the flush writes it once a write is possible.
         this._holdOffset += anchorDelta
-        this._followOffsetTarget(anchorDelta)
+        this._followAnchor(anchorDelta)
       }
     }
   }
@@ -1081,6 +1085,7 @@ export class Virtualizer<
     this._clampedAdjustment = null
     // A write to the old element will never be read back.
     this.pendingWrite = null
+    this._ownWriteAt = null
     this.scrollElement = null
     this.targetWindow = null
   }
@@ -1170,6 +1175,17 @@ export class Virtualizer<
             this.scrollState = null
           }
           this.pendingWrite = null
+          // Remember where our own write was reported. Its echo at rest
+          // leaves that as it is; any other report clears it.
+          if (
+            kind === 'readBack' ||
+            kind === 'clampedReadBack' ||
+            kind === 'clampedEcho'
+          ) {
+            this._ownWriteAt = offset
+          } else if (kind !== 'restEcho') {
+            this._ownWriteAt = null
+          }
 
           // A pending clamped compensation write (#1258) survives only its
           // own read-back, which the browser reports at the scroll max we
@@ -1292,25 +1308,22 @@ export class Virtualizer<
         // an update scheduled from a layout effect commits before paint.
         if (!this._canWriteScroll()) {
           this._holdOffset += anchor.delta
-          this._followOffsetTarget(anchor.delta)
+          this._followAnchor(anchor.delta)
           this.notify(false)
         } else if (
           isSmoothScroll(this.scrollState) &&
-          !approxEqual(
-            this.getScrollOffset() - anchor.delta,
-            this.scrollState.lastTargetOffset,
-          )
+          !this._landedBeforeAnchor(this.scrollState, anchor.delta)
         ) {
           // A smooth programmatic scroll is still travelling. Writing scrollTop
           // here would cancel the browser's animation, and Chromium drops a
           // smooth request re-issued in the frame right after that cancel, so
           // the journey would be stranded. The target is index-based and
           // recomputes against the new layout in reconcileScroll, so let the
           // animation run; the next scroll event re-syncs the tracked offset.
-          // A smooth scroll that has already landed (offset at its target,
-          // reconcile not yet retired it) still gets the anchor sync.
+          // A smooth scroll that has already landed (reconcile not yet
+          // retired it) still gets the anchor sync.
         } else {
-          this._followOffsetTarget(anchor.delta)
+          this._followAnchor(anchor.delta)
           this._scrollToOffset(this.getScrollOffset())
         }
       } else {
@@ -1345,6 +1358,7 @@ export class Virtualizer<
       scrollOffset: this.scrollOffset,
       pendingWrite: this.pendingWrite,
       clampedMaxAtWrite: this._clampedAdjustment?.maxAtWrite ?? null,
+      ownWriteAt: this._ownWriteAt,
     })
 
   // Re-issue a compensation write the browser clamped because the sizer had
@@ -2763,6 +2777,32 @@ export class Virtualizer<
     }
   }
 
+  // Whether a command had landed where a prepend's anchor (`delta`, already
+  // in `getScrollOffset()`) found the viewport: it has written (a `queued`
+  // command has not, wherever the fling is), and reconcile has seen it at
+  // its target or the viewport is where it last wrote. A correction since
+  // then can have moved the viewport and the target together.
+  private _landedBeforeAnchor = (state: ScrollState, delta: number) =>
+    state.phase !== 'queued' &&
+    (state.stableFrames > 0 ||
+      approxEqual(this.getScrollOffset() - delta, state.lastTargetOffset))
+
+  // A prepend's anchor moves the viewport with the rows it shows. An offset
+  // target moves with it. An index command that had landed is done: the
+  // reader stays on the rows it was aimed at, and its index now names
+  // others. An end target is still the end.
+  private _followAnchor = (delta: number) => {
+    this._followOffsetTarget(delta)
+    const state = this.scrollState
+    if (
+      state?.index != null &&
+      !state.toEnd &&
+      this._landedBeforeAnchor(state, delta)
+    ) {
+      this.scrollState = null
+    }
+  }
+
   measure = () => {
     // Reset pendingMin so the next getMeasurements rebuilds from index 0.
     // Without this, a prior resizeItem() that left pendingMin > 0 would

packages/virtual-core/src/scroll-classifier.ts

@@ -12,13 +12,16 @@ import { approxEqual } from './utils'
 //                    through since the write
 //   clampedEcho      a compensation write the browser clamped (#1258)
 //                    reporting at the max seen at write time
+//   restEcho         our own write reported again at rest, where the last
+//                    scroll event reported it
 //   external         anything else: the user, a fling, a smooth animation
 //                    frame
 type ScrollEventKind =
   | 'spurious'
   | 'readBack'
   | 'clampedReadBack'
   | 'clampedEcho'
+  | 'restEcho'
   | 'external'
 
 export interface ScrollEventInput {
@@ -44,6 +47,9 @@ export interface ScrollEventInput {
   // The element's max when a clamped compensation write was made (#1258),
   // or null when none is pending.
   clampedMaxAtWrite: number | null
+  // Where the last scroll event reported our own write (read back, clamped
+  // or echoed), until a report anywhere else.
+  ownWriteAt: number | null
 }
 
 export function classifyScrollEvent({
@@ -54,6 +60,7 @@ export function classifyScrollEvent({
   scrollOffset,
   pendingWrite,
   clampedMaxAtWrite,
+  ownWriteAt,
 }: ScrollEventInput): ScrollEventKind {
   // A scroll event that reports movement but lands on the offset we already
   // hold — and isn't a self-write read-back — is a spurious no-op re-emit
@@ -99,6 +106,17 @@ export function classifyScrollEvent({
   ) {
     return 'clampedEcho'
   }
+  // A write is reported again when the element comes to rest: `scrollend`
+  // follows its scroll event in the same frame's scroll steps, before
+  // reconcile; the fallback follows it after `isScrollingResetDelay`.
+  // Nothing has moved the element in between.
+  if (
+    !isScrolling &&
+    ownWriteAt !== null &&
+    Math.abs(offset - ownWriteAt) < 1.5
+  ) {
+    return 'restEcho'
+  }
   return 'external'
 }
 
@@ -142,14 +160,17 @@ export interface RetireInput {
 
 // Whether a scroll event that is not the read-back of our own write retires
 // the in-flight index command: an external scroll moved away from its
-// target. Our own measurement updates (including clamped writes) still need
-// to reconcile.
+// target, or our own write left the element where reconcile will not move
+// it. Our own measurement updates (including clamped writes) still need to
+// reconcile.
 export function externalRetiresCommand({
   kind,
   offset,
   command,
   target,
 }: RetireInput): boolean {
+  let fresh: number | undefined
+  const freshTarget = () => (fresh ??= target())
   return (
     kind !== 'spurious' &&
     kind !== 'readBack' &&
@@ -170,7 +191,14 @@ export function externalRetiresCommand({
     // has landed.
     !isAnimating(command.phase) &&
     !approxEqual(offset, command.lastTargetOffset) &&
-    !approxEqual(offset, target()) &&
+    !approxEqual(offset, freshTarget()) &&
+    // Our own write reported again at rest (`restEcho`): nothing else has
+    // moved the element, but reconcile writes only a target that moved. Once
+    // the target has moved since the command wrote it, reconcile lands the
+    // command there (with `scrollend`, a correction's echo arrives before
+    // reconcile has run on the measurements behind it); while it has not,
+    // nothing will bring the element back, and the command ends here.
+    (kind !== 'restEcho' || freshTarget() === command.lastTargetOffset) &&
     // A compensation write's clamped echo (#1258) keeps the command. The
     // order is deliberate, not tidiness: this clause stays after `target()`
     // (and `clampedReadBack` before it) because `target()` can rebuild the

packages/virtual-core/tests/ios-fling-wait.test.ts

@@ -213,6 +213,23 @@ test('iOS 27: a waiting index target follows rows measured during the fling', ()
   expect(h.writes).toEqual([4550])
 })
 
+test('iOS 27: a prepend as the fling passes the waiting target does not end the command', () => {
+  const h = flingOnIOS27()
+  h.run(() => {
+    h.v.setOptions({ ...h.v.options, anchorTo: 'end', getItemKey: (i) => i })
+    h.v._willUpdate()
+    h.v.scrollToIndex(20, { align: 'start' })
+    h.scroll(true, 1000)
+    h.v.setOptions({ ...h.v.options, count: 112, getItemKey: (i) => i - 12 })
+    h.v._willUpdate()
+    h.scroll(false)
+  })
+  h.expireTail()
+  // The held anchor keeps the reader's rows. Nothing had been written for
+  // the command, so it had not landed: it is written against the new list.
+  expect(h.writes).toEqual([1600, 1000])
+})
+
 // A touch that lands on a scroller still in its fling fires no touch or
 // pointer events on iOS (seen on the 26.5 and 27.0 simulators and an iPhone
 // on 27.0.1, #1307). Touch events arrive only once the fling has stopped,