@xmachines/docs 4.0.0 → 5.0.1

package/guides/atoms.md

@@ -0,0 +1,264 @@
+# Understanding Atoms in XMachines
+
+Atoms are the reactive substrate connecting actors to the outside world in XMachines. This page explains what they are, why XMachines uses them instead of observables or callbacks, and how the atom primitives map to distinct roles in the architecture.
+
+After reading this, you will understand why infrastructure never reads state directly from an actor — and what it does instead.
+
+---
+
+## What problem atoms solve
+
+When a state machine transitions, several things may need to react: the URL bar might update, a router might navigate, a renderer might swap views. The naive approach is to let each of those consumers call `actor.getSnapshot()` whenever they feel like it — or to have the actor call back into each consumer via callbacks.
+
+Both approaches break down:
+
+- **Polling** (`getSnapshot()` on a timer or event) is racy: consumers can observe inconsistent intermediate states during a transition sequence.
+- **Callbacks** create direct dependencies between the actor and infrastructure, violating the architectural invariant that business logic must not depend on runtime APIs.
+
+Atoms solve this with a **push–pull model**:
+
+- The actor **pushes** state changes into atoms synchronously on every transition.
+- Consumers **pull** values from atoms, and a derivation computes only when a dependency changed.
+- Changes propagate **atomically**, so no consumer ever sees a half-updated state.
+
+This model is sometimes called _glitch-free reactivity_: intermediate invalid states never escape to the environment.
+
+---
+
+## The atom primitives
+
+XMachines uses the atom of [`@xstate/store`](https://stately.ai/docs/xstate-store), accessed via [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md). One function builds both kinds, and the argument decides which.
+
+### `createAtom(value)` — writable values
+
+`Atom<T>` holds a single mutable value. Only the actor (or code it explicitly delegates to) writes to it. Everything else reads from it.
+
+```typescript
+import { createAtom } from "@xmachines/play-atom";
+
+const count = createAtom(0);
+
+count.set(1); // write
+count.set((previous) => previous + 1); // write from the previous value
+count.get(); // read → 2
+```
+
+In XMachines, `actor.state` is an `Atom<Snapshot>`. The actor updates it on every XState transition. Infrastructure reads it — never writes it.
+
+An atom notifies nobody when the new value compares equal to the old one. The default comparison is `Object.is`, and the `compare` option replaces it:
+
+```typescript
+const point = createAtom(
+	{ x: 0, y: 0 },
+	{ compare: (previous, next) => previous.x === next.x && previous.y === next.y },
+);
+```
+
+### `createAtom(fn)` — derived values
+
+`ReadonlyAtom<T>` derives a value from one or more other atoms. It recomputes only when its dependencies change, and it memoizes the result. The atom tracks each dependency for you: read another atom inside the function, and the edge exists.
+
+```typescript
+const route = createAtom(() => {
+	const snapshot = actor.state.get();
+	return snapshot.getMeta()?.route ?? null;
+});
+```
+
+In XMachines, `actor.currentRoute` is a `ReadonlyAtom<string | null>`. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
+
+> **A computed atom with a subscriber is EAGER.** `@xstate/store` builds a subscription on an effect that READS the atom, so a write to a dependency evaluates the derivation at once, inside that write. A computed atom that nobody subscribes to stays lazy, and it computes on a read. Keep a derivation cheap and free of a side effect.
+
+### Write one atom, derive the rest
+
+Every `set` flushes by itself, and the library exposes no batching. Two writes therefore give two propagations, and an observer that reads both atoms is evaluated **between** them, on a half-updated pair.
+
+The actor writes exactly one atom for each transition — `state` — and `currentRoute` and `currentView` are computed atoms over it. One write reaches both, the engine orders the evaluation, and no observer reads a torn pair. Follow the same rule in your own code: when two values must agree, derive the second from the first rather than writing both.
+
+### A derivation contains its own failures
+
+A subscriber makes a computed atom eager, so the derivation runs inside the `set` of its dependency — before any observer sees anything. No subscriber can wrap that, so a derivation that something may watch must not throw:
+
+```typescript
+const derived = createAtom((previous) => {
+	try {
+		return expensiveDerivation(source.get());
+	} catch (error) {
+		report(error);
+		return previous ?? null; // keep the last good value
+	}
+});
+```
+
+`actor.currentRoute` and `actor.currentView` both follow this rule. Each reports through the `onError` option of the actor and keeps its last good value, so one unbuildable route template or one malformed `meta.view` never breaks the transition for the other observers.
+
+### `createWritableAtom(value)` — the writable atom, with one signature
+
+`createAtom` carries two signatures, and TypeScript must prove the argument is not a function before it reaches the writable one. For a concrete type it proves that at once. For a type parameter, or a conditional type over one, it cannot, so it picks the computed signature and returns a `ReadonlyAtom` that carries no `set`.
+
+```typescript
+class Holder<T extends { value: unknown }> {
+	public readonly state: Atom<T["value"]>;
+
+	constructor(seed: T["value"]) {
+		// createAtom(seed) would give a ReadonlyAtom here.
+		this.state = createWritableAtom(seed);
+	}
+}
+```
+
+Use `createAtom` everywhere else.
+
+### `atom.subscribe(fn)` — reactive observation
+
+Every atom carries `subscribe`. The observer runs **synchronously**, inside the `set` of the atom that changed, and it returns a subscription with `unsubscribe()`.
+
+```typescript
+const subscription = actor.currentRoute.subscribe((route) => {
+	console.log("Route is now:", route);
+});
+
+subscription.unsubscribe();
+```
+
+Two consequences follow from the synchronous delivery, and both matter:
+
+- Several writes in one tick call the observer several times. Nothing coalesces them.
+- An observer that THROWS throws inside the `set`, and the failure lands in the code that wrote the atom.
+
+For both reasons, application code should use [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) instead.
+
+---
+
+## [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) — the safe helper
+
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) exports [`watchAtom(atom, onValue)`](../api/@xmachines/play-atom/functions/watchAtom.md) as a lifecycle-safe wrapper around `subscribe`. It returns a cleanup function:
+
+```typescript
+const stop = watchAtom(actor.currentRoute, (route) => {
+	console.log("Route is now:", route);
+});
+
+// Later — stops observing and prevents use-after-free
+stop();
+```
+
+[`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) handles three subtle correctness concerns for you:
+
+| Concern                | What happens without it                            | How [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md) handles it |
+| ---------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                                 |
+| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `scheduled` guard — only one microtask queued per synchronous burst              |
+| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                                      |
+
+Use [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) in framework adapters and application code. Use the raw `subscribe` only when you need the notification at the exact moment of the write.
+
+---
+
+## The release, and `using`
+
+`watchAtom()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
+function, and a `Disposable`. One value therefore serves two forms, and the same holds for
+the mount of [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md) and for `history.subscribe()` of
+[`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md).
+
+Keep the explicit call where the release outlives the scope that made it — a field that a
+teardown reads, an entry in a `Set` of releases:
+
+```typescript
+const stop = watchAtom(actor.currentRoute, render);
+onUnmount(() => stop());
+```
+
+Write `using` where the release belongs to one scope. The scope releases it, an exception
+releases it too, and the code carries no teardown:
+
+```typescript
+{
+	using stop = watchAtom(actor.currentRoute, render);
+	render(actor.currentRoute.get());
+	// stop() runs here, and it runs even when render() throws
+}
+```
+
+A scope releases from the last declaration to the first, so a release that depends on an
+earlier one is safe.
+
+Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
+`AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
+`await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
+forces every holder into an async function. `asCleanup` therefore refuses a release that
+returns a value, and a promise above all — a promise handed to it would go on the floor,
+released and unawaitable.
+
+`using` needs Node 24 or a browser with Explicit Resource Management. The publishable
+packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
+decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
+`Symbol.dispose` still calls it as a plain function.
+
+---
+
+## One instance, and why it matters
+
+`@xstate/store` holds the active subscriber in a variable of its own module. Two copies in one application build two separate graphs: a computed atom of the first copy and a subscription of the second copy never meet, the subscriber stays silent, and no error reports the fault. Every propagation of state in this architecture goes through an atom, so the second copy stops the whole reactivity of an application.
+
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) therefore declares `@xstate/store` as a **peer** dependency. A renderer declares it no more, because it reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) and names the engine in no import. Install one copy, and install it yourself. `tests/singleton-peers.test.ts` holds the rule true inside this workspace.
+
+---
+
+## Why not observables (RxJS) or event emitters?
+
+The XMachines architecture chose atoms over observable libraries and event emitters for three reasons:
+
+**1. One primitive, isolated.** Isolating the library behind [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) means one package holds every change of the reactive primitive, and no consuming package changes with it.
+
+**2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Atoms propagate atomically: every computed atom updates before any subscriber runs, and the algorithm resolves the diamond so that no subscriber reads a half-updated graph.
+
+**3. Memoized derivation.** An observable pushes a value to every subscriber whatever the value is. An atom compares, and a derivation that produces an equal value notifies nobody and stops the propagation there.
+
+---
+
+## The invariants in XMachines
+
+The [Play RFC](../rfc/play.md) defines five invariants that govern how atoms are used:
+
+| Invariant                     | What it means in practice                                                                                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **1. Actor Authority**        | Only actor code writes to `actor.state`. Never write to it from infrastructure.                             |
+| **2. Strict Separation**      | Business logic (`machine` definition) never imports browser APIs, routing libraries, or framework packages. |
+| **3. Atom-Only Reactivity**   | Cross-boundary communication uses atoms. Infrastructure does not poll `getSnapshot()`.                      |
+| **4. Passive Infrastructure** | Routers and renderers read atoms and forward events. They never decide state transitions.                   |
+| **5. State-Driven Reset**     | Invalid external navigation is overwritten by actor-derived state.                                          |
+
+---
+
+## Cleanup is mandatory
+
+Atoms do not clean themselves up when they go out of scope. Every subscription you create must be explicitly disposed when the consuming component or adapter unmounts.
+
+- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call the cleanup returned by [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md).
+- Router bridge `disconnect()` methods must release all atom subscriptions.
+- If you use `subscribe` directly, pair every call with `unsubscribe()` in teardown.
+
+Failing to clean up subscriptions causes memory leaks and stale callbacks firing after the consumer is gone.
+
+---
+
+## Summary
+
+| Primitive                                                           | Role in XMachines                              | Who uses it                        |
+| ------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| `createAtom(value)`                                                 | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
+| `createAtom(fn)`                                                    | Derivations: routes, view specs                | Actor defines; adapters read       |
+| `createWritableAtom(value)`                                         | The writable atom, for a generic value type    | Capability and mixin code          |
+| `atom.subscribe(fn)`                                                | Synchronous observation, at the write          | Infrastructure that needs no delay |
+| [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) | Lifecycle-safe, coalesced subscription         | Application code, adapter code     |
+
+## See also
+
+- [Understanding the Actor Model](actor-model.md) — why the actor owns all atom writes
+- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that atoms derive
+- [Getting Started](getting-started.md) — hands-on walkthrough using atoms to observe an actor
+- [@xmachines/play-atom](../api/@xmachines/play-atom/README.md) — API reference
+- [Play RFC](../rfc/play.md) — architectural specification
+- [XState Store](https://stately.ai/docs/xstate-store) — the library that provides the atom

package/guides/getting-started.md

@@ -98,7 +98,7 @@ Available variables:
 The test suite relies on TypeScript path aliases that resolve to source files. If aliases are not resolving:
 
 1. Run `pnpm run build` first — some packages need their `dist/` present even in development.
-2. Confirm your package's `vitest.config.ts` uses `defineXmVitestConfig` from `@xmachines/shared/vitest`, which automatically configures the `@xmachines/*` path aliases.
+2. Confirm your package's `vitest.config.ts` uses `defineXmVitestConfig` from [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md), which automatically configures the `@xmachines/*` path aliases.
 
 #### TypeScript errors about missing types after adding a dependency
 
@@ -154,16 +154,16 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 Every XMachines application needs these four packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/json-render-core
 ```
 
-| Package                                                               | Role                                                                                                                                                                            |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                              | XState v5 state machine engine (peer dependency)                                                                                                                                |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | The actor contract: `PlayActor`, which names no state machine library                                                                                                           |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                             |
-| `@xmachines/json-render-core`                                         | Spec and store types the actor layer builds on — a peer of `@xmachines/play-actor`, and of every renderer package                                                               |
+| Package                                                             | Role                                                                                                                                                                            |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                           |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                           |
+| `@xmachines/json-render-core`                                       | Spec and store types the actor layer builds on — a peer of [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), and of every renderer package                     |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -244,7 +244,7 @@ actor.start();
 
 // 5. Read state
 console.log(actor.getSnapshot().value); // "off"
-console.log(actor.state.get().value); // "off" (TC39 Signal)
+console.log(actor.state.get().value); // "off" (an atom read)
 
 // 6. Send events — the machine's guards decide all transitions
 actor.send({ type: "toggle" });
@@ -259,7 +259,42 @@ actor.stop();
 - Always use `setup({ types })` before `createMachine` — never bare `createMachine` from xstate.
 - Use `setup.assign(...)` for context mutations — not the bare `assign` from xstate.
 - Call `actor.start()` before sending events.
-- Call `actor.stop()` when done to clean up signal subscriptions.
+- Call `actor.stop()` when done to clean up atom subscriptions.
+
+### Observing the actor
+
+`actor.state`, `actor.currentRoute` and `actor.currentView` are **atoms**. `.get()` reads
+one time, as above. To react to a change, use
+[`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md), which returns the
+release:
+
+```typescript
+import { watchAtom } from "@xmachines/play-atom";
+
+const stop = watchAtom(actor.state, (snapshot) => {
+	console.log("the machine is now:", snapshot.value);
+});
+
+actor.send({ type: "toggle" }); // the callback runs from a microtask
+
+stop(); // release it, or write `using stop = watchAtom(...)`
+```
+
+Three rules cover every use of them:
+
+- **Read, never write.** The actor owns every atom it publishes. `currentRoute` and
+  `currentView` are DERIVED from `state`, so they carry no `set` at all.
+- **`watchAtom` coalesces.** Several writes in one tick reach the callback one time, with
+  the last value. `atom.subscribe` delivers synchronously instead, inside the write — use
+  it only when you need the notification at that exact moment.
+- **Release on teardown.** An atom holds its subscription until you release it. A
+  framework renderer does this for you; code that calls `watchAtom` itself does not.
+
+A renderer needs none of this: [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)
+and the other renderers observe `currentView` for you. Reach for `watchAtom` when you
+write infrastructure, or a debug panel beside the UI.
+
+[Understanding Atoms](atoms.md) states the whole model.
 
 ---
 
@@ -337,7 +372,7 @@ const createPlayer = definePlayer({
 const actor = createPlayer();
 actor.start();
 
-// Read the current route via TC39 Signal
+// Read the current route from the atom
 console.log(actor.currentRoute.get()); // "/"
 
 // Navigate — actor guards validate the transition
@@ -405,7 +440,7 @@ export function App() {
 
 #### Pattern 2: `connectRouter` pattern (Vanilla DOM, SvelteKit, Svelte)
 
-Used with framework-agnostic or server-rendered routers. `connectRouter` handles bidirectional sync: `actor.currentRoute` signal → browser URL, and browser URL changes → `play.route` events sent to the actor.
+Used with framework-agnostic or server-rendered routers. `connectRouter` handles bidirectional sync: the `actor.currentRoute` atom → browser URL, and browser URL changes → `play.route` events sent to the actor.
 
 ```typescript
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
@@ -676,7 +711,7 @@ const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
 
 #### Wrong Node.js version
 
-**Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
+**Error:** `SyntaxError: Cannot use import statement in a module` or the atom package is not resolved.
 
 **Fix:** Use Node.js `>= 24.0.0`. Check with:
 
@@ -695,9 +730,9 @@ node --version
 | `actor.start()`                                                                                                    | Activates the machine — always call before sending events                                                             |
 | `actor.send({ type })`                                                                                             | Sends an event; machine guards decide whether a transition occurs                                                     |
 | `actor.getSnapshot()`                                                                                              | Synchronous read of current state and context                                                                         |
-| `actor.state`                                                                                                      | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                                 |
-| `actor.currentRoute`                                                                                               | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                                     |
-| `actor.currentView`                                                                                                | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                          |
+| `actor.state`                                                                                                      | `Atom<Snapshot>` — the atom for reactive state observation                                                            |
+| `actor.currentRoute`                                                                                               | `ReadonlyAtom<string \| null>` — resolved URL from active state's `meta.route`                                        |
+| `actor.currentView`                                                                                                | `ReadonlyAtom<PlaySpec \| null>` — view spec from active state's `meta.view`                                          |
 | [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                                  |
 | `play.route` event                                                                                                 | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                       |
 | `always` guard                                                                                                     | Protects states — fires on entry before any event, even on direct URL access                                          |

package/guides/inspector.md

@@ -90,17 +90,17 @@ The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.
 ```typescript
 const inspect = (event: InspectionEvent) => {
 	if (event.type === "@xstate.actor") {
-		// ❌ throws — the signals are not assigned yet
+		// ❌ throws — the atoms are not assigned yet
 		console.log(event.actorRef.currentRoute.get());
 	}
 	if (event.type === "@xstate.snapshot") {
-		// ✅ construction has returned; signals are live
+		// ✅ construction has returned; atoms are live
 		console.log(event.actorRef.getSnapshot().value);
 	}
 };
 ```
 
-Capture the reference during construction if you need it, and read the signals from a later event or from outside the observer entirely.
+Capture the reference during construction if you need it, and read the atoms from a later event or from outside the observer entirely.
 
 ---
 

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