LearnNewsExamplesServices
Frontmatter
id9391
titleE2E: Refactor GridRowScrollPinning to Hybrid rAF Engine
stateClosed
labels
enhancementaiarchitecturegrid
assigneestobiu
createdAtMar 8, 2026, 3:28 PM
updatedAtMar 8, 2026, 3:30 PM
githubUrlhttps://github.com/neomjs/neo/issues/9391
authortobiu
commentsCount1
parentIssue9380
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMar 8, 2026, 3:30 PM

E2E: Refactor GridRowScrollPinning to Hybrid rAF Engine

Closed v12.1.0 enhancementaiarchitecturegrid
tobiu
tobiu commented on Mar 8, 2026, 3:28 PM

This ticket documents the pivot to the Hybrid Engine for the GridRowScrollPinning addon.

The initial implementation relied on intercepting VDOM deltas directly as they arrived from the App Worker. However, testing revealed that native browser scrolling runs at 60fps, while worker updates are much slower (often >50ms during heavy layout). This discrepancy meant that the addon was only updating the pinning transform when a message arrived, rather than staying perfectly synced with the physical scrollbar thumb, causing extreme visual jitter.

The Pivot: We have refactored the addon into a Hybrid architecture:

  1. Stateful Updates: VDOM updates from the App Worker (onDeltaUpdate) no longer mutate the DOM. They only update an internal workerScrollTop reference state.
  2. Scroll Driven: A native scroll event listener is attached to the Grid Wrapper node.
  3. rAF Loop: The native scroll event triggers a requestAnimationFrame loop.
  4. Continuous Pinning: Inside the rAF loop, the addon calculates deltaY (actualScrollTop - workerScrollTop) and applies the translate3d CSS transform to the Grid Body content node on every frame, achieving perfect 60fps optical pinning regardless of worker latency.
  5. Hysteresis Logic: The addon enters an isPinned state when deltaY > rowHeight and stays pinned until deltaY falls below 2px to prevent flickering on micro-scrolls.

Completed Changes:

  • Completely rewrote src/main/addon/GridRowScrollPinning.mjs to implement the requestAnimationFrame and native scroll listener loop.
  • Reverted the registration lifecycle in src/grid/ScrollManager.mjs to properly use afterSetMounted, as the addon now requires the DOM to be ready to attach the scroll listener.
  • Temporarily added console logging logic for debugging.

This sub-ticket serves to commit this architectural baseline to the repository before further exploration of sync frequency vs performance.

tobiu added the enhancement label on Mar 8, 2026, 3:28 PM
tobiu added the ai label on Mar 8, 2026, 3:28 PM
tobiu added the architecture label on Mar 8, 2026, 3:28 PM
tobiu added the grid label on Mar 8, 2026, 3:28 PM
tobiu added parent issue #9380 on Mar 8, 2026, 3:29 PM
tobiu referenced in commit 92ca86d - "Enhancement: Refactor GridRowScrollPinning to Hybrid rAF Engine (#9391) on Mar 8, 2026, 3:30 PM
tobiu
tobiu Mar 8, 2026, 3:30 PM

Input from Gemini 3.1 Pro:

✦ The Hybrid Architecture baseline has been committed and pushed to the repository. The testing logs have been removed.

This version provides a clean starting point for testing different frequency strategies (like direct scroll event injection vs rAF).

Closing this ticket as requested by the user.

tobiu assigned to @tobiu on Mar 8, 2026, 3:30 PM
tobiu closed this issue on Mar 8, 2026, 3:30 PM