fix(web): stable callbacks refresh before layout effects read them#25489

Problem

#25462 (the timeline-viewport split) merged from an old head, so its review fix for the Macroscope thread PRRT_kwDORLtfbc6wPVR2 never reached main. Main has useStableCallback refresh its ref in a useLayoutEffect in the component that owns the callback. Child layout effects run before the parent's, so a child that calls the stable callback from its own layout effect gets the previous render's function. useTimelinePositionRestore hits this: its viewport.navigate called the previous render's handleNavigation. After a thread switch with find open, the restore navigated the old visit and left the thread on screen in follow mode.

Fix

apps/web/src/hooks/useStableCallback.ts now refreshes the ref in useInsertionEffect. Insertion effects run in the mutation phase, before any layout effect in the commit runs, so every layout effect sees the function from the render being committed.

Test

apps/web/src/hooks/useStableCallback.browser.test.tsx renders a parent that passes a stable callback to a child, and the child calls it from a layout effect. Against main it fails: expected [ 'first->first', 'second->first' ] to deeply equal [ 'first->first', 'second->second' ]. With the fix it passes.

Blast radius

The change only affects apps/web: every caller is there (about 50 files). Mobile and client-runtime do not import the hook.

• Event handlers, passive effects, render: no change. The refresh still happens before passive effects and after render, and render still sees the previous commit's function, as the doc comment says.
• Layout effects: every one now sees the current function. Before, that held only for layout effects declared after the hook in the same component. Layout effects in children, or declared before the hook, saw the stale one. I read each useLayoutEffect in a file that uses the hook. None needs the previous function:
  • useTimelineFollow (scrollToEndStable) and ChatView (publishComposerOverlayHeightStable) already saw the current one.
  • ChatComposer calls onComposerRestingChangeStable, a ChatView stable callback, from its own layout effect. That is the same child-before-parent pattern as the bug, so the fix corrects it too.
• Layout-effect cleanups: the only timing that moves later. A layout cleanup that re-runs on a deps change in the component that owns the callback runs after that component's insertion effect, so it now sees the new function. Cleanups in children still see the old one. No caller calls a stable callback from a layout-effect cleanup.
• <Activity>: hidden subtrees run insertion effects but not layout effects. The web app does not use <Activity>, so nothing changes. If it did, the new behaviour would be the more correct one.
• React 19 rules: insertion effects must not read layout or schedule updates. Writing a ref does neither, and it is the pattern React documents for useEffectEvent shims. The React Compiler accepts it: apps/web/src/reactCompilerCoverage.test.ts passes.

Verification

• vp run check:changed: format, lint, knip, typecheck (7 packages) and tests (18 files, 259 tests) all pass. The first run hit a Vite dependency-optimization reload in a browser test; the rerun was clean.
• apps/web/src/reactCompilerCoverage.test.ts and the new test pass.
• Earlier live check on web of d5d74f184d, the same change on the #25462 branch: timeline scroll restore, follow while streaming, find, and the core shortcuts all worked.

Model: Claude Opus 5.5, Claude Code harness.

🤖 Generated with Claude Code