@xmachines/docs 4.0.0 → 5.0.0

package/guides/actor-model.md

@@ -14,12 +14,12 @@ Every XMachines application has exactly two roles:
 
 **Infrastructure** — the runtime environment. It reflects actor state into the world and forwards world events to the actor. It has no opinion on whether a transition is valid.
 
-The boundary between them is enforced by the signal protocol: the actor exposes `Signal.State` and `Signal.Computed` properties; infrastructure observes them. The actor never calls into infrastructure; infrastructure never mutates actor state directly.
+The boundary between them is enforced by the atom protocol: the actor exposes `Atom` and `ReadonlyAtom` properties; infrastructure observes them. The actor never calls into infrastructure; infrastructure never mutates actor state directly.
 
 ```
 Actor (business logic)
   │
-  │  emits signals: state, and currentRoute / currentView from its capabilities
+  │  emits atoms: state, and currentRoute / currentView from its capabilities
   ▼
 Infrastructure (runtime adapters)
   ├── Router Bridge — reflects currentRoute into the URL bar
@@ -35,13 +35,22 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It implements three reactive properties:
 
-| Property             | Type                              | What it is                                                                                                                                                     |
-| -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                                                 |
-| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`. Needs the routing capability.                                                                               |
-| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) that drives renderers. Needs the view capability. |
+| Property             | Type                             | What it is                                                                                                                                               |
+| -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor.state`        | `Atom<Snapshot>`                 | The ONE atom the actor writes. Updated on every XState transition, with the full machine snapshot.                                                       |
+| `actor.currentRoute` | `ReadonlyAtom<string \| null>`   | DERIVED from `state`, through the active state node's `meta.route`. Needs the routing capability.                                                        |
+| `actor.currentView`  | `ReadonlyAtom<PlaySpec \| null>` | DERIVED from `state`. Holds the [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) that drives renderers. Needs the view capability. |
 
-All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
+Infrastructure reads all three and writes none of them.
+
+**One write for each transition, and two derivations from it.** `state` receives the new
+snapshot, and the engine then evaluates `currentRoute` and `currentView` from it in one
+propagation. An observer that reads two of these atoms therefore never sees the new state
+beside an old derivation, and the composition order of the capabilities decides nothing.
+
+A derivation that fails reports through the `onError` option of the actor and keeps its
+last good value. It throws never, because it runs inside the write and a throw would break
+the transition for every other observer. See [Understanding Atoms](atoms.md).
 
 The actor also owns:
 
@@ -58,7 +67,7 @@ Infrastructure owns everything that touches the environment:
 - **Pushing URLs**: reading `actor.currentRoute` and calling `history.pushState()` or a router's navigation API.
 - **Forwarding navigation events**: listening to `popstate`, `routeChange`, or equivalent, then calling `actor.send({ type: "play.route", to: path })`.
 - **Rendering**: reading `actor.currentView` and projecting the spec through framework components.
-- **Lifecycle**: connecting on mount, disconnecting on unmount, explicitly cleaning up signal subscriptions.
+- **Lifecycle**: connecting on mount, disconnecting on unmount, explicitly cleaning up atom subscriptions.
 
 Infrastructure does **not**:
 
@@ -77,7 +86,7 @@ If a user navigates directly to `/admin` in the browser but the actor's guards r
 1. Receives `{ type: "play.route", to: "/admin" }` from the router bridge.
 2. Evaluates its guards. The guard fails.
 3. Does not transition. It remains in its current state (e.g., `/login`).
-4. `actor.currentRoute` still signals `"/login"`.
+4. `actor.currentRoute` still holds `"/login"`.
 5. The router bridge, watching `currentRoute`, calls its `navigateRouter("/login")` method.
 6. The URL bar resets to `/login`.
 
@@ -97,7 +106,7 @@ An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xm
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
-[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Signal.State<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based signal system of TC39.
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Atom<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based atom system.
 
 The two optional capability interfaces — [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) — are deliberately separate:
 
@@ -109,7 +118,7 @@ An actor implements only the capabilities it actually uses:
 ```typescript
 // Minimal actor: the contract alone, which is reactive state and send
 class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
-	readonly state = new Signal.State<SomeSnapshot>(initial);
+	readonly state = createAtom<SomeSnapshot>(initial);
 	send(event: SomeEvent): void {
 		/* dispatch */
 	}
@@ -121,9 +130,9 @@ class PlayerActor
 	extends Actor<SomeMachine>
 	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
 {
-	readonly state = new Signal.State(this.getSnapshot());
-	readonly currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-	readonly currentView = new Signal.State<PlaySpec | null>(null);
+	readonly state = createAtom(this.getSnapshot());
+	readonly currentRoute = createAtom(() => deriveRoute(this.state.get()));
+	readonly currentView = createAtom((): PlaySpec | null => deriveView(this.state.get()));
 }
 ```
 
@@ -161,7 +170,7 @@ const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
 
 The machine definition — the `setup().createMachine(...)` call — is pure TypeScript with zero runtime dependencies on browsers, routers, or UI frameworks. This is not a convention; it is enforced by the dependency graph.
 
-[`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) depends on `xstate` and [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md). It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
+[`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) depends on `xstate` and [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md). It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
 
 This has concrete practical benefits:
 
@@ -181,7 +190,7 @@ The Play RFC captures the actor/infrastructure split in a single statement:
 
 ## See also
 
-- [Understanding TC39 Signals](signals.md) — how the actor communicates with infrastructure
+- [Understanding Atoms](atoms.md) — how the actor communicates with infrastructure
 - [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
 - [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
 - [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)

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.
 
 ---