@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -1,8 +1,8 @@
-[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:362](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L362)
 
 Concrete XState actor implementing Play Architecture signal protocol
 
@@ -46,7 +46,7 @@ console.log(actor.currentRoute.get()); // '/'
 console.log(actor.currentView.get()); // { component: 'HomePage' }
 ```
 
-Signal lifecycle with watchers (microtask batching)
+Signal lifecycle with watchers
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -60,12 +60,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 +83,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 +103,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:454](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L454)
 
 #### 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?` | [`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\> |
 
 #### Returns
 
@@ -129,22 +129,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 (e.g. a required parameter is absent from context). **Throws** When a required `:param` placeholder in the route template has no matching value in the actor's context. Import the class from `@xmachines/play-xstate/errors`. **Example** `// Returns "/profile/alice" when context.userId === "alice" const route = actor.currentRoute.get();`                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:408](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L408) |
+| <a id="property-currentview"></a> `currentView`   | `public`   | [`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. **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:452](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L452) |
+| <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:425](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L425) |
+| <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:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L373) |
+| <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 +154,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,13 +166,44 @@ Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
 
 ---
 
+### can()
+
+```ts
+can(event): boolean;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:386](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L386)
+
+Returns whether the actor's current state can accept the given event.
+
+Typed to the machine's event union — passing an unknown event type is a
+compile error. Delegates to the underlying XState actor's snapshot.
+
+#### Parameters
+
+| Parameter | Type                                                                                  |
+| --------- | ------------------------------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> |
+
+#### Returns
+
+`boolean`
+
+#### Example
+
+```typescript
+if (actor.can({ type: "auth.logout" })) { ... }
+```
+
+---
+
 ### dispose()
 
 ```ts
 dispose(): void;
 ```
 
-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:727](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L727)
 
 Convenience dispose method for cleanup
 
@@ -190,29 +221,18 @@ Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
 getPersistedSnapshot(): Snapshot<unknown>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:152
-
-Obtain the internal state of the actor, which can be persisted.
-
-#### Returns
-
-`Snapshot`\<`unknown`\>
-
-#### Remarks
+Defined in: [packages/play-xstate/src/player-actor.ts:685](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L685)
 
-The internal state can be persisted from any actor, not only machines.
+Get the persisted snapshot of the wrapped XState actor.
 
-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](#)
-
-#### See
+#### Returns
 
-https://stately.ai/docs/persistence
+[`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>
 
-#### Inherited from
+#### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`getPersistedSnapshot`](../../play-actor/classes/AbstractActor.md#getpersistedsnapshot)
 
@@ -224,13 +244,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:609](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L609)
 
 Get current snapshot
 
 #### Returns
 
-`SnapshotFrom`\<`TMachine`\>
+[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>
 
 #### Overrides
 
@@ -244,7 +264,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:670](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L670)
+
+Listen for events emitted by the wrapped XState actor via the `emit` action.
 
 #### Type Parameters
 
@@ -254,48 +276,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:586](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L586)
 
-Send event to actor
+Send an event to the underlying XState 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,7 +374,7 @@ 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:541](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L541)
 
 Start the actor
 
@@ -336,7 +396,7 @@ 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:555](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L555)
 
 Stop the actor and cleanup
 
@@ -358,70 +418,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:631](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L631)
+
+Subscribe to snapshot updates from the wrapped XState actor.
 
-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
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-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);
-});
-```
+Subscription with an `unsubscribe()` method.
 
-```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();
-```
-
-When the actor is stopped, all of its observers will automatically be
-unsubscribed.
-
-##### Inherited from
+##### Overrides
 
 [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`subscribe`](../../play-actor/classes/AbstractActor.md#subscribe)
 
@@ -434,72 +449,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:642](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L642)
+
+Subscribe to snapshot updates from the wrapped XState actor.
 
-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 +481,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