@xmachines/docs 1.0.0-beta.9 → 1.0.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,49 @@
 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:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/build-url.ts#L40)
 
-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. **Must include a `query` field** (use `query: {}` when no query parameters are needed). Omitting `query` when `params` is present throws `MissingQueryContextError` to prevent silent query-string loss. |
 
 ## 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`.
+
+## Throws
+
+When the context has a `params` field but no
+`query` field. This indicates a routing-aware machine context that was not set up
+to receive query parameters, which would silently drop query params from
+`play.route` events. 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,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
 
 # Function: composeGuards()
 
@@ -6,7 +6,7 @@
 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:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/compose.ts#L78)
 
 Compose guards with AND logic using XState's and() helper
 

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
 
 # Function: composeGuardsOr()
 
@@ -6,7 +6,7 @@
 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:144](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/compose.ts#L144)
 
 Compose guards with OR logic using XState's or() helper
 

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

@@ -0,0 +1,38 @@
+[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:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/helpers.ts#L71)
+
+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

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.0.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.0.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,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
 
 # Function: eventMatches()
 
@@ -6,7 +6,7 @@
 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:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/helpers.ts#L50)
 
 Check if event type matches expected type
 

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.0.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,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
 
 # Function: hasContext()
 
@@ -6,7 +6,7 @@
 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.0.0/packages/play-xstate/src/guards/helpers.ts#L24)
 
 Check if context has a truthy value at path
 

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.0.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,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
 
 # Function: negateGuard()
 
@@ -6,7 +6,7 @@
 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:204](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/compose.ts#L204)
 
 Negate a guard using XState's not() helper
 

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.0.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.0.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.0.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:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L47)
+
+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?` | [`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\> | Persisted XState snapshot used to restore actor state. | [packages/play-xstate/src/types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L49) |

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

@@ -1,8 +1,8 @@
-[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:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L20)
 
 Player lifecycle hooks
 
@@ -10,17 +10,16 @@ Per CONTEXT.md: Rich set of hooks for observability
 
 ## 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-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                  | Called on actor errors           | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L38) |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                           | Called when actor starts         | [packages/play-xstate/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L22) |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                  | Called when state signal changes | [packages/play-xstate/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L35) |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                           | Called when actor stops          | [packages/play-xstate/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L25) |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition | [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L28) |

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

@@ -1,22 +1,24 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteContext
+[API](../../../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)
+Defined in: [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L19)
 
-Route build context from machine context
+Route build context from machine context.
 
-## Indexable
+All URL parameter substitution must go through `params` — flat context fields are not
+inspected. This is intentional: the index signature was removed to enable compile-time
+validation of context shapes and IDE autocomplete on context fields.
 
-```ts
-[key: string]: unknown
-```
+Machines using `formatPlayRouteTransitions` have `params` and `query` assigned
+automatically from each `play.route` event. Machines that call `buildRouteUrl` directly
+must populate `params` explicitly.
 
 ## 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) |
+| Property                                   | Type                            | Description                                                                        | Defined in                                                                                                                                             |
+| ------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-basepath"></a> `basePath?` | `string`                        | Base path for relative routes                                                      | [packages/play-xstate/src/routing/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L21) |
+| <a id="property-hash"></a> `hash?`         | `string`                        | Hash fragment                                                                      | [packages/play-xstate/src/routing/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L27) |
+| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) | [packages/play-xstate/src/routing/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L23) |
+| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | Query parameters                                                                   | [packages/play-xstate/src/routing/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L25) |

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

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteObject
+
+# Interface: RouteObject
+
+Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L1)
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                          | Type     | Defined in                                                                                                                                           |
+| --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `string` | [packages/play-xstate/src/routing/types.ts:2](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L2) |

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
 
 # Type Alias: ComposedGuard
 
@@ -6,7 +6,7 @@
 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)
+Defined in: [packages/play-xstate/src/guards/compose.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/compose.ts#L15)
 
 Narrowest public return type for guard composition helpers.
 

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
 
 # Type Alias: Guard\<TContext, TEvent\>
 
@@ -6,7 +6,7 @@
 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)
+Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/types.ts#L13)
 
 Standard XState guard function signature
 

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

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
 
 # Type Alias: GuardArray\<TContext, TEvent\>
 
 ```ts
-type GuardArray<TContext, TEvent> = Guard<TContext, TEvent>[] | string[];
+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)
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/types.ts#L23)
 
 Array of guard predicates or guard names