fix(routing): subscribe roots to broadcasts before any root broadcasts

[UberMouse]

The bug

buildRootComponent subscribes the root machine to the global emitter from a passive effect:

useEffect(() => {
  function handler(event: GlobalEvents) {
    recursivelySend(interpreter, event);
  }
  emitter.on("event", handler);
  return () => emitter.off("event", handler);
}, [interpreter]);

A routing root broadcasts the initial route from a passive effect too (the mount effect that calls handleLocationChange).

Passive effects run in tree order. So whether a root receives the initial routing event depends entirely on where it renders relative to the routing root:

<><RoutingRoot /><ListenerRoot /></>   // ListenerRoot MISSES the initial route
<><ListenerRoot /><RoutingRoot /></>   // ListenerRoot receives it

In the first case the routing root's mount effect has already broadcast by the time ListenerRoot's subscribe effect runs. The event is emitted into an emitter nobody is listening on yet, and it's gone — there's no replay for a non-slotted root.

Event delivery silently depending on JSX sibling order is not something callers can reasonably be expected to know about, and it fails in the direction that's hardest to debug: no error, just a machine that never got its route.

The fix

Subscribe during the layout phase.

React runs all layout effects for a commit before any passive effect for that commit, so every root is attached to the emitter before a passive effect can broadcast — regardless of render order. Broadcasting stays where it is; only the subscription moves.

Test

src/tests/rootSubscribesBeforeBroadcast.spec.tsx renders a routing root and a bare root in both orders and asserts the bare root sees the initial routing event either way.

On master the "rendered after" case fails and the "rendered before" case passes — the order dependence, pinned. Both pass with this change.

Context

Kawaka has been carrying exactly this change as a local pnpm patch (common/pnpm-patches/@koordinates__xstate-tree@5.5.1.patch) since May. It was added during an XState v5 migration wave, alongside a spec comment describing a routing event being "lost mid-transition".

The commit that introduced it describes the patch as being for "a TestRoutingContext export needed by the stories" — that's inaccurate; TestRoutingContext was already a public export in stock 5.5.1, and the patch has only ever contained this one-line effect change. Upstreaming it so the patch can be dropped.

Verification

• npx jest — 129 passed, 28 suites, no regressions (three consecutive clean runs)
• npm run lint -- --fix — 0 errors
• npm run build — clean
• npm run api-extractor -- --local — public API surface unchanged

[Copilot]

Pull request overview

This PR fixes an order-dependent routing bug in buildRootComponent where non-slotted roots could miss the initial routing broadcast depending on JSX sibling order. It does so by moving the global broadcast subscription from a passive effect to a layout effect, ensuring all roots are subscribed before any passive-effect routing broadcasts run.

Changes:

• Subscribe roots to the global emitter in useLayoutEffect (instead of useEffect) to eliminate sibling-order dependence for initial routing events.
• Add a regression test that renders a routing root and a listener root in both sibling orders and asserts the listener receives the initial route event.
• Add an in-code rationale comment explaining the React effect ordering issue being addressed.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/xstateTree.tsx	Moves root broadcast subscription to layout effect to guarantee subscription precedes passive-effect broadcasts (e.g., initial routing).
src/tests/rootSubscribesBeforeBroadcast.spec.tsx	Adds a regression test covering both sibling orders to prevent reintroducing the missed-initial-route behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🎉 This PR is included in version 5.5.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀