@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/api/@xmachines/play-xstate/README.md

@@ -1,628 +1,299 @@
 [API](../../README.md) / @xmachines/play-xstate
 
-# @xmachines/play-xstate
-
-**XState v5 adapter for Play Architecture with signal-driven reactivity and routing**
-
-Transform declarative state machines into live actors with TC39 Signals and parameter-aware navigation.
+<!-- generated-by: gsd-doc-writer -->
 
-## Overview
+# @xmachines/play-xstate
 
-`@xmachines/play-xstate` provides `definePlayer()`, the primary API for binding XState v5 state machines to the Play Architecture actor base. It enables business logic to control routing and state through guard-enforced transitions, signal lifecycle management, and XState DevTools compatibility.
+> XState v5 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
 
-Per [Play RFC](../../../rfc/play.md), this package implements:
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.0.0--beta.46-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
-- **Actor Authority (INV-01):** State machine guards decide navigation validity
-- **Strict Separation (INV-02):** Zero React/framework imports in business logic
-- **Signal-Only Reactivity (INV-05):** TC39 Signals expose all state changes
+Part of the [XMachines Play](../../README.md) monorepo.
 
-**Routing:** Supports `meta.route` patterns, `play.route` events with parameters, and route extraction.
+---
 
 ## Installation
 
 ```bash
-npm install xstate@^5.0.0
-npm install @xmachines/play-xstate
+npm install @xmachines/play-xstate xstate
 ```
 
-**Peer dependencies:**
+`xstate ^5.30.0` is a peer dependency and must be installed alongside this package.
 
-- `xstate` ^5.0.0 — State machine runtime
+---
 
 ## Quick Start
 
 ```typescript
-import { setup, assign } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Define XState machine with meta.route and view spec
-const machine = setup({
-	types: {
-		context: {} as {
-			isAuthenticated: boolean;
-			params: Record<string, string>;
-			query: Record<string, string>;
-		},
-		events: {} as
-			| { type: "play.route"; to: string; params?: Record<string, string> }
-			| { type: "auth.login" }
-			| { type: "auth.logout" },
+// 1. Define your XState v5 machine
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: { meta: { route: "/" } },
+		active: { meta: { route: "/active" } },
 	},
-}).createMachine(
-	formatPlayRouteTransitions({
-		id: "app",
-		initial: "login",
-		context: { isAuthenticated: false, params: {}, query: {} },
-		states: {
-			login: {
-				id: "login",
-				meta: {
-					route: "/login",
-					view: {
-						component: "Login",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Login", props: { title: "Sign In" }, children: [] },
-							},
-						},
-					},
-				},
-			},
-			dashboard: {
-				id: "dashboard",
-				meta: {
-					route: "/dashboard",
-					view: {
-						component: "Dashboard",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Dashboard", props: {}, children: [] },
-							},
-						},
-					},
-				},
-				always: [{ target: "login", guard: ({ context }) => !context.isAuthenticated }],
-			},
-		},
-		on: {
-			"auth.login": {
-				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: assign({ isAuthenticated: true }),
-			},
-			"auth.logout": {
-				target: ".login",
-				actions: assign({ isAuthenticated: false }),
-			},
-		},
-	}),
-);
+});
 
-// 2. Create player factory
+// 2. Create a player factory
 const createPlayer = definePlayer({ machine });
 
-// 3. Create and start actor
+// 3. Instantiate and start an actor
 const actor = createPlayer();
 actor.start();
 
-// 4. Observe signals
-console.log(actor.currentRoute.get()); // "/login"
-console.log(actor.currentView.get()); // { component: "Login", spec: {...} }
+// 4. Observe TC39 Signal-based reactive state
+console.log(actor.currentRoute.get()); // "/"
+console.log(actor.state.get().value); // "idle"
 
-// 5. Cleanup
-actor.dispose();
-```
+// 5. Send events — machine guards decide transitions
+actor.send({ type: "activate" });
 
-## API Reference
-
-### definePlayer()
-
-Create a player factory from an XState machine:
-
-```typescript
-const createPlayer = definePlayer<TMachine>({
-	machine: AnyStateMachine,
-	options?: PlayerOptions,
-}): PlayerFactory;
+actor.stop();
 ```
 
-**Config:**
+---
 
-- `machine` (required) - XState v5 state machine
-- `options` (optional) - Lifecycle hooks
+## API Summary
 
-**Returns:** Factory function `(input?, { snapshot }?) => PlayerActor`
+### `definePlayer(config)`
 
-**Example:**
+Creates a `PlayerFactory` from an XState v5 machine. The factory pattern enables multiple independent actor instances from a single configuration — useful for multi-user scenarios, SSR, or testing.
 
 ```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const machine = setup({
+	types: {
+		context: {} as { userId: string },
+		input: {} as { userId: string },
+	},
+}).createMachine({
+	context: ({ input }) => ({ userId: input.userId }),
+	initial: "home",
+	states: { home: {} },
+});
+
 const createPlayer = definePlayer({
-	machine: authMachine,
+	machine,
 	options: {
-		onStart: (actor) => console.log("Started:", actor.id),
-		onTransition: (actor, prev, next) => {
-			console.log("Transition:", prev.value, "→", next.value);
-		},
+		onStart: (actor) => console.log("started"),
+		onStop: (actor) => console.log("stopped"),
+		onTransition: (actor, prev, next) => console.log("transitioned"),
+		onStateChange: (actor, state) => console.log("state changed"),
+		onError: (actor, err) => console.error(err),
 	},
 });
 
-const actor1 = createPlayer({ userId: "user1" });
-const actor2 = createPlayer({ userId: "user2" });
-// Multiple independent actor instances
+// Each call returns an independent PlayerActor instance
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
 ```
 
-**Restoring from a snapshot:**
+#### `PlayerFactory` signature
 
 ```typescript
-const createPlayer = definePlayer({ machine });
+type PlayerFactory<TMachine> = (
+	input?: InputFrom<TMachine>,
+	options?: PlayerFactoryResumeOptions<TMachine>,
+) => PlayerActor<TMachine>;
+```
 
-const actor = createPlayer();
-actor.start();
+#### Restoring from a snapshot
 
-// ...persist the actor snapshot however your app stores it
+```typescript
 const snapshot = actor.getSnapshot();
 actor.stop();
 
-const restoredActor = createPlayer(undefined, { snapshot });
-restoredActor.start();
+// Restore to the exact saved state
+const restored = createPlayer({ userId: "alice" }, { snapshot });
+restored.start();
+console.log(restored.currentRoute.get()); // same route as when saved
 ```
 
-`restoredActor.initialRoute` still reflects the machine's default initial route, not the
-restored snapshot route. Router bridges rely on that invariant to distinguish a deep-link
-from a restored session during `connect()`.
-
-### PlayerActor
-
-Concrete actor implementing Play signal protocol:
-
-**Signal Properties:**
-
-- `state: Signal.State<AnyMachineSnapshot>` — Reactive snapshot of current state
-- `currentRoute: Signal.Computed<string | null>` — Derived URL from the current state's `meta.route` and `context.params`. Returns `null` when no route metadata is present or a required route parameter is missing from context.
-- `currentView: Signal.State<ViewMetadata | null>` — Current view spec (updated on every state transition). The spec is automatically enriched with `context.params` (URL params) and any `contextProps`-allowlisted context fields before being emitted (see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context)).
+---
 
-**Lifecycle ordering:**
+### `PlayerActor<TMachine>`
 
-- `state` and `currentRoute` update synchronously from the active XState snapshot.
-- `currentView` is then validated and cached from that same snapshot.
-- `onStateChange` runs after those signals are current.
-- `onTransition` runs after `send()` completes, with both previous and next snapshots.
-- `onStart` runs after the initial active snapshot has been published.
+Concrete actor class that wraps an XState v5 actor and exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
 
-**Methods:**
+#### Signals
 
-- `start()` — Start the actor (must call after creation)
-- `stop()` — Stop the actor
-- `send(event)` — Send event to actor. Typed as `EventFromLogic<TMachine>` when `TMachine` is specified.
-- `can(event)` — Returns `true` if the current state can accept the given event. Typed as `EventFromLogic<TMachine>` — passing an unknown event type is a compile error. Reads from the `state` signal (no allocation). Use instead of `getSnapshot().can()`.
-- `dispose()` — Convenience cleanup (calls `stop()`)
-- `getSnapshot()` — Get current XState snapshot, typed as `SnapshotFrom<TMachine>`
+| Signal         | Type                                   | Description                                                                                                      |
+| -------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | Current XState snapshot; updated on every active transition                                                      |
+| `currentRoute` | `Signal.Computed<string \| null>`      | Derived URL from active state's `meta.route` template and context                                                |
+| `currentView`  | `Signal.State<PlaySpec \| null>`       | View spec from active state's `meta.view` metadata; enriched with context params                                 |
+| `initialRoute` | `readonly string \| null`              | Machine's initial-state route (fixed at construction; used by router bridges for deep-link vs restore detection) |
 
-**Routing failure behavior:**
+#### Methods
 
-- `currentRoute` returns `null` instead of throwing when a required route parameter (e.g. `:username`) is absent from context. This handles transient states during navigation without crashing signal watchers.
-- Errors from `buildRouteUrl()` are typed as `MissingRouteParamError` (importable from `@xmachines/play-xstate/errors`).
+| Method          | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `start()`       | Start the actor and fire `onStart` hook                        |
+| `stop()`        | Stop the actor, clean up subscriptions, fire `onStop` hook     |
+| `send(event)`   | Send a typed event to the machine; fires `onTransition` hook   |
+| `can(event)`    | Returns `true` if the current state can accept the given event |
+| `getSnapshot()` | Returns the current XState snapshot                            |
+| `dispose()`     | Alias for `stop()`                                             |
 
-**View derivation and route-param enrichment:**
-
-- `currentView` emits a fresh `ViewMetadata` object on every transition so TC39 Signal equality checks always detect changes (including re-entries to the same state with different params).
-- `context.params` and `contextProps`-allowlisted context fields are merged into spec element props — see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context).
-
-**Example:**
+#### Signal usage example
 
 ```typescript
-const actor = createPlayer();
-actor.start();
+import { Signal } from "@xmachines/play-signals";
 
-// Observe signals with watcher
 const watcher = new Signal.subtle.Watcher(() => {
 	queueMicrotask(() => {
-		const route = actor.currentRoute.get();
-		console.log("Route changed:", route);
+		console.log("Route changed:", actor.currentRoute.get());
 	});
 });
+
 watcher.watch(actor.currentRoute);
-actor.currentRoute.get(); // Initial read
+actor.start();
 ```
 
-### Guard Composition
+---
+
+### Guard utilities
+
+Composable guard helpers that wrap XState's built-in `and()`, `or()`, and `not()` for use in machine `setup({ guards })` definitions.
 
 ```typescript
+import { setup } from "xstate";
 import {
-	composeGuards,
-	composeGuardsOr,
-	negateGuard,
-	hasContext,
-	eventMatches,
-	contextFieldMatches,
+	composeGuards, // AND logic: all guards must pass
+	composeGuardsOr, // OR logic:  at least one guard must pass
+	negateGuard, // NOT logic: inverts a guard
+	hasContext, // guard: context field is present and non-null
+	eventMatches, // guard: event type matches a string
+	contextFieldMatches, // guard: context field equals a value
 } from "@xmachines/play-xstate";
 
 const machine = setup({
 	guards: {
-		isLoggedIn: hasContext("userId"),
-		isAdmin: ({ context }) => context.role === "admin",
+		isLoggedIn: ({ context }) => !!context.userId,
+		hasAdminRole: ({ context }) => context.role === "admin",
 	},
 }).createMachine({
 	on: {
 		accessAdmin: {
-			// Array means AND - all guards must pass
-			guard: composeGuards(["isLoggedIn", "isAdmin"]),
+			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
-		accessPublic: {
-			// OR composition - any guard passes
-			guard: composeGuardsOr(["isLoggedIn", ({ event }) => event.type === "guest.access"]),
-			target: "publicArea",
-		},
-		logout: {
-			// NOT composition
-			guard: negateGuard("isLoggedIn"),
-			target: "login",
+		accessDashboard: {
+			guard: negateGuard("isGuest"),
+			target: "dashboard",
 		},
 	},
+	// ...
 });
 ```
 
-**Helpers:**
+---
 
-- `hasContext(path: string)` - Check if context property is truthy
-- `eventMatches(type: string)` - Check event type
-- `contextFieldMatches(fieldPath: string, expectedValue: unknown)` - Check context field with strict structural equality
-- `composeGuards(guards: Array)` - AND composition
-- `composeGuardsOr(guards: Array)` - OR composition
-- `negateGuard(guard)` - NOT composition
+### Routing utilities
 
-## Examples
+Helper functions for declarative route configuration in XState machines.
 
-### Guard Placement Philosophy
+#### `formatPlayRouteTransitions(machineConfig)`
 
-**Guards check if you can BE in a state (state entry), not if you can TAKE an event (event handlers).**
+Crawls machine states with `meta.route` and auto-generates `play.route` event handlers at the root level — eliminating boilerplate routing transitions.
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
 
-// Pattern 1: RECOMMENDED - Use formatPlayRouteTransitions utility
-const machineConfig = {
+const config = formatPlayRouteTransitions({
 	id: "app",
-	initial: "home",
-	context: { isAuthenticated: false },
 	states: {
 		home: {
 			id: "home",
-			meta: { route: "/", view: { component: "Home" } },
-		},
-		dashboard: {
-			id: "dashboard",
-			meta: { route: "/dashboard", view: { component: "Dashboard" } },
-			// Always-guard validates state entry
-			always: [
-				{
-					target: "login",
-					guard: ({ context }) => !context.isAuthenticated,
-				},
-			],
-		},
-		login: {
-			id: "login",
-			meta: { route: "/login", view: { component: "Login" } },
-		},
-	},
-};
-
-// formatPlayRouteTransitions handles routing infrastructure
-const machine = setup({
-	types: {
-		context: {} as {
-			isAuthenticated: boolean;
-			params: Record<string, string>;
-			query: Record<string, string>;
-		},
-		events: {} as
-			| { type: "play.route"; to: string; params?: Record<string, string> }
-			| { type: "auth.login" },
-	},
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const createPlayer = definePlayer({ machine });
-const actor = createPlayer();
-actor.start();
-
-// Navigation via play.route event
-actor.send({ type: "play.route", to: "/dashboard" });
-// Guard validates: Can I BE in dashboard state?
-// If !isAuthenticated → redirects to login
-```
-
-**Why this works:**
-
-- `formatPlayRouteTransitions` adds routing infrastructure (event.to → state mapping)
-- Always-guards handle business logic (authentication checks)
-- Clear separation: routing is infrastructure, guards are business logic
-
-**Anti-pattern (DON'T DO THIS):**
-
-```typescript
-// ❌ WRONG - Guard on event checking event properties
-on: {
-  "play.route": {
-    guard: ({ event }) => event.to === "/dashboard",
-    target: "dashboard"
-  }
-}
-```
-
-**Reference:** See `docs/examples/routing-patterns.md` for canonical `formatPlayRouteTransitions` usage with always-guards for authentication.
-
-### Lifecycle Hooks
-
-```typescript
-const createPlayer = definePlayer({
-	machine,
-	options: {
-		onStart: (actor) => {
-			console.log("Actor started:", actor.id);
-		},
-		onStop: (actor) => {
-			console.log("Actor stopped:", actor.id);
-		},
-		onTransition: (actor, prev, next) => {
-			console.log("State change:", {
-				from: prev.value,
-				to: next.value,
-				timestamp: Date.now(),
-			});
+			meta: { route: "/home" },
 		},
-		onStateChange: (actor, state) => {
-			// Called on every state update
-			console.log("Snapshot updated:", state.value);
-		},
-		onError: (actor, error) => {
-			console.error("Actor error:", error);
-			// Log to monitoring service, show error UI, etc.
+		profile: {
+			id: "profile",
+			meta: { route: "/users/:userId" },
 		},
 	},
 });
-```
-
-### XState DevTools Integration
-
-```typescript
-import { createBrowserInspector } from "@statelyai/inspect";
-import { definePlayer } from "@xmachines/play-xstate";
 
-const { inspect } = createBrowserInspector();
-
-const createPlayer = definePlayer({ machine });
-const actor = createPlayer();
-actor.start();
-
-// PlayerActor maintains XState Inspector compatibility
-// Inspector displays:
-// - State transitions and values
-// - Context data
-// - Events sent to actor
-// - Guard evaluation results
-
-// Signals accessible via actor properties, not snapshots
-console.log(actor.currentRoute.get()); // "/dashboard"
+// config now includes auto-generated play.route handlers:
+// on: { "play.route": [ { target: ".home", guard: e => e.to === "#home" }, ... ] }
+const machine = setup({}).createMachine(config);
 ```
 
-## Metadata Conventions
+> **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
 
-### Route Metadata
+#### Other routing exports
 
-```typescript
-// meta.route marks states as routable
-states: {
-	dashboard: {
-		id: "dashboard",
-		meta: {
-			route: "/dashboard", // URL path - marks state as routable
-		},
-	},
-}
-
-// Parameters
-meta: {
-	route: "/profile/:userId", // Required parameter
-	route: "/settings/:section?", // Optional parameter
-}
-
-// Inheritance
-meta: {
-	route: "/absolute", // Starts with / → doesn't inherit parent route
-	route: "relative", // Doesn't start with / → inherits parent route
-}
-```
-
-### View Metadata
+| Export                             | Description                                                               |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| `deriveRoute(meta)`                | Extract the route template string from a state's metadata object          |
+| `isAbsoluteRoute(route)`           | Returns `true` if the route string is an absolute URL path                |
+| `buildRouteUrl(template, context)` | Substitute `:param` placeholders in a route template using context values |
 
-View metadata drives the `currentView` signal. The `spec` field follows the `@json-render/core` `Spec` shape:
-
-```typescript
-meta: {
-	view: {
-		component: "Dashboard",  // Component name — must exist in the registry
-		spec: {
-			root: "root",         // Root element key
-			state: { tab: "general" },  // Optional: initial UI state (form values etc.)
-			elements: {
-				root: {
-					type: "Dashboard",
-					props: { title: "Dashboard" },  // Static props (non-undefined = cannot be overridden by route params)
-					children: [],
-				},
-			},
-		},
-	},
-}
-```
+---
 
-**Prop slots:** Declare a prop as `undefined` to allow URL params or context fields to fill
-it in automatically (see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context)):
+## Exported Types
 
 ```typescript
-// Route: /settings/:section?   Context: { username: "alice" }
-spec: {
-  root: "root",
-  contextProps: ["username"],    // expose context.username to components
-  elements: {
-    root: { type: "Settings", props: { section: undefined, username: undefined, theme: "dark" }, children: [] },
-  },
-}
-// After play.route to /settings/profile:
-// Component receives: { section: "profile", username: "alice", theme: "dark" }
-//   section  → from context.params (URL)
-//   username → from contextProps (context)
-//   theme    → from spec (explicit value, untouched)
-```
-
-## Error Handling
-
-All runtime errors thrown by this package extend `PlayError` from `@xmachines/play` and
-are exported from the `./errors` subpath:
-
-```typescript
-import { MissingRouteParamError, InvalidEventError } from "@xmachines/play-xstate/errors";
-```
-
-| Class                    | Code                       | When thrown                                              |
-| ------------------------ | -------------------------- | -------------------------------------------------------- |
-| `MissingRouteParamError` | `PLAY_ROUTE_PARAM_MISSING` | Required `:param` has no matching value in actor context |
-| `InvalidEventError`      | `PLAY_INVALID_EVENT`       | `actor.send()` called with a non-object value            |
-
-`MissingRouteParamError` carries `param` and `template` fields for programmatic access.
-`InvalidEventError` carries a `detail` property with the offending value.
-
-> **Note:** `currentRoute` does NOT throw `MissingRouteParamError` — it catches the error internally and returns `null` instead, keeping signal watchers stable during transient states.
-
-```typescript
-import { MissingRouteParamError, InvalidEventError } from "@xmachines/play-xstate/errors";
-
-try {
-	actor.send(null as any);
-} catch (err) {
-	if (err instanceof InvalidEventError) {
-		console.error("Non-object event passed to actor.send():", err.detail);
-	}
-}
-
-try {
-	const route = actor.currentRoute.get();
-} catch (err) {
-	if (err instanceof MissingRouteParamError) {
-		console.error(`Missing "${err.param}" for template "${err.template}"`);
-	}
-}
+import type {
+	PlayerConfig, // definePlayer() config argument shape
+	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError)
+	PlayerFactory, // Factory function returned by definePlayer()
+	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
+	Guard, // Single XState guard predicate
+	GuardArray, // Array of guards for compose helpers
+	ComposedGuard, // Return type of composeGuards / composeGuardsOr / negateGuard
+	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
+	RouteStateNode, // Single state node shape used during route crawling
+	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query? })
+} from "@xmachines/play-xstate";
 ```
 
-## Prop Enrichment from Routing and Context
-
-When `currentView` is derived, each spec element's `props` are enriched from two sources.
-Both use the **opt-in slot** pattern: declare a prop as `undefined` in the spec to allow
-it to be filled in automatically.
-
-### Merge priority (highest → lowest)
-
-| Source                             | When it applies                  | Wins over                 |
-| ---------------------------------- | -------------------------------- | ------------------------- |
-| Explicit non-`undefined` spec prop | Always                           | Everything                |
-| URL route param (`context.params`) | State has a `:param` URL segment | `contextProps` values     |
-| `contextProps` field               | Listed in `spec.contextProps`    | Nothing (lowest priority) |
-
-### URL route parameters
-
-URL path parameters (`:section?`, `:username`) are filled automatically — declare the prop
-as `undefined` to opt in:
-
-```typescript
-// Route: /settings/:section?
-elements: {
-  root: { type: "Settings", props: { section: undefined, user: "alice" }, children: [] }
-}
+---
 
-// play.route event: { to: "#settings", params: { section: "profile" } }
-// Component receives: { section: "profile", user: "alice" }
-```
+## Error Classes
 
-Extra params not declared in the spec are also passed through:
+Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to keep the main bundle lean.
 
 ```typescript
-// params: { section: "profile", tab: "security" }
-// Component receives: { section: "profile", tab: "security", user: "alice" }
+import {
+	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
+	MissingQueryContextError, // context.params present but context.query missing
+	MissingStateIdError, // meta.route declared without a state id field
+	InvalidMachineError, // PlayerActor constructed with a non-object machine
+	InvalidEventError, // actor.send() called with null/undefined/non-object
+	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
+	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
+} from "@xmachines/play-xstate/errors";
 ```
 
-### Context fields via `contextProps`
+All error classes extend `PlayError` from `@xmachines/play` and carry typed detail fields (`param`, `template`, `combinator`, etc.) for programmatic inspection without message parsing.
 
-For states where context data (e.g. `context.username`) should reach a component but there
-is no corresponding URL param, declare `contextProps` in the spec as an explicit allowlist:
+---
 
-```typescript
-// Dashboard at /dashboard — no :username URL param, but we want to show context.username
-spec: {
-  root: "root",
-  contextProps: ["username"],          // ← explicit allowlist
-  elements: {
-    root: { type: "Dashboard", props: { username: undefined }, children: [] },
-  },
-}
-
-// After auth.login sets context.username = "alice":
-// Component receives: { username: "alice" }
-```
+## Testing
 
-**Nothing leaks from context without an explicit `contextProps` declaration.**
-Only the named fields are ever exposed. `null` and `undefined` context values are excluded.
-
-If both a route param and a `contextProps` field share the same key, the route param wins:
+```bash
+# Run tests for this package in isolation
+npm test -w packages/play-xstate
 
-```typescript
-// context.username = "alice" (logged-in user)
-// play.route to /profile/demo → context.params.username = "demo"
-// contextProps: ["username"], props: { username: undefined }
-// Component receives: { username: "demo" }  ← route param wins
+# Watch mode
+npm run test:watch -w packages/play-xstate
 ```
 
-## Architecture
-
-This package implements Play RFC requirements:
+Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`.
 
-**Architectural Invariants:**
-
-- **Actor Authority (INV-01):** Guards decide navigation validity
-- **Strict Separation (INV-02):** Zero framework imports
-- **Signal-Only Reactivity (INV-05):** All state via TC39 Signals
-
-**XState DevTools:** Maintains Inspector compatibility — snapshots remain pure XState format, signals accessible via actor properties.
-
-**Routing:**
-
-- `meta.route` property marks states as routable
-- `play.route` events support parameters (enhancement)
-- Route extraction for URL patterns
-
-**Note:** Route parameter extraction uses URLPattern API. See [@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md) for polyfill requirements.
-
-## Related Packages
-
-- **[@xmachines/play-actor](../play-actor/README.md)** - AbstractActor base class
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals polyfill
-- **[@xmachines/play-router](../play-router/README.md)** - Route extraction utilities
-- **[@xmachines/play-react](../play-react/README.md)** - React renderer
-- **[@xmachines/play-vue](../play-vue/README.md)** - Vue renderer
-- **[@xmachines/play-solid](../play-solid/README.md)** - SolidJS renderer
-- **[@xmachines/play-dom](../play-dom/README.md)** - Vanilla DOM renderer
-- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent)
+---
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE) for details.
 
 @xmachines/play-xstate - XState v5 adapter for Play Architecture