@xmachines/docs 4.0.0 → 5.0.1

package/examples/@xmachines/play-vue-demo/variables/authCatalog.md

@@ -36,8 +36,17 @@ const authCatalog: Catalog<
 						{
 							children: SchemaType<"array", SchemaType<"string", unknown>>;
 							props: SchemaType<"propsOf", string>;
+							repeat: {
+								inner?: unknown;
+								kind: "any";
+								optional: true;
+							};
 							type: SchemaType<"ref", string>;
-							visible: SchemaType<"any", unknown>;
+							visible: {
+								inner?: unknown;
+								kind: "any";
+								optional: true;
+							};
 						}
 					>
 				>;
@@ -47,6 +56,24 @@ const authCatalog: Catalog<
 	},
 	{
 		actions: {
+			addTask: {
+				description: "Add a task (sends task.add to the machine)";
+				params: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			completeTask: {
+				description: "Mark a task done (sends task.complete to the machine)";
+				params: ZodObject<
+					{
+						id: ZodString;
+					},
+					$strip
+				>;
+			};
 			login: {
 				description: "Login with username";
 				params: ZodObject<
@@ -59,6 +86,24 @@ const authCatalog: Catalog<
 			logout: {
 				description: "Logout and return to home";
 			};
+			removeTask: {
+				description: "Remove a task (sends task.remove to the machine)";
+				params: ZodObject<
+					{
+						id: ZodString;
+					},
+					$strip
+				>;
+			};
+			resetForm: {
+				description: "Reset a demo form to its defaults (confirm-gated in the spec)";
+				params: ZodObject<
+					{
+						form: ZodString;
+					},
+					$strip
+				>;
+			};
 			route: {
 				description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
 				params: ZodObject<
@@ -69,6 +114,16 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			submitForm: {
+				description: "Submit a demo form; rejects when the form did not pass validation";
+				params: ZodObject<
+					{
+						form: ZodString;
+						valid: ZodOptional<ZodNullable<ZodBoolean>>;
+					},
+					$strip
+				>;
+			};
 		};
 		components: {
 			About: {
@@ -79,6 +134,23 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Button: {
+				props: ZodObject<
+					{
+						disabled: ZodOptional<ZodBoolean>;
+						label: ZodString;
+						testId: ZodOptional<ZodString>;
+						variant: ZodOptional<
+							ZodEnum<{
+								danger: "danger";
+								primary: "primary";
+								secondary: "secondary";
+							}>
+						>;
+					},
+					$strip
+				>;
+			};
 			Contact: {
 				props: ZodObject<
 					{
@@ -96,6 +168,26 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Field: {
+				props: ZodObject<
+					{
+						checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+						formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+						inputType: ZodOptional<
+							ZodEnum<{
+								email: "email";
+								text: "text";
+								textarea: "textarea";
+							}>
+						>;
+						label: ZodString;
+						placeholder: ZodOptional<ZodString>;
+						testId: ZodOptional<ZodString>;
+						value: ZodOptional<ZodString>;
+					},
+					$strip
+				>;
+			};
 			Home: {
 				props: ZodObject<
 					{
@@ -139,6 +231,26 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Panel: {
+				props: ZodObject<
+					{
+						note: ZodOptional<
+							ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>
+						>;
+						testId: ZodOptional<ZodString>;
+						title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
+						tone: ZodOptional<
+							ZodEnum<{
+								danger: "danger";
+								default: "default";
+								muted: "muted";
+								success: "success";
+							}>
+						>;
+					},
+					$strip
+				>;
+			};
 			Profile: {
 				props: ZodObject<
 					{
@@ -169,4 +281,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-vue/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-vue-demo/variables/demoComponents.md

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / demoComponents
+
+# Variable: demoComponents
+
+```ts
+const demoComponents: ComponentsMap<typeof authCatalog>;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/components/demo-components.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-vue/examples/demo/src/components/demo-components.ts#L22)
+
+demoComponents — the full catalog component map, shared with the router demos.

package/examples/@xmachines/play-vue-router-demo/README.md

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-vue-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-vue-router-demo
 
 Vue Router integration demo for the XMachines Play architecture using Vue Composition API.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `PlayRouterProvider` renderer-based integration with Vue Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Vue Composition API mapping to TC39 Signals lifecycle
+- Vue Composition API mapping to atoms lifecycle
 - Non-browser invariant tests plus browser E2E coverage
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
 
 ## Running the Demo
 
@@ -33,7 +34,7 @@ Use this order to understand how the demo is wired:
 2. `src/runtime.ts` creates the actor, starts it, builds the shared `registryResult`, and creates the `routeMap`.
 3. `src/router.ts` installs a single catch-all route; `PlayRenderer` selects the actual view from actor state.
 4. `src/App.vue` renders `<PlayRouterProvider>` with the shared actor, routeMap, router instance, and a `renderShell` renderer function.
-5. The renderer function creates the shared `Shell` component with actor, router, and registry as props.
+5. The renderer function creates the shared `Shell` component with actor, router, registry, and inspector as props — the last of which drives the debug panel's **Show Inspector** button.
 6. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
 7. Browser tests in `test/browser/` validate startup and auth route transitions.
 
@@ -55,7 +56,7 @@ export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", compo
 import { actor, routeMap, registryResult } from "./runtime.js";
 
 const renderShell = (currentActor, currentRouter) =>
-	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult });
+	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult, inspector });
 </script>
 
 <template>
@@ -92,19 +93,17 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user navigates to a protected route via a link, Vue Router updates the location. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions.
 2. **Passive Infrastructure:** The router does not execute Vue route guards for business logic. The actor dictates whether navigation is permitted. The Vue application only renders the state.
-3. **Signal-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when signals update, without polluting the Vue component tree with reactive refs that hold business state.
+3. **Atom-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when atoms update, without polluting the Vue component tree with reactive refs that hold business state.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and sync Vue-local render state
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and syncs Vue-local render state
 
-Notifications are one-shot, so re-arm is required. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
+One subscription lives for the whole watch, and no caller arms a watcher again. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
 
 ## Adapter Boundaries
 
@@ -122,18 +121,8 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-vue-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-vue-router-demo run test:browser` | Run browser-focused Vitest suite               |
 
-## Verification
-
-Use these checks to validate README claims against the current demo implementation:
-
-```bash
-pnpm --filter @xmachines/play-vue-router-demo run test
-pnpm --filter @xmachines/play-vue-router-demo run test:browser
-```
-
-Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
-
 ## Learn More
 
 - [Vue Router](../../../api/@xmachines/play-vue-router/README.md)
 - [Vue](../../../api/@xmachines/play-vue/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

package/examples/README.md

@@ -8,7 +8,7 @@ Practical code examples demonstrating current XMachines Play patterns and use ca
 
 Start with the fundamental machine + actor pattern:
 
-- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
+- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + atoms
 - **[Traffic Light](traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
 - **[Form Validation](form-validation.md)** — Typed context mutations with `setup.assign`, guards, and `$bindState`
 
@@ -60,7 +60,7 @@ The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
 # Install dependencies (from the monorepo root)
-pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom xstate
 
 # Run with tsx
 pnpm dlx tsx my-example.ts
@@ -81,7 +81,7 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)        | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)          | `PlayActor`                                                 |
 | [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `typedSpec`                         |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)      | TC39 Signals polyfill, `watchSignal`                        |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)            | The atom primitives, `watchAtom`                            |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)        | `RouterBridgeBase`, `RouteMap`, `Routable`                  |
 | [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) | `extractMachineRoutes`, `getRoutableRoutes`                 |
 

package/examples/basic-state-machine.md

@@ -63,7 +63,7 @@ actor.start();
 console.log(actor.getSnapshot().value); // "off"
 console.log(actor.getSnapshot().context.toggleCount); // 0
 
-// 6. Read state via TC39 Signal
+// 6. Read state from the atom
 console.log(actor.state.get().value); // "off"
 
 // 7. Send events
@@ -87,13 +87,13 @@ actor.stop();
 
 3. **`toggleSetup.assign(...)`** — Assigns context mutations using the typed setup's `assign` helper. This provides full inference from the declared context type — no manual type assertions needed.
 
-4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with TC39 Signal reactivity and Play Architecture hooks.
+4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with atom reactivity and Play Architecture hooks.
 
 5. **`actor.start()`** — Activates the machine. Always call `start()` before sending events.
 
 6. **`actor.getSnapshot()`** — Returns the current XState snapshot synchronously. `.value` is the state name; `.context` is the typed context object.
 
-7. **`actor.state.get()`** — TC39 Signal access to the current snapshot. Useful when wiring infrastructure that observes signals (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
+7. **`actor.state.get()`** — atom access to the current snapshot. Useful when wiring infrastructure that observes atoms (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
 
 8. **Event types use dot-separated lowercase** — `"toggle"` not `"TOGGLE"`. This matches the XMachines convention used throughout the codebase (e.g. `"auth.login"`, `"auth.logout"`, `"play.route"`).
 
@@ -101,7 +101,7 @@ actor.stop();
 
 - **`setup({ types })`**: The XState v5 typed entry point. Declares context, event, and input shapes before machine creation.
 - **`definePlayer({ machine })`**: Creates a factory function that returns `PlayerActor` instances.
-- **`actor.state`**: A `Signal.State<Snapshot>` — TC39 Signals-based reactive handle on the machine snapshot.
+- **`actor.state`**: An `Atom<Snapshot>` — an atom-based reactive handle on the machine snapshot.
 - **`actor.getSnapshot()`**: Synchronous snapshot access — use for one-time reads and TypeScript-typed context inspection.
 - **Typed `assign`**: Always call `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
 

package/examples/form-validation.md

@@ -224,7 +224,7 @@ view: {
 
 ## Connecting the Renderer
 
-The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from `@xmachines/play-dom`:
+The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md):
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";

package/examples/multi-router-integration.md

@@ -416,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
 
@@ -480,7 +480,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 // [{ stateId: "home", path: "/:machineId/play" }, ...]
 ```
 
-> **Param 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. 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
@@ -489,7 +489,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > extraction reads that value.
 >
 > These branches decide the CALLS of a navigation, and never the availability of the API.
-> `@xmachines/play-router` carries `urlpattern-polyfill` as an ordinary dependency and it
+> [`@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.
@@ -497,28 +497,28 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 
 ## Adapter Summary
 
-| Package                                 | Framework             | Pattern         | Key Import                                                                |
-| --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
-| `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
-| `@xmachines/play-react-router`          | React Router 7/8      | 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
 
@@ -526,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
 
@@ -240,7 +240,7 @@ 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 } from "@xmachines/play-dom-router";
@@ -252,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 });
 
@@ -265,7 +265,7 @@ 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";
@@ -285,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

@@ -81,7 +81,7 @@ const createPlayer = definePlayer({
 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
@@ -123,14 +123,14 @@ on: {
 - 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());
 });
 
@@ -142,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

@@ -13,7 +13,7 @@ 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 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 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 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, 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)