@xmachines/docs 4.0.0 → 5.0.0

package/guides/routing.md

@@ -19,11 +19,11 @@ The first direction needs a matcher, and every router writes its own. Express us
 
 `URLPattern` is the WHATWG standard for this, its syntax comes from `path-to-regexp`, and it is a superset of it. XMachines takes it as the pattern language, and it reads the whole of it.
 
-This is the same decision that [`@xmachines/play-signals`](signals.md) makes for reactivity: one standard, isolated behind one module, present on every runtime. There is no `SignalsUnavailableError`, because the polyfill makes the question impossible to ask, and there is no URLPattern availability error for the same reason.
+This is the same decision that [`@xmachines/play-atom`](atoms.md) makes for reactivity: one primitive, isolated behind one module, present on every runtime. There is no `AtomsUnavailableError`, because one package holds the reactive primitive and every consumer reads it from there, and there is no URLPattern availability error for the same reason.
 
 ### The API is always present
 
-`@xmachines/play-router` carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
+[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
 
 The native API arrived in Chrome 95, in Firefox 142 and in Safari 26. The browser floor of this workspace is Chrome 110, Firefox 115 and Safari 16.4. Chrome carries the API at that floor, and Firefox and Safari carry it far above it, so a Firefox or a Safari at the floor runs the polyfill. `test/url-pattern-parity.test.ts` measures the two implementations against each other, form by form. They agree on every form of the grammar, and they disagree about one shape that no bridge can produce — see the prefix rule below.
 
@@ -67,40 +67,60 @@ const machine = createMachine({
 
 ### Which forms work in which direction
 
-The table above is what the route map MATCHES. The two directions are not the same size
-today, and a route that uses only the inbound half stops the URL silently.
-
-| Form                          | URL to state | state to URL                                                           |
-| ----------------------------- | ------------ | ---------------------------------------------------------------------- |
-| a literal, `:name`, `:name?`  | yes          | yes                                                                    |
-| `:name*`                      | yes          | **no** — the `*` stops the push, and the URL does not move             |
-| `:name+`                      | yes          | **no** — the `+` reaches the URL, and a value with a `/` is encoded    |
-| `{…}`                         | yes          | **no** — the braces reach the URL                                      |
-| `:name(\d+)`, `(\d+)`         | yes          | **no** — the constraint reaches the URL, or it stops the push          |
-| `*`                           | yes          | **no** — the `*` stops the push, and the URL does not move             |
-| `:cat-id`, a hyphen in a name | yes          | **no** — the substitution throws, and the URL stops                    |
-| an escape, `\+` and `\(`      | yes          | yes — the bridge resolves the escape before it pushes                  |
-| an escape, `\:`               | yes          | **no** — the substitution reads the escaped `:` as a param, and throws |
-
-`buildRouteUrl` of `@xmachines/play-xstate` performs the outbound half, and it reads
-`:name` and `:name?` alone. A state whose route uses another form derives a URL that its
-own route matches never — or no URL at all, because `deriveCurrentRoute` catches the
-`MissingRouteParamError` and answers `null`.
-
-**Declare a route with a literal, `:name`, `:name?` and an escape until the outbound half
-reads the whole grammar.** The remaining forms are safe for a route that the machine never
-navigates TO, such as a catch-all that only receives a deep link. Issue #16 closes the
-difference.
-
-A constraint fails in one of two ways, and which one depends on a single character. The
-derived path carries the constraint whole — `/v/:major(\d+)` with `{ major: "2" }` gives
-`/v/2(\d+)` — and the bridge reads a path that holds a BACKSLASH through the grammar. It
-reads `(\d+)` as a param there, so the route resolves to no one path and the push stops.
-A constraint with no backslash, such as `([0-9]+)`, reaches the address bar as it stands.
-
-`buildRouteUrl` leaves an escape as the template writes it, and the bridge resolves it
-before the push. The actor route carries `/tags/c\+\+`, and the address bar receives
-`/tags/c++`, which is the path that the route matches.
+Both directions read ONE parse. `parsePattern` of
+[`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) answers the match,
+and `buildPath` of the same package walks the same parts back into a path.
+[`@xmachines/play-url`](../api/@xmachines/play-url/README.md) re-exports both, so the
+match reads them from there. A form that the route map matches therefore derives a URL,
+with the exceptions that the table names.
+
+| Form                             | URL to state | state to URL                                                   |
+| -------------------------------- | ------------ | -------------------------------------------------------------- |
+| a literal, `:name`, `:name?`     | yes          | yes                                                            |
+| `:name*`                         | yes          | yes — the value keeps each `/` that it carries                 |
+| `:name+`                         | yes          | yes — the context must hold a value                            |
+| `{…}`                            | yes          | yes — an optional group with no value goes away                |
+| `:name(\d+)`                     | yes          | yes — the build drops the constraint, and it tests nothing     |
+| `*`, `(\d+)`, an anonymous param | yes          | **no** — the param has no name, so no value can fill it        |
+| `:cat-id`, a hyphen in a name    | yes          | yes                                                            |
+| an escape, `\+`, `\(`, `\:`      | yes          | yes for `\+` and `\(` — `\:` derives a path the bridge refuses |
+
+`buildRouteUrl` of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)
+performs the outbound half. It throws `MissingRouteParamError` when a part needs a value
+that the context has not, and `deriveCurrentRoute` answers `null` for that error — so the
+address bar waits for the next snapshot that carries the value.
+
+It throws `InvalidRouteParamError` when a param carries a dot segment: `.`, `..`, or any
+percent-encoding of the two. A URL parser resolves such a segment away BEFORE it decodes
+the escapes, so the derived path is one that the route matches never. `deriveCurrentRoute`
+passes that error on, because the value corrects itself never: the derivation of
+`currentRoute` reports it through `onError` of the actor and keeps the last route, and
+`initialRoute` throws from the constructor. Check a param value that carries a name from a
+user before the machine puts it in the context.
+
+**An anonymous param is the one form that derives no URL.** URLPattern numbers such a
+group from `0`, and this library reports that name to no machine, so a machine can put no
+value under it. A route of this shape is correct for a state that only RECEIVES a deep
+link, such as a catch-all. Give the param a name when the machine navigates to it.
+
+**A constraint describes a value, and the build tests no value against it.** The derived
+path carries the value alone — `/page/:number(\d+)` with `{ number: "12" }` gives
+`/page/12` — so a value that the constraint refuses derives a path that the route matches
+never. The machine owns the value.
+
+A param that carries `*` or `+` matches across a separator, so its value holds a path and
+not one segment. The build encodes each segment of such a value and it keeps the `/`
+between them: `/files/:path*` with `{ path: "a/b" }` gives `/files/a/b`.
+
+The build resolves every escape, so the derived path carries the character and not the
+backslash that protects it. `/tags/c\+\+` derives `/tags/c++`, which is the path that the
+route matches.
+
+**An escaped `:` is the one escape that stops at the bridge.** The build derives
+`/time/10:30` for `/time/10\:30`, and the route matches that path — but a bridge refuses
+to push a path that holds a `:`, because a `:` in a CONCRETE path marks a param that
+nothing substituted. `resolveNavigationPath` therefore answers `null`, and the address bar
+follows that state never. Write `%3A` instead, as the section below prescribes.
 
 ### A literal that the grammar would read
 
@@ -120,7 +140,7 @@ and the paragraphs below give the form to write for each.
 /a%3Fb               matches /a?b
 ```
 
-**An escaped `:` matches, and it derives no URL.** `substituteParams` of `buildRouteUrl` reads `:30` of `/time/10\:30` as a param placeholder, finds no value for the name `30`, and throws `MissingRouteParamError` — which `deriveCurrentRoute` answers with `null`, so the address bar follows that state never. `\+` and `\(` carry no such risk, because neither character starts a param name. Write `%3A` instead: `/time/10%3A30` is an ordinary literal path, and both halves read it. Issue #16 closes the difference.
+**An escaped `:` matches, and it reaches no address bar.** The build resolves the escape, so `/time/10\:30` derives `/time/10:30`, which is the path that the route matches — but a bridge refuses a concrete path that holds a `:`, because that character marks a param that nothing substituted. Write `%3A` instead: `/time/10%3A30` is an ordinary literal path, and both halves read it end to end.
 
 A `?` has no literal form, and the escape does not give it one. A URL pathname ends at its first `?`, so `getStateIdByPath` cuts every location there. The route `/a\?b` compiles with no fault, and no location reaches it. Write `%3F` instead: `/a%3Fb` is an ordinary literal path, and it resolves.
 
@@ -198,7 +218,7 @@ A machine can own the whole router, or it can sit under a mount. `basePath` is t
 
 ### 3. `connect()` and `disconnect()` come in a pair, and one actor takes one bridge
 
-A bridge installs a signal watcher on the actor and a subscription on the router. Neither releases itself.
+A bridge installs an atom subscription on the actor and a subscription on the router. Neither releases itself.
 
 - Call `disconnect()` from the teardown of your component: `useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid.
 - A second `connect()` on an actor that already has a bridge throws `DuplicateBridgeError`. The actor takes one bridge, so that two bridges cannot drive it in opposite directions.
@@ -226,19 +246,19 @@ Two matchers that disagree is also a worse failure than one dependency. The matc
 
 ## Summary
 
-| Question                                  | Answer                                                          |
-| ----------------------------------------- | --------------------------------------------------------------- |
-| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names  |
-| Do I install a polyfill?                  | No. `@xmachines/play-router` carries one                        |
-| Which side turns a URL into a state?      | XMachines, in every adapter                                     |
-| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                            |
-| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name |
-| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component   |
+| Question                                  | Answer                                                                              |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- |
+| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names                      |
+| Do I install a polyfill?                  | No. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries one |
+| Which side turns a URL into a state?      | XMachines, in every adapter                                                         |
+| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                                                |
+| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name                     |
+| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component                       |
 
 ## See also
 
 - [Understanding State Machines](state-machines.md) — how `meta.route` reaches the route map
-- [Understanding TC39 Signals](signals.md) — the same decision, made for reactivity
+- [Understanding Atoms](atoms.md) — the same decision, made for reactivity
 - [Multi-router integration](../examples/multi-router-integration.md) — the provider pattern and `basePath`, end to end
 - [Routing patterns](../examples/routing-patterns.md) — worked route maps
 - [@xmachines/play-router](../api/@xmachines/play-router/README.md) — API reference

package/guides/state-machines.md

@@ -120,7 +120,7 @@ const appMachine = setup({/* ... */}).createMachine({
 });
 ```
 
-`meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
+`meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `ReadonlyAtom`) derives this path and emits it. The router bridge reads it and updates the URL.
 
 `meta.view` is a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
 
@@ -234,7 +234,7 @@ actions: {
 },
 ```
 
-Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
+Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via atoms — only the derived atoms (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a computed atom to the actor that derives from `actor.state`.
 
 ---
 
@@ -270,14 +270,14 @@ actor.start();
 | Switch on URL path in component                       | `meta.route` on state nodes                  | Routing intent lives with the state that owns it            |
 | `if (user.role === "admin")` scattered in components  | Guards on transitions                        | Auth logic is co-located with the transitions it governs    |
 | `useEffect` on route changes to decide what to render | `meta.view` on state nodes                   | View structure is declared alongside the state that owns it |
-| Shared mutable state across components                | Context + signals                            | Mutations are explicit, traceable, and test-covered         |
+| Shared mutable state across components                | Context + atoms                              | Mutations are explicit, traceable, and test-covered         |
 
 ---
 
 ## See also
 
 - [Understanding the Actor Model](actor-model.md) — how the machine definition becomes a live actor
-- [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
+- [Understanding Atoms](atoms.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), and the routing utilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -56,8 +56,8 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^7.0.1",
     "@types/node": "^26.6.2",
-    "oxfmt": "^0.68.0",
-    "oxlint": "^1.83.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.13.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,26 +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 `PlayActor` 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` 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`, beside the bridge that reads it, and `Viewable` and `PlaySpec` are in `@xmachines/play-view`, beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and `@xmachines/play-actor` names the capability packages nowhere. The shape of each interface is unchanged.
+**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;
 }
 
@@ -168,7 +198,7 @@ export interface PlaySpec extends Spec {
 }
 
 export interface Viewable {
-	readonly currentView: Signal.State<PlaySpec | null>;
+	readonly currentView: ReadonlyAtom<PlaySpec | null>;
 }
 
 // The Base Protocol — minimal contract
@@ -177,7 +207,7 @@ export abstract class PlayActor<
 	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;
@@ -211,7 +241,7 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 **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
 
@@ -236,7 +266,7 @@ class PlayerActor<TMachine extends AnyStateMachine>
 	extends Actor<AnyActorLogic>
 	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
 {
-	public state: Signal.State<SnapshotFrom<TMachine>>;
+	public state: Atom<SnapshotFrom<TMachine>>;
 }
 
 // A capability arrives through `compose`, and each one brings its own package
@@ -244,7 +274,7 @@ 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` and `@xmachines/play-view` hard dependencies of every actor. Both packages are optional peer dependencies now: `definePlayer({ machine })` installs neither, `withRouting` needs `@xmachines/play-router`, and `withView` needs `@xmachines/play-view`.
+**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.
 
@@ -258,9 +288,10 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 **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` holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
-- `@xmachines/play-url` holds the URL language — the URLPattern grammar, a base path, and the params of a framework router. It knows no machine and no bridge, and BOTH directions of the routing read it.
-- `@xmachines/play-router` keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
+- [`@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.
 
@@ -268,7 +299,7 @@ The export lists below name the original layout. Each package README names what
 
 - `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
@@ -297,41 +328,41 @@ The export lists below name the original layout. Each package README names what
 
 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 7/8 | 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
@@ -340,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";
@@ -353,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
@@ -371,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)