virtual-core: desktop Safari drops the prepend anchor write when history lands during the top rubber-band bounce
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 7.1k
- Forks
- 466
- Avg merge
- 2d 31m
- Merged PRs (30d)
- 13
Description
Describe the bug
On macOS Safari (18.4, navigator.maxTouchPoints 0, so none of the iOS deferral is involved), an end-anchored list loses its reading position when a prepend lands while the scroller is rubber-banding past its top edge.
Sequence, from a per-frame trace of the react chat example (anchorTo: 'end', directDomUpdates: true, 180 ms mock history load):
1283ms st=159 off=159 range=1-10 count=45 top=1
1300ms st=0 off=0 range=0-9 count=45 top=0 <- auto history load triggers
1316ms st=-20 off=-20 range=0-8 count=45 top=0 <- Safari rubber band, scrollTop negative
1383ms st=-69 off=-69 range=0-8 count=45 top=0
1466ms st=-51 off=-51 range=0-8 count=45 top=0
1484ms st=-46 off=-46 range=0-10 count=57 top=-12 <- 12 rows prepended, anchor write lost
setOptions resolves the anchor and _willUpdate writes scrollTop = 842 to keep row 0 in place. WebKit discards a scrollTop write made during an elastic bounce and animates back to 0. The next bounce scroll event reports the DOM value, the tracked offset follows it, and the viewport now shows the newly prepended rows: the reader is exactly one prepend away from where they were. While the eagerly bumped offset and the DOM disagree the viewport can also render blank, since the range is computed for a position the DOM never reaches.
The iOS flush path already treats the overscroll zone as unwritable (_flushIosDeferredIfReady, "Phase 2b"). The desktop write path has no such guard.
Steps to reproduce
pnpm --filter tanstack-react-virtual-example-chat dev, open in desktop Safari with a trackpad.- Fling upward hard enough to hit the top and bounce.
- The 180 ms mock load lands during the bounce. The list shows the newly loaded rows instead of the row you were reading.
With a slower (real) backend the load usually lands after the bounce has settled and the write goes through, so this needs a fast prepend to trigger. Cached or prefetched history makes that common.
What was tried
A deferral of writes made while scrollOffset < 0, replayed on the first in-bounds scroll event, lands on the correct row but shows the new rows for the duration of the bounce and then snaps back. That reads as a glitch every time and was dropped from #1280. On WebKit the reader's row cannot be held still through the bounce with scrollTop at all.
Options
- App level, to verify first:
overscroll-behavior: noneon the scroll container. Safari 16+ supports it and per specnonesuppresses the boundary bounce. If it removes the rubber band, the failure window disappears and the chat docs can recommend it next tooverflow-anchor: none. - Core: a CSS offset on the container for the bounce window, swapped for a real
scrollTopwrite once the offset is back in bounds. This is the technique from #1189, scoped to this one case. - Example: the auto-load fires on every bounce scroll event below 120 px, so after the first load finishes the bounce triggers a second one. Independent of the core issue, but it amplifies it.
Platform
- macOS, Safari 18.4 (20621.1.15.11.10)
@tanstack/virtual-coreatmain(also reproduces with #1280 applied; unrelated to the iOS path)
Related: #1280, #1189, #884.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce with pnpm --filter tanstack-react-virtual-example-chat dev in desktop Safari using a fast prepend during the top rubber-band. Read setOptions, _willUpdate, and _flushIosDeferredIfReady, comparing the desktop write path with the iOS overscroll handling and the techniques referenced in #1189 and #1280. Done means an end-anchored list preserves the reader's row during the bounce without rendering a blank viewport.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- frontend, performance
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100