[RFC] Enable React ViewTransition and fix the useSyncExternalStore issue

[matclayton]

RFC: publish router state to React as concurrent render frames

Edited to support fine-grained selectors. The first draft published one
frame through a changing Context value, which invalidated every consumer on
every navigation. A maintainer asked whether selector-level behaviour should
be preserved in the first implementation. It must be, and it now is — this
revision keeps it, with measurements below. Two further revisions followed
from review: navigation progress is now explicitly exempt from the frame, and
a staged frame is isolated to the render presenting it.

The problem

React's <ViewTransition> never fires across a TanStack Router navigation, and
it is not because the navigation is missing a transition. It already has one:
Transitioner.tsx overrides router.startTransition to call
React.startTransition, and the client loader commits every set of matches
through that override.

The update lands on the wrong lane. Every reactive router read goes through
useStore → useSyncExternalStoreWithSelector → useSyncExternalStore, and
React schedules those at a hardcoded SyncLane, from the store's own
subscription callback:

// react-dom, subscribeToStore → forceStoreRerender
function forceStoreRerender(fiber) {
  var root = enqueueConcurrentRenderForLane(fiber, 2); // 2 === SyncLane
  null !== root && scheduleUpdateOnFiber(root, fiber, 2);
}

The lane is a constant, and the callback runs after the startTransition scope
has exited. React does this deliberately: an external store cannot produce a
previous snapshot on demand, so old and new UI cannot render concurrently
without tearing. The cost is that the update carrying a new route is never a
transition, and <ViewTransition> only fires for transitions.

There is a second consequence, independent of animation and arguably more
serious: because consumers read mutable head atoms, a component rendering
while a navigation is in flight observes the route being prepared, not the one
on screen. A menu, toast, or modal opened during a slow navigation renders
against a route the user cannot see.

The proposal

Publish router state to React as render frames: complete, immutable
snapshots with a monotonic frameId, staged inside the Router's own
startTransition and committed only when React acknowledges the exact frame it
rendered. Behind an opt-in router option; default off.

router-core stays additive — a frameId on each aggregate state, a widened
_rendered acknowledgement, and a presented _state for matchRoute. No
shared signature changes, so Solid and Vue are untouched.

The interesting part is the React adapter, because a frame has to answer two
different questions at once.

Two scopes, two slots, and per-consumer state

A frame means different things depending on where you are standing. Outside the
route tree, "the router state" is what is on screen. Inside the route subtree
being prepared, it is what is being prepared. So there are two scopes: a root
scope that advances only on commit, and a presentation scope for the route
subtree that can also carry a staged successor.

Scope identity is stable for the router's lifetime, so a scope in Context
invalidates nobody. Each scope holds its two publications in separate slots,
committed and staged, and each consumer records in React state which one
its own render is presenting:

const staged = scope.staged
return staged && staged.frameId === frameId ? staged : scope.committed

React versions that state per tree. The notification that offers a staged frame
is sent from inside the Router's startTransition, so it keeps the transition
lane and lands in the work-in-progress tree only. The tree the user is still
looking at keeps its previous frameId, resolves to committed, and an urgent
update there cannot pull the staged route into view.

A consumer accepts the offer only if its own selection changed. One that
declines simply stays resolved to committed, where its selection is identical
by definition. That is the whole of the selector story — no changing Context
value, no global invalidation.

Progress is not route content

status and isLoading are deliberately exempt. They are overlaid onto every
slot in both scopes, so a spinner sees the navigation whether it sits above the
route tree or inside the route being left. location and matches are never
overlaid, so the exemption cannot surface a route the user cannot see.

This narrows the original draft's invariant that a render may not combine values
from different publications. Progress is now explicitly live; route content is
not.

Invariants

1. Every aggregate router state carries a monotonic frameId.
2. A render resolves its route content — location, matches, params, search —
   from exactly one publication.
3. Navigation progress (status, isLoading) is exempt from 2 and tracks the
   head in every scope.
4. A publication that React never acknowledges never becomes committed.
5. Only the newest staged publication may commit; a superseded one is dropped,
   whatever order the loaders resolve in.
6. A read outside the route tree only ever sees a committed publication.
7. Inside the route tree, a render may present a staged publication.
8. Publishing a frame re-renders only those consumers whose own selection
   changed.
9. A staged publication is visible only to the render presenting it. A component
   in the still-visible route that re-renders for an unrelated reason continues
   to observe the committed publication.
10. A consumer never misses a publication that lands between its render and the
    installation of its subscription.

What it costs

Correctness and selector parity looked like a trade-off, and three prototypes
each gave up one of them. Measured, not argued:

frame read strategy	urgent-render guard	untouched consumer
changing Context value	passes	6 renders, expected 3
single global pending ?? committed	fails — reads the pending route	3 renders
scoped by position, one mutable frame per scope	fails inside the route tree	3 renders
two slots + per-consumer React state	passes	3 renders

They only conflicted because one mutable answer was serving two questions, in
two trees. Splitting the slots and letting React version the choice resolves it.

Selector-call counts across the existing store-updates-during-navigation
cases are at or below the store path, never higher:

case	store	frames
async loader, async beforeLoad, pendingMs	7	3
redirection in preload	2	0
sync beforeLoad	5	3
nothing / not-found / preloaded variants	3	1–2

And it does what it set out to do. Counting real document.startViewTransition
calls on a two-route app on React canary:

Interaction	Before	After
React state + startTransition (control)	1	1
router.navigate() inside startTransition	0	1
<Link> navigation	0	1

The control row is the point: same elements, same names, same browser, same
React build — only the trigger differs. Mid-navigation the browser is animating
::view-transition-group/old/new(article-image-2), so it is a real shared-element
morph, not just a transition firing.

Open problems

Three, stated plainly.

Mount-time isolation. Invariant 9 holds for a consumer that is already
mounted. A consumer that mounts during a staged navigation has no prior state
and no way to tell which tree is rendering it, so it seeds from
staged ?? committed. If an urgent update in the committed tree mounts a new
router-state consumer mid-navigation, that first render can still read the
staged frame. Closing it appears to require the frame to arrive through a
changing Context value, which costs invariant 8. Whether both can hold at once
is the open question.

Two fixes rest on the mechanism, not a failing test. Recording the committed
selection outside render, and re-reading when the subscription is installed,
both address windows that act() never opens: it flushes passive effects at its
boundaries, so a publication cannot land between a consumer's render and its
effects, and a staged render is committed rather than discarded. Every other
guarantee above has a test that fails without it. These two do not, and I would
rather say so than let them look proven.

Breadth under a large route tree has not been profiled in production, and
whether this should eventually delegate to a native React concurrent-store
primitive — if one arrives — is genuinely open. That is why the proposal is an
option rather than a new default.

Status

Implementation, tests and a changeset: mixcloud#1, against
TanStack Router main. Verified across router-core, react-router,
solid-router and vue-router — lint, types on TS 5.6–7.0, unit, build, and
both e2e suites.

Reproduction and demo: mixcloud/router-transitions-poc — main is the
failure, the PR applies the branch as pnpm patches and measures the result.

[matclayton]

Posting this here mainly as food for thought, feel free to close it or pull it to pieces. We're looking deeply at INP issue right now and Router's useSyncExternalStore is frustrating blocker I'd love to remove, after many claude/codex sessions we have what we believe is a working prototype as laid out above, what are the core teams thought? As sadly I dont know the internals well enough to be confident in all the effects of such a change.

[matclayton]

Here is a POC https://github.com/mixcloud/router-transitions-poc/ showing that view transitions in react are broken, however applying our patches based on the above work, they now work see mixcloud/router-transitions-poc#2

A copy of the patches can be seen as a diff here mixcloud#1

[schiller-manuel]

fine grained selectors must continue to work. so "should the first implementation preserve selector-level" is an absolute yes.

[matclayton]

Happy to try and adjust the PoC, we also have issues with SSR we have yet to fully understand, but I wanted to gather feedback on if this is worth us attempting and if theres any appetite to upstream it if its solvable.

[matclayton]

@schiller-manuel I think I've managed to preserve the selectors now. If you take a look at mixcloud#1 it gives the desired behaviour seen below from the POC app

Screen.Recording.2026-08-28.at.20.35.46.mov