@xmachines/play-xstate 1.0.0-beta.9 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,463 +1,296 @@
-# @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 v5 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 ^5.31.0` 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";
 
-// 1. Define XState machine with meta.route
-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,
-	},
-}).createMachine({
-	id: "app",
-	initial: "login",
-	context: { userId: "" },
+// 1. Define your XState v5 machine
+const machine = setup({}).createMachine({
+	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: "/" } },
+		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() }),
-});
+// 2. Create a player factory
+const createPlayer = definePlayer({ machine });
 
-// 3. Create player factory
-const createPlayer = definePlayer({ machine, catalog });
-
-// 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;
-```
-
-**Config:**
-
-- `machine` (required) - XState v5 state machine
-- `catalog` (optional) - UI component catalog with Zod schemas
-- `options` (optional) - Lifecycle hooks
+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.
 
-**Returns:** Factory function `(input?) => PlayerActor`
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-**Example:**
+const machine = setup({
+	types: {
+		context: {} as { userId: string },
+		input: {} as { 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
+#### `PlayerFactory` signature
 
-Concrete actor implementing Play signal protocol:
-
-**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 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: 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 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,
-	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 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
-- `stateMatches(value: string)` - Check state value
-- `composeGuards(guards: Array)` - AND composition
-- `composeGuardsOr(guards: Array)` - OR composition
-- `negateGuard(guard)` - NOT composition
+---
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-xstate)
+### 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 { defineCatalog } from "@xmachines/play-catalog";
+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,
-				},
-			],
+			meta: { route: "/home" },
 		},
-		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
+// config now includes auto-generated play.route handlers:
+// on: { "play.route": [ { target: ".home", guard: e => e.to === "#home" }, ... ] }
+const machine = setup({}).createMachine(config);
 ```
 
-**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
+> **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
 
-**Anti-pattern (DON'T DO THIS):**
+#### Other routing exports
 
-```typescript
-// ❌ WRONG - Guard on event checking event properties
-on: {
-  "play.route": {
-    guard: ({ event }) => event.to === "/dashboard",
-    target: "dashboard"
-  }
-}
-```
+| 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 |
 
-**Reference:** See `docs/examples/routing-patterns.md` for canonical `formatPlayRouteTransitions` usage with always-guards for authentication.
+---
 
-### Lifecycle Hooks
+## Exported Types
 
 ```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);
-		},
-		onError: (actor, error) => {
-			console.error("Actor error:", error);
-			// Log to monitoring service, show error UI, etc.
-		},
-	},
-});
-```
-
-### XState DevTools Integration
-
-```typescript
-import { createBrowserInspector } from "@statelyai/inspect";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const { inspect } = createBrowserInspector();
-
-const createPlayer = definePlayer({ machine, catalog });
-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"
+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";
 ```
 
-## Metadata Conventions
+---
 
-### Route Metadata
+## Error Classes
 
-```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
+Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to keep the main bundle lean.
 
 ```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,
-		}),
-	},
-}
+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";
 ```
 
-## Architecture
+All error classes extend `PlayError` from `@xmachines/play` and carry typed detail fields (`param`, `template`, `combinator`, etc.) for programmatic inspection without message parsing.
 
-This package implements RFC Play v1 requirements:
+---
 
-**Architectural Invariants:**
+## Testing
 
-- **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
+```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#browser-support) 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)** - AbstractActor base class
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals polyfill
-- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
-- **[@xmachines/play-router](../play-router)** - Route extraction
-- **[@xmachines/play](../play)** - 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.