@xmachines/docs 3.0.0 → 5.0.0

package/rfc/play.md

@@ -3,7 +3,7 @@
 **Status:** Living  
 **Version:** 1.1  
 **Scope:** Universal runtime interoperability and reference implementation  
-**Non-goals:** Persistence, transport protocols, alternative state engines, non-signal reactivity
+**Non-goals:** Persistence, transport protocols, alternative state engines, non-atom reactivity
 
 ---
 
@@ -11,7 +11,7 @@
 
 This RFC defines the **Universal Player Architecture** and its reference implementation. The architecture establishes a design pattern that strictly separates **Business Logic (The Actor)** from **Infrastructure (The Runtime Adapter and View)**.
 
-The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **Standardized Signals (TC39)** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
+The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
 
 ---
 
@@ -35,7 +35,7 @@ The reference implementation provides a modular monorepo that satisfies the arch
 
 ### 2.2 Communication Medium
 
-- **Signals (TC39 Proposal)**
+- **Atoms (`@xstate/store`)**
     - Used exclusively for Actor ↔ Adapter communication
     - Enables synchronous, glitch-free propagation
 
@@ -43,26 +43,29 @@ The reference implementation provides a modular monorepo that satisfies the arch
 
 ## 3. Invariants
 
-1. **Actor Authority**  
+This document DEFINES the identifier of each invariant. Every other document and every
+source comment cites the identifier from this list, and it invents none of its own.
+
+1. **INV-01 — Actor Authority**  
    The Actor is the final authority on state and route validity.
 
-2. **Strict Separation**  
+2. **INV-02 — Strict Separation**  
    Business logic never depends on runtime APIs or routing libraries.
 
-3. **Signal-Only Reactivity**  
-   All cross-boundary communication uses standardized Signals.
+3. **INV-03 — Atom-Only Reactivity**  
+   All cross-boundary communication uses atoms.
 
-4. **Passive Infrastructure**  
+4. **INV-04 — Passive Infrastructure**  
    Runtime Adapters do not enforce guards, validation, or business rules.
 
-5. **State-Driven Reset**  
+5. **INV-05 — State-Driven Reset**  
    Invalid external navigation is always overwritten by Actor-derived state.
 
 ---
 
 ## 4. Core Mechanisms
 
-### 4.1 Reactive Substrate (Signals)
+### 4.1 Reactive Substrate (Atoms)
 
 - **Push–Pull Model**  
   The Actor pushes state updates; Adapters and Views pull computed values lazily.
@@ -89,7 +92,7 @@ The Actor has zero knowledge of:
 ### 4.3 Infrastructure Layer (Runtime Adapter)
 
 - **Watcher (Output)**  
-  Observes the Actor's _Intended Route_ signal and updates the environment accordingly.
+  Observes the Actor's _Intended Route_ atom and updates the environment accordingly.
 
 - **Reflector (Input)**  
   Listens to environment events (e.g. back/forward navigation) and forwards them as intents to the Actor.
@@ -105,19 +108,35 @@ If an intent is rejected:
 
 ### 5.1 Core Layer
 
-#### 5.1.1 `@xmachines/play-signals`
+#### 5.1.1 `@xmachines/play-atom`
 
 **Role:** Reactive Substrate
 
-Wraps the TC39 Signals (Stage 1) polyfill. By isolating the reactive primitive within this package, the ecosystem is protected from specification churn while providing the ergonomic API surface required by the rest of the architecture.
+Re-exports the atom of `@xstate/store`, whose reactive core adapts the Alien Signals algorithm. By isolating the reactive primitive within this package, the ecosystem is protected from churn in the underlying library while providing the ergonomic API surface required by the rest of the architecture.
 
 **Exports:**
 
-- `Signal` — Re-exported namespace from `signal-polyfill`:
-    - `Signal.State` — Actor output snapshot
-    - `Signal.Computed` — Lazy, pull-based derivation of routes and views
-    - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
-- `watchSignal` — Convenience function: subscribes to a single signal with a one-shot watcher lifecycle and microtask batching; returns a cleanup function
+- `createAtom(value)` — The writable atom. It holds the Actor output snapshot, and the derived view
+- `createAtom(fn)` — The computed atom. It derives a route from the snapshot, and it memoizes the result
+- `createWritableAtom(value)` — The writable atom, with one signature. Use it when the value type is a type parameter: the overload pair of `createAtom` reads an unresolved conditional type as a possible function, and it returns a `ReadonlyAtom`
+- `createAsyncAtom(fn)` — The computed atom of a promise, with a `pending`, `done` and `error` state
+- `watchAtom(atom, onValue)` — Convenience function: subscribes to one atom, coalesces the notifications into one microtask, and returns a cleanup function
+- The types `Atom`, `ReadonlyAtom`, `Readable`, `BaseAtom`, `AnyAtom` and `AtomOptions`
+
+**One instance:** `@xstate/store` is a PEER dependency, and it must resolve to ONE copy. The library holds the active subscriber in a module variable, so two copies track no dependency across a package boundary. `tests/singleton-peers.test.ts` holds this rule true for the workspace.
+
+**Two properties that a reader has to know:**
+
+- A subscription EVALUATES a computed atom, and it does not merely notify. `@xstate/store` builds the subscription on an effect that reads the atom, so a computed atom with a subscriber is eager, and a derivation runs one time for each write of a dependency. A computed atom with NO subscriber stays lazy, and it derives when a reader calls `get()`.
+- The propagation is SYNCHRONOUS, inside the `set` of the atom that changed, and the library exposes no batching. A callback that throws therefore throws inside that `set`, and an observer of two atoms is evaluated between two writes.
+
+**Therefore the Actor writes ONE atom for each transition.** `state` is that atom. `currentRoute` and `currentView` are computed atoms over it, so one write reaches both in one propagation and the engine orders the evaluation. Two writes would flush two times, and an observer of `state` and `currentView` would read the new state beside the old view in between.
+
+**A derivation of the Actor reports through `onError`, keeps its last good value, and throws never.** `currentRoute` and `currentView` both follow this rule. A subscriber makes a computed atom eager, so the derivation runs inside the `set` of `state`, inside the state-engine subscription: a throw that left it would unwind into the event dispatch and break the transition for every other observer. The containment therefore belongs to the derivation, and not to each subscriber — a consumer that writes its own `watchAtom(actor.currentRoute, …)` is protected by the same rule that protects a router bridge.
+
+The rule covers the reactive path. A pure helper such as `deriveCurrentRoute` still throws, because it holds no error channel and no previous value; its callers decide. Construction is the other caller: an unbuildable `initialRoute` fails the construction, which is where a developer wants to see it.
+
+Infrastructure that runs HOST code from a subscription contains that code by the same reasoning: `useAtomEffect` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) catches a throw of the host callback and throws it again from a microtask.
 
 #### 5.1.2 `@xmachines/play`
 
@@ -130,24 +149,37 @@ Exports the minimal shared contracts that allow the Logic Engine and Infrastruct
 - `PlayEvent<TPayload>` — Generic intent event dispatched from Infrastructure to Actor. Any object with `{ readonly type: string }` plus optional typed payload fields.
 - `PlayError` — Structured error base with `scope` and `code` fields for consistent error handling across all `@xmachines/*` packages.
 
-> **Note:** Routing contracts (`RouterBridge`, `PlayRouteEvent`) live in `@xmachines/play-router`, not here. This keeps the core protocol package dependency-free.
+> **Note:** Routing contracts (`RouterBridge`, `PlayRouteEvent`) live in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), not here. This keeps the core protocol package dependency-free.
 
 #### 5.1.3 `@xmachines/play-actor`
 
 **Role:** Abstract Logic Engine
 
-Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `AbstractActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull signal contract**.
+Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `PlayActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull atom contract**.
 
 The base class requires only two abstract members: **reactive state** and **typed event dispatch**. Routing and view rendering are opt-in via separate interfaces, allowing actors to compose only the capabilities they need.
 
+**Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), beside the bridge that reads it, and `Viewable` and `PlaySpec` are in [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names the capability packages nowhere. The shape of each interface is unchanged.
+
 ```ts
 import { Actor, type AnyActorLogic, type EventObject } from "xstate";
-import type { Signal } from "@xmachines/play-signals";
+import type {
+	AnyAtom,
+	Atom,
+	AtomOptions,
+	BaseAtom,
+	Readable,
+	ReadonlyAtom,
+	createAsyncAtom,
+	createAtom,
+	createWritableAtom,
+	watchAtom,
+} from "@xmachines/play-atom";
 import type { Spec } from "@xmachines/json-render-core";
 
 // Optional capability: Routing
 export interface Routable {
-	readonly currentRoute: Signal.Computed<string | null>;
+	readonly currentRoute: ReadonlyAtom<string | null>;
 	readonly initialRoute: string | null;
 }
 
@@ -166,23 +198,23 @@ export interface PlaySpec extends Spec {
 }
 
 export interface Viewable {
-	readonly currentView: Signal.State<PlaySpec | null>;
+	readonly currentView: ReadonlyAtom<PlaySpec | null>;
 }
 
 // The Base Protocol — minimal contract
-export abstract class AbstractActor<
+export abstract class PlayActor<
 	TLogic extends AnyActorLogic,
 	TEvent extends EventObject = EventObject,
 > extends Actor<TLogic> {
 	// Reactive Output (Snapshot)
-	public abstract state: Signal.State<unknown>;
+	public abstract state: Atom<unknown>;
 
 	// Input Channel (typed for specific event shapes)
 	public abstract override send(event: TEvent): void;
 }
 ```
 
-**Design Rationale:** The original design placed `currentRoute`, `currentView`, and `catalog` directly on `AbstractActor`. The implementation extracted these into `Routable` and `Viewable` interfaces because:
+**Design Rationale:** The original design placed `currentRoute`, `currentView`, and `catalog` directly on `PlayActor`. The implementation extracted these into `Routable` and `Viewable` interfaces because:
 
 1. Not all actors need routing (e.g. embedded sub-actors)
 2. Not all actors need view rendering (e.g. background logic actors)
@@ -194,22 +226,22 @@ export abstract class AbstractActor<
 
 **Role:** Concrete Logic Adapter (XState v5)
 
-Wraps XState v5 to satisfy the `AbstractActor` contract. Provides the primary API for creating actors from state machine definitions.
+Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
 
 **Primary Exports:**
 
 - `definePlayer` — Factory builder: accepts a machine config, returns a factory function that creates `PlayerActor` instances
-- `PlayerActor` — Concrete class extending `AbstractActor` and implementing both `Routable` and `Viewable`
+- `PlayerActor` — Concrete class extending `PlayActor`. It carries state and send alone, and a capability mixin adds the rest
+- `compose`, `withRouting`, `withView` — The composition of the optional capabilities onto `PlayerActor`
 
 **Utility Exports:**
 
-- Guard combinators: `composeGuards`, `composeGuardsOr`, `negateGuard`, `hasContext`, `eventMatches`, `contextFieldMatches`
 - Route derivation: `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`, `formatPlayRouteTransitions`
 
 **Responsibilities:**
 
 - Derive `currentRoute` and `currentView` from active state node metadata
-- Manage signal lifecycle (create on start, dispose on stop)
+- Manage atom lifecycle (create on start, dispose on stop)
 - Support snapshot restore for resumable sessions
 - Provide XState DevTools compatibility
 
@@ -228,18 +260,22 @@ const definePlayer = <TMachine extends AnyStateMachine>(
 	return (input?, restore?) => new PlayerActor(machine, options, input, restore?.snapshot);
 };
 
-// PlayerActor composes all capabilities
+// PlayerActor carries the core protocol alone. It extends the actor class of XState
+// directly, and `PlayActor` is a contract that it implements.
 class PlayerActor<TMachine extends AnyStateMachine>
-	extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
-	implements Routable, Viewable
+	extends Actor<AnyActorLogic>
+	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
 {
-	public state: Signal.State<AnyMachineSnapshot>;
-	public currentRoute: Signal.Computed<string | null>;
-	public currentView: Signal.State<PlaySpec | null>;
-	public readonly initialRoute: string | null;
+	public state: Atom<SnapshotFrom<TMachine>>;
 }
+
+// A capability arrives through `compose`, and each one brings its own package
+const RoutedPlayer = compose(PlayerActor, withRouting, withView);
+// RoutedPlayer instances hold `currentRoute`, `initialRoute` and `currentView`
 ```
 
+**Design Rationale:** The RFC made `PlayerActor` implement both capabilities directly. The implementation split them into mixins, because a direct implementation made [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) and [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) hard dependencies of every actor. Both packages are optional peer dependencies now: `definePlayer({ machine })` installs neither, `withRouting` needs [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), and `withView` needs [`@xmachines/play-view`](../api/@xmachines/play-view/README.md).
+
 **Design Rationale:** The original design passed a `catalog` to `definePlayer` and returned `{ create, catalog }`. The implementation decoupled catalogs entirely — component schemas are defined via `@xmachines/json-render-core`'s `defineCatalog` and bound to renderers via `defineRegistry`, not to actors. This means a single actor can be rendered by different component libraries without change.
 
 ### 5.3 Router Layer
@@ -250,11 +286,20 @@ class PlayerActor<TMachine extends AnyStateMachine>
 
 Provides the complete routing infrastructure: route extraction from state machines, bidirectional route mapping, and the abstract `RouterBridgeBase` that all framework-specific router adapters extend.
 
+**Design Rationale:** The RFC put the whole of the routing in one package. The implementation split it at two boundaries, because a consumer paid for both halves and used one:
+
+- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
+- [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) holds the pattern LANGUAGE — one parse of the URLPattern pathname grammar, and the path that `buildPath` writes back from it. A parse is string work, so the package carries no URLPattern API and no polyfill. BOTH directions of the routing read it: the match of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) reads the parse, and the routing capability of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) reads the same parse to build a URL, so that package installs no matching machinery.
+- [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) holds the URL LAYER — the URLPattern API with its polyfill, a base path, a location splitter, and the params of a framework router. It reads [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) for the language and re-exports it whole. It knows no machine and no bridge.
+- [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
+
+The export lists below name the original layout. Each package README names what it holds now.
+
 **Protocol Exports:**
 
 - `RouterBridge` — Interface: `{ connect(): void; disconnect(): void }`
 - `PlayRouteEvent` — Routing event: `{ type: 'play.route'; to: string; params?; query?; match? }`
-- `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (signal watching, route synchronization, param/query extraction). Subclasses implement only three methods:
+- `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (atom watching, route synchronization, param/query extraction). Subclasses implement only three methods:
     - `navigateRouter(path)` — Push a path into the framework router
     - `watchRouterChanges()` — Subscribe to framework router navigation events
     - `unwatchRouterChanges()` — Unsubscribe from framework router events
@@ -266,7 +311,6 @@ Provides the complete routing infrastructure: route extraction from state machin
 - `extractMachineRoutes` — Build complete route tree from a machine definition
 - `buildRouteTree` — Construct hierarchical tree from flat route info
 - `createRouteMap` / `RouteMap` — Bidirectional path ↔ state ID resolution
-- `BaseRouteMap` / `BaseRouteMapping` — Shared base for adapter-specific route maps
 
 **Validation & Query Exports:**
 
@@ -284,41 +328,41 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 Each adapter extends `RouterBridgeBase` and implements the three abstract methods for its target router. All share the same architectural pattern:
 
-| Package                                 | Router          | Framework |
-| --------------------------------------- | --------------- | --------- |
-| `@xmachines/play-tanstack-react-router` | TanStack Router | React     |
-| `@xmachines/play-tanstack-solid-router` | TanStack Router | SolidJS   |
-| `@xmachines/play-react-router`          | React Router v7 | React     |
-| `@xmachines/play-vue-router`            | Vue Router 4/5  | Vue       |
-| `@xmachines/play-solid-router`          | SolidJS Router  | SolidJS   |
+| Package                                                                                           | Router           | Framework |
+| ------------------------------------------------------------------------------------------------- | ---------------- | --------- |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack Router  | React     |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Router  | SolidJS   |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8 | React     |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router 4/5   | Vue       |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router   | SolidJS   |
 
 **Runtime Adapter Responsibilities (all adapters):**
 
 - **Input (Reflector):** Listen to router navigation events, extract params/query, send `PlayRouteEvent` to Actor
-- **Output (Watcher):** Observe Actor's `currentRoute` signal, call `navigateRouter()` when it changes
+- **Output (Watcher):** Observe Actor's `currentRoute` atom, call `navigateRouter()` when it changes
 - **Reset:** If Actor rejects a navigation (guard failure), the adapter overwrites the URL bar to match Actor state
 
 ### 5.4 View Layer
 
 #### 5.4.1 View Renderers
 
-Each view renderer provides a `PlayRenderer` component that passively observes the actor's `currentView` signal and projects the JSON spec into framework-native components via `@json-render`.
+Each view renderer provides a `PlayRenderer` component that passively observes the actor's `currentView` atom and projects the JSON spec into framework-native components via `@json-render`.
 
-| Package                 | Framework   | JSON-Render Backend            |
-| ----------------------- | ----------- | ------------------------------ |
-| `@xmachines/play-react` | React       | `@xmachines/json-render-react` |
-| `@xmachines/play-vue`   | Vue 3       | `@xmachines/json-render-vue`   |
-| `@xmachines/play-solid` | SolidJS     | `@xmachines/json-render-solid` |
-| `@xmachines/play-dom`   | Vanilla DOM | `@xmachines/json-render-core`  |
+| Package                                                           | Framework   | JSON-Render Backend            |
+| ----------------------------------------------------------------- | ----------- | ------------------------------ |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | React       | `@xmachines/json-render-react` |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)     | Vue 3       | `@xmachines/json-render-vue`   |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) | SolidJS     | `@xmachines/json-render-solid` |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)     | Vanilla DOM | `@xmachines/json-render-core`  |
 
 **Shared Architecture (all renderers):**
 
-1. Subscribe to `actor.currentView` signal
+1. Subscribe to `actor.currentView` atom
 2. Resolve a `StateStore` (external or auto-created per view transition via `@xstate/store`)
 3. Wire `actions` prop to `actor.send()` via `ActionProvider`
 4. Render `spec` through the framework's `Renderer` with a `registry` (defined via `defineRegistry`)
 
-**`@xmachines/play-react` exports (representative):**
+**[`@xmachines/play-react`](../api/@xmachines/play-react/README.md) exports (representative):**
 
 ```ts
 // Batteries-included composite — standard entry point
@@ -327,7 +371,7 @@ Each view renderer provides a `PlayRenderer` component that passively observes t
 export { PlayUIProvider } from "./PlayUIProvider";
 export type { PlayUIProviderProps } from "./PlayUIProvider";
 
-// Escape-hatch primitive — owns actor lifecycle, signal bridge, ViewContext
+// Escape-hatch primitive — owns actor lifecycle, atom bridge, ViewContext
 // Props: actor, registryResult, store?, fallback?, onError?, onRenderError?, children (required)
 export { ActorProvider } from "./ActorProvider";
 export type { ActorProviderProps } from "./ActorProvider";
@@ -340,7 +384,7 @@ export const PlayRenderer: React.FC = () => {
 
 // Hooks
 export { usePlayView } from "./ActorProvider"; // returns ViewContextValue | null
-export { useSignalEffect } from "./useSignalEffect";
+export { useAtomEffect } from "./useAtomEffect";
 export { useActor } from "./useActor";
 
 // Error handling
@@ -358,7 +402,7 @@ export {
 } from "@xmachines/json-render-react";
 ```
 
-**Design Rationale:** `PlayRenderer` is now a **zero-prop leaf component** — it reads view context from the enclosing `ActorProvider` via `usePlayView()`. All mount-time concerns (actor bridging, signal subscription, store lifecycle, `onRenderError` injection) are centralised in `ActorProvider`. `PlayUIProvider` is the batteries-included composite that wraps `ActorProvider` + `JSONUIProvider` with a handler bridge. This mirrors the provider/renderer split in `@xmachines/json-render-*` and makes the separation of concerns explicit.
+**Design Rationale:** `PlayRenderer` is now a **zero-prop leaf component** — it reads view context from the enclosing `ActorProvider` via `usePlayView()`. All mount-time concerns (actor bridging, atom subscription, store lifecycle, `onRenderError` injection) are centralised in `ActorProvider`. `PlayUIProvider` is the batteries-included composite that wraps `ActorProvider` + `JSONUIProvider` with a handler bridge. This mirrors the provider/renderer split in `@xmachines/json-render-*` and makes the separation of concerns explicit.
 
 ### 5.5 Schema Layer (External)
 
@@ -431,7 +475,7 @@ import { createDashboard, machine } from "./features/dashboard/player";
 import { catalog } from "./catalog";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
 
 // 1. Create the actor
 const actor = createDashboard();