@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,27 +2,32 @@
 
 # Class: PlayerActor\<TMachine\>
 
-Defined in: [packages/play-xstate/src/player-actor.ts:362](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L362)
+Defined in: [packages/play-xstate/src/player-actor.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L202)
 
-Concrete XState actor implementing Play Architecture signal protocol
+The concrete XState actor. It implements the signal protocol of the Play Architecture
 
-Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) to provide XState v6 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.
+The class extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md), and therefore the
+`Actor` class of XState. It gives you the XState v5 integration, and it keeps the
+compatibility with the ecosystem, such as the XState inspection and the devtools.
+The constructor of the base class receives the machine. Therefore a `PlayerActor`
+**is** the XState actor, and it is no wrapper around one: every member of the
+XState `Actor` class works on the state of this instance, and this class adds the
+reactive state on the TC39 Signals for the observation by the infrastructure.
 
-**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
-rendering support.
+**Capabilities:** the class implements both the
+[@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) interface and the
+[@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) interface. It therefore supports the
+routing and the view rendering.
 
-**Architectural Context:** Implements **Actor Authority (INV-01)** by ensuring the
-XState machine's guards control all navigation decisions. Infrastructure observes
-the actor's signals (`state`, `currentRoute`, `currentView`) but cannot directly
-manipulate state—all mutations flow through the state machine's event handlers.
+**Architectural context:** the class implements **Actor Authority (INV-01)**,
+because the guards of the XState machine control every decision of the
+navigation. The infrastructure observes the signals of the actor (`state`,
+`currentRoute`, and `currentView`), but it changes no state directly: every
+change goes through the event handlers of the state machine.
 
 ## Examples
 
-Basic actor creation and lifecycle
+The creation of an actor, and its lifecycle
 
 ```typescript
 import { setup } from "xstate";
@@ -32,7 +37,14 @@ const machine = setup({}).createMachine({
 	initial: "idle",
 	states: {
 		idle: {
-			meta: { route: "/", view: { component: "HomePage" } },
+			meta: {
+				route: "/",
+				// A view spec needs `root` and `elements`. Every other shape derives null.
+				view: {
+					root: "home",
+					elements: { home: { type: "HomePage", props: {}, children: [] } },
+				},
+			},
 		},
 	},
 });
@@ -41,12 +53,12 @@ const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
-// Observe signals
+// Observe the signals
 console.log(actor.currentRoute.get()); // '/'
-console.log(actor.currentView.get()); // { component: 'HomePage' }
+console.log(actor.currentView.get()?.root); // 'home'
 ```
 
-Signal lifecycle with watchers
+The signal lifecycle with a watcher
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -60,26 +72,28 @@ const watcher = new Signal.subtle.Watcher(() => {
 
 watcher.watch(actor.state);
 actor.send({ type: "play.route", to: "#about" });
-// Watcher notification scheduled via microtask by the watcher itself
+// The watcher schedules its own notification in a microtask
 ```
 
 ## See
 
 - [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
-- [@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) for view rendering capability
+- [definePlayer](../functions/definePlayer.md) for the creation through a factory
+- [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) for the signal protocol
+- [@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) for the routing capability
+- [@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) for the view rendering capability
 
 ## Remarks
 
-**Routing:** This actor supports both XState's `route: {}` config pattern
-and `play.route` events with parameters. The `deriveRoute()` function checks
-`meta.route` (Stately pattern) for URL templates with parameter substitution support.
+**The routing:** this actor supports the `route: {}` config pattern of XState and
+also a `play.route` event with parameters. The `deriveRoute()` function reads
+`meta.route`, which is the Stately pattern, for a URL template, and it substitutes
+each parameter.
 
-**View Signal Pattern:** The `currentView` signal is a direct `Signal.State` (not
-`Signal.Computed`) to ensure proper watcher propagation in PlayRenderer. Views are
-cached and updated at state entry, not computed on every read.
+**The pattern of the view signal:** the `currentView` signal is a direct
+`Signal.State`, and not a `Signal.Computed`. The propagation to a watcher in
+PlayRenderer is therefore correct. The class derives each view at the entry of a
+state and keeps it, and it computes no view on a read.
 
 ## Extends
 
@@ -87,9 +101,9 @@ cached and updated at state entry, not computed on every read.
 
 ## Type Parameters
 
-| Type Parameter                                                                                 | Description                  |
-| ---------------------------------------------------------------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v6 state machine type |
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
 
 ## Implements
 
@@ -108,16 +122,16 @@ new PlayerActor<TMachine>(
 restoredSnapshot?): PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:459](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L459)
+Defined in: [packages/play-xstate/src/player-actor.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L360)
 
 #### Parameters
 
-| 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`\> |
+| 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,23 +143,22 @@ Defined in: [packages/play-xstate/src/player-actor.ts:459](https://gitlab.com/xm
 
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Overrides                                                                                                                        | Inherited from                                                                                                                               | Defined in                                                                                                                                                     |
-| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-_parent"></a> `_parent?`          | `public`   | `AnyActor`                                                                                                                                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`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:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L413) |
-| <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:457](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L457) |
-| <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:430](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L430) |
-| <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`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject), `any`\> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-ref)                 | -                                                                                                                                                              |
-| <a id="property-registrykey"></a> `registryKey`   | `public`   | `string` \| `undefined`                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`registryKey`](../../play-actor/classes/AbstractActor.md#property-registrykey) | -                                                                                                                                                              |
-| <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)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\> | 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:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L375) |
-| <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-trigger"></a> `trigger`           | `public`   | `ActorTrigger`\<`SendableEventFromLogic`\<`TLogic`\>\>                                                                                                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`trigger`](../../play-actor/classes/AbstractActor.md#property-trigger)         | -                                                                                                                                                              |
+| 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`. It derives the current URL path from the `meta.route` template of the active machine state and from the context of the actor. It returns `null` when the current state has no `meta.route` field, and also when it cannot resolve the complete route template. A necessary `:param` that the context does not hold is caught inside the signal, and a `MissingRouteParamError` therefore never leaves `get()`: that condition is temporary during a transition, and the signal computes the value again on the next snapshot. **Example** `// It returns "/profile/alice" when context.params.userId === "alice", // and null while the param is still absent. const route = actor.currentRoute.get();`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:304](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L304) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | The reactive signal of the current view spec. The signal derives the spec from the `meta.view` metadata of the active state. It emits a **new object reference** on each real change of the view on the screen: the view of a different state, or a change of a param or of the context that changes the resolved spec. A re-entry with `reenter: true` and new params also changes the spec. A snapshot that changes no view on the screen, such as an assign of the context alone, keeps the previous reference. A provider below the signal therefore mounts the UI again not on every event. The `PlaySpec` of the emission carries the context of the machine in its composed `state` field, under the read-only `/context` subtree. A spec therefore reads the context, and also each URL param, through the ordinary state grammar (`{ $state: "/context/params/section" }`). The context-projection module of `@xmachines/play-actor` holds the complete contract. The signal returns `null` when the current state has no `meta.view` metadata. Two states can declare two separate `meta.view` literals with an identical structure. A transition between those two states then emits two different references, and a provider mounts the UI again. Move the shared literal into one `typedSpec` constant, and the identity then removes the duplicate. **Example** `const view = actor.currentView.get(); if (view) { console.log(view.root); // for example "root" console.log(view.elements); // the Spec elements of @xmachines/json-render-core }` | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L358) |
+| <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 of the initial state of the machine. The constructor fixes it, and it never changes, also when the code restores the actor from a snapshot. A router bridge compares it with the browser URL, and it therefore separates a deep link (a URL that is not the initial one → the router wins) from a restore (the initial URL, and the actor at a different route from the restore → the actor wins). `deriveInitialRoute` derives the value statically from the machine definition, with the pure `initialTransition` helper of XState: the chain of the initial states and their `meta.route` templates are fixed at the moment of the machine definition, and the substitution of a `:param` uses the real initial context of the machine for the `input` of this actor. The code makes no second actor, and a snapshot of a restore changes the value never: it is always the **default** initial route of the machine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:323](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L323) |
+| <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"`\]\>\>                    | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:263](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L263) |
+| <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
 
@@ -173,12 +186,12 @@ Defined in: `xstate`
 can(event): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:388](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L388)
+Defined in: [packages/play-xstate/src/player-actor.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L276)
 
-Returns whether the actor's current state can accept the given event.
+Tells you if the current state of the actor accepts 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.
+The type is the event union of the machine. An unknown event type is therefore a
+compile error. The method evaluates the event against the snapshot signal.
 
 #### Parameters
 
@@ -198,36 +211,44 @@ if (actor.can({ type: "auth.logout" })) { ... }
 
 ---
 
-### dispose()
+### ~~dispose()~~
 
 ```ts
 dispose(): void;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:731](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L731)
+Defined in: [packages/play-xstate/src/player-actor.ts:751](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L751)
 
-Convenience dispose method for cleanup
-
-Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
+The dispose method, for the cleanup. It is the alias of [stop](#stop).
 
 #### Returns
 
 `void`
 
+#### Deprecated
+
+Use [stop](#stop). Will be removed in the next major.
+
 ---
 
 ### getPersistedSnapshot()
 
 ```ts
-getPersistedSnapshot(): Snapshot<unknown>;
+getPersistedSnapshot(options?): Snapshot<unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:689](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L689)
+Defined in: [packages/play-xstate/src/player-actor.ts:696](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L696)
 
-Get the persisted snapshot of the wrapped XState actor.
+Returns the persisted snapshot of this actor.
 
-Suitable for serialization and later restoration via the factory's
-`restore.snapshot` option.
+Use it to serialize the state, and to restore it later with the
+`restore.snapshot` option of the factory.
+
+#### Parameters
+
+| Parameter  | Type      |
+| ---------- | --------- |
+| `options?` | `unknown` |
 
 #### Returns
 
@@ -245,9 +266,9 @@ Suitable for serialization and later restoration via the factory's
 getSnapshot(): SnapshotFrom<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:613](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L613)
+Defined in: [packages/play-xstate/src/player-actor.ts:595](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L595)
 
-Get current snapshot
+Returns the current snapshot
 
 #### Returns
 
@@ -265,28 +286,28 @@ Get current snapshot
 on<TType>(type, handler): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:674](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L674)
+Defined in: [packages/play-xstate/src/player-actor.ts:681](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L681)
 
-Listen for events emitted by the wrapped XState actor via the `emit` action.
+Listens for the events that this actor emits with the `emit` action.
 
 #### Type Parameters
 
-| Type Parameter             |
-| -------------------------- |
-| `TType` _extends_ `string` |
+| Type Parameter          |
+| ----------------------- |
+| `TType` _extends_ `any` |
 
 #### Parameters
 
-| Parameter | Type                  | Description                                         |
-| --------- | --------------------- | --------------------------------------------------- |
-| `type`    | `TType`               | Emitted event type to listen for, or `"*"` for all. |
-| `handler` | (`emitted`) => `void` | Called with each matching emitted event.            |
+| Parameter | Type                  | Description                                                            |
+| --------- | --------------------- | ---------------------------------------------------------------------- |
+| `type`    | `TType`               | The type of the emitted event to listen for, or `"*"` for every event. |
+| `handler` | (`emitted`) => `void` | The actor calls it with each emitted event that matches.               |
 
 #### Returns
 
 [`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-Subscription with an `unsubscribe()` method.
+The subscription, with an `unsubscribe()` method.
 
 #### Overrides
 
@@ -331,18 +352,19 @@ Defined in: `xstate`
 send(event): void;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:590](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L590)
+Defined in: [packages/play-xstate/src/player-actor.ts:556](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L556)
 
-Send an event to the underlying XState actor.
+Sends an event to this actor.
 
-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.
+The guards of the state machine of the actor decide if the event causes a
+transition. Give any event of the event union of the machine: a domain event, a
+routing event, and so on.
 
 #### Parameters
 
-| Parameter | Type                                                                                  | Description                                                   |
-| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> | An event from the machine's `EventFromLogic<TMachine>` union. |
+| Parameter | Type                                                                                  | Description                                                      |
+| --------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> | An event of the `EventFromLogic<TMachine>` union of the machine. |
 
 #### Returns
 
@@ -350,16 +372,17 @@ Pass any event from the machine's event union — domain events, routing events,
 
 #### Throws
 
-When `event` is not a plain object (`null`, `undefined`,
-a string, number, etc.). Import the class from `@xmachines/play-xstate/errors`.
+When `event` is not a plain object, for example
+`null`, `undefined`, a string, or a number. Import the class from
+`@xmachines/play-xstate/errors`.
 
 #### Example
 
 ```typescript
-// Domain event (typed to machine's event union)
+// A domain event, with the type of the event union of the machine
 actor.send({ type: "auth.login", userId: "123" });
 
-// Routing event
+// A routing event
 actor.send({ type: "play.route", to: "#home" });
 ```
 
@@ -375,11 +398,15 @@ actor.send({ type: "play.route", to: "#home" });
 start(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:545](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L545)
+Defined in: [packages/play-xstate/src/player-actor.ts:482](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L482)
 
-Start the actor
+Starts the actor.
 
-Per RESEARCH.md Pitfall 1: Always call start() after creation
+The method fires `onStart` on each real start, which is every transition from
+"not running" to "running". A start after a stop is such a transition, and XState
+permits it: its own `start()` stops only while the actor RUNS already. A second
+call while the actor runs fires no hook. Therefore a defensive double mount runs
+the side effects of `onStart` one time for one real start.
 
 #### Returns
 
@@ -397,9 +424,16 @@ Per RESEARCH.md Pitfall 1: Always call start() after creation
 stop(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:559](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L559)
+Defined in: [packages/play-xstate/src/player-actor.ts:512](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L512)
+
+Stops the actor and cleans up.
 
-Stop the actor and cleanup
+The method fires `onStop` only when the actor ran. This matches XState, where a
+stop of an actor that never started, or of an actor that stopped already, does
+nothing and tears nothing down. Therefore the paired cleanup runs never two
+times, and it runs never against a resource that `onStart` did not take. A stop
+does not close the actor for ever: a later `start()` is a new lifecycle, and it
+fires `onStart` again.
 
 #### Returns
 
@@ -419,23 +453,23 @@ Stop the actor and cleanup
 subscribe(observer): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:635](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L635)
+Defined in: [packages/play-xstate/src/player-actor.ts:618](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L618)
 
-Subscribe to snapshot updates from the wrapped XState actor.
+Subscribes to the snapshot updates of this actor.
 
-Accepts an observer object, exactly like XState's `Actor.subscribe`.
+The method accepts an observer object, exactly like `Actor.subscribe` of XState.
 
 ##### Parameters
 
-| 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. |
+| Parameter  | Type                                                                                                                                             | Description                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `observer` | [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\> | The observer, with a `next`, an `error`, and a `complete` handler. |
 
 ##### Returns
 
 [`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-Subscription with an `unsubscribe()` method.
+The subscription, with an `unsubscribe()` method.
 
 ##### Overrides
 
@@ -450,25 +484,25 @@ subscribe(
    completeListener?): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:646](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L646)
+Defined in: [packages/play-xstate/src/player-actor.ts:629](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/player-actor.ts#L629)
 
-Subscribe to snapshot updates from the wrapped XState actor.
+Subscribes to the snapshot updates of this actor.
 
-Accepts listener functions, exactly like XState's `Actor.subscribe`.
+The method accepts listener functions, exactly like `Actor.subscribe` of XState.
 
 ##### Parameters
 
-| 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). |
+| Parameter           | Type                   | Description                                                                      |
+| ------------------- | ---------------------- | -------------------------------------------------------------------------------- |
+| `nextListener?`     | (`snapshot`) => `void` | The listener function of each snapshot.                                          |
+| `errorListener?`    | (`error`) => `void`    | The actor calls it on an error.                                                  |
+| `completeListener?` | () => `void`           | The actor calls it when it completes, which means that it reaches a final state. |
 
 ##### Returns
 
 [`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
-Subscription with an `unsubscribe()` method.
+The subscription, with an `unsubscribe()` method.
 
 ##### Overrides