fix(scroll): round 11 — MessageThread native scroll listener (WebKit E2E flake)

[TortoiseWolfe]

Summary

• Monday 2026-05-18 scheduled cron E2E run on main (run 26020030467) failed webkit-msg 1/1 on messaging-scroll.spec.ts:266 (T007-T008: Jump button).
• Round-10 fix (fix(ci): serialize E2E runs via repo-wide concurrency mutex #89, commit 996211e) added dispatchEvent(new Event('scroll', { bubbles: true })) after every programmatic scrollTop = N in the test, but the React onScroll JSX prop on MessageThread.tsx:353 does NOT reliably receive synthetic dispatched scroll events on WebKit.
• Fix: bind handleScroll natively via addEventListener('scroll', ...) inside a useEffect, remove the React onScroll prop. Native listeners fire deterministically for both real user scrolls AND programmatic dispatchEvent across all three browser engines.

Root cause (why round 10 didn't fully close this)

React's synthetic onScroll is special — the native scroll event doesn't bubble, so React 17+ artificially makes it bubble through its synthetic event system by listening at the React root. That delegation pipeline assumes the event was generated through the browser's normal scroll mechanism. A programmatically-dispatched new Event('scroll', { bubbles: true }) produces a native event that bubbles through DOM listeners, but does NOT always reach React's synthetic onScroll handler on WebKit (chromium and firefox route it correctly through their respective scroll-delegation paths).

This is a real cross-engine difference. The test dispatch IS correct; the React JSX prop is the brittle layer.

What this change does

+  // Bind handleScroll as a native DOM event listener instead of via React's
+  // `onScroll` JSX prop. Reason: React's synthetic onScroll does not reliably
+  // fire on WebKit when test code dispatches a programmatic
+  // `dispatchEvent(new Event('scroll', { bubbles: true }))` after assigning
+  // `scrollTop`.
+  useEffect(() => {
+    const parent = parentRef.current;
+    if (!parent) return;
+    parent.addEventListener('scroll', handleScroll, { passive: true });
+    return () => parent.removeEventListener('scroll', handleScroll);
+  }, [handleScroll]);

   ...

   <div
     ref={parentRef}
-    onScroll={handleScroll}
     className="absolute inset-0 overflow-y-auto"
     data-testid="message-thread"
     style={{ overscrollBehavior: 'contain' }}
   >

Functionally identical for users — the handler is the same callback, only the binding mechanism changes.

Why this is the right fix (not a hack)

• User scrolls still work — native addEventListener('scroll', ...) catches all scroll events, including real user scrolls.
• Test scrolls now work — programmatic el.dispatchEvent(new Event('scroll')) fires native listeners deterministically.
• No new abstraction — same callback, same effect deps, just bound via a different API surface.
• Tracks an actual browser engine bug class — React's synthetic onScroll has known WebKit edge cases. Documented inline + in CLAUDE.md.

Test plan

• 31 MessageThread unit tests pass
• Type-check clean
• Lint clean
• CI passes on this PR
• After merge, scheduled webkit-msg CI cron runs green
• PR feat: #48 Three.js Game at /game/3d (047 — full SpecKit cascade) #95 ([Feature] 047 Three.js Game #48 Three.js Game) can then merge onto a green main

Notes for reviewer

This unblocks PR #95. Merge order:

1. This PR → main (green CI required)
2. PR feat: #48 Three.js Game at /game/3d (047 — full SpecKit cascade) #95 → main (already green on its own branch CI; will be rebased or re-tested after this lands)

🤖 Generated with Claude Code