Skip to content

fix: prevent fast-scroll gaps - #2

Draft
ImLunaHey wants to merge 6 commits into
mainfrom
agent/avoid-scroll-gaps
Draft

fix: prevent fast-scroll gaps#2
ImLunaHey wants to merge 6 commits into
mainfrom
agent/avoid-scroll-gaps

Conversation

@ImLunaHey

@ImLunaHey ImLunaHey commented Jul 30, 2026

Copy link
Copy Markdown
Member

What changed

  • add opt-in synchronousWheelScrolling for products that prioritize guaranteed wheel/trackpad rendering over threaded scrolling
  • render cancelable wheel destinations before changing the element's scrollTop
  • pre-render non-cancelable wheel destinations without double-applying native scroll
  • make automatic scrollToOffset and scrollToIndex calls commit their target before moving the element
  • preserve measurement-based anchor corrections during pre-scroll commits
  • track the bounds of the last DOM range committed by React and synchronously recover escaped native ranges
  • configure the demo with synchronous wheel input and an eight-viewport pixel buffer
  • keep the demo's browser-native scrollbar
  • isolate the demo viewport and rows for cheaper layout and paint
  • retain a viewport-sized fallback for native touch, keyboard, and scrollbar checkerboarding
  • pin development CI to the matching core virtualizer commit

Root cause

High-velocity threaded scrolling can paint a new offset before JavaScript receives a scroll event. More overscan reduces checkerboarding but cannot guarantee real content for arbitrary physical jumps.

The opt-in wheel path handles input before the browser changes the scroll position, so it can commit destination rows first. Automatic programmatic jumps use the same ordering. Native scrollbar-thumb dragging provides no cancellable event containing its target before the browser moves, so the native control is retained and that extreme-drag limitation is documented rather than replaced with a non-native scrollbar.

Validation

  • full package check and frozen-lockfile install
  • 25 tests with 100% statement, branch, function, and line coverage
  • cancelable and non-cancelable pixel, line, and page wheel behavior covered
  • measurement correction during pre-render covered
  • React Doctor reports zero issues
  • package audit and demo production build pass
  • trusted browser wheel jumps of 100,000px and 1,000,000px remained covered
  • automatic programmatic jumps commit their destination before moving the viewport
  • keyed prepend anchoring remains stable

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant