Skip to content

fix(indicator): keep the thumb under a finger that lands while the list scrolls - #20

Merged
gfrancischini merged 2 commits into
mainfrom
fix/indicator-thumb-touch-race
Nov 11, 2026
Merged

gfrancischini merged 2 commits into
mainfrom
fix/indicator-thumb-touch-race

Conversation

@gfrancischini

@gfrancischini gfrancischini commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

Summary

The indicator's pan tells the JS thread that a finger is on the track through runOnJS. That message waits behind any list scroll events already queued on the JS thread. On a busy JS thread, those events passed the handle's check and moved the thumb back to the list's old offset, away from the finger. It stayed there until the finger moved far enough to activate the pan, or lifted.

 pan.onBegin                                  // UI thread
+  fingerOnTrackOnUI = true
   runOnJS(setFingerOnTrack)(true)            // queued behind the list's scroll events
   thumb.y = finger

 onScrollToOffsetPercentage(offset)           // JS thread
   if fingerOnTrack                           // JS copy, cleared when the lift reaches JS
     return
-  thumb.y = clamp(offset) * (track - thumb)
+  runOnUI(followList)(clamp(offset))
   show the bar, restart the hide timer

+followList(offset)                           // UI thread
+  if fingerOnTrackOnUI                       // a report queued before the finger landed
+    return
+  thumb.y = offset * (track - thumb)

Each copy of the flag covers one end of the touch:

  • The UI copy covers touch-down. It is set the moment the finger lands, and the thumb's move is checked against it on the same thread.
  • The JS copy covers the lift, as before. The list follows the drag, so scroll events from the drag are still queued when the finger lifts. The copy also keeps those events from restarting the hide timer under a resting finger.

The dots bar already checks on the UI thread. It needs no JS copy because its list stays still during a drag (onScrollToIndex is debounced).

Also in this PR:

  • Example screen. A new IndicatorGrab screen: 2000 rows, and every scroll frame keeps the JS thread busy for 40 ms.
  • Test fixture. src/__fixtures__/jsThread.ts lets a test reproduce the JS thread's queue (see Evidence).
  • Docs. The backlog item is removed, docs/unit-testing.md documents the fixture, and CLAUDE.md describes the handle rule with both flags.

Evidence

Unit tests. Under Jest runOnJS runs at once, so the race could not happen in a test. With the new fixture, runOnJS calls made inside whileJsThreadIsBusy(...) wait until whatever the test does on the JS thread has run, as calls queued behind it would on a device. The rest of Reanimated is the real one.

list at 0.1; JS thread busy: finger lands at 275, list reports 0.2
  -> thumb at 250, under the finger     main: 100, the list's old offset    fails on main, passes here
list at 0.1; finger at 275, moves to 400; JS thread busy: finger lifts, list reports 0.5
  -> thumb at 375, where it lifted      main: 375                           passes on both; guards the lift

Mutation check:

  • Without the UI-thread check, the first test fails (100).
  • Moving the write ahead of the JS check, so the JS flag only guards the hide timer, makes the second test fail (250).

yarn test (110 passed, 1 todo), yarn typecheck and yarn lint pass.

On a device.

  • Setup: Android emulator (API 36), example app on Expo SDK 52 (Reanimated 3.16, New Architecture), on the IndicatorGrab screen.
  • Gesture: the same on both builds. Fling from the top, then rest a finger on the track at 80% of its height for 2.5 s, then lift. The gray dot is the finger.

Before on main, after on this branch, same gesture

The same side by side as a video:

before-after.mp4

One second into the hold:

One second into the hold: on main the thumb is at the top of the track, here it is under the finger

Thumb read from every frame of the recordings (30 fps). The finger rests at y = 1872 px, and the track spans 501 to 2274 px.

Before (main) After (this branch)
Finger lands Under the finger for 1 frame Under the finger
Finger rests (2.5 s) Back at the top of the track (top edge at 503 px, about 1260 px above the finger) for 74 frames (2.47 s) Under the finger on every frame
Finger lifts Jumps back to the finger Stays

Merge Danger

Door: two-way

The change is limited to the indicator's handle and pan. Reverting it restores the old behavior.

Blast Radius: indicator thumb

  • Per-frame cost. Each onScrollToOffsetPercentage call now sends one runOnUI instead of writing translateY from JS. That costs the same: a JS write of a shared value is already scheduled onto the UI thread, on Reanimated 3 (runOnUI in mutables.ts) and on 2.12 (scheduleOnUI in MutableValue.cpp). The handle still reads no shared value from JS.
  • Track height. The thumb now reads the track height from the layout shared value on the UI thread, where it used to read a JS copy. Both are set in the same onLayout.
  • API. The handle's name and signature are unchanged. The dots and the tab bar are not touched.
  • Tests and package. One test suite now replaces Reanimated's runOnJS with a wrapper that can hold calls back; the rest of Reanimated stays real. The example screen and the fixture are not published.

🤖 Generated with Claude Code

gfrancischini and others added 2 commits November 11, 2026 16:50
…st scrolls

The pan tells the JS thread that a finger is on the track through
runOnJS. Scroll events already in line on the JS thread when the finger
landed still passed the handle's check and moved the thumb back to the
list's old offset, away from the finger, until the finger moved far
enough to activate the pan or lifted. It needs a busy JS thread, such as
a fling through a heavy list.

The pan now also keeps the flag in a shared value, set on the UI thread
at touch down, and the handle sends the thumb's position there with
runOnUI, where the check runs. The JS copy still gates the handle first:
when the finger lifts, the list's scroll events from the drag report
where the finger was a few frames before, and they must not restart the
hide timer under a resting finger.

Under Jest runOnJS runs at once, so the suite opts in to a fixture whose
runOnJS calls wait while the test plays what the JS thread had in line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…read

IndicatorGrab keeps the JS thread busy for 40 ms on every scroll frame,
as a heavy screen would, so the list's scroll events pile up there while
it flings. Fling the list, then rest a finger on the track: the thumb
must stay under it. On the previous indicator it went back to where the
list was until the finger lifted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the scroll-indicator touch-handling change.

No open issues 🎉

What changed in this PR

Fixes FastScrollIndicator so queued list scroll reports cannot move the thumb away from a resting finger, while preserving protection against stale reports after lift.

Changes:

  • Adds a UI-thread touch flag and guarded thumb updates, retaining the existing JS-thread check.
  • Adds regression tests, a delayed-runOnJS fixture, and a busy-thread example screen.
  • Updates testing guidance, handle conventions, and the backlog.
File Description
src/​FastScrollIndicator/​FastScrollIndicator.tsx Guards list-driven thumb updates on the UI thread.
src/​FastScrollIndicator/​__tests__/​FastScrollIndicator.test.tsx Tests queued scroll reports at touch-down and lift.
src/​__fixtures__/​jsThread.ts Adds controlled queuing of runOnJS calls for tests.
example/​src/​screens.ts Adds the IndicatorGrab route type.
example/​src/​NavigationTree.tsx Registers the new example screen.
example/​src/​indicatorGrab/​IndicatorGrab.tsx Demonstrates grabbing the indicator with a busy JS thread.
example/​src/​ExamplesScreen.tsx Adds navigation to the new example.
docs/​unit-testing.md Documents the busy-thread fixture and its use.
docs/​backlog.md Records the fix and removes the resolved backlog item.
CLAUDE.md Documents the complementary UI- and JS-thread guards.

Review effort: Balanced

@gfrancischini
gfrancischini merged commit 1f30821 into main Nov 11, 2026
4 checks passed
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.

2 participants