@xmachines/docs 3.0.0 → 5.0.0

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

@@ -18,11 +18,11 @@ Jump to the section that applies to you:
 
 You need the following installed before cloning the repository:
 
-| Requirement | Version            | Notes                                                                                                                                                   |
-| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Node.js     | `>= 24.0.0`        | The floor to DEVELOP. The suite writes `using`, which needs V8 13.4. A published package declares `>= 22.0.0`, and the emitted JavaScript parses there. |
-| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces.                                   |
-| Git         | any recent version | Conventional commit format is enforced by CI                                                                                                            |
+| Requirement | Version            | Notes                                                                                                                 |
+| ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Node.js     | `>= 24.0.0`        | The floor to develop AND to consume. Every `package.json` `engines` field declares it.                                |
+| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces. |
+| Git         | any recent version | Conventional commit format is enforced by CI                                                                          |
 
 No global TypeScript install is needed — it is installed as a dev dependency via `pnpm install --frozen-lockfile`.
 
@@ -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
 
@@ -140,7 +140,7 @@ This section covers installing XMachines packages into your own application and
 
 ### Prerequisites
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>= 24.0.0`
 - **pnpm** via corepack (`corepack enable`)
 - **TypeScript** `>= 5.7` (strict mode recommended)
 - **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
@@ -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/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
-| [`@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)
 
@@ -171,7 +171,7 @@ pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-sig
 # Provider pattern (framework-integrated routers)
 pnpm add @xmachines/play-tanstack-react-router   # TanStack Router (React)
 pnpm add @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
-pnpm add @xmachines/play-react-router            # React Router v7
+pnpm add @xmachines/play-react-router            # React Router 7/8
 pnpm add @xmachines/play-vue-router              # Vue Router 4.x/5.x
 pnpm add @xmachines/play-solid-router            # SolidJS Router
 
@@ -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.
 
 ---
 
@@ -269,11 +304,13 @@ State machines control navigation through `meta.route` on states and `play.route
 
 #### Define a routable machine with `formatPlayRouteTransitions`
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
 const appSetup = setup({
@@ -328,11 +365,14 @@ const appMachine = appSetup.createMachine(
 	}),
 );
 
-const createPlayer = definePlayer({ machine: appMachine });
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 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
@@ -353,7 +393,7 @@ actor.stop();
 
 **Routing rules:**
 
-- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
+- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
 - Send `play.route` events with `to: "#stateId"` — always use the `id` field prefixed with `#`, never raw URL paths.
 - The machine context **must** include `params: Record<string, string>` and `query: Record<string, string>`.
 - Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
@@ -372,12 +412,8 @@ Used with framework-integrated routers like TanStack Router. All three props (`a
 // React + TanStack Router example
 import { useMemo, useEffect } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import {
-	PlayRouterProvider,
-	extractMachineRoutes,
-	createRouteMapFromTree,
-} from "@xmachines/play-tanstack-react-router";
-
+import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 // Build OUTSIDE of JSX — must be stable references
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -404,11 +440,12 @@ 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";
-import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -610,7 +647,7 @@ window.addEventListener("beforeunload", () => disconnect());
 `play.route` event never appears. No error is raised — a context without a
 `query` field builds a query-less URL, exactly like `query: {}`.
 
-**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
+**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 nothing is needed — the generated transitions assign `event.query` to context
 on every navigation. A machine that handles `play.route` by hand must do that
 assignment itself:
@@ -627,8 +664,9 @@ on: {
 ```
 
 (Older releases threw `MissingQueryContextError` at construction for a
-routing-aware context without a `query` field; the error class remains
-exported for `instanceof` compatibility but is never thrown.)
+routing-aware context without a `query` field. That class is gone: the generated
+`play.route` transitions assign `query` on every navigation, so the loss it
+guarded against cannot happen.)
 
 #### Missing `id` on routable states
 
@@ -673,9 +711,9 @@ 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 `>= 22.0.0`. Check with:
+**Fix:** Use Node.js `>= 24.0.0`. Check with:
 
 ```bash
 node --version
@@ -685,23 +723,23 @@ node --version
 
 ## Key Concepts Reference
 
-| Term                                                                                                  | Description                                                                                                     |
-| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `setup({ types })`                                                                                    | XState v5 entry point — declares TypeScript types for context, events, and input                                |
-| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) instances |
-| `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`                                    |
-| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/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                                    |
-| [`extractMachineRoutes`](../api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                      |
-| [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                 |
-| [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                               |
-| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                          |
+| Term                                                                                                               | Description                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `setup({ types })`                                                                                                 | XState v5 entry point — declares TypeScript types for context, events, and input                                      |
+| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md)                       | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) instances |
+| `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`                                                                                                      | `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                                          |
+| [`extractMachineRoutes`](../api/@xmachines/play-router/xstate/functions/extractMachineRoutes.md)                   | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                            |
+| [`createRouteMapFromTree`](../api/@xmachines/play-router/index/functions/createRouteMapFromTree.md)                | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                       |
+| [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                                    | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                                     |
+| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)               | React component that connects a `PlayerActor` to TanStack React Router                                                |
 
 ---
 

package/guides/inspector.md

@@ -22,7 +22,7 @@ Install the inspect client alongside your existing XState dependency:
 pnpm add -D @statelyai/inspect
 ```
 
-Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md):
+Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md):
 
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
@@ -42,7 +42,7 @@ actor.start();
 
 `createBrowserInspector()` opens Stately's hosted inspector in a new tab and streams the actor's events to it. From there the machine draws itself, every transition animates, and the context is readable at each step.
 
-That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
+That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
 
 ```typescript
 // Function form — the common case
@@ -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.
 
 ---
 
@@ -190,8 +190,8 @@ const createPlayer = definePlayer({ machine: appMachine, options });
 
 ## Related documentation
 
-- **[`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
-- **[`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)** — the actor an inspector observes
+- **[`PlayerOptions`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
+- **[`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)** — the actor an inspector observes
 - **[Understanding the Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
 - **[Getting Started](getting-started.md)** — installing packages and creating your first actor
 - **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options