@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,67 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / 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)
+
+Compose guards with OR logic using XState's or() helper
+
+Combines multiple guard predicates using OR semantics—at least one guard must pass
+for the composition to succeed. Uses XState's built-in `or()` helper for proper
+type inference.
+
+## Type Parameters
+
+| Type Parameter | Default type | Description                |
+| -------------- | ------------ | -------------------------- |
+| `TContext`     | `any`        | State machine context type |
+| `TEvent`       | `any`        | Event type                 |
+
+## Parameters
+
+| Parameter | Type                                                                  | Description                              |
+| --------- | --------------------------------------------------------------------- | ---------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names |
+
+## Returns
+
+[`ComposedGuard`](../type-aliases/ComposedGuard.md)
+
+XState or() guard composition
+
+## Throws
+
+If guards array is empty
+
+## Example
+
+OR composition with named guards
+
+```typescript
+import { setup } from "xstate";
+import { composeGuardsOr } from "@xmachines/play-xstate";
+
+const machine = setup({
+	guards: {
+		isOwner: ({ context }) => context.role === "owner",
+		isAdmin: ({ context }) => context.role === "admin",
+	},
+}).createMachine({
+	on: {
+		deleteResource: {
+			// Either guard can pass
+			guard: composeGuardsOr(["isOwner", "isAdmin"]),
+			actions: "delete",
+		},
+	},
+});
+```
+
+## See
+
+- [composeGuards](composeGuards.md) for AND composition
+- [negateGuard](negateGuard.md) for NOT logic

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

@@ -0,0 +1,127 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
+
+# Function: definePlayer()
+
+```ts
+function definePlayer<TMachine, TCatalog>(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)
+
+Create a player factory from XState machine and catalog
+
+Factory pattern that accepts an XState v5 machine and optional UI catalog,
+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 |
+
+## Parameters
+
+| Parameter | Type                                                                      | Description                 |
+| --------- | ------------------------------------------------------------------------- | --------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`, `TCatalog`\> | Player configuration object |
+
+## Returns
+
+[`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`\>
+
+Factory function that creates actor instances with optional input context
+
+## Examples
+
+Basic player factory without catalog
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: { meta: { route: "/" } },
+		active: { meta: { route: "/active" } },
+	},
+});
+
+const createPlayer = definePlayer({ machine });
+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 });
+
+// Create actors for different users
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
+
+alice.start();
+bob.start();
+
+// Independent state machines
+console.log(alice.state.get() !== bob.state.get());
+```
+
+## See
+
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.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

@@ -0,0 +1,109 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
+
+# Function: deriveRoute()
+
+```ts
+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)
+
+Derive route from XState state metadata
+
+Extracts route URL template from `meta.route` in the active state's metadata.
+Supports both string routes (`"/about"`) and object routes with path property
+(`{ path: "/about" }`). Returns null for states without route metadata (not
+all states need to be routable).
+
+**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
+routing information from state machine definitions rather than external configuration.
+The route is determined by the Actor's current state, not by infrastructure decisions.
+
+## Parameters
+
+| Parameter   | Type                            | Description                            |
+| ----------- | ------------------------------- | -------------------------------------- |
+| `stateMeta` | `Record`\<`string`, `unknown`\> | State metadata from snapshot.getMeta() |
+
+## Returns
+
+`string` \| `null`
+
+Route path template (may include :params) or null if no route found
+
+## Examples
+
+Basic route extraction
+
+```typescript
+import { deriveRoute } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+
+const machine = setup({}).createMachine({
+	states: {
+		about: {
+			meta: { route: "/about", view: { component: "AboutPage" } },
+		},
+	},
+});
+
+const actor = createActor(machine);
+actor.start();
+const snapshot = actor.getSnapshot();
+const meta = snapshot.getMeta();
+
+const route = deriveRoute(meta);
+console.log(route); // "/about"
+```
+
+Route with parameters
+
+```typescript
+const machine = setup({}).createMachine({
+	states: {
+		profile: {
+			meta: {
+				route: "/profile/:userId",
+				view: { component: "ProfilePage", userId: (ctx) => ctx.userId },
+			},
+		},
+	},
+});
+
+const route = deriveRoute(snapshot.getMeta());
+console.log(route); // "/profile/:userId" (template, before substitution)
+```
+
+Route object format
+
+```typescript
+const machine = setup({}).createMachine({
+	states: {
+		dashboard: {
+			meta: {
+				route: { path: "/dashboard" },
+				view: { component: "Dashboard" },
+			},
+		},
+	},
+});
+
+const route = deriveRoute(snapshot.getMeta());
+console.log(route); // "/dashboard"
+```
+
+## See
+
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [buildRouteUrl](buildRouteUrl.md) for URL construction with parameter substitution
+- [isAbsoluteRoute](isAbsoluteRoute.md) for checking path absoluteness
+
+## Remarks
+
+This function checks `meta.route` for route definitions. States with `route: {}` config
+are routable. Parameter substitution happens via [buildRouteUrl](buildRouteUrl.md), not in this
+function (deriveRoute returns templates).
+
+**Non-routable States:** States without `meta.route` return `null`. This is intentional—
+not all states need routes. For example, intermediate loading states or substates may
+not correspond to distinct URLs.

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

@@ -0,0 +1,40 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / 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)
+
+Check if event type matches expected type
+
+## Type Parameters
+
+| Type Parameter                                                         | Default type                                        |
+| ---------------------------------------------------------------------- | --------------------------------------------------- |
+| `TEvent` _extends_ [`PlayEvent`](../../play/type-aliases/PlayEvent.md) | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
+
+## Parameters
+
+| Parameter   | Type     | Description         |
+| ----------- | -------- | ------------------- |
+| `eventType` | `string` | Expected event type |
+
+## Returns
+
+[`Guard`](../type-aliases/Guard.md)\<`unknown`, `TEvent`\>
+
+Guard predicate checking event type
+
+## Example
+
+```typescript
+const machine = setup({
+	guards: {
+		isSubmitEvent: eventMatches("submit"),
+		isBackOrForward: composeGuardsOr([eventMatches("back"), eventMatches("forward")]),
+	},
+});
+```

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

@@ -0,0 +1,54 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
+
+# Function: formatPlayRouteTransitions()
+
+```ts
+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)
+
+Formats play.route transitions from declarative route configs
+
+Crawls machine states looking for states with meta.route and generates
+transitions that handle `play.route` events by matching event.to to state IDs.
+
+Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
+
+## Type Parameters
+
+| Type Parameter                                                              |
+| --------------------------------------------------------------------------- |
+| `T` _extends_ [`RouteMachineConfig`](../type-aliases/RouteMachineConfig.md) |
+
+## Parameters
+
+| Parameter       | Type | Description                                                                     |
+| --------------- | ---- | ------------------------------------------------------------------------------- |
+| `machineConfig` | `T`  | XState machine config (before createMachine). Must extend `RouteMachineConfig`. |
+
+## Returns
+
+`T`
+
+The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
+
+## Example
+
+```typescript
+const machineConfig = {
+	id: "myMachine",
+	states: {
+		home: { id: "home", meta: { route: "/home" } },
+		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+	},
+};
+
+const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+```
+
+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

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

@@ -0,0 +1,42 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / 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)
+
+Check if context has a truthy value at path
+
+Per CONTEXT.md: Convenience helper for common guard pattern
+
+## Type Parameters
+
+| Type Parameter | Default type                    |
+| -------------- | ------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\> |
+
+## Parameters
+
+| Parameter | Type     | Description                            |
+| --------- | -------- | -------------------------------------- |
+| `path`    | `string` | Dot-separated path to context property |
+
+## Returns
+
+[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
+
+Guard predicate checking if property is truthy
+
+## Example
+
+```typescript
+const machine = setup({
+	guards: {
+		hasUserId: hasContext("userId"),
+		hasEmail: hasContext("user.email"),
+	},
+});
+```

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

@@ -0,0 +1,41 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
+
+# Function: isAbsoluteRoute()
+
+```ts
+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)
+
+Check if route path is absolute
+
+Determines whether a route path is absolute (starts with `/`) or relative.
+Absolute paths don't inherit from parent routes, while relative paths can be
+composed with parent paths for nested routing.
+
+## Parameters
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `path`    | `string` | Route path to check |
+
+## Returns
+
+`boolean`
+
+true if path starts with '/', false otherwise
+
+## Example
+
+```typescript
+import { isAbsoluteRoute } from "@xmachines/play-xstate";
+
+console.log(isAbsoluteRoute("/dashboard")); // true
+console.log(isAbsoluteRoute("settings")); // false
+console.log(isAbsoluteRoute("./about")); // false
+```
+
+## See
+
+[deriveRoute](deriveRoute.md) for route extraction

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

@@ -0,0 +1,26 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / mergeViewProps
+
+# Function: mergeViewProps()
+
+```ts
+function mergeViewProps(view, context): Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-props.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-props.ts#L115)
+
+Merge view metadata with context for props
+
+Per CONTEXT.md: "Merge meta.view with relevant context data for component props"
+
+## Parameters
+
+| Parameter | Type                                                                                  | Description                  |
+| --------- | ------------------------------------------------------------------------------------- | ---------------------------- |
+| `view`    | [`ViewMetadata`](../../play-actor/interfaces/ViewMetadata.md)                         | View metadata from meta.view |
+| `context` | \| [`ViewMergeContext`](../type-aliases/ViewMergeContext.md) \| `null` \| `undefined` | Machine context              |
+
+## Returns
+
+`Record`\<`string`, `unknown`\>
+
+Merged props object

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

@@ -0,0 +1,61 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / 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)
+
+Negate a guard using XState's not() helper
+
+Inverts a guard's result—if the guard passes, NOT fails; if guard fails, NOT passes.
+Uses XState's built-in `not()` helper for proper serialization.
+
+## Type Parameters
+
+| Type Parameter | Default type | Description                |
+| -------------- | ------------ | -------------------------- |
+| `TContext`     | `any`        | State machine context type |
+| `TEvent`       | `any`        | Event type                 |
+
+## Parameters
+
+| Parameter | Type                                                                    | Description                             |
+| --------- | ----------------------------------------------------------------------- | --------------------------------------- |
+| `guard`   | `string` \| [`Guard`](../type-aliases/Guard.md)\<`TContext`, `TEvent`\> | Guard predicate or guard name to negate |
+
+## Returns
+
+[`ComposedGuard`](../type-aliases/ComposedGuard.md)
+
+XState not() guard negation
+
+## Example
+
+NOT composition with named guard
+
+```typescript
+import { setup } from "xstate";
+import { negateGuard } from "@xmachines/play-xstate";
+
+const machine = setup({
+	guards: {
+		isGuest: ({ context }) => !context.userId,
+	},
+}).createMachine({
+	on: {
+		accessDashboard: {
+			// Allow if NOT a guest (i.e., authenticated)
+			guard: negateGuard("isGuest"),
+			target: "dashboard",
+		},
+	},
+});
+```
+
+## See
+
+- [composeGuards](composeGuards.md) for AND composition
+- [composeGuardsOr](composeGuardsOr.md) for OR composition

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

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / stateMatches
+
+# Function: stateMatches()
+
+```ts
+function stateMatches<TContext>(stateValue): Guard<TContext, PlayEvent>;
+```
+
+Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/helpers.ts#L75)
+
+## Type Parameters
+
+| Type Parameter | Default type                    |
+| -------------- | ------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\> |
+
+## Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `stateValue` | `string` |
+
+## Returns
+
+[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>

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

@@ -0,0 +1,39 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / validateComponentBinding
+
+# Function: validateComponentBinding()
+
+```ts
+function validateComponentBinding(view, catalog): void;
+```
+
+Defined in: [packages/play-xstate/src/catalog/validate-binding.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/catalog/validate-binding.ts#L22)
+
+Validate component binding against catalog
+
+Per CONTEXT.md:
+
+- "Component references: String keys"
+- "Mismatch detection: Both compile-time (TypeScript) and runtime validation"
+
+## Parameters
+
+| Parameter | Type                                                          | Description                  |
+| --------- | ------------------------------------------------------------- | ---------------------------- |
+| `view`    | [`ViewMetadata`](../../play-actor/interfaces/ViewMetadata.md) | View metadata from meta.view |
+| `catalog` | [`Catalog`](../type-aliases/Catalog.md)                       | Component catalog            |
+
+## Returns
+
+`void`
+
+## Example
+
+```typescript
+const view = { component: "Dashboard", userId: "123" };
+validateComponentBinding(view, catalog);
+// Throws if 'Dashboard' not in catalog
+```
+
+## Throws
+
+Error if component not found in catalog