@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

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

@@ -1,473 +1,361 @@
-[Documentation](../../README.md) / @xmachines/play-xstate
+[API](../../README.md) / @xmachines/play-xstate
 
-# @xmachines/play-xstate
-
-**XState v5 adapter for Play Architecture with signal-driven reactivity and routing**
+<!-- generated-by: gsd-doc-writer -->
 
-Transform declarative state machines into live actors with TC39 Signals and parameter-aware navigation.
-
-## 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 with catalog binding, signal lifecycle management, and XState DevTools compatibility.
+> XState v6 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.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.51-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
+pnpm add @xmachines/play-xstate xstate
 ```
 
-**Peer dependencies:**
+`xstate ^6.0.0-alpha.19` is a peer dependency and must be installed alongside this package.
 
-- `xstate` ^5.0.0 — State machine runtime
-
-> `zod` is a direct dependency of `@xmachines/play-xstate` (not a peer). You do not need to install it separately unless you use it in your own catalog schemas.
+---
 
 ## Quick Start
 
 ```typescript
 import { setup } from "xstate";
-import { z } from "zod";
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
+import { definePlayer, emptyEventSchema, playMetaSchema } from "@xmachines/play-xstate";
 
-// 1. Define XState machine with meta.route
+// 1. Define your XState v6 machine
 const machine = setup({
-	types: {
-		context: {} as { userId: string },
-		events: {} as { type: "play.route"; to: string } | { type: "auth.login"; userId: string },
-	},
-	guards: {
-		isLoggedIn: ({ context }) => !!context.userId,
+	schemas: {
+		events: { activate: emptyEventSchema },
+		meta: playMetaSchema, // types meta.route / meta.view on state nodes
 	},
 }).createMachine({
-	id: "app",
-	initial: "login",
-	context: { userId: "" },
+	initial: "idle",
 	states: {
-		login: {
-			id: "login",
-			meta: {
-				route: "/login",
-				view: { component: "LoginForm" },
-			},
-			on: {
-				"auth.login": {
-					guard: "isLoggedIn",
-					target: "dashboard",
-				},
-			},
-		},
-		dashboard: {
-			id: "dashboard",
-			meta: {
-				route: "/dashboard",
-				view: { component: "Dashboard", props: { userId: "" } },
-			},
-		},
+		idle: { meta: { route: "/" }, on: { activate: { target: "active" } } },
+		active: { meta: { route: "/active" } },
 	},
 });
 
-// 2. Define catalog with Zod schemas
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({ userId: z.string() }),
-});
-
-// 3. Create player factory
-const createPlayer = definePlayer({ machine, catalog });
+// 2. Create a player factory
+const createPlayer = definePlayer({ machine });
 
-// 4. Create and start actor
-const actor = createPlayer({ userId: "" });
+// 3. Instantiate and start an actor
+const actor = createPlayer();
 actor.start();
 
-// 5. Send events (play.route with parameters)
-actor.send({ type: "play.route", to: "/login" });
+// 4. Observe TC39 Signal-based reactive state
+console.log(actor.currentRoute.get()); // "/"
+console.log(actor.state.get().value); // "idle"
 
-// 6. Observe signals
-console.log(actor.currentRoute.get()); // "/login"
-console.log(actor.currentView.get()); // { component: "LoginForm", props: {...} }
+// 5. Send events — machine guards decide transitions
+actor.send({ type: "activate" });
 
-// 7. Cleanup
-actor.dispose();
+actor.stop();
 ```
 
-## API Reference
+---
 
-### definePlayer()
+## API Summary
 
-Create a player factory from XState machine and catalog:
+### `definePlayer(config)`
 
-```typescript
-const createPlayer = definePlayer<TMachine, TCatalog>({
-	machine: AnyStateMachine,
-	catalog?: Catalog,
-	options?: PlayerOptions,
-}): PlayerFactory;
-```
+Creates a `PlayerFactory` from an XState v6 machine. The factory pattern enables multiple independent actor instances from a single configuration — useful for multi-user scenarios, SSR, or testing.
 
-**Config:**
-
-- `machine` (required) - XState v5 state machine
-- `catalog` (optional) - UI component catalog with Zod schemas
-- `options` (optional) - Lifecycle hooks
-
-**Returns:** Factory function `(input?) => PlayerActor`
+```typescript
+import { setup, types } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-**Example:**
+const machine = setup({
+	schemas: {
+		context: types<{ userId: string }>(),
+		input: types<{ userId: string }>(),
+	},
+}).createMachine({
+	context: ({ input }) => ({ userId: input.userId }),
+	initial: "home",
+	states: { home: {} },
+});
 
-```typescript
 const createPlayer = definePlayer({
-	machine: authMachine,
-	catalog: authCatalog,
+	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" });
 ```
 
-### PlayerActor
-
-Concrete actor implementing Play signal protocol:
+#### `PlayerFactory` signature
 
-**Signal Properties:**
+```typescript
+type PlayerFactory<TMachine> = (
+	input?: InputFrom<TMachine>,
+	options?: PlayerFactoryResumeOptions<TMachine>,
+) => PlayerActor<TMachine>;
+```
 
-- `state: Signal.State<AnyMachineSnapshot>` — Reactive snapshot of current state
-- `currentRoute: Signal.Computed<string | null>` — Derived navigation path
-- `currentView: Signal.State<ViewMetadata | null>` — Current UI structure (updated at state entry)
+#### Restoring from a snapshot
 
-**Actor Properties:**
+```typescript
+const snapshot = actor.getSnapshot();
+actor.stop();
 
-- `catalog: Catalog` — Component catalog
+// Restore to the exact saved state
+const restored = createPlayer({ userId: "alice" }, { snapshot });
+restored.start();
+console.log(restored.currentRoute.get()); // same route as when saved
+```
 
-**Constructor:**
+---
 
-```typescript
-new PlayerActor(machine, catalog, options, input?)
-```
+### `PlayerActor<TMachine>`
 
-- `input` — Typed as `InputFrom<TMachine>`. Consumers receive compile-time validation against the machine's input schema. Pass initial context values required by the machine.
+Concrete actor class that wraps an XState v6 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: PlayEvent)` — Send event to actor
-- `dispose()` — Convenience cleanup (calls stop())
+| 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) |
 
-**Prop validation modes** (via `PlayerOptions.propValidation`):
+#### Methods
 
-- `"lenient"` (default) — On catalog prop validation failure, calls `onError` hook and renders with unvalidated props
-- `"strict"` — On catalog prop validation failure, calls `onError` hook and sets `currentView` to `null` (blocks render)
+| 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()`                                             |
 
-**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 combine predicates with AND, OR, and NOT logic. Each helper returns a plain predicate — call it inside a transition function with the transition arguments and return early to block the transition. String guard names are resolved against the named guards declared in `setup({ guards })`.
 
 ```typescript
+import { setup } from "xstate";
 import {
-	composeGuards,
-	composeGuardsOr,
-	negateGuard,
-	hasContext,
-	eventMatches,
-	stateMatches,
+	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 canAccessAdmin = composeGuards(["isLoggedIn", "hasAdminRole"]);
+const isAuthenticated = negateGuard("isGuest");
+
 const machine = setup({
 	guards: {
-		isLoggedIn: hasContext("userId"),
-		isAdmin: ({ context }) => context.role === "admin",
+		isLoggedIn: ({ context }) => !!context.userId,
+		hasAdminRole: ({ context }) => context.role === "admin",
+		isGuest: ({ context }) => !context.userId,
 	},
 }).createMachine({
 	on: {
-		accessAdmin: {
-			// Array means AND - all guards must pass
-			guard: composeGuards(["isLoggedIn", "isAdmin"]),
-			target: "adminPanel",
+		accessAdmin: (args) => {
+			if (!canAccessAdmin(args)) return;
+			return { 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: (args) => {
+			if (!isAuthenticated(args)) return;
+			return { target: "dashboard" };
 		},
 	},
+	// ...
 });
 ```
 
-**Helpers:**
+---
 
-- `hasContext(path: string)` - Check if context property is truthy
-- `eventMatches(type: string)` - Check event type
-- `stateMatches(value: string)` - Check state value
-- `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
+#### `createRoutedMachine(setup)`
 
-**Guards check if you can BE in a state (state entry), not if you can TAKE an event (event handlers).**
+The recommended entry point: returns a `createMachine` with the same signature as the setup's own — full contextual typing for the config — that wires routing up at runtime.
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
+import { createRoutedMachine } from "@xmachines/play-xstate";
+
+const appSetup = setup({/* schemas, guards, ... */});
 
-// Pattern 1: RECOMMENDED - Use formatPlayRouteTransitions utility
-const machineConfig = {
+const machine = createRoutedMachine(appSetup)({
 	id: "app",
-	initial: "home",
-	context: { isAuthenticated: false },
 	states: {
 		home: {
 			id: "home",
-			meta: { route: "/", view: { component: "Home" } },
+			meta: { route: "/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" } },
+		profile: {
+			id: "profile",
+			meta: { route: "/users/:userId" },
 		},
 	},
-};
-
-// formatPlayRouteTransitions handles routing infrastructure
-const machine = setup({
-	types: {
-		events: {} as { type: "play.route"; to: string } | { type: "auth.login" },
-	},
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const catalog = defineCatalog({
-	Home,
-	Dashboard,
-	Login,
 });
-
-const createPlayer = definePlayer({ machine, catalog });
-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
+#### `formatPlayRouteTransitions(machineConfig)`
 
-**Anti-pattern (DON'T DO THIS):**
+The underlying transform. Crawls machine states with `meta.route` and wires them to XState v6's native routing: each routed state gets a native `route: {}` config (targetable via the built-in `xstate.route` event and visible to graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition — patching `params`/`query` into context — while re-raising `xstate.route` only for states that declare their own `route` config. Unknown targets fall through to user-defined `play.route` fallbacks (e.g. a 404 route); one `play.route` send is one atomic transition, so exit actions see the old `params` and entry actions the new ones.
 
 ```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
+import { setup } from "xstate";
+import {
+	formatPlayRouteTransitions,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
-```typescript
-const createPlayer = definePlayer({
-	machine,
-	catalog,
-	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(),
-			});
-		},
-		onStateChange: (actor, state) => {
-			// Called on every state update
-			console.log("Snapshot updated:", state.value);
+const config = formatPlayRouteTransitions({
+	id: "app",
+	states: {
+		home: {
+			id: "home",
+			meta: { route: "/home" },
 		},
-		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
+// config now carries native route configs plus the play.route forwarder:
+// states: { home: { ..., route: {} }, profile: { ..., route: {} } }
+// on: { "play.route": [forwarder, ...userFallbacks] }
+// The forwarder navigates injected-route targets directly (atomically);
+// xstate.route is raised only for states declaring their own route config.
+const machine = setup({
+	schemas: {
+		events: { "play.route": playRouteEventSchema },
+		meta: playMetaSchema,
+	},
+}).createMachine(config);
+```
 
-```typescript
-import { createBrowserInspector } from "@statelyai/inspect";
-import { definePlayer } from "@xmachines/play-xstate";
+Because the injected `route` configs are static, route transitions keep statically-known targets — `machineToGraph()` sees real edges to every routed state, so reachability queries work.
 
-const { inspect } = createBrowserInspector();
+> **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
 
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer();
-actor.start();
+#### Other routing exports
 
-// PlayerActor maintains XState Inspector compatibility
-// Inspector displays:
-// - State transitions and values
-// - Context data
-// - Events sent to actor
-// - Guard evaluation results
+| Export                             | Description                                                               |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| `playMetaSchema`                   | Shared `schemas.meta` declaration for `meta.route` / `meta.view` metadata |
+| `playRouteEventSchema`             | Shared `schemas.events` entry for the `play.route` event payload          |
+| `emptyEventSchema`                 | Shared `schemas.events` entry for events that carry no payload            |
+| `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 |
 
-// Signals accessible via actor properties, not snapshots
-console.log(actor.currentRoute.get()); // "/dashboard"
-```
-
-## Metadata Conventions
+---
 
-### Route Metadata
+## Exported Types
 
 ```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
-}
+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?, basePath?, hash? })
+	RouteObject, // Route metadata object shape: { path: string }
+	RouteMetadata, // Union: string | RouteObject
+} from "@xmachines/play-xstate";
 ```
 
-### View Metadata
+---
 
-```typescript
-meta: {
-	view: {
-		component: "Dashboard", // Must exist in catalog
-		props: { userId: "user123" }, // Validated against Zod schema
-		title: "Dashboard", // Additional metadata
-	},
-}
-
-// Dynamic props from context
-meta: {
-	view: {
-		component: "Dashboard",
-		props: (context) => ({
-			userId: context.userId,
-			notifications: context.unreadCount,
-		}),
-	},
-}
-```
+## Error Classes
 
-## Architecture
+Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to keep the main bundle lean.
 
-This package implements RFC Play v1 requirements:
-
-**Architectural Invariants:**
+```typescript
+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
+	UnresolvableGuardNameError, // string guard name could not be resolved at call time
+	InvalidGuardEntryError, // guard entry was neither a predicate nor a name (e.g. undefined)
+} from "@xmachines/play-xstate/errors";
+```
 
-- **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
+All error classes extend `PlayError` from `@xmachines/play` and carry typed detail fields (`param`, `template`, `combinator`, etc.) for programmatic inspection without message parsing.
 
-**XState DevTools:** Maintains Inspector compatibility — snapshots remain pure XState format, signals accessible via actor properties.
+---
 
-**Routing:**
+## Testing
 
-- `meta.route` property marks states as routable
-- `play.route` events support parameters (enhancement)
-- Route extraction for URL patterns
+```bash
+# Run tests for this package in isolation
+pnpm --filter @xmachines/play-xstate test
 
-**Note:** Route parameter extraction uses URLPattern API. See [@xmachines/play-tanstack-react-router browser support](../play-tanstack-react-router/README.md) for polyfill requirements.
+# Watch mode
+pnpm --filter @xmachines/play-xstate run test:watch
+```
 
-## Related Packages
+Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`.
 
-- **[@xmachines/play-actor](../play-actor/README.md)** - AbstractActor base class
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals polyfill
-- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
-- **[@xmachines/play-router](../play-router/README.md)** - Route extraction
-- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent)
+---
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+MIT — see [LICENSE](LICENSE) for details.
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
-
-@xmachines/play-xstate - XState v5 adapter for Play Architecture
+@xmachines/play-xstate - XState v6 adapter for Play Architecture
 
 Provides definePlayer() API for binding XState state machines to the
-actor base with catalog binding, signal lifecycle, and DevTools integration.
+actor base with signal lifecycle and DevTools integration.
 
-Per RFC Play v1, this package implements the Logic Layer adapter that
+Per the Play RFC, this package implements the Logic Layer adapter that
 transforms declarative machine definitions into live actors with signal-driven
 reactivity.
 
@@ -477,36 +365,42 @@ reactivity.
 
 ## Interfaces
 
-- [CatalogEntry](interfaces/CatalogEntry.md)
 - [PlayerConfig](interfaces/PlayerConfig.md)
+- [PlayerFactoryResumeOptions](interfaces/PlayerFactoryResumeOptions.md)
 - [PlayerOptions](interfaces/PlayerOptions.md)
 - [RouteContext](interfaces/RouteContext.md)
+- [RouteObject](interfaces/RouteObject.md)
 
 ## Type Aliases
 
-- [Catalog](type-aliases/Catalog.md)
 - [ComposedGuard](type-aliases/ComposedGuard.md)
 - [Guard](type-aliases/Guard.md)
 - [GuardArray](type-aliases/GuardArray.md)
 - [PlayerFactory](type-aliases/PlayerFactory.md)
+- [PlayRoutePayload](type-aliases/PlayRoutePayload.md)
 - [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
+- [RouteMetadata](type-aliases/RouteMetadata.md)
 - [RouteStateNode](type-aliases/RouteStateNode.md)
-- [ValidationResult](type-aliases/ValidationResult.md)
-- [ViewMergeContext](type-aliases/ViewMergeContext.md)
+- [SetupLike](type-aliases/SetupLike.md)
+- [WithOptional](type-aliases/WithOptional.md)
+
+## Variables
+
+- [emptyEventSchema](variables/emptyEventSchema.md)
+- [playMetaSchema](variables/playMetaSchema.md)
+- [playRouteEventSchema](variables/playRouteEventSchema.md)
 
 ## Functions
 
 - [buildRouteUrl](functions/buildRouteUrl.md)
 - [composeGuards](functions/composeGuards.md)
 - [composeGuardsOr](functions/composeGuardsOr.md)
+- [contextFieldMatches](functions/contextFieldMatches.md)
+- [createRoutedMachine](functions/createRoutedMachine.md)
 - [definePlayer](functions/definePlayer.md)
 - [deriveRoute](functions/deriveRoute.md)
 - [eventMatches](functions/eventMatches.md)
 - [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
 - [hasContext](functions/hasContext.md)
 - [isAbsoluteRoute](functions/isAbsoluteRoute.md)
-- [mergeViewProps](functions/mergeViewProps.md)
 - [negateGuard](functions/negateGuard.md)
-- [stateMatches](functions/stateMatches.md)
-- [validateComponentBinding](functions/validateComponentBinding.md)
-- [validateViewProps](functions/validateViewProps.md)