@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-xstate/classes/PlayerActor.md

@@ -1,15 +1,17 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerActor
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerActor
 
 # Class: PlayerActor\<TMachine\>
 
-Defined in: [packages/play-xstate/src/player-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L120)
+Defined in: [packages/play-xstate/src/player-actor.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L193)
 
 Concrete XState actor implementing Play Architecture signal protocol
 
-Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) to provide XState v5 integration
-while maintaining ecosystem compatibility (XState inspection, devtools). This actor
-wraps an internal XState actor and exposes TC39 Signal-based reactive state for
-Infrastructure observation.
+Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) — and so XState's own `Actor` —
+to provide XState v5 integration while maintaining ecosystem compatibility (XState
+inspection, devtools). The machine is handed to the base constructor, so a
+`PlayerActor` **is** the XState actor rather than a wrapper around one: everything
+XState's `Actor` exposes operates on this instance's own state, and the class adds
+TC39 Signal-based reactive state for Infrastructure observation on top.
 
 **Capabilities:** Implements both [@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) and
 [@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) interfaces, providing routing and view
@@ -32,7 +34,14 @@ const machine = setup({}).createMachine({
 	initial: "idle",
 	states: {
 		idle: {
-			meta: { route: "/", view: { component: "HomePage" } },
+			meta: {
+				route: "/",
+				// A view spec needs `root` and `elements` — other shapes derive null.
+				view: {
+					root: "home",
+					elements: { home: { type: "HomePage", props: {}, children: [] } },
+				},
+			},
 		},
 	},
 });
@@ -43,10 +52,10 @@ actor.start();
 
 // Observe signals
 console.log(actor.currentRoute.get()); // '/'
-console.log(actor.currentView.get()); // { component: 'HomePage' }
+console.log(actor.currentView.get()?.root); // 'home'
 ```
 
-Signal lifecycle with watchers (microtask batching)
+Signal lifecycle with watchers
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -60,12 +69,12 @@ const watcher = new Signal.subtle.Watcher(() => {
 
 watcher.watch(actor.state);
 actor.send({ type: "play.route", to: "#about" });
-// Watcher notification scheduled via microtask
+// Watcher notification scheduled via microtask by the watcher itself
 ```
 
 ## See
 
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [Play RFC](../../../../rfc/play.md)
 - [definePlayer](../functions/definePlayer.md) for factory creation
 - [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) for signal protocol
 - [@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) for routing capability
@@ -83,13 +92,13 @@ cached and updated at state entry, not computed on every read.
 
 ## Extends
 
-- [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\>
+- [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\>\>
 
 ## Type Parameters
 
-| Type Parameter                         | Description                  |
-| -------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` | XState v5 state machine type |
+| Type Parameter                                                                                 | Description                  |
+| ---------------------------------------------------------------------------------------------- | ---------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine type |
 
 ## Implements
 
@@ -103,21 +112,21 @@ cached and updated at state entry, not computed on every read.
 ```ts
 new PlayerActor<TMachine>(
    machine,
-   catalog,
    options,
-input?): PlayerActor<TMachine>;
+   input?,
+restoredSnapshot?): PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L142)
+Defined in: [packages/play-xstate/src/player-actor.ts:343](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L343)
 
 #### Parameters
 
-| Parameter | Type                                                             |
-| --------- | ---------------------------------------------------------------- |
-| `machine` | `TMachine`                                                       |
-| `catalog` | [`Catalog`](../type-aliases/Catalog.md) \| `null` \| `undefined` |
-| `options` | [`PlayerOptions`](../interfaces/PlayerOptions.md)\<`TMachine`\>  |
-| `input?`  | `InputFrom`\<`TMachine`\>                                        |
+| Parameter           | Type                                                                        |
+| ------------------- | --------------------------------------------------------------------------- |
+| `machine`           | `TMachine`                                                                  |
+| `options`           | [`PlayerOptions`](../interfaces/PlayerOptions.md)\<`TMachine`\>             |
+| `input?`            | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\> |
+| `restoredSnapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>    |
 
 #### Returns
 
@@ -129,22 +138,22 @@ Defined in: [packages/play-xstate/src/player-actor.ts:142](https://gitlab.com/xm
 
 ## Properties
 
-| Property                                          | Modifier | Type                                                                                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Overrides                                                                                                                        | Inherited from                                                                                                                           | Defined in                                                                                                                                                                               |
-| ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-_parent"></a> `_parent?`          | `public` | `AnyActorRef`                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`_parent`](../../play-actor/classes/AbstractActor.md#property-_parent)     | node_modules/xstate/dist/declarations/src/createActor.d.ts:33                                                                                                                            |
-| <a id="property-catalog"></a> `catalog`           | `public` | [`Catalog`](../type-aliases/Catalog.md)                                                                                                     | Component catalog for view resolution Maps component names to actual component implementations. Used by renderers to resolve view.component to actual UI components.                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L140) |
-| <a id="property-clock"></a> `clock`               | `public` | `Clock`                                                                                                                                     | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`clock`](../../play-actor/classes/AbstractActor.md#property-clock)         | node_modules/xstate/dist/declarations/src/createActor.d.ts:25                                                                                                                            |
-| <a id="property-currentroute"></a> `currentRoute` | `public` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                                | Current route signal Computed signal derived from state machine. Infrastructure observes to sync browser URL. Invariant: Passive Infrastructure - Infrastructure reflects route, never decides. **Example** `const watcher = new Signal.subtle.Watcher(() => { const route = actor.currentRoute.get(); console.log('Route changed:', route); }); watcher.watch(actor.currentRoute);`                                                                                                                                                                                                                     | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L138) |
-| <a id="property-currentview"></a> `currentView`   | `public` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`ViewMetadata`](../../play-actor/interfaces/ViewMetadata.md) \| `null`\> | Current view signal State signal containing UI structure schema from meta.view. Infrastructure renders view. Invariant: Logic-Driven UI - View structure is defined by business logic, not JSX. **Example** `const watcher = new Signal.subtle.Watcher(() => { const view = actor.currentView.get(); console.log('View changed:', view); }); watcher.watch(actor.currentView);`                                                                                                                                                                                                                          | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L139) |
-| <a id="property-id"></a> `id`                     | `public` | `string`                                                                                                                                    | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`id`](../../play-actor/classes/AbstractActor.md#property-id)               | node_modules/xstate/dist/declarations/src/createActor.d.ts:28                                                                                                                            |
-| <a id="property-logic"></a> `logic`               | `public` | `AnyActorLogic`                                                                                                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`logic`](../../play-actor/classes/AbstractActor.md#property-logic)         | node_modules/xstate/dist/declarations/src/createActor.d.ts:18                                                                                                                            |
-| <a id="property-options"></a> `options`           | `public` | `Readonly`\<`ActorOptions`\<`TLogic`\>\>                                                                                                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`options`](../../play-actor/classes/AbstractActor.md#property-options)     | node_modules/xstate/dist/declarations/src/createActor.d.ts:26                                                                                                                            |
-| <a id="property-ref"></a> `ref`                   | `public` | `ActorRef`\<`any`, `any`, `any`\>                                                                                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-ref)             | node_modules/xstate/dist/declarations/src/createActor.d.ts:34                                                                                                                            |
-| <a id="property-sessionid"></a> `sessionId`       | `public` | `string`                                                                                                                                    | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`sessionId`](../../play-actor/classes/AbstractActor.md#property-sessionid) | node_modules/xstate/dist/declarations/src/createActor.d.ts:38                                                                                                                            |
-| <a id="property-src"></a> `src`                   | `public` | `string` \| `AnyActorLogic`                                                                                                                 | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`src`](../../play-actor/classes/AbstractActor.md#property-src)             | node_modules/xstate/dist/declarations/src/createActor.d.ts:42                                                                                                                            |
-| <a id="property-state"></a> `state`               | `public` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`AnyMachineSnapshot`\>                                                    | Reactive snapshot of current actor state. Typed as `Signal.State<unknown>` at the abstract level; concrete implementations narrow this to the actual snapshot type (e.g., `Signal.State<AnyMachineSnapshot>` in `@xmachines/play-xstate`'s `PlayerActor`). Infrastructure observes this signal to react to state changes without directly coupling to the Actor's internal state machine implementation. **Example** `// Infrastructure observes state signal const watcher = new Signal.subtle.Watcher(() => { console.log('Actor state changed:', actor.state.get()); }); watcher.watch(actor.state);` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L137) |
-| <a id="property-system"></a> `system`             | `public` | `AnyActorSystem`                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`system`](../../play-actor/classes/AbstractActor.md#property-system)       | node_modules/xstate/dist/declarations/src/createActor.d.ts:40                                                                                                                            |
-| <a id="property-systemid"></a> `systemId`         | `public` | `string` \| `undefined`                                                                                                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`systemId`](../../play-actor/classes/AbstractActor.md#property-systemid)   | node_modules/xstate/dist/declarations/src/createActor.d.ts:36                                                                                                                            |
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Overrides                                                                                                                        | Inherited from                                                                                                                           | Defined in                                                                                                                                             |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-_parent"></a> `_parent?`          | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`_parent`](../../play-actor/classes/AbstractActor.md#property-_parent)     | -                                                                                                                                                      |
+| <a id="property-clock"></a> `clock`               | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                               | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`clock`](../../play-actor/classes/AbstractActor.md#property-clock)         | -                                                                                                                                                      |
+| <a id="property-currentroute"></a> `currentRoute` | `public`   | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | A TC39 `Signal.Computed` that derives the current URL path from the active machine state's `meta.route` template and the actor's context. Returns `null` when the current state has no `meta.route`, or when the route template cannot be fully resolved — a required `:param` absent from context is caught internally (`MissingRouteParamError` never escapes `get()`): the condition is transient mid-transition and the signal recomputes on the next snapshot. **Example** `// Returns "/profile/alice" when context.params.userId === "alice", // and null while the param is still missing. const route = actor.currentRoute.get();`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L292) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | Reactive signal containing the current view spec derived from the active state's `meta.view` metadata. Emits a **fresh object reference** whenever the rendered view actually changes — a different state's view, or a param/context change that alters the resolved spec (including `reenter: true` re-entries with new params). Snapshots that do not change the rendered view (e.g. context-only assigns) keep the previous reference so downstream providers do not remount the UI on every event. The emitted `PlaySpec` has its element `props` enriched with `context.params` before emission — URL path parameters (e.g. `:section?`) flow into component props automatically. See `mergeRouteParamsIntoProps` for the merge priority rules. Returns `null` when the current state has no `meta.view` metadata. Two states declaring separate but structurally identical `meta.view` literals emit distinct references on a transition between them (a provider remount); hoist the shared literal into one `typedSpec` constant to deduplicate by identity. **Example** `const view = actor.currentView.get(); if (view) { console.log(view.root); // e.g. "root" console.log(view.elements); // @xmachines/json-render-core Spec elements }` | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L341) |
+| <a id="property-id"></a> `id`                     | `public`   | `string`                                                                                                                            | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`id`](../../play-actor/classes/AbstractActor.md#property-id)               | -                                                                                                                                                      |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction, never changes even when the actor is restored from a snapshot. Router bridges compare this against the browser URL to distinguish a deep-link (non-initial URL → router wins) from a restore (initial URL + actor at a different restored route → actor wins). Derived statically from the machine definition via `deriveInitialRoute` (XState's pure `initialTransition` helper): the initial state chain and its `meta.route` templates are fixed at machine definition time, while `:param` substitution uses the machine's real initial context for this actor's `input`. No extra actor is ever created, and a restored snapshot never influences the value — it is always the machine's **default** initial route.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L309) |
+| <a id="property-logic"></a> `logic`               | `public`   | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`logic`](../../play-actor/classes/AbstractActor.md#property-logic)         | -                                                                                                                                                      |
+| <a id="property-options"></a> `options`           | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`options`](../../play-actor/classes/AbstractActor.md#property-options)     | -                                                                                                                                                      |
+| <a id="property-ref"></a> `ref`                   | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<`any`, `any`, `any`\>                                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-ref)             | -                                                                                                                                                      |
+| <a id="property-sessionid"></a> `sessionId`       | `public`   | `string`                                                                                                                            | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`sessionId`](../../play-actor/classes/AbstractActor.md#property-sessionid) | -                                                                                                                                                      |
+| <a id="property-src"></a> `src`                   | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`src`](../../play-actor/classes/AbstractActor.md#property-src)             | -                                                                                                                                                      |
+| <a id="property-state"></a> `state`               | `public`   | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`ReturnType`\<`TMachine`\[`"transition"`\]\>\>                    | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:252](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L252) |
+| <a id="property-system"></a> `system`             | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                             | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`system`](../../play-actor/classes/AbstractActor.md#property-system)       | -                                                                                                                                                      |
+| <a id="property-systemid"></a> `systemId`         | `public`   | `string` \| `undefined`                                                                                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`systemId`](../../play-actor/classes/AbstractActor.md#property-systemid)   | -                                                                                                                                                      |
 
 ## Methods
 
@@ -154,11 +163,11 @@ Defined in: [packages/play-xstate/src/player-actor.ts:142](https://gitlab.com/xm
 observable: InteropSubscribable<any>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
+Defined in: `xstate`
 
 #### Returns
 
-`InteropSubscribable`\<`any`\>
+[`InteropSubscribable`](https://www.jsdocs.io/package/xstate#InteropSubscribable)\<`any`\>
 
 #### Inherited from
 
@@ -166,53 +175,77 @@ Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
 
 ---
 
-### dispose()
+### can()
 
 ```ts
-dispose(): void;
+can(event): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:434](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L434)
+Defined in: [packages/play-xstate/src/player-actor.ts:265](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L265)
 
-Convenience dispose method for cleanup
+Returns whether the actor's current state can accept the given event.
 
-Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
+Typed to the machine's event union — passing an unknown event type is a
+compile error. Evaluated against the current snapshot signal.
+
+#### Parameters
+
+| Parameter | Type                                                                                  |
+| --------- | ------------------------------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> |
 
 #### Returns
 
-`void`
+`boolean`
+
+#### Example
+
+```typescript
+if (actor.can({ type: "auth.logout" })) { ... }
+```
 
 ---
 
-### getPersistedSnapshot()
+### dispose()
 
 ```ts
-getPersistedSnapshot(): Snapshot<unknown>;
+dispose(): void;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:152
+Defined in: [packages/play-xstate/src/player-actor.ts:719](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L719)
 
-Obtain the internal state of the actor, which can be persisted.
+Convenience dispose method for cleanup — an alias for [stop](#stop).
 
 #### Returns
 
-`Snapshot`\<`unknown`\>
+`void`
+
+---
+
+### getPersistedSnapshot()
+
+```ts
+getPersistedSnapshot(options?): Snapshot<unknown>;
+```
 
-#### Remarks
+Defined in: [packages/play-xstate/src/player-actor.ts:672](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L672)
 
-The internal state can be persisted from any actor, not only machines.
+Get this actor's persisted snapshot.
 
-Note that the persisted state is not the same as the snapshot from
-[Actor.getSnapshot](../../play-actor/classes/AbstractActor.md#getsnapshot). Persisted state represents the internal state of
-the actor, while snapshots represent the actor's last emitted value.
+Suitable for serialization and later restoration via the factory's
+`restore.snapshot` option.
 
-Can be restored with [ActorOptions.state](#)
+#### Parameters
 
-#### See
+| Parameter  | Type      |
+| ---------- | --------- |
+| `options?` | `unknown` |
 
-https://stately.ai/docs/persistence
+#### Returns
 
-#### Inherited from
+[`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>
+
+#### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`getPersistedSnapshot`](../../play-actor/classes/AbstractActor.md#getpersistedsnapshot)
 
@@ -224,13 +257,13 @@ https://stately.ai/docs/persistence
 getSnapshot(): SnapshotFrom<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:307](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L307)
+Defined in: [packages/play-xstate/src/player-actor.ts:570](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L570)
 
 Get current snapshot
 
 #### Returns
 
-`SnapshotFrom`\<`TMachine`\>
+[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>
 
 #### Overrides
 
@@ -244,7 +277,9 @@ Get current snapshot
 on<TType>(type, handler): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:115
+Defined in: [packages/play-xstate/src/player-actor.ts:657](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L657)
+
+Listen for events this actor emits via the `emit` action.
 
 #### Type Parameters
 
@@ -254,48 +289,86 @@ Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:115
 
 #### Parameters
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| `type`    | `TType`               |
-| `handler` | (`emitted`) => `void` |
+| Parameter | Type                  | Description                                         |
+| --------- | --------------------- | --------------------------------------------------- |
+| `type`    | `TType`               | Emitted event type to listen for, or `"*"` for all. |
+| `handler` | (`emitted`) => `void` | Called with each matching emitted event.            |
 
 #### Returns
 
-`Subscription`
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-#### Inherited from
+Subscription with an `unsubscribe()` method.
+
+#### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`on`](../../play-actor/classes/AbstractActor.md#on)
 
 ---
 
+### select()
+
+```ts
+select<TSelected>(selector, equalityFn?): Readable<TSelected>;
+```
+
+Defined in: `xstate`
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TSelected`    |
+
+#### Parameters
+
+| Parameter     | Type                        |
+| ------------- | --------------------------- |
+| `selector`    | (`snapshot`) => `TSelected` |
+| `equalityFn?` | (`a`, `b`) => `boolean`     |
+
+#### Returns
+
+`Readable`\<`TSelected`\>
+
+#### Inherited from
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`select`](../../play-actor/classes/AbstractActor.md#select)
+
+---
+
 ### send()
 
 ```ts
 send(event): void;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L282)
+Defined in: [packages/play-xstate/src/player-actor.ts:532](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L532)
 
-Send event to actor
+Send an event to this actor.
 
-Forwards events to the underlying XState actor. The actor's state machine
-guards determine whether each event is valid from the current state.
+The actor's state machine guards decide whether the event causes a transition.
+Pass any event from the machine's event union — domain events, routing events, etc.
 
 #### Parameters
 
-| Parameter | Type                                                | Description                           |
-| --------- | --------------------------------------------------- | ------------------------------------- |
-| `event`   | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) | Any event object with a type property |
+| Parameter | Type                                                                                  | Description                                                   |
+| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> | An event from the machine's `EventFromLogic<TMachine>` union. |
 
 #### Returns
 
 `void`
 
+#### Throws
+
+When `event` is not a plain object (`null`, `undefined`,
+a string, number, etc.). Import the class from `@xmachines/play-xstate/errors`.
+
 #### Example
 
 ```typescript
-// Domain event
+// Domain event (typed to machine's event union)
 actor.send({ type: "auth.login", userId: "123" });
 
 // Routing event
@@ -314,11 +387,15 @@ actor.send({ type: "play.route", to: "#home" });
 start(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L239)
+Defined in: [packages/play-xstate/src/player-actor.ts:460](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L460)
 
-Start the actor
+Start the actor.
 
-Per RESEARCH.md Pitfall 1: Always call start() after creation
+Fires `onStart` on each real start — every transition from not-running to
+running, including a start after a stop, which XState allows (its own
+`start()` bails only while the actor is already RUNNING). A repeated call
+while running does not re-fire it, so a defensive double mount does not
+re-run `onStart` side effects for one actual start.
 
 #### Returns
 
@@ -336,9 +413,16 @@ Per RESEARCH.md Pitfall 1: Always call start() after creation
 stop(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:253](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L253)
+Defined in: [packages/play-xstate/src/player-actor.ts:490](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L490)
 
-Stop the actor and cleanup
+Stop the actor and clean up.
+
+Fires `onStop` only when the actor was actually running — mirroring
+XState, where stopping a never-started or already-stopped actor is a
+no-op with zero teardown — so paired cleanup never runs twice, nor
+against resources `onStart` never acquired. Stopping does not close the
+actor for good: a later `start()` is a fresh lifecycle and fires
+`onStart` again.
 
 #### Returns
 
@@ -358,70 +442,25 @@ Stop the actor and cleanup
 subscribe(observer): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:113
+Defined in: [packages/play-xstate/src/player-actor.ts:594](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L594)
+
+Subscribe to this actor's snapshot updates.
 
-Subscribe an observer to an actor’s snapshot values.
+Accepts an observer object, exactly like XState's `Actor.subscribe`.
 
 ##### Parameters
 
-| Parameter  | Type                | Description                                                                                                                                  |
-| ---------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observer` | `Observer`\<`any`\> | Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot |
+| Parameter  | Type                                                                                                                                             | Description                                       |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| `observer` | [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\> | Observer with `next`/`error`/`complete` handlers. |
 
 ##### Returns
 
-`Subscription`
-
-##### Remarks
-
-The observer will receive the actor’s snapshot value when it is emitted.
-The observer can be:
-
-- A plain function that receives the latest snapshot, or
-- An observer object whose `.next(snapshot)` method receives the latest
-  snapshot
-
-##### Examples
-
-```ts
-// Observer as a plain function
-const subscription = actor.subscribe((snapshot) => {
-	console.log(snapshot);
-});
-```
-
-```ts
-// Observer as an object
-const subscription = actor.subscribe({
-	next(snapshot) {
-		console.log(snapshot);
-	},
-	error(err) {
-		// ...
-	},
-	complete() {
-		// ...
-	},
-});
-```
-
-The return value of `actor.subscribe(observer)` is a subscription object
-that has an `.unsubscribe()` method. You can call
-`subscription.unsubscribe()` to unsubscribe the observer:
-
-```ts
-const subscription = actor.subscribe((snapshot) => {
-	// ...
-});
-
-// Unsubscribe the observer
-subscription.unsubscribe();
-```
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-When the actor is stopped, all of its observers will automatically be
-unsubscribed.
+Subscription with an `unsubscribe()` method.
 
-##### Inherited from
+##### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`subscribe`](../../play-actor/classes/AbstractActor.md#subscribe)
 
@@ -434,72 +473,27 @@ subscribe(
    completeListener?): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:114
+Defined in: [packages/play-xstate/src/player-actor.ts:605](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-xstate/src/player-actor.ts#L605)
+
+Subscribe to this actor's snapshot updates.
 
-Subscribe an observer to an actor’s snapshot values.
+Accepts listener functions, exactly like XState's `Actor.subscribe`.
 
 ##### Parameters
 
-| Parameter           | Type                   |
-| ------------------- | ---------------------- |
-| `nextListener?`     | (`snapshot`) => `void` |
-| `errorListener?`    | (`error`) => `void`    |
-| `completeListener?` | () => `void`           |
+| Parameter           | Type                   | Description                                              |
+| ------------------- | ---------------------- | -------------------------------------------------------- |
+| `nextListener?`     | (`snapshot`) => `void` | Snapshot listener function.                              |
+| `errorListener?`    | (`error`) => `void`    | Called when the actor errors.                            |
+| `completeListener?` | () => `void`           | Called when the actor completes (reaches a final state). |
 
 ##### Returns
 
-`Subscription`
-
-##### Remarks
-
-The observer will receive the actor’s snapshot value when it is emitted.
-The observer can be:
-
-- A plain function that receives the latest snapshot, or
-- An observer object whose `.next(snapshot)` method receives the latest
-  snapshot
-
-##### Examples
-
-```ts
-// Observer as a plain function
-const subscription = actor.subscribe((snapshot) => {
-	console.log(snapshot);
-});
-```
-
-```ts
-// Observer as an object
-const subscription = actor.subscribe({
-	next(snapshot) {
-		console.log(snapshot);
-	},
-	error(err) {
-		// ...
-	},
-	complete() {
-		// ...
-	},
-});
-```
-
-The return value of `actor.subscribe(observer)` is a subscription object
-that has an `.unsubscribe()` method. You can call
-`subscription.unsubscribe()` to unsubscribe the observer:
-
-```ts
-const subscription = actor.subscribe((snapshot) => {
-	// ...
-});
-
-// Unsubscribe the observer
-subscription.unsubscribe();
-```
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-When the actor is stopped, all of its observers will automatically be
-unsubscribed.
+Subscription with an `unsubscribe()` method.
 
-##### Inherited from
+##### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`subscribe`](../../play-actor/classes/AbstractActor.md#subscribe)
 
@@ -511,16 +505,16 @@ unsubscribed.
 toJSON(): object;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:135
+Defined in: `xstate`
 
 #### Returns
 
 `object`
 
-| Name           | Type     | Defined in                                                     |
-| -------------- | -------- | -------------------------------------------------------------- |
-| `id`           | `string` | node_modules/xstate/dist/declarations/src/createActor.d.ts:137 |
-| `xstate$$type` | `number` | node_modules/xstate/dist/declarations/src/createActor.d.ts:136 |
+| Name           | Type     | Defined in |
+| -------------- | -------- | ---------- |
+| `id`           | `string` | -          |
+| `xstate$$type` | `number` | -          |
 
 #### Inherited from