Summary

Fixes both manifestations of #1233. On iOS WebKit the end-anchored virtualizer defers scroll compensation while it considers the scroller live, accumulating deltas in _iosDeferredAdjustment and replaying them in _flushIosDeferredIfReady() once things settle. Both bugs are the deferral replaying a delta whose premise no longer holds by flush time.

Fix 1 — absolute scroll commands invalidate the pending deferral

scrollToOffset / scrollToIndex (and therefore scrollToEnd) compute their target from current measurements, so any deferred delta pending at that moment is stale — the command already accounts for the measurements the delta was compensating for. Previously the delta survived the command and replayed on the next flush (~150 ms later, at isScrollingResetDelay), shifting the list off the just-established position.

Reported symptom: programmatically restoring a saved reading position (repeated scrollToOffset while rows measure in) lands pixel-correct, then the flush fires and shifts the list a constant +74 px.

Fix: drop the deferral as the first statement of both absolute commands. Relative commands (scrollBy) keep it, since they build on the current offset. Off-iOS this is a no-op — the field is always 0 there.

Fix 2 — the flush drops a negative delta the browser's end clamp already absorbed

With anchorTo: 'end' and the reader pinned at the bottom, a row above the viewport re-measuring smaller during isScrolling shrinks maxScrollOffset; the browser clamps scrollTop onto the new bottom, which is already the correct end-anchored position. The library had separately deferred a negative compensation for that same shrink, and the flush replayed it on top of the clamped position, lifting the view off the bottom by the net delta.

Reported symptom: a single room-open accumulated twelve deltas summing to −101 while the list settled at the bottom; the flush then wrote scrollTop 3543 → 3442, 101 px above the bottom.

Fix: the flush recognizes the end clamp (cur >= max - 1) and drops the stale negative delta. Positive deltas still replay — content growth above the viewport does not clamp (the browser can't shrink to fit growth) and the consumer's DOM sizer may not have grown yet, so a positive delta is still needed.

Testing

• iOS deferral: an absolute scroll command invalidates a pending deferred adjustment (Fix 1, both commands).
• iOS deferral: a negative delta at the end clamp is dropped, not replayed (Fix 2).
• iOS deferral: a positive delta at the end clamp still replays (growth above does not clamp) (guards against over-correcting Fix 2).
• Full virtual-core suite passes (122/122); typecheck and eslint clean.

Both fixes are device-verified by the reporter (@stevan-borus) in production — the constant +74 px restore drift and the −101 px bottom jump are both gone.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Prevented stale iOS scroll adjustments from replaying after users issue absolute scroll commands.
  • Improved end-anchored scrolling near the bottom of a list by avoiding compensations that could move the view away from the correct position.
  • Preserved valid positive adjustments during end-anchored scrolling.

• Documentation

  • Clarified iOS deferred-scrolling behavior for absolute and relative scroll commands.