@xmachines/docs 3.0.0 → 5.0.0

package/examples/multi-router-integration.md

@@ -25,12 +25,13 @@ Used by framework adapters that have a React/Solid/Vue provider context. The `Pl
 import { useEffect, useMemo } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { defineRegistry } from "@xmachines/play-react";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 const { registry } = defineRegistry(authCatalog, {
   components: { /* ...your components */ },
@@ -66,15 +67,16 @@ export function App() {
 }
 ```
 
-### React + React Router v7 (`@xmachines/play-react-router`)
+### React + React Router 7/8 (`@xmachines/play-react-router`)
 
 ```typescript
 import { createBrowserRouter, RouterProvider } from "react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 function createAppRuntime() {
   const actor = createPlayer();
@@ -116,11 +118,13 @@ export default function App() {
 ```typescript
 import { Router, Route } from "@solidjs/router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -164,11 +168,13 @@ export default function App() {
 ```typescript
 import { createRouter, createRootRoute, createRoute, RouterProvider } from "@tanstack/solid-router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -222,7 +228,8 @@ export default function App() {
 <script setup lang="ts">
 	import { h, inject } from "vue";
 	import { createRouter, createWebHistory } from "vue-router";
-	import { PlayRouterProvider, createRouteMap } from "@xmachines/play-vue-router";
+	import { PlayRouterProvider } from "@xmachines/play-vue-router";
+	import { createRouteMap } from "@xmachines/play-router/xstate";
 	import { defineRegistry } from "@xmachines/play-vue";
 	import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
@@ -258,18 +265,20 @@ Used by vanilla DOM and Svelte adapters. Call `connectRouter` directly after cre
 ### Vanilla DOM (`@xmachines/play-dom-router`)
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { createPlayUI, defineRegistry } from "@xmachines/play-dom";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+// The router needs `withRouting`, and the renderer below needs `withView`.
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -306,10 +315,15 @@ window.addEventListener("beforeunload", () => {
 // lib/router.ts
 import { defineRegistry } from "@xmachines/play-svelte";
 import { authCatalog, authMachine } from "@xmachines/play-actor-shared";
-import { definePlayer } from "@xmachines/play-xstate";
-import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
-
-const createDemoPlayer = definePlayer({ machine: authMachine });
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { connectRouter } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 const { registry } = defineRegistry(authCatalog, {
 	components: {/* ...your Svelte components */},
@@ -337,11 +351,17 @@ export const disconnectRouter = connectRouter({ actor, routeMap });
 
 ```typescript
 // lib/router.ts — identical pattern to SvelteKit, different import
-import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter } from "@xmachines/play-svelte-spa-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { authMachine } from "@xmachines/play-actor-shared";
 
-const createDemoPlayer = definePlayer({ machine: authMachine });
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 export const actor = createDemoPlayer();
 actor.start();
@@ -396,8 +416,8 @@ const disconnect = connectRouter({
 ```
 
 The Svelte adapters take the same two prefix options. They need no `router`:
-`@xmachines/play-svelte-spa-router` reads an optional `window`, and
-`@xmachines/play-sveltekit-router` reads an optional `location`.
+[`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md) reads an optional `window`, and
+[`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md) reads an optional `location`.
 
 ### What the Prefix Changes
 
@@ -446,7 +466,7 @@ An actor never changes identity, so a segment of the prefix that _identifies_ th
 For a host router that declares real route objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
-import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
 
 const tree = extractMachineRoutes(authMachine);
 
@@ -460,7 +480,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 // [{ stateId: "home", path: "/:machineId/play" }, ...]
 ```
 
-> **Polyfill note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. Both adapters therefore need a `URLPattern` polyfill on an older runtime when they are mounted. With no prefix, both keep the parse of their framework whenever it reports at least one
+> **Param note.** Under a mount, [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md) and [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md) resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. With no prefix, both keep the parse of their framework whenever it reports at least one
 > param the pattern declares, and every required one. A pattern whose params are ALL
 > optional and a framework that reports none — `/settings/:section?` under a catch-all of
 > the host — is settled by the PATH: `/settings` is the bare form of that pattern, so
@@ -468,35 +488,37 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > value, such as `/settings/security`, still reaches the extraction, because only the
 > extraction reads that value.
 >
-> These branches decide the CALLS of a navigation, and not whether the application needs
-> the polyfill. `RouteMap` compiles each parameterized route in its constructor and
-> throws there without `URLPattern`, so one `:param` in the route map makes the polyfill
-> a startup requirement on an older runtime.
+> These branches decide the CALLS of a navigation, and never the availability of the API.
+> [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries `urlpattern-polyfill` as an ordinary dependency and it
+> uses the native `URLPattern` when the runtime has one, so you install no polyfill and
+> you load none. A BAD pattern is a question of the route map: `RouteMap` compiles each
+> parameterized route in its constructor and throws an `InvalidRoutePatternError` there.
+> The [routing guide](../guides/routing.md) states the pattern language.
 
 ## Adapter Summary
 
-| Package                                 | Framework             | Pattern         | Key Import                                                                |
-| --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
-| `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
-| `@xmachines/play-react-router`          | React Router v7       | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
-| `@xmachines/play-tanstack-react-router` | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
-| `@xmachines/play-solid-router`          | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-tanstack-solid-router` | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-vue-router`            | Vue Router            | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-sveltekit-router`      | SvelteKit             | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
-| `@xmachines/play-svelte-spa-router`     | Svelte SPA Router     | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
+| Package                                                                                           | Framework             | Pattern         | Key Import                                                                |
+| ------------------------------------------------------------------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8      | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router            | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit             | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router     | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
 
 ## Renderer Packages
 
 Each framework also has a companion renderer package for the view layer:
 
-| Package                  | Framework   | Key API                                            |
-| ------------------------ | ----------- | -------------------------------------------------- |
-| `@xmachines/play-dom`    | Vanilla DOM | `createPlayUI`, `createRenderer`, `defineRegistry` |
-| `@xmachines/play-react`  | React       | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-solid`  | SolidJS     | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-vue`    | Vue 3       | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-svelte` | Svelte 5    | `PlayRenderer`, `defineRegistry`                   |
+| Package                                                             | Framework   | Key API                                            |
+| ------------------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | Vanilla DOM | `createPlayUI`, `createRenderer`, `defineRegistry` |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | React       | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | SolidJS     | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | Vue 3       | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | Svelte 5    | `PlayRenderer`, `defineRegistry`                   |
 
 ## Architectural Invariants
 
@@ -504,9 +526,9 @@ All adapters preserve the 5 architectural invariants:
 
 1. **Actor Authority (INV-01):** Machine guards validate all navigation
 2. **Strict Separation (INV-02):** Business logic (machine) has zero framework imports
-3. **State-Driven Reset (INV-03):** Browser back/forward sends `play.route` events to actor
+3. **Atom-Only Reactivity (INV-03):** atoms work identically in all adapters
 4. **Passive Infrastructure (INV-04):** Router observes actor, never decides
-5. **Signal-Only Reactivity (INV-05):** TC39 Signals work identically in all adapters
+5. **State-Driven Reset (INV-05):** Browser back/forward sends `play.route` events to actor
 
 ## Next Steps
 

package/examples/routing-patterns.md

@@ -6,7 +6,7 @@ How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTr
 
 XMachines inverts the usual routing model. The **actor** owns navigation — its guards decide which states are valid. The **router** is passive infrastructure that observes `actor.currentRoute` and keeps the browser URL in sync. This is **Actor Authority (INV-01)**.
 
-Every routing interaction starts with a `play.route` event sent to the actor. If the machine's guards allow the transition, the state changes and `actor.currentRoute` updates. The router bridge sees the new signal value and pushes a history entry. The URL never changes unless the actor approves.
+Every routing interaction starts with a `play.route` event sent to the actor. If the machine's guards allow the transition, the state changes and `actor.currentRoute` updates. The router bridge sees the new atom value and pushes a history entry. The URL never changes unless the actor approves.
 
 ## Key Concepts
 
@@ -64,7 +64,8 @@ Instead of hand-writing `play.route` event handlers for every routable state, wr
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
 interface AuthContext {
@@ -108,14 +109,16 @@ const authMachine = authSetup.createMachine(
 ```typescript
 on: {
   "play.route": [
-    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: true, actions: assign({ params, query }) },
-    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: true, actions: assign({ params, query }) },
-    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: true, actions: assign({ params, query }) },
-    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: true, actions: assign({ params, query }) },
+    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: false, actions: assign({ params, query }) },
+    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: false, actions: assign({ params, query }) },
+    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: false, actions: assign({ params, query }) },
+    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
 
+`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state that must re-enter its own domain.
+
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
@@ -204,7 +207,10 @@ const authMachine = authSetup.createMachine(
 ## Complete Actor Usage
 
 ```typescript
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -234,16 +240,11 @@ actor.stop();
 
 ## Vanilla Router Setup
 
-To sync the browser URL with `actor.currentRoute`, use `@xmachines/play-dom-router`:
+To sync the browser URL with `actor.currentRoute`, use [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md):
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
@@ -251,7 +252,7 @@ const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree: authMachine, history });
 
 // connectRouter handles all bidirectional sync:
-// - actor.currentRoute signal → browser URL (history.push)
+// - actor.currentRoute atom → browser URL (history.push)
 // - browser URL changes → play.route event sent to actor
 const disconnect = connectRouter({ actor, router, routeMap });
 
@@ -264,11 +265,11 @@ window.addEventListener("beforeunload", () => {
 
 ## React Router Setup
 
-For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react-router`:
+For React, use [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) or [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md):
 
 ```tsx
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -284,7 +285,7 @@ function App() {
 | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
 | **Actor Authority (INV-01)**        | Guards on the machine validate every navigation. The router cannot change state directly.      |
 | **Passive Infrastructure (INV-04)** | The router observes `actor.currentRoute` — it never decides where to go.                       |
-| **State-Driven Reset (INV-03)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
+| **State-Driven Reset (INV-05)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
 | **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, actions, and context are pure TypeScript.      |
 
 ## Next Steps

package/examples/traffic-light.md

@@ -17,7 +17,9 @@ Applicable patterns:
 
 ```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";
 
 // 1. Typed setup
 const trafficSetup = setup({
@@ -70,13 +72,16 @@ const trafficMachine = trafficSetup.createMachine(
 );
 
 // 3. Player factory
-const createPlayer = definePlayer({ machine: trafficMachine });
+const createPlayer = definePlayer({
+	machine: trafficMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 
 // 4. Create and start actor
 const actor = createPlayer();
 actor.start();
 
-// 5. Read current route via signal
+// 5. Read current route from the atom
 console.log(actor.currentRoute.get()); // "/red"
 
 // 6. Advance with domain events
@@ -105,9 +110,9 @@ actor.stop();
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: true, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: true, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: true, actions: assign({ params, query }) },
+    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: false, actions: assign({ params, query }) },
+    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: false, actions: assign({ params, query }) },
+    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
@@ -116,15 +121,16 @@ on: {
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
 - The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
+- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state that must re-enter its own domain.
 
-## `actor.currentRoute` Signal
+## The `actor.currentRoute` atom
 
-`actor.currentRoute` is a `Signal.Computed<string | null>` derived from the active state's `meta.route` template and `context.params`. Route signals let router bridges observe URL changes reactively without polling.
+`actor.currentRoute` is a `ReadonlyAtom<string | null>` derived from the active state's `meta.route` template and `context.params`. A route atom lets a router bridge observe URL changes reactively without polling.
 
 ```typescript
-import { watchSignal } from "@xmachines/play-signals";
+import { watchAtom } from "@xmachines/play-atom";
 
-const unwatch = watchSignal(actor.currentRoute, () => {
+const unwatch = watchAtom(actor.currentRoute, () => {
 	console.log("URL changed to:", actor.currentRoute.get());
 });
 
@@ -136,7 +142,7 @@ unwatch();
 
 - **`meta.route`**: Marks a state as routable. The value is a URL template (e.g. `"/profile/:username"`).
 - **`formatPlayRouteTransitions`**: Utility that auto-generates `play.route` handlers from `id` + `meta.route` pairs. Wrap your machine config before passing to `createMachine`.
-- **`actor.currentRoute`**: TC39 `Signal.Computed` containing the resolved URL for the active state.
+- **`actor.currentRoute`**: a computed atom containing the resolved URL for the active state.
 - **`play.route` events**: Navigation events with a `to: "#stateId"` target. Use `to: "#red"` (state ID), not `to: "/red"` (URL path).
 
 ## Next Steps

package/guides/README.md

@@ -12,7 +12,8 @@ Background reading that explains the _why_ behind XMachines design decisions.
 
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
-- **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+- **[Understanding Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
+- **[Understanding Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling
 

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, currentRoute, currentView
+  │  emits atoms: state, and currentRoute / currentView from its capabilities
   ▼
 Infrastructure (runtime adapters)
   ├── Router Bridge — reflects currentRoute into the URL bar
@@ -33,20 +33,29 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md). It implements three reactive properties:
+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`.                                                                             |
-| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) that drives renderers. |
+| 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:
 
 - **Guards** — it decides whether a transition is valid. If a router sends a `play.route` event for a path the actor's guards reject, the actor does not transition. It then emits its current valid route back through `currentRoute`, and the router bridge overwrites the URL to match.
-- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
+- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
 - **Initial route** — `actor.initialRoute` is the route the actor starts in. Router adapters use this for initial navigation, not the browser's current URL.
 
 ---
@@ -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`.
 
@@ -87,17 +96,19 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 ---
 
-## [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — the enforced contract
+## [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) — the enforced contract
+
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the contract that all actor implementations satisfy. It is an INTERFACE, and it names no state machine library.
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) extends `Actor` of XState, which means:
 
 - XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) adds one abstract requirement: a reactive `state` property of type `Signal.State<unknown>`. This is the single point where XState's pull-based snapshot API is bridged to TC39's push-based signal system.
+[`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-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md) — are deliberately separate:
+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:
 
 - Not every actor needs routing (e.g., a background data-sync actor).
 - Not every actor drives a view (e.g., a sub-actor composed inside a parent).
@@ -105,26 +116,33 @@ The two optional capability interfaces — [`Routable`](../api/@xmachines/play-a
 An actor implements only the capabilities it actually uses:
 
 ```typescript
-// Minimal actor: just reactive state
-class MinimalActor extends AbstractActor<SomeLogic> {
-	state = new Signal.State(this.getSnapshot());
+// Minimal actor: the contract alone, which is reactive state and send
+class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
+	readonly state = createAtom<SomeSnapshot>(initial);
+	send(event: SomeEvent): void {
+		/* dispatch */
+	}
 }
 
-// Full actor: state + routing + view
-class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewable {
-	state = new Signal.State(this.getSnapshot());
-	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-	currentView = new Signal.State<PlaySpec | null>(null);
+// Full actor: the contract, the routing and the view. It extends the actor class of
+// its own engine, and `PlayActor` stays out of the inheritance.
+class PlayerActor
+	extends Actor<SomeMachine>
+	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
+{
+	readonly state = createAtom(this.getSnapshot());
+	readonly currentRoute = createAtom(() => deriveRoute(this.state.get()));
+	readonly currentView = createAtom((): PlaySpec | null => deriveView(this.state.get()));
 }
 ```
 
-In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
 
 ---
 
-## [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) — the factory builder
+## [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) — the factory builder
 
-[`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md) is the primary entry point for creating actors:
+[`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) is the primary entry point for creating actors:
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -137,7 +155,7 @@ const actor = createPlayer();
 actor.start();
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
+[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
 
 The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
 
@@ -152,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:
 
@@ -172,9 +190,9 @@ 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 [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md)
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 - [Play RFC](../rfc/play.md) — complete architectural specification