Skip to content

perf(dots): stop reading shared values from JS and crossing to JS on every drag frame - #17

Merged
gfrancischini merged 2 commits into
mainfrom
perf/dots-no-sync-reads
Nov 10, 2026
Merged

gfrancischini merged 2 commits into
mainfrom
perf/dots-no-sync-reads

Conversation

@gfrancischini

Copy link
Copy Markdown
Owner

Summary

Two costs in FastScrollSectionDotsBar, both listed in docs/backlog.md.

1. The handle read shared values from JS. Apps reach the bar's onSectionChange from onViewableIndexChanged, and it read enableExternalScrollEvents.value and containerScrollY.value. On Reanimated 3 a JS read of a shared value runs through executeOnUIRuntimeSync. That takes the UI runtime's lock, so the JS thread waits whenever the UI thread is running worklets, and during a scroll it runs them on every frame. #15 measured two reads of this shape on the IndicatorCost screen during scrolls: p50 0.44–0.79 ms, p95 12–17 ms. Here the handle runs on viewability changes, not on every frame, so the cost is smaller than it was in the indicator, but it is the same wait.

The indicator kept JS copies. Here one of the values is a derived value computed on the UI thread, so the handle sends the section to the UI thread instead and does the reads there:

 onSectionChange(section)                       // JS, each viewability change
-  if (enableExternalScrollEvents.value)        // sync read
-    pointStylePositionY.value = thumbYOnDot(section.sectionIndex)
-    containerYOnPointStylePositionY.value = containerScrollY.value   // sync read
+  followListOnUI(section.sectionIndex)         // runOnUI, async

+followListOnUI(sectionIndex)                   // worklet, built once per dotSize/dotMargin
+  if (!enableExternalScrollEvents.value) return
+  pointStylePositionY.value = thumbYOnDot(sectionIndex)
+  containerYOnPointStylePositionY.value = containerScrollY.value

thumbYOnDot moves to FastScrollSectionDots/utils.ts with a 'worklet' directive, next to the other UI-thread helpers.

2. The pan crossed to JS on every frame the finger moved. Each crossing went through onSectionChange, which restarts the onScrollToIndex debounce, re-locks the bar's visibility and calls show() on the section list (two state updates, an animated scrollToIndex, a reset of the 1 s retry and the 3 s hide timer). All of that ran on every frame, even with the finger on one dot.

 pan
   onBegin
+    draggedSectionIndex = -1                   // a new touch always reports its section
     followFinger(y)
   onStart / onUpdate
     followFinger(y)
   onFinalize
     snap the thumb
     runOnJS(onThumbPositionChange)             // unchanged: always once on lift

 followFinger(y)                                // worklet
   move the thumb
-  runOnJS(onThumbPositionChange)               // every frame
+  section = findSectionOnPosition(y, dotPositions)        // already a worklet
+  if section.sectionIndex != draggedSectionIndex
+    draggedSectionIndex = section.sectionIndex
+    runOnJS(onThumbPositionChange)             // only when the finger reaches another dot

findSectionOnPosition becomes generic over { y }, so the worklet can call it with the dot positions it already holds in a shared value. The pan is still built once: draggedSectionIndex is a shared value, and the "same pan callbacks" test passes unchanged.

The backlog entries for both items are removed.

Evidence

JS crossings per drag, on Reanimated 3. Android emulator (API 36), Expo Go for SDK 52, dev bundle, Categories screen. A temporary console.log in onThumbPositionChange (not committed), counted in the Metro log. The same scripted drag each run: a finger on the dots moves 20% of the screen down in 1.4 s, moves 3 px back and forth twice, then lifts (106 touch events).

Version Run 1 Run 2
before (main) 47 54
after (this PR) 8 11

After the change, each crossing is a section change, the touch down or the lift. Before, almost every move event crossed.

The behavior that changes, on Reanimated 3. Same setup. The same scripted drag on both versions:

  1. Scroll the list a little so the dots show.
  2. A finger lands on the dots, moves down to Bracelets / Yellow Gold in 0.6 s, then moves sideways over that dot for 3.6 s (a zigzag 1.5% of the screen wide, at one height, so it never leaves the dot), then lifts.
Finger reaches the dot Finger lifts List scrolls to Yellow Gold
before (main) +0.6 s +4.4 s +5.3 s, after the lift
after (this PR) +0.6 s +4.4 s +1.6 s, with the finger still down

Before, every move restarted the 1 s debounce, so the list waited for the finger to stop. Now only a new section restarts it.

Before (main) After (this PR)
The list stays on Bracelets / 18k Gold while the finger moves over the Yellow Gold dot, and scrolls there a second after the lift. The list scrolls to Bracelets / Yellow Gold a second after the finger reaches its dot, while the finger keeps moving.

Frames at +0.8, +2.0, +3.2, +4.2 and +5.6 s after the touch down (top: before, bottom: after). The grey circle on the dots is the finger:

Full resolution: before.mp4, after.mp4. Everything else in the recordings matches: the section list opens on touch down and its active row follows the finger. The example's thumb is a pale bar over white dots and does not show, so where it lands after a report is left to the unit tests below.

Unit tests. Two new tests in FastScrollSectionDots.test.tsx:

finger reaches Vegetables, keeps moving over its dot 600 ms later
  -> onScrollToIndex(5) 1000 ms after reaching the dot      fails on main (debounce restarted), passes here
drag ends on Vegetables, list closes, new touch on Vegetables
  -> the section list opens again                           guards the reset in onBegin; fails when it is removed

Under Jest (Reanimated 2.12) runOnUI runs synchronously and a .value read is a plain JS read, so the wait from part 1 cannot show there. The handle's behavior is covered by the existing tests, which pass unchanged: the thumb moves to the reported section, ignores reports while a finger is down, and the strip scrolls to keep the active dot in view.

yarn test (103 passed, 1 todo), yarn typecheck (Reanimated 2.12 and 3), yarn lint and yarn prepack pass.

Merge Danger

Door: two-way

Internal to the dots bar. The props, the handles and the gesture are unchanged.

Blast Radius: dots drag

  • Debounce timing while dragging. Before, any movement restarted the 1 s debounce, so the list scrolled 1 s after the finger stopped moving. Now only a section change restarts it, so the list scrolls 1 s after the finger reached the section, even if the finger is still moving over that dot. A finger resting on a dot already did this before. The lift still reports the snapped section, so the list ends on it as before. A drag that stays on one section for over a second now scrolls the list before the lift, then again after it, so an app whose onScrollToIndex does more than scroll (a retry, analytics) sees that call twice. In the example, FlashList's first long jump can land a section off; the lift's call corrects it.
  • When the handle's work runs. On Reanimated 3 the writes to the thumb were already asynchronous (a JS write of a shared value goes through runOnUI, src/mutables.ts); only the reads were synchronous. The thumb lands at the same time as before. The finger check now runs on the UI thread, where the pan sets the flag, so a report that arrives right after a touch down is dropped there rather than racing it.

🤖 Generated with Claude Code

…every drag frame

The bar's onSectionChange handle, which apps reach from
onViewableIndexChanged, read two shared values on the JS thread. On
Reanimated 3 such a read takes the UI runtime's lock, so the JS thread
waited while the UI thread ran worklets. The handle now sends the section
to the UI thread with runOnUI, and the reads happen there.

The pan called runOnJS on every frame the finger moved. Each call went
through onSectionChange, which restarts the onScrollToIndex debounce,
re-locks the bar's visibility, and calls show() on the section list
(state updates, an animated scrollToIndex, the retry and hide timers).
The pan now finds the section in the worklet and only crosses to JS when
it changes, plus once when a touch begins and once on lift.

Visible change: while the finger moves within one section, the debounce
is no longer restarted, so the list scrolls to that section a second
after the finger reached its dot, as it already did for a finger that
rests on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gfrancischini added a commit that referenced this pull request Nov 10, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini requested a balanced review from Copilot November 10, 2026 19:21

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.

🟡 Changes recommended

Suppressing same-dot updates can leave the newly opened section picker at the top with the active row offscreen because the requested section is not centered after the list mounts.

1 open issue
What changed in this PR

This PR reduces cross-thread work in FastScrollSectionDotsBar, extending the earlier indicator optimization to section-based scrolling.

Changes:

  • Moves list-following shared-value reads onto the UI thread.
  • Reports drag updates to JavaScript only when the section changes, while preserving touch-down and lift notifications.
  • Adds debounce and reopening regression tests and removes the corresponding backlog entries.
File Description
src/​FastScrollSectionDots/​utils.ts Adds a thumb-position worklet and generalizes section lookup.
src/​FastScrollSectionDots/​FastScrollSectionDotsBar.tsx Moves handle work to the UI thread and filters repeated drag notifications.
src/​FastScrollSectionDots/​__tests__/​FastScrollSectionDots.test.tsx Tests same-dot debounce timing and picker reopening.
docs/​backlog.md Removes the two addressed performance items.

Review effort: Balanced

Comment on lines +266 to +268
if (section && section.sectionIndex !== draggedSectionIndex.value) {
draggedSectionIndex.value = section.sectionIndex;
runOnJS(onThumbPositionChange)(yPosition);

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Confirmed, and fixed in 70a3989 as suggested: the dots still report only on a new section, and FastScrollSectionFullList centers the active section when the list lays out (onLayout), with the same retry a second later that show() uses.

The touch that opens the list reports its section before the list is mounted, so that show() cannot scroll it. Before this PR the next frame's report did; with the deduplication the next report only comes on another dot or on lift.

Unit test. centers the section a touch opens the section list on, while the finger stays on its dot: list closed, finger touches Dairy, the list lays out, the finger moves 2 px without leaving Dairy's dot.

Code Result
this PR before 70a3989 fails: scrollTo is never called
this PR at 70a3989 passes: the list centers Dairy (scrollTo({ y: 55 }))

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

On device. Android emulator (API 36), Expo Go for SDK 52, dev bundle, Categories screen. The same scripted gesture on both builds: scroll the list a little so the dots show, touch the dot of Necklaces / Silver Gold (low on the bar, far down the section list) with the section list closed, zigzag sideways over that dot for 3.6 s (1.5% of the screen wide, so it never leaves the dot), lift. Times from the touch down, read from the recordings at 5 fps:

Build Section list opens Section list centers Necklaces / Silver Gold Finger lifts
before 70a3989 +0.2 s, at its top +4.4 s, after the lift +3.7 s
at 70a3989 +0.2 s, at its top +1.2 s, with the finger still down +3.7 s

At 70a3989 the first scroll, on layout, hits a row the list has not measured yet, and the retry a second later centers it. That is the same timing show() had when the list was already open.

Before 70a3989 At 70a3989
The section list stays on Bracelets / Earrings while the finger is on the dot, and scrolls to Necklaces / Silver Gold after the lift. The section list scrolls to Necklaces / Silver Gold, highlighted, while the finger is still on the dot.

Frames at +0.6, +1.4, +2.4, +3.4 and +4.6 s after the touch down (top: before, bottom: after). The grey circle at the bottom of the dots is the finger:

Full resolution: before.mp4, after.mp4.

The touch that opens the section list reports its section before the
list is mounted, so show() could not scroll it. Before the dots stopped
reporting every frame, the next frame's report scrolled it; now the next
report only comes on another dot or on lift, so a finger that stays on a
low dot left the list at its top, with the active row out of view.

The list now centers the active section when it lays out, with the same
retry a second later that show() uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gfrancischini added a commit that referenced this pull request Nov 10, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini merged commit 305578f into main Nov 10, 2026
3 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