@xmachines/docs 3.0.0 → 5.0.0

package/contributing/architecture.md

@@ -1,20 +1,20 @@
 # Architecture
 
-XMachines Play implements the **Universal Player Architecture** — a layered, actor-authority design where XState machines are the single source of truth for routing, navigation, and view selection. Infrastructure (routers, renderers) is strictly passive: it observes actor signals and reflects them, never enforcing guards or making decisions.
+XMachines Play implements the **Universal Player Architecture** — a layered, actor-authority design where XState machines are the single source of truth for routing, navigation, and view selection. Infrastructure (routers, renderers) is strictly passive: it observes actor atoms and reflects them, never enforcing guards or making decisions.
 
 ## System Overview
 
-XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes TC39 Signals emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through TC39 Signals — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes atoms emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through atoms — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
 
 ## Architectural Invariants
 
-| ID     | Name                       | Rule                                                                                                                                     |
-| ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| INV-01 | **Actor Authority**        | Infrastructure proposes intents via `play.route` events; Actor decides via XState guards                                                 |
-| INV-02 | **Strict Separation**      | No direct dependencies between Actor and Infrastructure layers. `play-xstate` never imports UI frameworks or routing libraries           |
-| INV-03 | **Passive Infrastructure** | Infrastructure observes Actor signals, never controls state                                                                              |
-| INV-04 | **Signal-Only Reactivity** | All Actor→Infrastructure state changes flow through TC39 Signals (`Signal.State`, `Signal.Computed`). No subscriptions or event emitters |
-| INV-05 | **State-Driven Reset**     | Invalid external navigation is overwritten by Actor-derived state                                                                        |
+| ID     | Name                       | Rule                                                                                                                           |
+| ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| INV-01 | **Actor Authority**        | Infrastructure proposes intents via `play.route` events; Actor decides via XState guards                                       |
+| INV-02 | **Strict Separation**      | No direct dependencies between Actor and Infrastructure layers. `play-xstate` never imports UI frameworks or routing libraries |
+| INV-03 | **Atom-Only Reactivity**   | All Actor→Infrastructure state changes flow through atoms (`Atom`, `ReadonlyAtom`). No subscriptions or event emitters         |
+| INV-04 | **Passive Infrastructure** | Infrastructure observes Actor atoms, never controls state                                                                      |
+| INV-05 | **State-Driven Reset**     | Invalid external navigation is overwritten by Actor-derived state                                                              |
 
 ## Component Diagram
 
@@ -22,17 +22,22 @@ XMachines JS is the JavaScript/TypeScript reference implementation of the **Univ
 graph TD
     subgraph Layer0["Layer 0 — Protocol / Primitives"]
         play["@xmachines/play\n(PlayEvent, PlayError)"]
-        signals["@xmachines/play-signals\n(TC39 Signal, watchSignal)"]
+        atoms["@xmachines/play-atom\n(atoms, watchAtom)"]
         shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
     end
 
     subgraph Layer1["Layer 1 — Abstract Actor Base"]
-        actor["@xmachines/play-actor\n(AbstractActor, Routable, Viewable, PlaySpec)"]
+        actor["@xmachines/play-actor\n(PlayActor)"]
+    end
+
+    subgraph Layer2v["Layer 2 — The View Half"]
+        view["@xmachines/play-view\n(Viewable, PlaySpec, the view store lifecycle)"]
     end
 
     subgraph Layer2["Layer 2 — Concrete Implementations"]
-        xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, guards, routing)"]
-        router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, extractMachineRoutes)"]
+        xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, routing)"]
+        router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, Routable)"]
+        routerxstate["@xmachines/play-router/xstate\n(extractMachineRoutes, createRouteMap)"]
 
         subgraph Views["View Renderers"]
             react["@xmachines/play-react"]
@@ -55,12 +60,12 @@ graph TD
     end
 
     play --> actor
-    signals --> actor
+    atoms --> actor
     actor --> xstate
     actor --> router
     actor --> Views
-    signals --> xstate
-    signals --> router
+    atoms --> xstate
+    atoms --> router
     play --> xstate
     play --> router
     router --> RouterAdapters
@@ -72,24 +77,29 @@ graph TD
 | Package                                                                                           | Responsibility                                          | Key File                                                            |
 | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
 | [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | Core protocol types and error base class                | `packages/play/src/index.ts`                                        |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)                             | TC39 Signal polyfill isolation wrapper                  | `packages/play-signals/src/index.ts`                                |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `AbstractActor` base class + capability interfaces      | `packages/play-actor/src/abstract-actor.ts`                         |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | The atom primitives, isolated in one package            | `packages/play-atom/src/index.ts`                                   |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `PlayActor`, and nothing else                           | `packages/play-actor/src/play-actor.ts`                             |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `Viewable`, `PlaySpec`, the shared view half            | `packages/play-view/src/view-types.ts`                              |
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v5 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | Route extraction, `RouteMap`, `RouterBridgeBase`        | `packages/play-router/src/router-bridge-base.ts`                    |
+| [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md)                             | The route pattern language: one parse, and `buildPath`  | `packages/play-pattern/src/pattern-grammar.ts`                      |
+| [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | The URLPattern API, a base path, framework params       | `packages/play-url/src/url-pattern-utils.ts`                        |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `RouteMap`, `RouterBridgeBase`, the provider lifecycle  | `packages/play-router/src/router-bridge-base.ts`                    |
+| [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md)                        | Route extraction from an XState machine                 | `packages/play-router/src/xstate/extract-routes.ts`                 |
 | [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | React renderer: `ActorProvider`, `PlayRenderer`         | `packages/play-react/src/ActorProvider.tsx`                         |
 | [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | Vue 3 renderer: `ActorProvider.vue`, `PlayRenderer.vue` | `packages/play-vue/src/ActorProvider.vue`                           |
 | [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | SolidJS renderer                                        | `packages/play-solid/src/ActorProvider.tsx`                         |
 | [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | Svelte 5 renderer                                       | `packages/play-svelte/src/ActorProvider.svelte`                     |
 | [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | Vanilla DOM renderer                                    | `packages/play-dom/src/create-play-ui.ts`                           |
+| [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md)             | The framework-free TanStack bridge base                 | `packages/play-tanstack-router/src/tanstack-router-bridge-base.ts`  |
 | [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack React Router bridge                            | `packages/play-tanstack-react-router/src/tanstack-router-bridge.ts` |
 | [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack SolidJS Router bridge                          | `packages/play-tanstack-solid-router/src/solid-router-bridge.ts`    |
 | [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router 4/5 bridge                                   | `packages/play-vue-router/src/vue-router-bridge.ts`                 |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router v7 bridge                                  | `packages/play-react-router/src/react-router-bridge.ts`             |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8 bridge                                 | `packages/play-react-router/src/react-router-bridge.ts`             |
 | [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router bridge                                   | `packages/play-solid-router/src/solid-router-bridge.ts`             |
 | [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla DOM hash/history router bridge                  | `packages/play-dom-router/src/dom-router-bridge.ts`                 |
 | [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit router bridge                                 | `packages/play-sveltekit-router/src/sveltekit-router-bridge.ts`     |
 | [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router bridge                                | `packages/play-svelte-spa-router/src/svelte-spa-router-bridge.ts`   |
-| `@xmachines/shared`                                                                               | Shared configs: tsconfig, oxlint, oxfmt, vitest         | `packages/shared/config/`                                           |
+| [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | Shared configs: tsconfig, oxlint, oxfmt, vitest         | `packages/shared/config/`                                           |
 | `@xmachines/docs`                                                                                 | API docs and RFC documentation                          | `packages/docs/`                                                    |
 
 ## Data Flow
@@ -100,14 +110,19 @@ graph TD
 flowchart TD
     A["XState machine transition"]
     B["PlayerActor observes its own transitions"]
-    C["actor.state Signal.State updated — synchronous, no batching"]
-    D["actor.currentRoute Signal.Computed recomputes\nderives URL from meta.route + context.params"]
-    E["validateAndCacheView(snapshot)\nactor.currentView Signal.State updated"]
-    F["Framework signal watcher fires\nmicrotask"]
+    C["actor.state atom updated — the ONE write of the transition"]
+    D["actor.currentRoute computed atom recomputes\nderives URL from meta.route + context.params"]
+    E["actor.currentView computed atom recomputes\nderives the PlaySpec from meta.view"]
+    F["Framework atom subscription fires\nmicrotask"]
     G["ActorProvider reads actor.currentView.get()"]
     H["PlayRenderer renders via @xmachines/json-render-* Renderer"]
 
-    A --> B --> C --> D --> E --> F --> G --> H
+    A --> B --> C
+    C --> D
+    C --> E
+    D --> F
+    E --> F
+    F --> G --> H
 ```
 
 ### User Navigation (Browser URL → Actor)
@@ -121,7 +136,7 @@ flowchart TD
     E["buildPlayRouteEvent(path, routeMap)\nresolves stateId from URL via URLPattern"]
     F["actor.send({ type: 'play.route', to: '#stateId', params, query })"]
     G["XState machine guard evaluates transition"]
-    H["machine transitions → signals update\n→ URL bar updated"]
+    H["machine transitions → atoms update\n→ URL bar updated"]
     I["guard blocks → machine stays\n→ router re-syncs to actor's current route"]
 
     A --> B --> C --> D --> E --> F --> G
@@ -133,9 +148,9 @@ flowchart TD
 
 ```mermaid
 flowchart TD
-    A["actor.currentRoute Signal.Computed changes"]
-    B["RouterBridgeBase routeWatcher\nTC39 Signal.subtle.Watcher fires"]
-    C["watchSignal microtask queued\nneedsEnqueue dedup guard"]
+    A["actor.currentRoute computed atom changes"]
+    B["RouterBridgeBase routeWatcher\natom subscription fires"]
+    C["watchAtom microtask queued\nscheduled dedup guard"]
     D["syncRouterFromActor(route) called"]
     E["lastSyncedPath set\necho suppression — prevents circular callback"]
     F["navigateRouter(path)\ncalls framework router's navigate API"]
@@ -170,23 +185,23 @@ flowchart TD
     B["resolveViewMeta(meta)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
     C["snapshot.context\nprojected wholesale as the /context slice"]
     D["composePlayState(spec.state, slice)\nstate: { ...authored, context: slice }"]
-    E["reuseComposedState (in validateAndCacheView)\ncarry previous state reference when the slice is value-unchanged"]
-    F["Derived PlaySpec (with viewKey) set on currentView signal"]
+    E["reuseComposedState (in the currentView atom)\ncarry previous state reference when the slice is value-unchanged"]
+    F["Derived PlaySpec (with viewKey) is the value of the currentView atom"]
 
     A --> B --> C --> D --> E --> F
 ```
 
-**State signals on the actor:**
+**State atoms on the actor:**
 
-| Signal               | Type                               | Description                                                                                      |
-| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `actor.state`        | `Signal.State<AnyMachineSnapshot>` | XState snapshot; updated synchronously on active states only                                     |
-| `actor.currentRoute` | `Signal.Computed<string \| null>`  | Derived from `meta.route` + `context.params`; `null` when unroutable                             |
-| `actor.currentView`  | `Signal.State<PlaySpec \| null>`   | Set explicitly per-transition (not computed) to ensure watcher notifications on self-transitions |
+| Atom                 | Type                             | Description                                                                                                                                                                                                      |
+| -------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor.state`        | `Atom<AnyMachineSnapshot>`       | XState snapshot; the ONE write of a transition, on active states only                                                                                                                                            |
+| `actor.currentRoute` | `ReadonlyAtom<string \| null>`   | Derived from `meta.route` + `context.params`; `null` when unroutable. It carries `compare: () => false`, so EVERY transition notifies — a refused guard derives the same path, and the bridge must still hear it |
+| `actor.currentView`  | `ReadonlyAtom<PlaySpec \| null>` | Derived from `meta.view`; the `previous` value gates an emission, so an unchanged view keeps its reference                                                                                                       |
 
 ## Key Abstractions
 
-### [`PlayEvent<TPayload>`](../api/@xmachines/play/type-aliases/PlayEvent.md)
+### [`PlayEvent<TPayload>`](../api/@xmachines/play/index/type-aliases/PlayEvent.md)
 
 The minimal event contract for Actor communication: any object with a `readonly type: string` property. `TPayload` extends `Record<string, unknown>` for additional fields. Framework-agnostic; used directly by XState, router adapters, and domain logic. Part of [`@xmachines/play`](../api/@xmachines/play/README.md).
 
@@ -196,12 +211,12 @@ import type { PlayEvent } from "@xmachines/play";
 type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 ```
 
-### [`PlayError`](../api/@xmachines/play/classes/PlayError.md)
+### [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)
 
 Base class for all `@xmachines/*` typed runtime errors. Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 
 if (err instanceof RouterSyncError) {
@@ -209,27 +224,39 @@ if (err instanceof RouterSyncError) {
 }
 ```
 
-### [`AbstractActor<TLogic, TEvent>`](../api/@xmachines/play-actor/classes/AbstractActor.md)
+### [`PlayActor<TSnapshot, TEvent>`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
 
-Abstract base class extending XState `Actor`. Declares `public abstract state: Signal.State<unknown>` and `public abstract override send(event: TEvent): void`. Maintains XState ecosystem compatibility (devtools, inspection) while enforcing the signal protocol. Concrete implementations extend this (e.g. [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)).
+The actor contract, as an INTERFACE. It asks for two members: a reactive `state: Atom<TSnapshot>`, and a typed `send(event: TEvent): void`. It names no state machine library, so a consumer of the contract installs `xstate` never. An implementation satisfies it (e.g. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)).
 
-### [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md)
+### [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md)
 
-Optional capability interface. Exposes `currentRoute: Signal.Computed<string | null>` (derived URL path) and `readonly initialRoute: string | null` (machine's initial route, fixed at definition time). Router bridges consume this interface directly — they never depend on the concrete [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md).
+Optional capability interface. Exposes `currentRoute: ReadonlyAtom<string | null>` (derived URL path) and `readonly initialRoute: string | null` (machine's initial route, fixed at definition time). Router bridges consume this interface directly — they never depend on the concrete [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md).
 
-### [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md)
+### [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md)
 
-Optional capability interface. Exposes `currentView: Signal.State<PlaySpec | null>`. View renderers (`PlayRenderer`) consume this contract to resolve the current view description into UI without coupling to the framework or actor implementation.
+Optional capability interface. Exposes `currentView: ReadonlyAtom<PlaySpec | null>`. View renderers (`PlayRenderer`) consume this contract to resolve the current view description into UI without coupling to the framework or actor implementation.
 
-### [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)
+### [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)
 
 Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
 
-### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
+
+Concrete XState v5 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to atoms. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
+
+[`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) are OPTIONAL capabilities, and the class implements neither. Each one is a mixin behind its own entry point — [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) and [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) — and `compose` builds the class that an application needs:
+
+```typescript
+definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
+```
+
+The core imports neither capability, so an application that declares no route loads no routing code, and one that renders no view loads no view code and installs no json-render.
+
+**The composition order decides nothing.** `PlayerActor` writes ONE atom for each transition — `state` — and every capability that publishes a value DERIVES it with a computed atom over that one. The engine evaluates `currentRoute` and `currentView` from a single write, in topological order, so a router bridge sees a guard redirect and a renderer sees the view of the same snapshot whatever order `compose` applied.
 
-Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — and so XState's own `Actor`, receiving the machine in its constructor, so an instance IS the actor rather than a wrapper around one; implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Bridges its own subscription to TC39 Signals. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
+An earlier release wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there: two writes flushed two times, and an observer of `state` and `currentView` read the new state beside the old view in between. `onSnapshot` remains for a capability that must run an EFFECT on a transition, and an override still calls `super.onSnapshot()` first.
 
-### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/type-aliases/PlayerFactory.md)
+### [`definePlayer(config)`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/index/type-aliases/PlayerFactory.md)
 
 Factory creator. Each call constructs one `PlayerActor`, which is itself the XState actor and derives its own `initialRoute` from its pre-start snapshot. Restoring a snapshot is the exception: the default initial route can only come from XState's pure `initialTransition` helper, whose inert actor scope constructs a throwaway actor and evaluates the initial transition twice. Returns `(input?, restore?) => PlayerActor<TMachine>`.
 
@@ -241,7 +268,7 @@ const actor = createPlayer(); // or createPlayer(input) or createPlayer(undefine
 actor.start();
 ```
 
-### [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md)
+### [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md)
 
 Abstract base class capturing all common router bridge logic. Template Method pattern — subclasses implement exactly three abstract methods: `navigateRouter(path)`, `watchRouterChanges()`, `unwatchRouterChanges()`. Manages `isConnected`, `lastSyncedPath` (echo suppression), `isProcessingNavigation` (re-entrant guard redirect prevention), and `routeWatcher` lifecycle. Enforces one-bridge-per-actor via a module-level `WeakMap`.
 
@@ -259,11 +286,11 @@ class MyRouterBridge extends RouterBridgeBase {
 }
 ```
 
-### [`RouteMap`](../api/@xmachines/play-router/classes/RouteMap.md) / [`createRouteMap`](../api/@xmachines/play-router/functions/createRouteMap.md)
+### [`RouteMap`](../api/@xmachines/play-router/index/classes/RouteMap.md) / [`createRouteMap`](../api/@xmachines/play-router/xstate/functions/createRouteMap.md)
 
-Bidirectional `stateId ↔ URL path` lookup. [`createRouteMap(machine)`](../api/@xmachines/play-router/functions/createRouteMap.md) → [`RouteMap`](../api/@xmachines/play-router/classes/RouteMap.md). [`createRouteMapFromTree(routeTree)`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md) takes the output of [`extractMachineRoutes(machine)`](../api/@xmachines/play-router/functions/extractMachineRoutes.md) directly. Internally uses `URLPattern` for parameterized route matching (e.g. `/profile/:userId`).
+Bidirectional `stateId ↔ URL path` lookup. [`createRouteMap(machine)`](../api/@xmachines/play-router/xstate/functions/createRouteMap.md) of [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) → [`RouteMap`](../api/@xmachines/play-router/index/classes/RouteMap.md). [`createRouteMapFromTree(routeTree)`](../api/@xmachines/play-router/index/functions/createRouteMapFromTree.md) of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) takes the output of [`extractMachineRoutes(machine)`](../api/@xmachines/play-router/xstate/functions/extractMachineRoutes.md) directly. Both drop the synthetic root node of the tree, so neither map answers a state ID that the machine does not hold. The match of a parameterized route, for example `/profile/:userId`, uses `URLPattern` of [`@xmachines/play-url`](../api/@xmachines/play-url/README.md).
 
-### [`PlayRouteEvent`](../api/@xmachines/play-router/interfaces/PlayRouteEvent.md)
+### [`PlayRouteEvent`](../api/@xmachines/play-router/index/interfaces/PlayRouteEvent.md)
 
 Unified routing event sent by router adapters to the Actor.
 
@@ -277,11 +304,11 @@ interface PlayRouteEvent {
 }
 ```
 
-### [`watchSignal(signal, callback)`](../api/@xmachines/play-signals/functions/watchSignal.md)
+### [`watchAtom(atom, callback)`](../api/@xmachines/play-atom/functions/watchAtom.md)
 
-Subscribe to a single TC39 signal with microtask batching and memory-safe cleanup. Uses a one-shot `Signal.subtle.Watcher` lifecycle — re-arms after each notification. `disposed` flag guards post-cleanup callbacks; `needsEnqueue` deduplicates rapid synchronous signal changes. Returns a `() => void` cleanup function.
+Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It builds one `subscribe` for the life of the watch, so no code arms anything again. The `disposed` flag guards post-cleanup callbacks, and the `scheduled` guard deduplicates rapid synchronous atom changes. Returns a `Cleanup` function.
 
-### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
+### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
 Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition targets the matching state, guards on `event.to === "#stateId"`, and assigns `event.params` and `event.query` to context. Returns the same config type `T` — directly usable by `setup().createMachine()`.
 
@@ -291,26 +318,26 @@ All five view renderer packages follow an identical structural pattern:
 
 | Component        | Role                                                                                             |
 | ---------------- | ------------------------------------------------------------------------------------------------ |
-| `ActorProvider`  | Subscribes to `actor.currentView` signal; owns signal lifecycle; provides view context           |
+| `ActorProvider`  | Subscribes to the `actor.currentView` atom; owns the atom lifecycle; provides view context       |
 | `PlayUIProvider` | Convenience wrapper combining `ActorProvider` + framework's `JSONUIProvider`                     |
 | `PlayRenderer`   | Zero-prop leaf component; reads from context; delegates to `@xmachines/json-render-*` `Renderer` |
 | `useActor()`     | Hook/composable for accessing the raw actor in consuming components                              |
 
-**Framework-specific signal bridging:**
+**Framework-specific atom bridging:**
 
-| Package                                                             | Signal → Render mechanism                                                                                                                                                                                                                         |
+| Package                                                             | Atom → Render mechanism                                                                                                                                                                                                                           |
 | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | `useSignalEffect` → `useReducer` force-update                                                                                                                                                                                                     |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | `useAtomEffect` → `useReducer` force-update                                                                                                                                                                                                       |
 | [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | Vue reactivity bridge via `watchEffect` equivalent                                                                                                                                                                                                |
 | [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | SolidJS native reactive integration                                                                                                                                                                                                               |
 | [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | Svelte 5 runes (`$effect`) via `actor-context.svelte.ts`                                                                                                                                                                                          |
 | [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | Manual DOM updates via [`createPlayUI`](../api/@xmachines/play-dom/functions/createPlayUI.md) / [`createRenderer`](../api/@xmachines/play-dom/functions/createRenderer.md) / [`PlayRenderer`](../api/@xmachines/play-dom/classes/PlayRenderer.md) |
 
-Per-view component state is managed by `@xstate/store`: a fresh store atom is created per [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) transition (uncontrolled mode), or an external `store` prop is passed via `ActorProvider`/`PlayUIProvider` (controlled mode).
+Per-view component state is managed by `@xstate/store`: a fresh store atom is created per [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) transition (uncontrolled mode), or an external `store` prop is passed via `ActorProvider`/`PlayUIProvider` (controlled mode).
 
 ## Router Adapter Pattern
 
-All eight router adapter packages follow the Template Method pattern via [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md). Each adapter implements exactly three abstract methods:
+All eight router adapter packages follow the Template Method pattern via [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md). Each adapter implements exactly three abstract methods:
 
 ```typescript
 // How to tell the framework router to change URL
@@ -342,24 +369,25 @@ Each adapter also exports a framework-integrated provider component (e.g. `PlayR
 packages/
 ├── shared/                     # Zero-dependency shared configs (tsconfig, oxlint, oxfmt, vitest)
 ├── play/                       # Layer 0: Core protocol: PlayEvent, PlayError, assertNonNullable
-├── play-signals/               # Layer 0: TC39 Signal polyfill wrapper — all signal imports go here
-│   └── src/                    # Re-exports signal-polyfill; watchSignal utility
-├── play-actor/                 # Layer 1: AbstractActor base + Routable, Viewable, PlaySpec interfaces
+├── play-atom/                  # Layer 1: the atom primitives — all atom imports go here
+│   └── src/                    # Declares the atom contract, binds the engine; watchAtom utility
+├── play-actor/                 # Layer 2: the PlayActor contract — state and send, and nothing else
+├── play-pattern/               # Layer 1: the route pattern language — one parse, and the path it builds back
+├── play-url/                   # Layer 2: the URL layer — the URLPattern API, a base path, framework params
+├── play-view/                  # Layer 3: Viewable, PlaySpec, the view store lifecycle, the context projection
 │
-├── play-xstate/                # Layer 2: Concrete XState v5 actor: definePlayer, PlayerActor
+├── play-xstate/                # Layer 5: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
-│       ├── guards/                      # composeGuards, composeGuardsOr, negateGuard, hasContext...
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
 │       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
-├── play-router/                # Layer 2: Route extraction, bidirectional mapping, bridge base
+├── play-router/                # Layer 4: Route extraction, bidirectional mapping, bridge base
 │   └── src/
 │       ├── router-bridge-base.ts        # RouterBridgeBase (Template Method for all adapters)
-│       ├── extract-routes.ts            # extractMachineRoutes → RouteTree
 │       ├── base-route-map.ts            # RouteMap (bidirectional stateId ↔ path)
-│       ├── create-route-map.ts          # createRouteMap factory (URLPattern-based)
+│       ├── xstate/                      # the machine half — extractMachineRoutes, createRouteMap
 │       ├── router-sync.ts               # buildPlayRouteEvent, extractRouteParams, sanitizePathname
 │       └── types.ts                     # PlayRouteEvent, RouterBridge, RouteTree, WindowLike...
 │
@@ -371,7 +399,7 @@ packages/
 │
 ├── play-tanstack-react-router/ # Router adapter: TanStack Router (React)
 ├── play-tanstack-solid-router/ # Router adapter: TanStack Router (SolidJS)
-├── play-react-router/          # Router adapter: React Router v7
+├── play-react-router/          # Router adapter: React Router 7/8
 ├── play-vue-router/            # Router adapter: Vue Router 4/5
 ├── play-solid-router/          # Router adapter: SolidJS Router
 ├── play-svelte-spa-router/     # Router adapter: Svelte SPA Router
@@ -398,56 +426,39 @@ packages/<name>/
 
 ## TypeScript Build Graph
 
-The monorepo uses **TypeScript composite project references** (`"composite": true` per package) for a correct, incremental, dependency-ordered build. The root `tsconfig.json` lists all packages in layer order — leaves first, dependents last. `tsc --build` at the root resolves the full dependency graph automatically.
+The monorepo uses **TypeScript composite project references** (`"composite": true` per package) for a correct, incremental, dependency-ordered build. The root `tsconfig.json` lists every package in layer order — leaves first, dependents last — and it is the ONLY build order of the workspace. `tsc --build` at the root reads that array and resolves the graph.
 
-```mermaid
-flowchart LR
-    subgraph L0["Layer 0 — no internal deps"]
-        ps[play-signals]
-        p[play]
-        d[docs]
-    end
-    subgraph L1["Layer 1 — depends on L0"]
-        pa[play-actor]
-    end
-    subgraph L2["Layer 2 — depends on L0 + L1"]
-        pr[play-router]
-        pdr[play-dom-router]
-        psk[play-sveltekit-router]
-        px[play-xstate]
-        prea[play-react]
-        pv[play-vue]
-        pso[play-solid]
-        psv[play-svelte]
-        pdo[play-dom]
-        ptsr[play-tanstack-react-router]
-        pvr[play-vue-router]
-        psor[play-solid-router]
-        pssr[play-svelte-spa-router]
-        ptss[play-tanstack-solid-router]
-    end
-    subgraph L3["Layer 3 — examples / play-react-router"]
-        ex["play-react-router\nplay-*/examples/demo"]
-    end
+**The layer table and the diagram live in [development.md](development.md#build-layers).** They stood here too, and the copy drifted: it kept the numbers of an earlier release, so a reader who added a package placed it in the wrong block of the root array. One home for the question, as for the `references` arrays that the root file replaced.
 
-    L0 --> L1 --> L2 --> L3
-```
+Two facts about the graph belong to this document, because they are architecture and not build order:
+
+- **The routers read NO view package.** `play-router` and the eight adapters name `play-view` and the five renderers in no manifest. A consumer that routes and renders nothing of its own therefore installs no json-render.
+- **The renderers read no router.** The two halves meet in the application alone, which is INV-02.
 
-With `declarationMap: true` in the base tsconfig (from `@xmachines/shared/tsconfig`), IDE "Go to Definition" jumps to TypeScript source files rather than compiled `.d.ts` files, and refactoring works correctly across package boundaries without requiring a build step.
+With `declarationMap: true` in the base tsconfig (from [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md)), IDE "Go to Definition" jumps to TypeScript source files rather than compiled `.d.ts` files, and refactoring works correctly across package boundaries without requiring a build step.
 
 **Dependency rules:**
 
-| Layer                                           | May import from                                     | Must not import from             |
-| ----------------------------------------------- | --------------------------------------------------- | -------------------------------- |
-| Protocol (`play`, `play-signals`, `play-actor`) | External libs only                                  | Any other `@xmachines/*` package |
-| Actor logic (`play-xstate`)                     | Protocol layer                                      | View renderers, router adapters  |
-| Router infrastructure (`play-router`)           | Protocol layer, `@statelyai/graph`                  | View renderers                   |
-| Router adapters (`play-*-router`)               | `play-router`, protocol layer, framework router lib | Other view renderers             |
-| View renderers (`play-*`)                       | Protocol layer, `@xmachines/json-render-*`          | Router adapters                  |
+The **protocol layer** is `play`, `play-atom` and `play-actor`. The three form a chain — `play-atom` reads `play`, and `play-actor` reads `play-atom` — and none of them reads a package below.
+
+| Layer                                 | May import from                                         | Must not import from             |
+| ------------------------------------- | ------------------------------------------------------- | -------------------------------- |
+| Protocol (`play`)                     | External libs only                                      | Any other `@xmachines/*` package |
+| Protocol (`play-atom`)                | `play`, `@xstate/store`                                 | Any other `@xmachines/*` package |
+| Protocol (`play-actor`)               | `play`, `play-atom`                                     | Any other `@xmachines/*` package |
+| Pattern language (`play-pattern`)     | External libs only                                      | Any other `@xmachines/*` package |
+| URL layer (`play-url`)                | Protocol layer, `play-pattern`, `urlpattern-polyfill`   | Any other `@xmachines/*` package |
+| View half (`play-view`)               | Protocol layer, `@xmachines/json-render-core`           | Router adapters, framework code  |
+| Actor logic (`play-xstate`)           | Protocol layer, `play-pattern`, `xstate`                | View renderers, router adapters  |
+| Router infrastructure (`play-router`) | Protocol layer, `play-url`, `@statelyai/graph`          | View renderers                   |
+| Router adapters (`play-*-router`)     | `play-router`, protocol layer, framework router lib     | View renderers                   |
+| View renderers (`play-*`)             | Protocol layer, `play-view`, `@xmachines/json-render-*` | Router adapters                  |
+
+`play-view` and `play-router` are OPTIONAL peer dependencies of `play-xstate`, because the two capability subpaths carry them: [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) names the first and [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) names the second. The core entry point imports neither.
 
 ## Error Handling
 
-All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/classes/PlayError.md) and carry two stable fields:
+All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md) and carry two stable fields:
 
 - `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
 - `code` — a stable machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
@@ -456,48 +467,46 @@ All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/classes/Pl
 
 ```mermaid
 flowchart TD
-    PE["PlayError\n@xmachines/play"]
+    PE["PlayError\n@xmachines/play/errors"]
     PE --> NNE["NonNullableError\nPLAY_NON_NULLABLE"]
     PE --> RSE["RouterSyncError\nPLAY_ROUTER_SYNC_FAILED"]
-    PE --> UPE["URLPatternUnavailableError\nPLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE"]
     PE --> DBE["DuplicateBridgeError\nPLAY_ROUTER_DUPLICATE_BRIDGE"]
     PE --> IEE["InvalidEventError\nPLAY_XSTATE_INVALID_EVENT"]
     PE --> IME["InvalidMachineError\nPLAY_XSTATE_INVALID_MACHINE"]
     PE --> MRP["MissingRouteParamError\nPLAY_XSTATE_ROUTE_PARAM_MISSING"]
+    PE --> IRP["InvalidRouteParamError\nPLAY_XSTATE_ROUTE_PARAM_INVALID"]
     PE --> MSI["MissingStateIdError\nPLAY_XSTATE_MISSING_STATE_ID"]
-    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT\n(deprecated — never thrown)"]
     PE --> IRE["InvalidRouteMetadataError\nPLAY_XSTATE_INVALID_ROUTE_METADATA"]
     PE --> ATN["ActorThrewNonErrorError\nPLAY_XSTATE_NON_ERROR_THROWN"]
-    PE --> EGA["EmptyGuardArrayError\nPLAY_XSTATE_EMPTY_GUARD_ARRAY"]
 ```
 
 Package-specific errors are exported from `./errors` subpath imports:
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 import { InvalidEventError } from "@xmachines/play-xstate/errors";
 ```
 
 **Error behavior by case:**
 
-| Error                        | Package       | Behavior                                                                                   |
-| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
-| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                  |
-| `MissingQueryContextError`   | `play-xstate` | Deprecated — never thrown; exported only so existing `instanceof` handlers keep compiling  |
-| `ActorThrewNonErrorError`    | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause` |
-| `EmptyGuardArrayError`       | `play-xstate` | Structural programmer error — `composeGuards`/`composeGuardsOr` called with `[]`           |
-| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                 |
-| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                  |
-| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                        |
-| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained  |
+| Error                     | Package       | Behavior                                                                                                                                                            |
+| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MissingRouteParamError`  | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                                                                                           |
+| `InvalidRouteParamError`  | `play-xstate` | Permanent — `deriveCurrentRoute` passes it on: `currentRoute` reports it through `onError` and keeps its last route, and `initialRoute` throws from the constructor |
+| `ActorThrewNonErrorError` | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause`                                                                          |
+| `RouterSyncError`         | `play-router` | Wraps router sync failures                                                                                                                                          |
+| `DuplicateBridgeError`    | `play-router` | Two bridges registered for the same actor                                                                                                                           |
+| View errors               | `play-xstate` | Caught in the `currentView` atom; forwarded to `onError` hook; last valid view retained                                                                             |
 
 ## Application Bootstrap (React example)
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { createRouteMapFromTree, PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 
@@ -530,8 +539,8 @@ const machine = setup({}).createMachine(machineConfig);
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 
-// 3. Create player factory and start actor
-const createPlayer = definePlayer({ machine });
+// 3. Create player factory and start actor — the providers need BOTH capabilities
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
 const actor = createPlayer();
 actor.start();
 
@@ -552,53 +561,53 @@ function App() {
 
 ## Anti-Patterns
 
-### Importing `signal-polyfill` directly
+### Importing `@xstate/store` directly
 
 ```typescript
-// ❌ Wrong — bypasses the TC39 Signal isolation layer
-import { Signal } from "signal-polyfill";
+// ❌ Wrong — bypasses the atom isolation layer, and names the engine in your own .d.ts
+import { createAtom } from "@xstate/store";
 
-// ✅ Correct — all signal imports go through play-signals
-import { Signal } from "@xmachines/play-signals";
+// ✅ Correct — all atom imports go through play-atom
+import { createAtom } from "@xmachines/play-atom";
 ```
 
 ### Using framework state for business logic
 
 ```typescript
-// ❌ Wrong — violates INV-04 (Signal-Only Reactivity) and INV-02 (Passive Infrastructure)
+// ❌ Wrong — violates INV-03 (Atom-Only Reactivity) and INV-04 (Passive Infrastructure)
 const [currentUser, setCurrentUser] = useState(null);
 
-// ✅ Correct — observe the actor signal directly
+// ✅ Correct — observe the actor atom directly
 const currentUser = useActorSelector(actor, (s) => s.context.currentUser);
 ```
 
 ### Calling `navigateRouter` inside `watchRouterChanges`
 
-Calling `navigateRouter()` before updating `lastSyncedPath` inside the `watchRouterChanges` callback causes an echo loop. The router navigation fires the watcher again, which sends a duplicate `play.route` event. Always update `lastSyncedPath` before calling `navigateRouter()` — see [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md) source at `packages/play-router/src/router-bridge-base.ts`.
+Calling `navigateRouter()` before updating `lastSyncedPath` inside the `watchRouterChanges` callback causes an echo loop. The router navigation fires the watcher again, which sends a duplicate `play.route` event. Always update `lastSyncedPath` before calling `navigateRouter()` — see [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md) source at `packages/play-router/src/router-bridge-base.ts`.
 
 ### Skipping `sanitizePathname` in custom bridge implementations
 
-Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()` and process pathnames directly skip the length/content guards that protect the route-map lookup from malformed or oversized paths. Always call [`sanitizePathname(path)`](../api/@xmachines/play-router/functions/sanitizePathname.md) before processing.
+Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()` and process pathnames directly skip the length/content guards that protect the route-map lookup from malformed or oversized paths. Always call [`sanitizePathname(path)`](../api/@xmachines/play-router/index/functions/sanitizePathname.md) before processing.
 
 ## Cross-Cutting Concerns
 
-**Circular update prevention:** `lastSyncedPath` in [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md) provides echo suppression for the actor→router direction; `isProcessingNavigation` flag guards against re-entrant guard-redirect loops in `syncActorFromRouter`. `needsEnqueue` in [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) deduplicates rapid synchronous signal changes via microtask batching.
+**Circular update prevention:** `lastSyncedPath` in [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md) provides echo suppression for the actor→router direction; `isProcessingNavigation` flag guards against re-entrant guard-redirect loops in `syncActorFromRouter`. `scheduled` in [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md) deduplicates rapid synchronous atom changes via microtask coalescing.
 
-**SSR / test injection:** [`WindowLike`](../api/@xmachines/play-router/interfaces/WindowLike.md) and [`LocationLike`](../api/@xmachines/play-router/interfaces/LocationLike.md) structural interfaces in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) allow injecting mock objects in router adapters, enabling testing without a real browser environment.
+**SSR / test injection:** [`WindowLike`](../api/@xmachines/play-router/index/interfaces/WindowLike.md) and [`LocationLike`](../api/@xmachines/play-router/index/interfaces/LocationLike.md) structural interfaces in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) allow injecting mock objects in router adapters, enabling testing without a real browser environment.
 
-**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. A renderer writes to `console.error` in ONE case: it contained a failure, and no handler of the host receives that failure. Such a failure is the one result that nobody can debug. Give `onError` to send the failure of a view to your own observability tool instead.
+**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. A renderer writes to `console.error` in ONE case: it contained a failure, and no handler of the host receives that failure. Such a failure is the one result that nobody can debug. Give `onError` to send the failure of a view to your own observability tool instead.
 
 Five paths reach that case. The host gives no `onError` prop. The handler of the host throws, or the producer of the `fallback` throws, or a release of the caller throws — each of those reports the failure of the HOST, which no handler of the host receives. `ActorProvider` of play-vue stops a second report of one error, and `onError` stays silent there on purpose, because the four other renderers see such an error never.
 
-Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of `@xmachines/play-actor` names a `/context` projection that it cannot derive, one time for each spec; `@xmachines/play-xstate` names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and `@xmachines/play-router` names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
+Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) names a `/context` projection that it cannot derive, one time for each spec; [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
 
 **Authentication:** Not in scope. Enforced via XState guards on `play.route` transitions. The guard evaluates machine `context` (e.g., `isLoggedIn`) before permitting navigation. No library-level auth primitives — the machine defines all access control.
 
-**TC39 Signal isolation:** All signal imports go through [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md), which re-exports the `signal-polyfill` reference implementation. This isolates the codebase from Stage-1 API churn — a polyfill version upgrade or API change requires editing only one package.
+**Atom isolation:** All atom imports go through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md), which re-exports the atom of `@xstate/store`. This isolates the codebase from churn in that library — a version upgrade or API change requires editing only one package.
 
 **Global state:** An `activeBridges` WeakMap at module level in `packages/play-router/src/router-bridge-base.ts` prevents duplicate bridges per actor. This is the only module-level mutable state in the library.
 
-**Threading:** Single-threaded event loop. No worker threads. XState actor subscription callbacks fire synchronously in `send()`. Signal updates are synchronous to ensure router bridges see guard redirects immediately.
+**Threading:** Single-threaded event loop. No worker threads. XState actor subscription callbacks fire synchronously in `send()`. Atom updates are synchronous to ensure router bridges see guard redirects immediately.
 
 ---