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

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

@@ -31,7 +31,7 @@ Use this order to understand the implementation:
 2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes hash URL changes with the actor via `play.route` events and reflects actor-approved routes back to the hash 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).
+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-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: {
@@ -307,7 +298,7 @@ window.addEventListener("beforeunload", () => {
 
 **Key points:**
 
-- `actions` in `defineCatalog` must include every action name referenced in `meta.view` spec `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
+- `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.
 

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

package/guides/getting-started.md

@@ -206,10 +206,10 @@ window.addEventListener("beforeunload", () => {
 });
 ```
 
-**React** — use `PlayRenderer` from `@xmachines/play-react`:
+**React** — use `PlayUIProvider` + `PlayRenderer` from `@xmachines/play-react`:
 
 ```tsx
-import { PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { authCatalog } from "@xmachines/play-actor-shared";
 import { Home, Login } from "./components/index.js";
 
@@ -222,7 +222,11 @@ const registryResult = defineRegistry(authCatalog, {
 });
 
 function App() {
-	return <PlayRenderer actor={actor} registryResult={registryResult} />;
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
@@ -288,17 +292,17 @@ actor.stop();
 
 ## Glossary
 
-| Term                         | Description                                                                                            |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input                       |
-| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                               |
-| `actor.start()`              | Activates the machine — always call before sending events                                              |
-| `actor.send({ type })`       | Sends an event to the machine                                                                          |
-| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                                  |
-| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                  |
-| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`                  |
-| `actor.currentView`          | `Signal.State<ViewMetadata \| null>` — view spec from the active state's `meta.view`; drives renderers |
-| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs                      |
+| Term                         | Description                                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input                   |
+| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                           |
+| `actor.start()`              | Activates the machine — always call before sending events                                          |
+| `actor.send({ type })`       | Sends an event to the machine                                                                      |
+| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                              |
+| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                              |
+| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`              |
+| `actor.currentView`          | `Signal.State<PlaySpec \| null>` — view spec from the active state's `meta.view`; drives renderers |
+| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs                  |
 
 ## Next Steps