@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-xstate/functions/buildRouteUrl.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
 
 # Function: buildRouteUrl()
 
@@ -6,38 +6,42 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/build-url.ts#L28)
+Defined in: [packages/play-xstate/src/routing/build-url.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/build-url.ts#L35)
 
-Build full URL from route template and context
+Build a full URL from a route template and the actor's context.
 
-Per CONTEXT.md:
+Substitutes `:param` and `:param?` placeholders from `context.params`,
+then appends query params and hash fragments.
 
-- "currentRoute derivation: Full URL generation including query params, hash, base path"
-- "Parameters: String template syntax — /user/:id"
-- "Inheritance: relative paths inherit parent route"
-
-Per RESEARCH.md Pattern 3: Replace :param with context values
+All parameter values must be in `context.params`. Flat context fields are not
+inspected — this is intentional so misspelled placeholders produce a compile-time
+error rather than silently resolving to `undefined`.
 
 ## Parameters
 
-| Parameter       | Type                                            | Description                                |
-| --------------- | ----------------------------------------------- | ------------------------------------------ |
-| `routeTemplate` | `string`                                        | Route path with :param placeholders        |
-| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Route context with parameters, query, hash |
+| Parameter       | Type                                            | Description                                                                                                                                                                           |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routeTemplate` | `string`                                        | Route path template, e.g. `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                            |
+| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Actor context object. Route parameters must be in `context.params`; flat context fields are not inspected. A missing `query` field builds a query-less URL, exactly like `query: {}`. |
 
 ## Returns
 
 `string`
 
-Full URL string
+The fully resolved URL string.
+
+## Throws
+
+When a **required** `:param` placeholder has no
+matching value in context. Optional parameters (`:param?`) are silently omitted
+when missing. Import the class from `@xmachines/play-xstate/errors`.
 
 ## Example
 
 ```typescript
-const url = buildRouteUrl("/user/:id", {
-	id: "123",
-	query: { tab: "profile" },
-	hash: "section-1",
-});
-// Result: '/user/123?tab=profile#section-1'
+buildRouteUrl("/user/:id", { params: { id: "123" }, query: { tab: "profile" }, hash: "top" });
+// → "/user/123?tab=profile#top"
+
+buildRouteUrl("/settings/:section?", { params: {}, query: {} });
+// → "/settings"  (optional param omitted, no query string)
 ```

package/api/@xmachines/play-xstate/functions/composeGuards.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
 
-# Function: composeGuards()
+# ~~Function: composeGuards()~~
 
 ```ts
 function composeGuards<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L72)
+Defined in: [packages/play-xstate/src/guards/compose.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/compose.ts#L82)
 
 Compose guards with AND logic using XState's and() helper
 
@@ -77,3 +77,8 @@ guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => conte
 
 - [composeGuardsOr](composeGuardsOr.md) for OR composition
 - [negateGuard](negateGuard.md) for NOT logic
+
+## Deprecated
+
+Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+compose with `setup()`-typed guard slots and will be removed in the next major.

package/api/@xmachines/play-xstate/functions/composeGuardsOr.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
 
-# Function: composeGuardsOr()
+# ~~Function: composeGuardsOr()~~
 
 ```ts
 function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L138)
+Defined in: [packages/play-xstate/src/guards/compose.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/compose.ts#L149)
 
 Compose guards with OR logic using XState's or() helper
 
@@ -65,3 +65,8 @@ const machine = setup({
 
 - [composeGuards](composeGuards.md) for AND composition
 - [negateGuard](negateGuard.md) for NOT logic
+
+## Deprecated
+
+Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+compose with `setup()`-typed guard slots and will be removed in the next major.

package/api/@xmachines/play-xstate/functions/contextFieldMatches.md

@@ -0,0 +1,43 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / contextFieldMatches
+
+# ~~Function: contextFieldMatches()~~
+
+```ts
+function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
+```
+
+Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/helpers.ts#L75)
+
+Check if a context field matches an expected value.
+
+- Accepts an explicit dot-separated field path (e.g. `"user.role"`)
+- Uses strict equality for primitives, deep structural equality for objects
+- Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
+- Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
+- Does NOT use substring matching — `"a"` will not match `"active"`
+
+For XState state-node matching, use the built-in `in:` guard syntax instead.
+
+## Type Parameters
+
+| Type Parameter | Default type                    |
+| -------------- | ------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\> |
+
+## Parameters
+
+| Parameter       | Type      | Description                                                          |
+| --------------- | --------- | -------------------------------------------------------------------- |
+| `fieldPath`     | `string`  | Dot-separated path to context property (e.g., "status", "user.role") |
+| `expectedValue` | `unknown` | Value to compare against (string, object, Date, etc.)                |
+
+## Returns
+
+[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
+
+Guard predicate checking if context field matches
+
+## Deprecated
+
+Part of the guard utilities slated for removal in the next major —
+write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/definePlayer.md

@@ -1,36 +1,31 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
 
 # Function: definePlayer()
 
 ```ts
-function definePlayer<TMachine, TCatalog>(config): PlayerFactory<TMachine>;
+function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/define-player.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/define-player.ts#L111)
+Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/define-player.ts#L61)
 
-Create a player factory from XState machine and catalog
+Create a player factory from an XState machine
 
-Factory pattern that accepts an XState v5 machine and optional UI catalog,
+Factory pattern that accepts an XState v5 machine,
 returning a function that creates [PlayerActor](../classes/PlayerActor.md) instances. This enables
 creating multiple actor instances from a single configuration, useful for
 testing, multi-instance scenarios, or server-side rendering.
 
-**Architectural Context:** Implements **Strict Separation (INV-02)** by accepting
-the machine definition (pure business logic) separately from the catalog (UI vocabulary).
-The machine references component names in `meta.view` without importing React/framework code.
-
 ## Type Parameters
 
-| Type Parameter                         | Default type                    | Description                        |
-| -------------------------------------- | ------------------------------- | ---------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` | -                               | XState v5 state machine type       |
-| `TCatalog`                             | `Record`\<`string`, `unknown`\> | Optional UI component catalog type |
+| Type Parameter                                                                                 | Description                  |
+| ---------------------------------------------------------------------------------------------- | ---------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine type |
 
 ## Parameters
 
-| Parameter | Type                                                                      | Description                 |
-| --------- | ------------------------------------------------------------------------- | --------------------------- |
-| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`, `TCatalog`\> | Player configuration object |
+| Parameter | Type                                                          | Description                 |
+| --------- | ------------------------------------------------------------- | --------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | Player configuration object |
 
 ## Returns
 
@@ -40,7 +35,7 @@ Factory function that creates actor instances with optional input context
 
 ## Examples
 
-Basic player factory without catalog
+Basic player factory
 
 ```typescript
 import { setup } from "xstate";
@@ -59,54 +54,10 @@ const actor = createPlayer();
 actor.start();
 ```
 
-Player factory with catalog and parameter-aware routing
-
-```typescript
-import { setup } from "xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { definePlayer } from "@xmachines/play-xstate";
-import { z } from "zod";
-
-const catalog = defineCatalog({
-	HomePage: z.object({}),
-	ProfilePage: z.object({ userId: z.string() }),
-});
-
-const machine = setup({
-	types: {
-		context: {} as { userId: string },
-		events: {} as { type: "play.route"; to: string; params?: Record<string, string> },
-	},
-}).createMachine({
-	initial: "home",
-	context: { userId: "" },
-	states: {
-		home: {
-			route: {},
-			meta: {
-				route: "/",
-				view: { component: "HomePage" },
-			},
-		},
-		profile: {
-			route: {},
-			meta: {
-				route: "/profile/:userId",
-				view: { component: "ProfilePage", userId: (ctx) => ctx.userId },
-			},
-		},
-	},
-});
-
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer({ userId: "user123" });
-actor.start();
-```
-
 Multiple actor instances from single factory
 
 ```typescript
-const createPlayer = definePlayer({ machine, catalog });
+const createPlayer = definePlayer({ machine });
 
 // Create actors for different users
 const alice = createPlayer({ userId: "alice" });
@@ -121,7 +72,7 @@ console.log(alice.state.get() !== bob.state.get());
 
 ## See
 
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [Play RFC](../../../../rfc/play.md)
 - [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
 - [PlayerConfig](../interfaces/PlayerConfig.md) for configuration options
 - [PlayerFactory](../type-aliases/PlayerFactory.md) for factory function signature

package/api/@xmachines/play-xstate/functions/deriveRoute.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
 
 # Function: deriveRoute()
 
@@ -6,7 +6,7 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/derive-route.ts#L90)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/derive-route.ts#L91)
 
 Derive route from XState state metadata
 
@@ -94,7 +94,7 @@ console.log(route); // "/dashboard"
 
 ## See
 
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [Play RFC](../../../../rfc/play.md)
 - [buildRouteUrl](buildRouteUrl.md) for URL construction with parameter substitution
 - [isAbsoluteRoute](isAbsoluteRoute.md) for checking path absoluteness
 

package/api/@xmachines/play-xstate/functions/eventMatches.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
 
-# Function: eventMatches()
+# ~~Function: eventMatches()~~
 
 ```ts
 function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/helpers.ts#L49)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/helpers.ts#L52)
 
 Check if event type matches expected type
 
@@ -38,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+Part of the guard utilities slated for removal in the next major —
+write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
 
 # Function: formatPlayRouteTransitions()
 
@@ -6,7 +6,7 @@
 function formatPlayRouteTransitions<T>(machineConfig): T;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L65)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L89)
 
 Formats play.route transitions from declarative route configs
 
@@ -51,4 +51,4 @@ This automatically generates play.route handlers at the root level that:
 
 - Match event.to against state IDs (e.g., event.to === "#home")
 - Target the appropriate state
-- Assign routeParams and queryParams from the event to context
+- Assign params and query from the event to context

package/api/@xmachines/play-xstate/functions/hasContext.md

@@ -1,17 +1,15 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
 
-# Function: hasContext()
+# ~~Function: hasContext()~~
 
 ```ts
 function hasContext<TContext>(path): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/helpers.ts#L23)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/helpers.ts#L24)
 
 Check if context has a truthy value at path
 
-Per CONTEXT.md: Convenience helper for common guard pattern
-
 ## Type Parameters
 
 | Type Parameter | Default type                    |
@@ -40,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+Part of the guard utilities slated for removal in the next major —
+write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/isAbsoluteRoute.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
 
 # Function: isAbsoluteRoute()
 
@@ -6,7 +6,7 @@
 function isAbsoluteRoute(path): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/derive-route.ts#L150)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/derive-route.ts#L160)
 
 Check if route path is absolute
 

package/api/@xmachines/play-xstate/functions/negateGuard.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
 
-# Function: negateGuard()
+# ~~Function: negateGuard()~~
 
 ```ts
 function negateGuard<TContext, TEvent>(guard): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:198](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L198)
+Defined in: [packages/play-xstate/src/guards/compose.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/compose.ts#L211)
 
 Negate a guard using XState's not() helper
 
@@ -59,3 +59,8 @@ const machine = setup({
 
 - [composeGuards](composeGuards.md) for AND composition
 - [composeGuardsOr](composeGuardsOr.md) for OR composition
+
+## Deprecated
+
+Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+compose with `setup()`-typed guard slots and will be removed in the next major.

package/api/@xmachines/play-xstate/interfaces/PlayerConfig.md

@@ -1,24 +1,20 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerConfig
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerConfig
 
-# Interface: PlayerConfig\<TMachine, TCatalog\>
+# Interface: PlayerConfig\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L9)
+Defined in: [packages/play-xstate/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L7)
 
 Configuration for definePlayer()
 
-Per CONTEXT.md: Single config object with machine, catalog, options
-
 ## Type Parameters
 
-| Type Parameter                         | Default type                    |
-| -------------------------------------- | ------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` | -                               |
-| `TCatalog`                             | `Record`\<`string`, `unknown`\> |
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
 
 ## Properties
 
-| Property                                 | Type                                              | Description                                                  | Defined in                                                                                                                                                               |
-| ---------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-catalog"></a> `catalog?` | `TCatalog`                                        | UI component catalog (optional - allows machines without UI) | [packages/play-xstate/src/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L17) |
-| <a id="property-machine"></a> `machine`  | `TMachine`                                        | XState v5 state machine                                      | [packages/play-xstate/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L14) |
-| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | Lifecycle hooks and configuration                            | [packages/play-xstate/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L20) |
+| Property                                 | Type                                              | Description                       | Defined in                                                                                                                             |
+| ---------------------------------------- | ------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-machine"></a> `machine`  | `TMachine`                                        | XState v5 state machine           | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L9)   |
+| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | Lifecycle hooks and configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L12) |

package/api/@xmachines/play-xstate/interfaces/PlayerFactoryResumeOptions.md

@@ -0,0 +1,22 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactoryResumeOptions
+
+# Interface: PlayerFactoryResumeOptions\<TMachine\>
+
+Defined in: [packages/play-xstate/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L111)
+
+Optional restore arguments for the player factory.
+
+Mirrors XState's createActor options bag while preserving the existing
+`createPlayer(input?)` calling convention for fresh actors.
+
+## Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+
+## Properties
+
+| Property                                   | Type                                                                     | Description                                                                                                                                                                                                                              | Defined in                                                                                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-snapshot"></a> `snapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\> | Persisted XState snapshot used to restore actor state. Typed as XState's own `ActorOptions["snapshot"]` — the exact type `createActor` accepts and `getPersistedSnapshot()` returns — so restoring a stored snapshot never needs a cast. | [packages/play-xstate/src/types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L119) |

package/api/@xmachines/play-xstate/interfaces/PlayerOptions.md

@@ -1,26 +1,24 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerOptions
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerOptions
 
 # Interface: PlayerOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L28)
+Defined in: [packages/play-xstate/src/types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L18)
 
-Player lifecycle hooks
-
-Per CONTEXT.md: Rich set of hooks for observability
+Player lifecycle hooks — the observability surface around the actor.
 
 ## Type Parameters
 
-| Type Parameter                         |
-| -------------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` |
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
 
 ## Properties
 
-| Property                                               | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                                                               |
-| ------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-onerror"></a> `onError?`               | (`actor`, `error`) => `void`                  | Called on actor errors                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L46) |
-| <a id="property-onstart"></a> `onStart?`               | (`actor`) => `void`                           | Called when actor starts                                                                                                                                                                                                                                                                                                                                            | [packages/play-xstate/src/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L30) |
-| <a id="property-onstatechange"></a> `onStateChange?`   | (`actor`, `state`) => `void`                  | Called when state signal changes                                                                                                                                                                                                                                                                                                                                    | [packages/play-xstate/src/types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L43) |
-| <a id="property-onstop"></a> `onStop?`                 | (`actor`) => `void`                           | Called when actor stops                                                                                                                                                                                                                                                                                                                                             | [packages/play-xstate/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L33) |
-| <a id="property-ontransition"></a> `onTransition?`     | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition                                                                                                                                                                                                                                                                                                                                    | [packages/play-xstate/src/types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L36) |
-| <a id="property-propvalidation"></a> `propValidation?` | `"strict"` \| `"lenient"`                     | Prop validation failure mode (default: 'lenient') - 'lenient': On validation failure, call onError hook and render with unvalidated props (current behavior). Documents as explicit trade-off. - 'strict': On validation failure, call onError hook and set viewSignal to null (no render). Blocks rendering until machine transitions to a state with valid props. | [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L57) |
+| Property                                             | Type                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                               |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-inspect"></a> `inspect?`             | \| [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<`InspectionEvent`\> \| ((`inspectionEvent`) => `void`) | Inspection observer forwarded verbatim to XState's `createActor`. This is the creation-time attachment route, and the only one that observes the actor's construction events. Attaching later via `actor.system.inspect(fn)` also works, but only sees events from that point on. A `PlayerActor` is itself the XState actor, so its own events carry `actorRef === playerActor` and can be recognised by identity. Each `PlayerActor` is also its own root system, so `event.rootId === actor.sessionId` demultiplexes the whole tree — including events from invoked and spawned children, whose `actorRef` is the child. One caveat comes with that identity: the `@xstate.actor` event fires from inside the actor's constructor, so its `actorRef` is the instance mid-construction. `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet — reading them there throws. Capture the reference and read the signals from a later event, or from outside the observer. **Example** `import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } });` For an inspector created after the factory (e.g. behind a dev-tools toggle), pass a forwarding function: `inspect: (event) => currentInspector?.(event)`. | [packages/play-xstate/src/types.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L102) |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                                                                                           | Called on actor errors: a snapshot restore that fails at `start()`, a throwing action or guard, and view-derivation failures. Read when an error is delivered, not at construction: the options bag is shared by reference, so a handler attached to it later still receives actor errors, and removing the handler restores the loud default below. With a handler in place, the error is routed there and counts as handled. XState decides its global rethrow per observer, beyond this option's reach: a subscription of your own without an `error` listener still forces it, `onError` or not. Without `onError`, actor errors stay loud (an unhandled rethrow via `setTimeout`) so they are never silently swallowed — and your own `error` subscribers do not suppress that default; only `onError` does. An actor failure that is already an `Error` arrives unchanged, keeping the identity the machine gave it. A machine that throws a non-`Error` value arrives as `ActorThrewNonErrorError` with the thrown value on `cause`.                                                                                                                                                                                                                                                                                                             | [packages/play-xstate/src/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L68)   |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                                                                                                    | Called on each real start: every transition from not-running to running, including a start after a stop. A repeated `start()` while the actor is already running does not re-fire it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [packages/play-xstate/src/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L24)   |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                                                                                           | Called when state signal changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L45)   |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                                                                                                    | Called on each real stop: only when a running actor was actually torn down. Repeated `stop()`/`dispose()` calls, and stopping an actor that never started, do not fire it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L31)   |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void`                                                                          | Called after every event `send()` processes — including events the machine ignores, where `prevState` and `nextState` are the same snapshot. Compare the two when only real transitions matter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L38)   |