fix(virtual-core): notify synchronously after above-viewport resize compensation

`resizeItem` writes `scrollTop` synchronously inside the ResizeObserver
callback to compensate for an above-viewport size change, but then notified
asynchronously. The browser could paint one frame with the new `scrollTop`
and the old item transforms, so the viewport visibly jumped by the resize
delta and snapped back on the next commit (#1227) — the scrollbar stayed
anchored (skew=0) but the content flashed.

When a compensation actually moves the scroll position, notify synchronously
so the transform commit lands in the same paint as the scroll write. Resizes
that move nothing (below-fold measurements) and iOS-deferred adjustments keep
the cheaper async notify. `applyScrollAdjustment` now reports whether it wrote
`scrollTop` this tick to drive that decision.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: piecyk

.changeset/fix-up-scroll-compensation-flash.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Fix a one-frame viewport jump when above-viewport rows resize while scrolling up (#1227). `resizeItem` writes `scrollTop` synchronously inside the ResizeObserver callback to compensate for the size change, but then notified asynchronously — so the browser could paint a frame with the new `scrollTop` and the old item transforms, making the content jerk by the resize delta and snap back. When a compensation actually moves the scroll position, `resizeItem` now notifies synchronously so the transform commit lands in the same paint as the scroll write. Resizes that don't move the scroll position (below-fold measurements, iOS-deferred adjustments) keep the cheaper async notify.

packages/virtual-core/src/index.ts

@@ -679,8 +679,15 @@ export class Virtualizer<
     this.options.onChange?.(this, sync)
   }
 
-  private applyScrollAdjustment(delta: number, behavior?: ScrollBehavior) {
-    if (delta === 0) return
+  // Returns `true` when it performed a synchronous `scrollTop` write this
+  // tick, `false` when the delta was zero or the write was deferred (iOS).
+  // `resizeItem` uses that to decide whether the follow-up `notify` must be
+  // synchronous so the grown transforms commit in the same paint (#1227).
+  private applyScrollAdjustment(
+    delta: number,
+    behavior?: ScrollBehavior,
+  ): boolean {
+    if (delta === 0) return false
 
     if (process.env.NODE_ENV !== 'production' && this.options.debug) {
       console.info('correction', delta)
@@ -691,6 +698,7 @@ export class Virtualizer<
       (this.isScrolling || this._iosTouching || this._iosJustTouchEnded)
     ) {
       this._iosDeferredAdjustment += delta
+      return false
     } else {
       this._scrollToOffset(this.getScrollOffset(), {
         adjustments: (this.scrollAdjustments += delta),
@@ -716,6 +724,7 @@ export class Virtualizer<
         if (this.scrollOffset < 0) this.scrollOffset = 0
         this.scrollAdjustments = 0
       }
+      return true
     }
   }
 
@@ -1599,13 +1608,26 @@ export class Virtualizer<
       this.itemSizeCache.set(key, size)
       this.itemSizeCacheVersion++
 
+      let adjustedSync = false
       if (wasAtEnd) {
-        this.applyScrollAdjustment(this.getTotalSize() - prevTotalSize)
+        adjustedSync = this.applyScrollAdjustment(
+          this.getTotalSize() - prevTotalSize,
+        )
       } else if (shouldAdjustScroll) {
-        this.applyScrollAdjustment(delta)
+        adjustedSync = this.applyScrollAdjustment(delta)
       }
 
-      this.notify(false)
+      // When we just moved `scrollTop` to compensate for an above-viewport
+      // resize, the grown item transforms must commit in the SAME frame as
+      // that write. `applyScrollAdjustment` writes `scrollTop` synchronously
+      // inside this ResizeObserver callback, but an async `notify` schedules
+      // the transform render for a later commit — so the browser can paint
+      // one frame with the new `scrollTop` and the old positions, and the
+      // viewport visibly jumps by `delta` before snapping back (#1227). A
+      // synchronous notify flushes the render in this same callback, so both
+      // land in one paint. When nothing moved (or the write was deferred on
+      // iOS), keep the cheaper async notify.
+      this.notify(adjustedSync)
     }
   }
 

packages/virtual-core/tests/index.test.ts

@@ -2553,9 +2553,11 @@ test('scroll-up jank: idle (scrollDirection=null) still applies adjustment', ()
 function createAdjustmentVirtualizer({
   count = 30,
   offset,
+  onChange,
 }: {
   count?: number
   offset: number
+  onChange?: (instance: any, sync: boolean) => void
 }) {
   const scrollToFn = vi.fn()
   let scrollCb: ((o: number, s: boolean) => void) | null = null
@@ -2571,6 +2573,7 @@ function createAdjustmentVirtualizer({
         offsetHeight: 200,
       }) as any,
     scrollToFn,
+    onChange,
     observeElementRect: (_inst: any, cb: any) => {
       cb({ width: 400, height: 200 })
       return () => {}
@@ -2735,6 +2738,54 @@ test('multi-frame reflow: above-viewport re-measure compensation is never skippe
   expect(v.scrollOffset).toBe(725)
 })
 
+test('above-viewport compensation notifies synchronously so the scroll write and transforms commit in one paint (#1227)', () => {
+  // applyScrollAdjustment writes scrollTop synchronously inside the resize
+  // (ResizeObserver) callback. If the follow-up notify were async, the
+  // browser could paint one frame with the new scrollTop but the old item
+  // transforms — the viewport visibly jumps by `delta` and snaps back. The
+  // compensating resize must notify synchronously (sync=true) so the render
+  // flushes in the same callback.
+  const onChange = vi.fn()
+  const { v, scrollToFn } = createAdjustmentVirtualizer({
+    offset: 600,
+    onChange,
+  })
+  v['getMeasurements']()
+  onChange.mockClear()
+  scrollToFn.mockClear()
+
+  // Item 0 sits entirely above the fold (offset 600) — a first measurement
+  // there compensates regardless of scroll direction, moving scrollTop.
+  v.resizeItem(0, 90)
+
+  // The compensation write happened...
+  expect(scrollToFn).toHaveBeenCalledTimes(1)
+  // ...and its notify was synchronous so transforms flush in this same frame.
+  expect(onChange).toHaveBeenCalled()
+  expect(onChange.mock.calls.at(-1)![1]).toBe(true)
+})
+
+test('a resize that moves no scroll position keeps the cheaper async notify (#1227)', () => {
+  // No scroll write → no same-frame constraint → the notify stays async so we
+  // don't force a synchronous render on every below-fold measurement.
+  const onChange = vi.fn()
+  const { v, scrollToFn } = createAdjustmentVirtualizer({
+    offset: 0,
+    onChange,
+  })
+  v['getMeasurements']()
+  onChange.mockClear()
+  scrollToFn.mockClear()
+
+  // Item 10 (start 500) sits below the fold at offset 0 — measuring it does
+  // not compensate, so scrollTop is untouched.
+  v.resizeItem(10, 90)
+
+  expect(scrollToFn).not.toHaveBeenCalled()
+  expect(onChange).toHaveBeenCalled()
+  expect(onChange.mock.calls.at(-1)![1]).toBe(false)
+})
+
 // ─── end anchoring / chat-style reverse virtualization ──────────────────────
 
 function createChatVirtualizer({