Repository navigation
perf(dots): stop reading shared values from JS and crossing to JS on every drag frame - #17
Conversation
…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>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 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
| if (section && section.sectionIndex !== draggedSectionIndex.value) { | ||
| draggedSectionIndex.value = section.sectionIndex; | ||
| runOnJS(onThumbPositionChange)(yPosition); |
There was a problem hiding this comment.
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>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>




Summary
Two costs in
FastScrollSectionDotsBar, both listed indocs/backlog.md.1. The handle read shared values from JS. Apps reach the bar's
onSectionChangefromonViewableIndexChanged, and it readenableExternalScrollEvents.valueandcontainerScrollY.value. On Reanimated 3 a JS read of a shared value runs throughexecuteOnUIRuntimeSync. 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:
thumbYOnDotmoves toFastScrollSectionDots/utils.tswith 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 theonScrollToIndexdebounce, re-locks the bar's visibility and callsshow()on the section list (two state updates, an animatedscrollToIndex, 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.findSectionOnPositionbecomes 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:draggedSectionIndexis 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.loginonThumbPositionChange(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).main)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:
main)Before, every move restarted the 1 s debounce, so the list waited for the finger to stop. Now only a new section restarts it.
main)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:Under Jest (Reanimated 2.12)
runOnUIruns synchronously and a.valueread 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 lintandyarn prepackpass.Merge Danger
Door: two-way
Internal to the dots bar. The props, the handles and the gesture are unchanged.
Blast Radius: dots drag
onScrollToIndexdoes 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.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