@xmachines/docs 1.1.0 → 2.0.0

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayerOptions\<TMachine\>
 
-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)
+Defined in: [packages/play-xstate/src/types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L18)
 
 Player lifecycle hooks — the observability surface around the actor.
 
@@ -16,9 +16,9 @@ Player lifecycle hooks — the observability surface around the actor.
 
 | 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)   |
+| <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/v2.0.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/v2.0.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/v2.0.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/v2.0.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/v2.0.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/v2.0.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.1.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/v2.0.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.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) |
+| <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/v2.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/v2.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/v2.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/v2.0.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.1.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/v2.0.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.1.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/v2.0.0/packages/play-xstate/src/routing/types.ts#L2) |

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

@@ -6,7 +6,7 @@
 type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 ```
 
-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)
+Defined in: [packages/play-xstate/src/guards/compose.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L32)
 
 Narrowest public return type for guard composition helpers.
 

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

@@ -6,7 +6,7 @@
 type Guard<TContext, TEvent> = (args) => boolean;
 ```
 
-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)
+Defined in: [packages/play-xstate/src/guards/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/types.ts#L12)
 
 Standard XState guard function signature — guards receive `{ context, event }`.
 

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

@@ -6,7 +6,7 @@
 type GuardArray<TContext, TEvent> = (Guard<TContext, TEvent> | string)[];
 ```
 
-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)
+Defined in: [packages/play-xstate/src/guards/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/types.ts#L22)
 
 Array of guard predicates or guard names — an array means AND: all must pass.
 

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

@@ -9,7 +9,7 @@ type PlayerFactory<TMachine> =
 		: (input, options?) => PlayerActor<TMachine>;
 ```
 
-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)
+Defined in: [packages/play-xstate/src/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L131)
 
 Factory function returned by definePlayer() — each call creates an
 independent actor instance from the same configuration.

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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L70)
 
 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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L71)
 
 ---
 
@@ -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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L56)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
 
 ---
 
@@ -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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L72)

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.1.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/v2.0.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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
 
 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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
 
 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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L19)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 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.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L27)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L44)
 
 Nested child states, recursively crawled for additional route declarations.

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.1.0/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.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:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L333)
+Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L338)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

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

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L291)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L291)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

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.1.0/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.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:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L312)
+Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L317)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -24,10 +24,15 @@ import { xmSvelteRunes } from "@xmachines/shared/vite-aliases";
 
 export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
 
+`packages/play-svelte/svelte.config.js` states the same policy a second
+time, because that file is published and this package is not — see
+`tests/svelte-runes-policy.test.ts`, which holds the two together. Change
+one and change the other.
+
 ## Returns
 
 `object`
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `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) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L318) |

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.1.0/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.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.1.0/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.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.1.0/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.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.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) |
+| <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/v2.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/v2.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/v2.0.0/packages/shared/config/vitest.ts#L138) |

package/contributing/architecture.md

@@ -167,11 +167,11 @@ flowchart TD
 ```mermaid
 flowchart TD
     A["XState snapshot.getMeta()"]
-    B["resolveViewMeta(meta)\nfinds first meta.view with root + elements"]
-    C["Extract context.params\nURL path params set by formatPlayRouteTransitions assign"]
-    D["Extract contextProps allowlist\nexplicit opt-in from PlaySpec.contextProps"]
-    E["mergeRouteParamsIntoProps()\npriority: spec prop > URL param > contextProps value"]
-    F["Enriched PlaySpec set on currentView signal"]
+    B["resolveViewMeta(meta)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
+    C["snapshot.context\nprojected wholesale as the /context slice"]
+    D["composePlayState(spec.state, slice)\nstate: { ...authored, context: slice }"]
+    E["reuseComposedState (in validateAndCacheView)\ncarry previous state reference when the slice is value-unchanged"]
+    F["Derived PlaySpec (with viewKey) set on currentView signal"]
 
     A --> B --> C --> D --> E --> F
 ```
@@ -223,7 +223,7 @@ Optional capability interface. Exposes `currentView: Signal.State<PlaySpec | nul
 
 ### [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)
 
-Extends `@xmachines/json-render-core` `Spec` with `readonly contextProps?: readonly string[]` — an explicit allowlist of machine context fields that `deriveCurrentView` merges into element props. Only fields named here are ever exposed to components. `typedSpec<TContext>()` provides compile-time validation of `contextProps` entries against the machine's context type.
+Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
 

package/contributing/deployment.md

@@ -73,7 +73,7 @@ The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml
 The `node-build` job runs with:
 
 ```bash
-pnpm run build           # tsc --build (TypeScript composite build)
+pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
 pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
 ```
 
@@ -162,7 +162,7 @@ Step by step:
 1. **Enable corepack** — activates the pinned pnpm version.
 2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
 3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
-4. **Build** — runs `tsc --build` to produce compiled `dist/` output in all packages.
+4. **Build** — runs `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
 5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
 6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
 

package/contributing/development.md

@@ -41,14 +41,16 @@ pnpm install --frozen-lockfile
 pnpm run build
 ```
 
-The root-level `tsc --build` command uses TypeScript project references to build all packages in the correct dependency order automatically. You never need to sequence builds manually.
+The root build is two commands: `vite build` emits every package's JavaScript, then `tsc --build` emits the declarations through TypeScript project references, in dependency order. You never need to sequence builds manually.
 
-To build a single package (and its upstream dependencies):
+To build a single package:
 
 ```bash
 pnpm --filter @xmachines/<package-name> run build
 ```
 
+That runs the same two commands scoped to one package, so it produces the same `dist/` the root build would — JavaScript and declarations. It needs no other package's `dist/` to exist first: cross-package imports resolve to `src/` through the `source` export condition.
+
 ### Dev Container (Optional)
 
 A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
@@ -188,7 +190,7 @@ The monorepo uses **TypeScript project references** for correct build-order mana
 
 - The **root `tsconfig.json`** coordinates all packages via a `references` array — it compiles nothing itself
 - Each package has `composite: true` in its own `tsconfig.json`, enabling incremental and referenced builds
-- Packages declare `references` to their `@xmachines/*` dependencies so `tsc --build` resolves order automatically
+- The root `references` array is what orders the build; a package's own `tsc --build` needs no reference graph, because cross-package imports resolve to `src/` through the `source` export condition
 - With `declarationMap: true` in the base config, **Go to Definition** in your IDE navigates to `.ts` source files rather than compiled `.d.ts` files
 
 ### Build Layers

package/contributing/testing.md

@@ -264,23 +264,32 @@ class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
 }
 ```
 
-**Factory functions for lightweight inline mocks:**
+**Factory functions for lightweight inline mocks — use `stubOf`, never a double-cast:**
 
 ```typescript
+import { stubOf } from "@xmachines/shared/test-support";
+
 function createMockActor(initialView: PlaySpec | null = null) {
-	return {
+	return stubOf<AbstractActor<AnyActorLogic> & Viewable>({
 		currentView: new Signal.State<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
 		stop: vi.fn(),
 		getSnapshot: vi.fn(),
 		subscribe: vi.fn(),
-		state: new Signal.State({} as unknown),
+		state: new Signal.State<unknown>({}),
 		currentRoute: new Signal.Computed(() => null),
-	} as unknown as AbstractActor<AnyActorLogic> & Viewable;
+	});
 }
 ```
 
+`stubOf` keeps every declared member type-checked against the target type (a
+`send` with the wrong signature is a compile error) while allowing the rest to
+be absent — the one unsound assertion lives inside the helper, not at call
+sites. `X as unknown as T` is banned in this repo; if `stubOf` cannot express
+the case, `unsafeCast<T>(value)` from the same module is the deliberate,
+greppable escape hatch.
+
 ### Async and signal patterns
 
 **Flushing the microtask queue (required for Signal propagation):**
@@ -317,14 +326,16 @@ watcher.unwatch(actor.currentRoute); // Always clean up
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
 
 ```typescript
-const bad: PlaySpec = typedSpec<MyCtx>({
+const bad: PlaySpec = typedSpec({
 	root: "root",
-	// @ts-expect-error "typo" is not a key of MyCtx — typedSpec enforces this
-	contextProps: ["typo"],
 	elements: {},
+	// @ts-expect-error "stat" is not a PlaySpec field — typedSpec flags it on an
+	// inline literal (excess-property checking does not reach aliased or spread
+	// objects; use `satisfies PlaySpec` at the literal for those)
+	stat: {},
 });
 // At runtime the object exists; only the compile-time error is being tested
-expect(bad.contextProps).toEqual(["typo"]);
+expect(bad.root).toBe("root");
 ```
 
 For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `src/`:
@@ -343,8 +354,11 @@ These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.j
 ### Error testing
 
 ```typescript
-// Synchronous throws
-expect(() => actor.send(null as unknown as PlayEvent)).toThrow(InvalidEventError);
+import { unsafeCast } from "@xmachines/shared/test-support";
+
+// Synchronous throws — feed a runtime guard an invalid value through
+// unsafeCast, the named escape hatch (never `null as unknown as PlayEvent`).
+expect(() => actor.send(unsafeCast<PlayEvent>(null))).toThrow(InvalidEventError);
 
 // Error with message pattern
 expect(() => extractMachineRoutes(dupMachine)).toThrow(/Duplicate route paths detected/);

package/examples/@xmachines/play-dom-demo/README.md

@@ -1,11 +1,11 @@
 [Examples](../../README.md) / @xmachines/play-dom-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-dom-demo
 
 Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `createPlayUI` without a router.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
 `container`, observes actor.state via watchSignal, and updates button

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -3,10 +3,10 @@
 # Function: initShell()
 
 ```ts
-function initShell(actor, appElement, inspector): () => void;
+function initShell(actor, appElement): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.
@@ -14,11 +14,10 @@ Returns a disconnect function.
 
 ## Parameters
 
-| Parameter    | Type            |
-| ------------ | --------------- |
-| `actor`      | `AuthActor`     |
-| `appElement` | `HTMLElement`   |
-| `inspector`  | `DemoInspector` |
+| Parameter    | Type          |
+| ------------ | ------------- |
+| `actor`      | `AuthActor`   |
+| `appElement` | `HTMLElement` |
 
 ## Returns
 

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-dom-demo/variables/About.md

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Contact.md

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
 
 Contact — Public contact page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Dashboard.md

@@ -6,7 +6,7 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
 
 Dashboard — Protected authenticated home. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout