@@ -0,0 +1,7 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+fix(virtual-core): hold a scroll correction the element cannot take instead of writing it (#1287)
+
+A prepend's anchor delta or an above-viewport size change that lands while a `scrollTop` write is impossible (iOS during a touch gesture or its momentum tail, any WebKit while the element is rubber-banding past an edge) is now held: `scrollOffset` carries the corrected position, the rows and the total size are exposed shifted back by the held amount so every adapter keeps the reader's row where it is, and one write moves the element once a write is possible. Before, the write was discarded during the bounce on desktop Safari (the bounce stalled with the new rows and a blank top on screen), and on iOS the new rows showed through the bounce and snapped back at the flush.
@@ -623,3 +623,7 @@ scrollOffset: number
 ```
 
 This option represents the current scroll position along the scrolling axis. It is measured in pixels from the starting point of the scrollable area.
+
+It is a position in the list's layout, and it stays consistent with `getOffsetForIndex`, the argument to `scrollToOffset`, and `initialOffset`: restoring a saved value returns to the same layout position. That is the same item only while the items and sizes before it are unchanged; to restore across changes, pair it with `takeSnapshot()` and `initialMeasurementsCache` as described above, or scroll to the item with `scrollToIndex`.
+
+While a scroll correction is held, because a write to the element is impossible at that moment (a touch gesture or its momentum on iOS, or the element rubber-banding past an edge), `getVirtualItems()` and `getTotalSize()` describe what is rendered, shifted by the held amount so the rows on screen do not move, while `scrollOffset` keeps the layout position. The hold ends with a single write once the element can take it. Prefer `getVirtualItems()` positions over `item.start - scrollOffset` for where a row sits in the viewport, since that difference is off by the held amount for the length of the gesture or bounce.
@@ -34,6 +34,7 @@ function App() {
   const nextMessageIndexRef = React.useRef(initialMessages.length)
   const streamTimerRef = React.useRef<number | null>(null)
   const loadingHistoryRef = React.useRef(false)
+  const lastScrollTopRef = React.useRef(0)
   const [messages, setMessages] = React.useState(initialMessages)
   const [loadingHistory, setLoadingHistory] = React.useState(false)
   const [didInitialScroll, setDidInitialScroll] = React.useState(false)
@@ -178,7 +179,14 @@ function App() {
           className="Messages"
           onScroll={(event) => {
             if (!autoHistoryEnabled || virtualizer.isAtEnd(80)) return
-            if (event.currentTarget.scrollTop < 120) {
+            const { scrollTop } = event.currentTarget
+            const movingUp = scrollTop < lastScrollTopRef.current
+            lastScrollTopRef.current = scrollTop
+            // Load only while the reader scrolls up into the top. Safari's
+            // rubber band reports negative positions past the top and then
+            // settles back down to 0; neither is the reader asking for more
+            // history, and loading on the settle would load twice per bounce.
+            if (movingUp && scrollTop >= 0 && scrollTop < 120) {
               prependHistory()
             }
           }}