@xmachines/docs 1.0.0-beta.9 → 1.1.0

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.1.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.1.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.1.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.1.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.1.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.1.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.1.0/packages/play-xstate/src/routing/types.ts#L2) |

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

@@ -1,14 +1,19 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
 
-# Type Alias: 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)
+Defined in: [packages/play-xstate/src/guards/compose.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/compose.ts#L17)
 
 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`.
+
+## Deprecated
+
+The guard utilities will be removed in the next major — use
+XState's own combinator types directly.

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

@@ -1,16 +1,14 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
 
-# Type Alias: Guard\<TContext, TEvent\>
+# ~~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)
+Defined in: [packages/play-xstate/src/guards/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/types.ts#L12)
 
-Standard XState guard function signature
-
-Per CONTEXT.md: Guards receive { context, event } per XState standard
+Standard XState guard function signature — guards receive `{ context, event }`.
 
 ## Type Parameters
 
@@ -32,3 +30,7 @@ Per CONTEXT.md: Guards receive { context, event } per XState standard
 `boolean`
 
 boolean indicating if guard passes
+
+## Deprecated
+
+The guard utilities will be removed in the next major.

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

@@ -1,16 +1,14 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
 
-# Type Alias: GuardArray\<TContext, TEvent\>
+# ~~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:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/guards/types.ts#L22)
 
-Array of guard predicates or guard names
-
-Per CONTEXT.md: Array means AND - all guards must pass
+Array of guard predicates or guard names — an array means AND: all must pass.
 
 ## Type Parameters
 
@@ -18,3 +16,7 @@ Per CONTEXT.md: Array means AND - all guards must pass
 | -------------- | --------------------------------------------------- |
 | `TContext`     | `Record`\<`string`, `unknown`\>                     |
 | `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
+
+## Deprecated
+
+The guard utilities will be removed in the next major.

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

@@ -1,29 +1,26 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
 
 # Type Alias: PlayerFactory\<TMachine\>
 
 ```ts
-type PlayerFactory<TMachine> = (input?) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> =
+	undefined extends InputFrom<TMachine>
+		? (input?, options?) => PlayerActor<TMachine>
+		: (input, options?) => 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)
+Defined in: [packages/play-xstate/src/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L131)
 
-Factory function returned by definePlayer()
+Factory function returned by definePlayer() — each call creates an
+independent actor instance from the same configuration.
 
-Per CONTEXT.md: Factory supports creating multiple actor instances
+Input requiredness mirrors XState's `createActor`: a machine whose input
+cannot be `undefined` makes the factory's first argument required, so
+forgetting it is a compile error instead of an actor that starts in an
+error status with a `null` initial route.
 
 ## Type Parameters
 
-| Type Parameter                         |
-| -------------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` |
-
-## Parameters
-
-| Parameter | Type                      |
-| --------- | ------------------------- |
-| `input?`  | `InputFrom`\<`TMachine`\> |
-
-## Returns
-
-[`PlayerActor`](../classes/PlayerActor.md)\<`TMachine`\>
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
 
 # Type Alias: RouteMachineConfig
 
@@ -6,7 +6,17 @@
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
+
+Minimal structural constraint for machine configs accepted by
+`formatPlayRouteTransitions`.
+
+This is intentionally loose so the function accepts both the bare `createMachine`
+config object and the stricter `setup().createMachine` config without requiring
+any type casts at the call site. The generic `T extends RouteMachineConfig`
+parameter on `formatPlayRouteTransitions` preserves the original concrete type
+through the transform, so the return value remains directly usable by
+`setup().createMachine()`.
 
 ## Indexable
 
@@ -22,7 +32,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:2
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)
 
 ---
 
@@ -32,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L56)
 
 ---
 
@@ -42,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)

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

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMetadata
+
+# Type Alias: RouteMetadata
+
+```ts
+type RouteMetadata = string | RouteObject;
+```
+
+Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/types.ts#L6)

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
 
 # Type Alias: RouteStateNode
 
@@ -6,7 +6,14 @@
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+
+Minimal structural shape of a single XState state node as read by
+`formatPlayRouteTransitions` when crawling the machine config.
+
+Only the fields the function actually inspects are typed here; all other
+state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
+the index signature.
 
 ## Indexable
 
@@ -22,7 +29,9 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+
+Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
 ---
 
@@ -32,14 +41,19 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L19)
+
+State metadata — `meta.route` marks the state as routable.
 
 #### route?
 
 ```ts
-optional route?: string;
+optional route?: RouteMetadata;
 ```
 
+URL path template — string form (e.g. `"/profile/:username"`) or object
+form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
+
 ---
 
 ### states?
@@ -48,4 +62,6 @@ optional route?: string;
 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)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L27)
+
+Nested child states, recursively crawled for additional route declarations.