@xmachines/docs 1.0.0 → 1.1.0

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayerConfig\<TMachine\>
 
-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)
+Defined in: [packages/play-xstate/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L7)
 
 Configuration for definePlayer()
 
@@ -16,5 +16,5 @@ Configuration for definePlayer()
 
 | 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) |
+| <a id="property-machine"></a> `machine`  | `TMachine`                                        | XState v5 state machine           | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L9)   |
+| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | Lifecycle hooks and configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L12) |

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

@@ -2,7 +2,7 @@
 
 # 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)
+Defined in: [packages/play-xstate/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L111)
 
 Optional restore arguments for the player factory.
 
@@ -17,6 +17,6 @@ Mirrors XState's createActor options bag while preserving the existing
 
 ## 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) |
+| Property                                   | Type                                                                     | Description                                                                                                                                                                                                                              | Defined in                                                                                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-snapshot"></a> `snapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\> | Persisted XState snapshot used to restore actor state. Typed as XState's own `ActorOptions["snapshot"]` — the exact type `createActor` accepts and `getPersistedSnapshot()` returns — so restoring a stored snapshot never needs a cast. | [packages/play-xstate/src/types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/types.ts#L119) |

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

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

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteContext
 
-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)
+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.
 
@@ -18,7 +18,7 @@ must populate `params` explicitly.
 
 | 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) |
+| <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

@@ -2,7 +2,7 @@
 
 # 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)
+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
 
@@ -14,4 +14,4 @@ Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xma
 
 | 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) |
+| <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 @@
 [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:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/guards/compose.ts#L15)
+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 @@
 [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/v1.0.0/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 @@
 [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)[];
 ```
 
-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)
+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

@@ -3,28 +3,24 @@
 # Type Alias: PlayerFactory\<TMachine\>
 
 ```ts
-type PlayerFactory<TMachine> = (input?, options?) => 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:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L57)
+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`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
-
-## Parameters
-
-| Parameter  | Type                                                                                      |
-| ---------- | ----------------------------------------------------------------------------------------- |
-| `input?`   | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\>               |
-| `options?` | [`PlayerFactoryResumeOptions`](../interfaces/PlayerFactoryResumeOptions.md)\<`TMachine`\> |
-
-## Returns
-
-[`PlayerActor`](../classes/PlayerActor.md)\<`TMachine`\>

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

@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
+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`.
@@ -32,7 +32,7 @@ through the transform, so the return value remains directly usable by
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)
+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)
 
 ---
 
@@ -42,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:5
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L56)
+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)
 
 ---
 
@@ -52,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:5
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)
+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

@@ -6,4 +6,4 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L6)
+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

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+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.
@@ -29,7 +29,7 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+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.
 
@@ -41,7 +41,7 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L19)
+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.
 
@@ -62,6 +62,6 @@ form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L27)
+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.

package/api/@xmachines/shared/README.md

@@ -1,11 +1,11 @@
 [API](../../README.md) / @xmachines/shared
 
-<!-- generated-by: gsd-doc-writer -->
-
 # `@xmachines/shared`
 
 Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation

package/api/@xmachines/shared/vite-aliases/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L221)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L330)
+Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L333)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -3,10 +3,10 @@
 # Function: xmOptimizeDeps()
 
 ```ts
-function xmOptimizeDeps(extra?): DepOptimizationOptions;
+function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L286)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L291)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 
@@ -16,14 +16,19 @@ discovering them lazily at runtime. Without this, adding or changing dependencie
 "Re-optimizing dependencies because lockfile has changed" warnings that slow down
 and occasionally destabilise browser test runs.
 
-Pass `extra` to include framework-specific packages (e.g. `["@xmachines/json-render-vue/schema"]`).
-The base set (`@xmachines/json-render-core`) is always included.
+Every entry has to be a dependency the calling package declares. pnpm gives each
+package its own `node_modules`, so a specifier the project does not declare cannot
+be resolved from its root — and the optimizer only warns: `Failed to resolve
+dependency: <name>, present in client 'optimizeDeps.include'` on stderr, with the
+run carrying on. That reads as a failure inside a passing job, and it hides the
+same message when it is real. So nothing is pre-bundled by default: pass the
+packages this project actually depends on.
 
 ## Parameters
 
-| Parameter | Type       | Default value | Description                                                       |
-| --------- | ---------- | ------------- | ----------------------------------------------------------------- |
-| `extra`   | `string`[] | `[]`          | Additional package specifiers to pre-bundle (framework-specific). |
+| Parameter | Type       | Default value | Description                                                    |
+| --------- | ---------- | ------------- | -------------------------------------------------------------- |
+| `include` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
 
 ## Returns
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L258)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L309)
+Defined in: [vite-aliases.ts:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L312)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -30,4 +30,4 @@ export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L310) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:313](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L313) |

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L167)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L64)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L117)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
 | -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L125) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L132) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L138) |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L125) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L132) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L138) |

package/contributing/architecture.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Architecture
 
 XMachines Play implements the **Universal Player Architecture** — a layered, actor-authority design where XState machines are the single source of truth for routing, navigation, and view selection. Infrastructure (routers, renderers) is strictly passive: it observes actor signals and reflects them, never enforcing guards or making decisions.
@@ -101,8 +99,8 @@ graph TD
 ```mermaid
 flowchart TD
     A["XState machine transition"]
-    B["PlayerActor xstateActor.subscribe(snapshot)"]
-    C["StateSignalManager.scheduleUpdate(snapshot)\nactor.state Signal.State updated — synchronous"]
+    B["PlayerActor observes its own transitions"]
+    C["actor.state Signal.State updated — synchronous, no batching"]
     D["actor.currentRoute Signal.Computed recomputes\nderives URL from meta.route + context.params"]
     E["validateAndCacheView(snapshot)\nactor.currentView Signal.State updated"]
     F["Framework signal watcher fires\nmicrotask"]
@@ -229,11 +227,11 @@ Extends `@xmachines/json-render-core` `Spec` with `readonly contextProps?: reado
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
 
-Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md); implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Wraps an internal `xstate.Actor` and bridges its subscription to TC39 Signals via `StateSignalManager`. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
+Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — and so XState's own `Actor`, receiving the machine in its constructor, so an instance IS the actor rather than a wrapper around one; implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Bridges its own subscription to TC39 Signals. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
 
 ### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/type-aliases/PlayerFactory.md)
 
-Factory creator. Pre-computes `initialRoute` once from the machine's initial state (zero extra actor instantiation per factory call). Returns `(input?, restore?) => PlayerActor<TMachine>`.
+Factory creator. Each call constructs one `PlayerActor`, which is itself the XState actor and derives its own `initialRoute` from its pre-start snapshot. Restoring a snapshot is the exception: the default initial route can only come from XState's pure `initialTransition` helper, whose inert actor scope constructs a throwaway actor and evaluates the initial transition twice. Returns `(input?, restore?) => PlayerActor<TMachine>`.
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -354,7 +352,7 @@ packages/
 │       ├── define-player.ts             # definePlayer factory
 │       ├── guards/                      # composeGuards, composeGuardsOr, negateGuard, hasContext...
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
-│       └── signals/                     # StateSignalManager (XState → TC39 Signal bridge)
+│       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
 ├── play-router/                # Layer 2: Route extraction, bidirectional mapping, bridge base
 │   └── src/
@@ -467,8 +465,10 @@ flowchart TD
     PE --> IME["InvalidMachineError\nPLAY_XSTATE_INVALID_MACHINE"]
     PE --> MRP["MissingRouteParamError\nPLAY_XSTATE_ROUTE_PARAM_MISSING"]
     PE --> MSI["MissingStateIdError\nPLAY_XSTATE_MISSING_STATE_ID"]
-    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT"]
+    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT\n(deprecated — never thrown)"]
     PE --> IRE["InvalidRouteMetadataError\nPLAY_XSTATE_INVALID_ROUTE_METADATA"]
+    PE --> ATN["ActorThrewNonErrorError\nPLAY_XSTATE_NON_ERROR_THROWN"]
+    PE --> EGA["EmptyGuardArrayError\nPLAY_XSTATE_EMPTY_GUARD_ARRAY"]
 ```
 
 Package-specific errors are exported from `./errors` subpath imports:
@@ -481,14 +481,16 @@ import { InvalidEventError } from "@xmachines/play-xstate/errors";
 
 **Error behavior by case:**
 
-| Error                        | Package       | Behavior                                                                                  |
-| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
-| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                 |
-| `MissingQueryContextError`   | `play-xstate` | Structural programmer error — always re-throws                                            |
-| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                |
-| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                 |
-| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                       |
-| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained |
+| Error                        | Package       | Behavior                                                                                   |
+| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                  |
+| `MissingQueryContextError`   | `play-xstate` | Deprecated — never thrown; exported only so existing `instanceof` handlers keep compiling  |
+| `ActorThrewNonErrorError`    | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause` |
+| `EmptyGuardArrayError`       | `play-xstate` | Structural programmer error — `composeGuards`/`composeGuardsOr` called with `[]`           |
+| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                 |
+| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                  |
+| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                        |
+| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained  |
 
 ## Application Bootstrap (React example)