@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,80 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / validateViewProps
+
+# Function: validateViewProps()
+
+Implementation — shared by both overloads
+
+## Call Signature
+
+```ts
+function validateViewProps<TCatalog>(componentName, props, catalog): ValidationResult;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L35)
+
+Validate view props against Zod schema — generic overload for typed catalogs
+
+When called with a typed catalog, `componentName` is constrained to `keyof TCatalog`.
+Malformed catalog entries or unknown component names produce compile-time errors
+rather than runtime failures.
+
+### Type Parameters
+
+| Type Parameter                                               | Description                        |
+| ------------------------------------------------------------ | ---------------------------------- |
+| `TCatalog` _extends_ [`Catalog`](../type-aliases/Catalog.md) | Catalog type (must extend Catalog) |
+
+### Parameters
+
+| Parameter       | Type                        | Description                                           |
+| --------------- | --------------------------- | ----------------------------------------------------- |
+| `componentName` | keyof `TCatalog` & `string` | Component name constrained to string keys of TCatalog |
+| `props`         | `unknown`                   | Props to validate                                     |
+| `catalog`       | `TCatalog`                  | Typed component catalog                               |
+
+### Returns
+
+[`ValidationResult`](../type-aliases/ValidationResult.md)
+
+Zod parse result
+
+## Call Signature
+
+```ts
+function validateViewProps(componentName, props, catalog): ValidationResult;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L64)
+
+Validate view props against Zod schema — base overload for untyped catalogs
+
+Per CONTEXT.md:
+
+- "Prop validation: At state entry"
+- "currentView derivation: Merge meta.view with relevant context data"
+
+Per RESEARCH.md Pattern 4: Use safeParse() for validation
+
+### Parameters
+
+| Parameter       | Type                                    | Description                    |
+| --------------- | --------------------------------------- | ------------------------------ |
+| `componentName` | `string`                                | Component name from catalog    |
+| `props`         | `unknown`                               | Props to validate              |
+| `catalog`       | [`Catalog`](../type-aliases/Catalog.md) | Component catalog with schemas |
+
+### Returns
+
+[`ValidationResult`](../type-aliases/ValidationResult.md)
+
+Zod parse result
+
+### Example
+
+```typescript
+const props = { userId: "123", stats: { logins: 5 } };
+const result = validateViewProps("Dashboard", props, catalog);
+if (!result.success) {
+	console.error(result.error);
+}
+```

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

@@ -0,0 +1,16 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / CatalogEntry
+
+# Interface: CatalogEntry
+
+Defined in: [packages/play-xstate/src/catalog/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/types.ts#L9)
+
+UI component catalog entry with schema and component reference
+
+Per CONTEXT.md: String keys reference components, Zod schemas validate props
+
+## Properties
+
+| Property                                    | Type                   | Description                                    | Defined in                                                                                                                                                                               |
+| ------------------------------------------- | ---------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-component"></a> `component` | `unknown`              | React component (or other framework component) | [packages/play-xstate/src/catalog/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/types.ts#L13) |
+| <a id="property-schema"></a> `schema`       | `ZodType`\<`unknown`\> | Zod schema for component props                 | [packages/play-xstate/src/catalog/types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/types.ts#L11) |

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

@@ -0,0 +1,24 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerConfig
+
+# Interface: PlayerConfig\<TMachine, TCatalog\>
+
+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)
+
+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`\> |
+
+## 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) |

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

@@ -0,0 +1,26 @@
+[Documentation](../../../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)
+
+Player lifecycle hooks
+
+Per CONTEXT.md: Rich set of hooks for observability
+
+## Type Parameters
+
+| Type Parameter                         |
+| -------------------------------------- |
+| `TMachine` _extends_ `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) |

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

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteContext
+
+# Interface: RouteContext
+
+Defined in: [packages/play-xstate/src/routing/types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/types.ts#L11)
+
+Route build context from machine context
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                                         | Type                            | Description                    | Defined in                                                                                                                                                                               |
+| ------------------------------------------------ | ------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath?`       | `string`                        | Base path for relative routes  | [packages/play-xstate/src/routing/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/types.ts#L13) |
+| <a id="property-hash"></a> `hash?`               | `string`                        | Hash fragment                  | [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/types.ts#L19) |
+| <a id="property-query"></a> `query?`             | `Record`\<`string`, `unknown`\> | Query parameters               | [packages/play-xstate/src/routing/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/types.ts#L17) |
+| <a id="property-routeparams"></a> `routeParams?` | `Record`\<`string`, `unknown`\> | Route parameters to substitute | [packages/play-xstate/src/routing/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/types.ts#L15) |

package/api/@xmachines/play-xstate/type-aliases/Catalog.md

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / Catalog
+
+# Type Alias: Catalog
+
+```ts
+type Catalog = Catalog | Record<string, CatalogEntry>;
+```
+
+Defined in: [packages/play-xstate/src/catalog/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/types.ts#L28)
+
+Component catalog mapping
+
+Re-export from @xmachines/play-catalog for consistent API.
+
+Supports two formats:
+
+- Direct Zod schemas: `Record<string, z.ZodType>` via defineCatalog()
+- CatalogEntry objects: `Record<string, CatalogEntry>` with { schema, component }
+
+PlayerActor accepts either format - if entry has 'schema' property, uses CatalogEntry pattern,
+otherwise treats as direct Zod schema.

package/api/@xmachines/play-xstate/type-aliases/ComposedGuard.md

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
+
+# Type Alias: ComposedGuard
+
+```ts
+type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
+```
+
+Defined in: [packages/play-xstate/src/guards/compose.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L14)
+
+Narrowest public return type for guard composition helpers.
+
+`GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
+widest-compatible concrete XState guard type that does not use `any`.

package/api/@xmachines/play-xstate/type-aliases/Guard.md

@@ -0,0 +1,34 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
+
+# Type Alias: Guard\<TContext, TEvent\>
+
+```ts
+type Guard<TContext, TEvent> = (args) => boolean;
+```
+
+Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/types.ts#L13)
+
+Standard XState guard function signature
+
+Per CONTEXT.md: Guards receive { context, event } per XState standard
+
+## Type Parameters
+
+| Type Parameter | Default type                                        |
+| -------------- | --------------------------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\>                     |
+| `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
+
+## Parameters
+
+| Parameter      | Type                                            | Description                               |
+| -------------- | ----------------------------------------------- | ----------------------------------------- |
+| `args`         | \{ `context`: `TContext`; `event`: `TEvent`; \} | Guard arguments with context and event    |
+| `args.context` | `TContext`                                      | Current machine context                   |
+| `args.event`   | `TEvent`                                        | Event that triggered the guard evaluation |
+
+## Returns
+
+`boolean`
+
+boolean indicating if guard passes

package/api/@xmachines/play-xstate/type-aliases/GuardArray.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
+
+# Type Alias: GuardArray\<TContext, TEvent\>
+
+```ts
+type GuardArray<TContext, TEvent> = Guard<TContext, TEvent>[] | string[];
+```
+
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/types.ts#L23)
+
+Array of guard predicates or guard names
+
+Per CONTEXT.md: Array means AND - all guards must pass
+
+## Type Parameters
+
+| Type Parameter | Default type                                        |
+| -------------- | --------------------------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\>                     |
+| `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
+
+# Type Alias: PlayerFactory\<TMachine\>
+
+```ts
+type PlayerFactory<TMachine> = (input?) => PlayerActor<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L65)
+
+Factory function returned by definePlayer()
+
+Per CONTEXT.md: Factory supports creating multiple actor instances
+
+## Type Parameters
+
+| Type Parameter                         |
+| -------------------------------------- |
+| `TMachine` _extends_ `AnyStateMachine` |
+
+## Parameters
+
+| Parameter | Type                      |
+| --------- | ------------------------- |
+| `input?`  | `InputFrom`\<`TMachine`\> |
+
+## Returns
+
+[`PlayerActor`](../classes/PlayerActor.md)\<`TMachine`\>

package/api/@xmachines/play-xstate/type-aliases/RouteMachineConfig.md

@@ -0,0 +1,45 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
+
+# Type Alias: RouteMachineConfig
+
+```ts
+type RouteMachineConfig = object;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L29)
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+### context?
+
+```ts
+optional context?: unknown;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+
+---
+
+### on?
+
+```ts
+optional on?: Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+
+---
+
+### states?
+
+```ts
+optional states?: Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L31)

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -0,0 +1,51 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
+
+# Type Alias: RouteStateNode
+
+```ts
+type RouteStateNode = object;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+### id?
+
+```ts
+optional id?: string;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L14)
+
+---
+
+### meta?
+
+```ts
+optional meta?: object;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+
+#### route?
+
+```ts
+optional route?: string;
+```
+
+---
+
+### states?
+
+```ts
+optional states?: Record<string, RouteStateNode>;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L18)

package/api/@xmachines/play-xstate/type-aliases/ValidationResult.md

@@ -0,0 +1,17 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / ValidationResult
+
+# Type Alias: ValidationResult
+
+```ts
+type ValidationResult =
+	| {
+			data: Record<string, unknown>;
+			success: true;
+	  }
+	| {
+			error: z.ZodError | Error;
+			success: false;
+	  };
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L11)

package/api/@xmachines/play-xstate/type-aliases/ViewMergeContext.md

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / ViewMergeContext
+
+# Type Alias: ViewMergeContext
+
+```ts
+type ViewMergeContext = object;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L5)
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+### queryParams?
+
+```ts
+optional queryParams?: Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L7)
+
+---
+
+### routeParams?
+
+```ts
+optional routeParams?: Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L6)