@xmachines/docs 1.0.0-beta.32 → 1.0.0-beta.34

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

@@ -8,7 +8,7 @@ Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play arch
 
 - Shared auth machine reused without framework-specific business logic
 - `connectRouter` pathname URL ↔ actor sync via `@xmachines/play-sveltekit-router`
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
 - Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
 
@@ -30,8 +30,8 @@ Use this order to understand the implementation:
 1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
 2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
-4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+4. `src/App.svelte` imports the singleton `actor` and `registryResult` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
@@ -52,20 +52,18 @@ export function cleanupDemo(): void {
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
+	import { Shell } from "@xmachines/play-svelte-demo";
+	import { actor, registryResult } from "./lib/router.js";
 </script>
 
-<Shell {actor} {registry} />
+<Shell {actor} {registryResult} />
 ```
 
 ```svelte
-<!-- Shell.svelte — sending events (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
+<!-- Shell.svelte — rendering (shape) -->
+<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 ## Key Files

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

@@ -29,15 +29,16 @@ Use this order to understand the implementation:
 
 1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts the Vue app.
 2. The actor is provided to all components via `app.provide("actor", actor)`.
-3. `src/App.vue` injects the actor and builds the component registry with `defineRegistry(authCatalog, { components, actions })`.
-4. `<PlayRenderer :actor="actor" :registry="registry" :actions="..." />` observes actor view signals and renders the active view component.
-5. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
-6. Browser tests in `test/browser/` validate startup and interaction behavior.
+3. `src/App.vue` injects the actor and builds the typed `registryResult` with `defineRegistry(authCatalog, { components, actions })` inside `computed` — real async action handlers dispatching to `actor.send()`.
+4. `<PlayUIProvider :actor="actor" :registryResult="registryResult"><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` SFC observes `actor` signals directly for nav visibility.
+6. `<DebugPanel :actor="actor" />` shows live state, auth status, and current route.
+7. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
+8. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer();
+const actor = definePlayer({ machine: authMachine })();
 actor.start();
 
 const app = createApp(App);
@@ -48,46 +49,63 @@ app.mount("#app");
 ```vue
 <!-- src/App.vue (shape) -->
 <script setup lang="ts">
-const actor = inject<AuthActor>("actor")!;
-
-const { registry } = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-	},
-	actions: { login: async () => {}, logout: async () => {} },
-});
+const typedActor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+
+const registryResult = computed(() =>
+	defineRegistry(authCatalog, {
+		components: {
+			Home: HomeSFC,
+			About: AboutSFC,
+			Contact: ContactSFC,
+			Login: LoginSFC,
+			Dashboard: DashboardSFC,
+			Overview: OverviewSFC,
+			Stats: StatsSFC,
+			Profile: ProfileSFC,
+			Settings: SettingsSFC,
+			Navigation: NavigationSFC,
+			NavBar: NavBarViewSFC,
+		},
+		actions: {
+			login: async (args) =>
+				typedActor.send({
+					type: "auth.login",
+					username: assertNonNullable(args, "args").username,
+				}),
+			logout: async () => typedActor.send({ type: "auth.logout" }),
+			route: async (args) => {
+				const { to, params } = assertNonNullable(args, "args");
+				typedActor.send({
+					type: "play.route",
+					to,
+					...(params != null && { params }),
+				});
+			},
+		},
+	}),
+);
 </script>
 
 <template>
-	<PlayRenderer
-		:actor="actor"
-		:registry="registry"
-		:actions="{ login: 'auth.login', logout: 'auth.logout' }"
-	/>
+	<div class="demo-app" data-demo-shell>
+		<header class="demo-header">
+			<h1 class="demo-title">XMachines Play Vue Demo</h1>
+			<NavBar :actor="typedActor" />
+		</header>
+		<main class="demo-content" data-demo-content>
+			<PlayUIProvider :actor="typedActor" :registryResult="registryResult">
+				<PlayRenderer />
+			</PlayUIProvider>
+		</main>
+		<DebugPanel :actor="typedActor" />
+	</div>
 </template>
 ```
 
-```vue
-<!-- src/components/Login.vue (shape) -->
-<script setup lang="ts">
-const actor = inject("actor")!;
-const login = () => actor.send({ type: "auth.login", username: "demo" });
-</script>
-```
-
 ## Key Files
 
 - `src/main.ts` - actor creation/start and Vue app mount with actor injection
-- `src/App.vue` - registry construction and `PlayRenderer` composition
+- `src/App.vue` - registry construction and `PlayUIProvider` + `PlayRenderer` composition
 - `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage

package/examples/form-validation.md

@@ -90,12 +90,9 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/",
 					view: {
-						component: "Home",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Home", props: { title: "Welcome" }, children: [] },
-							},
+						root: "root",
+						elements: {
+							root: { type: "Home", props: { title: "Welcome" }, children: [] },
 						},
 					},
 				},
@@ -106,26 +103,23 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/login",
 					view: {
-						component: "Login",
-						spec: {
-							root: "root",
-							// Local state store — initial value shown in the form field
-							state: { username: "" },
-							elements: {
-								root: {
-									type: "Login",
-									props: {
-										title: "Sign In",
-										// $bindState wires the prop to the local state store (two-way)
-										username: { $bindState: "/username" },
-									},
-									children: [],
-									on: {
-										// emit("submit") → resolves username from $state, calls login action
-										submit: {
-											action: "login",
-											params: { username: { $state: "/username" } },
-										},
+						root: "root",
+						// Local state store — initial value shown in the form field
+						state: { username: "" },
+						elements: {
+							root: {
+								type: "Login",
+								props: {
+									title: "Sign In",
+									// $bindState wires the prop to the local state store (two-way)
+									username: { $bindState: "/username" },
+								},
+								children: [],
+								on: {
+									// emit("submit") → resolves username from $state, calls login action
+									submit: {
+										action: "login",
+										params: { username: { $state: "/username" } },
 									},
 								},
 							},
@@ -139,17 +133,14 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/dashboard",
 					view: {
-						component: "Dashboard",
-						spec: {
-							root: "root",
-							elements: {
-								root: {
-									type: "Dashboard",
-									props: { title: "Dashboard" },
-									children: [],
-									on: {
-										logout: { action: "logout" },
-									},
+						root: "root",
+						elements: {
+							root: {
+								type: "Dashboard",
+								props: { title: "Dashboard" },
+								children: [],
+								on: {
+									logout: { action: "logout" },
 								},
 							},
 						},
@@ -193,18 +184,18 @@ actor.stop();
 
 ## `$bindState` and `$state` Pattern
 
-`meta.view.spec` uses the `@json-render/core` spec format. Two special directives wire the component to a local per-state state store:
+`meta.view` uses the `@json-render/core` spec format (`PlaySpec`). Two special directives wire the component to a local per-state state store:
 
 | Directive                     | Direction | Usage                                                       |
 | ----------------------------- | --------- | ----------------------------------------------------------- |
 | `{ $bindState: "/username" }` | Two-way   | Prop reads and writes the state store key `/username`       |
 | `{ $state: "/username" }`     | Read-only | Reads the current value from the state store at `/username` |
 
-The `state:` object in the spec sets the initial values for the local store. When the user types in the form field, the renderer keeps the store in sync. On submit, action params read the final value via `$state`.
+The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the renderer keeps the store in sync. On submit, action params read the final value via `$state`.
 
 ```typescript
-// In the machine spec — the renderer handles the rest:
-spec: {
+// In the machine meta.view — the renderer handles the rest:
+view: {
   root: "root",
   state: { username: "" },         // initial store value
   elements: {
@@ -232,8 +223,88 @@ spec: {
 - **`always` transitions**: Entry guards on states. Used for protected routes — if the guard fires, the machine redirects before the state is fully entered.
 - **Lowercase dot-separated event types**: `"auth.login"`, `"auth.logout"`, `"play.route"` — not `SCREAMING_SNAKE_CASE`.
 
+## Connecting the Renderer
+
+The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from `@xmachines/play-dom`:
+
+```typescript
+import { createRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+import type { ComponentFn } from "@xmachines/play-dom";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({ title: z.string(), username: z.string().optional() }) },
+		Dashboard: { props: z.object({ title: z.string() }) },
+	},
+	actions: {
+		// Must declare all actions that appear in meta.view on-bindings
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+type AppCatalog = typeof catalog;
+
+// Component implementations receive typed props + emit/on helpers
+const Home: ComponentFn<AppCatalog, "Home"> = ({ props }) => {
+	const el = document.createElement("section");
+	el.textContent = props.title;
+	return el;
+};
+
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on, ctx }) => {
+	const section = document.createElement("section");
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	// Keep the local state store in sync as the user types
+	input.addEventListener("input", () => {
+		ctx.store.update((s) => ({ ...s, username: input.value }));
+	});
+	const button = document.createElement("button");
+	button.textContent = "Log In";
+	const submit = on("submit"); // bound to the spec's on.submit binding
+	button.addEventListener("click", () => submit.emit()); // resolves $state, calls login action
+	section.append(input, button);
+	return section;
+};
+
+const Dashboard: ComponentFn<AppCatalog, "Dashboard"> = ({ props, on }) => {
+	const section = document.createElement("section");
+	section.textContent = props.title;
+	const btn = document.createElement("button");
+	btn.textContent = "Log Out";
+	const logout = on("logout");
+	btn.addEventListener("click", () => logout.emit());
+	section.append(btn);
+	return section;
+};
+
+// createRenderer builds the factory once — call mount() when the actor is ready
+const mount = createRenderer(catalog, { Home, Login, Dashboard });
+
+const actor = createPlayer();
+actor.start();
+
+const disconnect = mount(actor, document.getElementById("app")!);
+
+// Cleanup
+window.addEventListener("beforeunload", () => {
+	disconnect();
+	actor.stop();
+});
+```
+
+**Key points:**
+
+- `actions` in `defineCatalog` must include every action name referenced in `meta.view` `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
+- `on("submit").emit()` resolves `params` from the current state store at call time — the `$state: "/username"` in the spec is read at that moment, not at render time.
+- `ctx.store.update(fn)` is the standard write path for two-way binding. The spec's `$bindState` directive only wires the read direction (prop ← store); the write direction (store ← input) must be implemented in the component.
+
 ## Next Steps
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
+- **[play-dom README](../../packages/play-dom/README.md)** — Full `ComponentFn`, `ActionFn`, and spec directive reference
 - **[play-router README](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/examples/routing-patterns.md

@@ -249,20 +249,19 @@ import {
 	connectRouter,
 	createRouteMap,
 } from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
 
-const routeTree = extractMachineRoutes(authMachine);
+// createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
 const history = createBrowserHistory({ window });
-const router = createRouter({ routeTree, history });
+const router = createRouter({ routeTree: authMachine, history });
 
 // connectRouter handles all bidirectional sync:
-// - actor.currentRoute → browser URL
-// - browser URL changes → play.route event to actor
+// - actor.currentRoute signal → browser URL (history.push)
+// - browser URL changes → play.route event sent to actor
 const disconnect = connectRouter({ actor, router, routeMap });
 
-// cleanup on unload
+// Cleanup on unload
 window.addEventListener("beforeunload", () => {
 	disconnect();
 	router.destroy();
@@ -271,26 +270,17 @@ window.addEventListener("beforeunload", () => {
 
 ## React Router Setup
 
-For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react-router` with the `PlayRouterProvider` and `createRouteMapFromTree`:
+For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react-router`:
 
-```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
+```tsx
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 function App() {
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      router={router}
-      routeMap={routeMap}
-      renderer={(currentActor, currentRouter) => (
-        <Shell actor={currentActor} router={currentRouter} registry={registry} />
-      )}
-    />
-  );
+	return <PlayRouterProvider actor={actor} router={router} routeMap={routeMap} />;
 }
 ```
 

package/guides/README.md

@@ -9,6 +9,14 @@ Entry points for the current XMachines Play architecture.
 - **[Installation](installation.md)** — Core packages, framework-specific additions, TypeScript config, ESM setup
 - **[Getting Started](getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
 
+## Concepts
+
+Background reading that explains the _why_ behind XMachines design decisions. Read these when you want to understand the architecture, not just use the API.
+
+- **[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, scattered guards, and component-level routing logic
+- **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, what `AbstractActor` enforces, 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 five architectural invariants they enforce
+
 ## Examples
 
 - **[Examples Index](../examples/README.md)** — Conceptual patterns and complete runnable demo applications

package/guides/actor-model.md

@@ -0,0 +1,180 @@
+# Understanding the Actor Model and the Actor/Infrastructure Split
+
+XMachines is built around one central design principle: **business logic must never depend on infrastructure**. This page explains what that means, why the split is enforced the way it is, and what concrete responsibilities belong to each side of the boundary.
+
+After reading this, you will understand why a state machine in XMachines has no import from React, Vue, or any router — and why that constraint is a feature, not a limitation.
+
+---
+
+## Two roles, one boundary
+
+Every XMachines application has exactly two roles:
+
+**The Actor** — owns state, guards, routing intent, and view structure. It has zero knowledge of browsers, routing libraries, or UI frameworks.
+
+**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.
+
+```
+Actor (business logic)
+  │
+  │  emits signals: state, currentRoute, currentView
+  ▼
+Infrastructure (runtime adapters)
+  ├── Router Bridge — reflects currentRoute into the URL bar
+  ├── Renderer — renders currentView into framework components
+  └── ... (any other observer)
+
+Infrastructure → actor: only via actor.send({ type: "..." })
+```
+
+---
+
+## What the actor owns
+
+An actor in XMachines is a `PlayerActor` — a concrete class that extends XState's `Actor` class via `AbstractActor`. 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` that drives renderers. |
+
+All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
+
+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`) 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.
+
+---
+
+## What infrastructure owns
+
+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.
+
+Infrastructure does **not**:
+
+- Decide whether a `play.route` event is valid (that is the actor's job via guards).
+- Override the URL to something the actor did not emit.
+- Read `actor.getSnapshot()` to make routing decisions (use `actor.currentRoute` instead).
+
+---
+
+## The reset invariant
+
+One of the most important behaviors in XMachines falls out directly from this split.
+
+If a user navigates directly to `/admin` in the browser but the actor's guards reject that route (because the user is not authenticated), the actor:
+
+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"`.
+5. The router bridge, watching `currentRoute`, calls its `navigateRouter("/login")` method.
+6. The URL bar resets to `/login`.
+
+The environment is always made to match actor reality. The router bridge does not need any special "auth guard" logic — the state machine already has it.
+
+This is why the invariant is called **State-Driven Reset** in the Play RFC.
+
+---
+
+## `AbstractActor` — the enforced contract
+
+`AbstractActor` (from `@xmachines/play-actor`) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+
+- XState's inspection API works (`@xstate/inspect`)
+- XState DevTools attach to actors normally
+- The full XState ecosystem (testing utilities, visualization) is compatible
+
+`AbstractActor` 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.
+
+The two optional capability interfaces — `Routable` and `Viewable` — 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).
+
+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());
+}
+
+// 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);
+}
+```
+
+In practice you never write `PlayerActor` yourself — `definePlayer` from `@xmachines/play-xstate` creates one from your machine definition.
+
+---
+
+## `definePlayer` — the factory builder
+
+`definePlayer({ machine })` is the primary entry point for creating actors:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js";
+
+const createPlayer = definePlayer({ machine: myMachine });
+
+// Each call creates an independent actor instance
+const actor = createPlayer();
+actor.start();
+```
+
+`definePlayer` 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):
+
+```typescript
+const actor = createPlayer({ userId: "abc" }); // with input
+const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
+```
+
+---
+
+## Why the actor has no framework imports
+
+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` depends on `xstate` and `@xmachines/play-signals`. 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:
+
+- **Portable**: the same machine runs in a browser, a Node.js server, a web worker, and a Vitest test suite — with zero modification.
+- **Testable in isolation**: you test the machine with `actor.send()` and `actor.state.get()`. No DOM, no router, no React to mock.
+- **Replaceable infrastructure**: swap the React renderer for a Vue renderer, or swap TanStack Router for React Router, without touching the machine file.
+
+---
+
+## The lock statement
+
+The Play RFC captures the actor/infrastructure split in a single statement:
+
+> _Logic is sovereign. Infrastructure reflects, never decides. Capabilities compose, never prescribe. Logic owns structure and flow. Adapters project, never decide. This is Universal Player._
+
+---
+
+## See also
+
+- [Understanding TC39 Signals](signals.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 README](../api/@xmachines/play-actor/README.md) — API reference for `AbstractActor`
+- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — API reference for `definePlayer` and `PlayerActor`
+- [Play RFC](../rfc/play.md) — complete architectural specification