@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-xstate/index/functions/compose.md

@@ -0,0 +1,224 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / compose
+
+# Function: compose()
+
+## Call Signature
+
+```ts
+function compose<TMachine>(Base): PlayerConstructor<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L102)
+
+Builds an actor class from a base and a list of capabilities.
+
+It applies each capability from left to right, so the LAST one is the outermost class,
+and the return type accumulates what each one adds:
+`compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.
+
+Use this form, and not the nested one. Each capability declares a FIXED return type, so
+`withView(withRouting(PlayerActor))` builds the same class at run time and answers
+`Viewable` alone at the type level — a router bridge then refuses the actor with
+TS2739. The overloads below are what carries `Routable` through.
+
+### Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+
+### Parameters
+
+| Parameter | Type                                                                      | Description                                          |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to build on, normally `PlayerActor`. |
+
+### Returns
+
+[`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`\>
+
+### Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+```
+
+Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it
+applies them from left to right.
+
+## Call Signature
+
+```ts
+function compose<TMachine, TC1>(Base, c1): PlayerConstructor<TMachine, TC1>;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L105)
+
+Builds an actor class from a base and a list of capabilities.
+
+It applies each capability from left to right, so the LAST one is the outermost class,
+and the return type accumulates what each one adds:
+`compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.
+
+Use this form, and not the nested one. Each capability declares a FIXED return type, so
+`withView(withRouting(PlayerActor))` builds the same class at run time and answers
+`Viewable` alone at the type level — a router bridge then refuses the actor with
+TS2739. The overloads below are what carries `Routable` through.
+
+### Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+| `TC1` _extends_ `object`                                                                       |
+
+### Parameters
+
+| Parameter | Type                                                                      | Description                                          |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to build on, normally `PlayerActor`. |
+| `c1`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC1`\>        | -                                                    |
+
+### Returns
+
+[`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`, `TC1`\>
+
+### Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+```
+
+Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it
+applies them from left to right.
+
+## Call Signature
+
+```ts
+function compose<TMachine, TC1, TC2>(Base, c1, c2): PlayerConstructor<TMachine, TC1 & TC2>;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:109](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L109)
+
+Builds an actor class from a base and a list of capabilities.
+
+It applies each capability from left to right, so the LAST one is the outermost class,
+and the return type accumulates what each one adds:
+`compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.
+
+Use this form, and not the nested one. Each capability declares a FIXED return type, so
+`withView(withRouting(PlayerActor))` builds the same class at run time and answers
+`Viewable` alone at the type level — a router bridge then refuses the actor with
+TS2739. The overloads below are what carries `Routable` through.
+
+### Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+| `TC1` _extends_ `object`                                                                       |
+| `TC2` _extends_ `object`                                                                       |
+
+### Parameters
+
+| Parameter | Type                                                                      | Description                                          |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to build on, normally `PlayerActor`. |
+| `c1`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC1`\>        | -                                                    |
+| `c2`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC2`\>        | -                                                    |
+
+### Returns
+
+[`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`, `TC1` & `TC2`\>
+
+### Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+```
+
+Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it
+applies them from left to right.
+
+## Call Signature
+
+```ts
+function compose<TMachine, TC1, TC2, TC3>(
+	Base,
+	c1,
+	c2,
+	c3,
+): PlayerConstructor<TMachine, TC1 & TC2 & TC3>;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:114](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L114)
+
+Builds an actor class from a base and a list of capabilities.
+
+It applies each capability from left to right, so the LAST one is the outermost class,
+and the return type accumulates what each one adds:
+`compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.
+
+Use this form, and not the nested one. Each capability declares a FIXED return type, so
+`withView(withRouting(PlayerActor))` builds the same class at run time and answers
+`Viewable` alone at the type level — a router bridge then refuses the actor with
+TS2739. The overloads below are what carries `Routable` through.
+
+### Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+| `TC1` _extends_ `object`                                                                       |
+| `TC2` _extends_ `object`                                                                       |
+| `TC3` _extends_ `object`                                                                       |
+
+### Parameters
+
+| Parameter | Type                                                                      | Description                                          |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to build on, normally `PlayerActor`. |
+| `c1`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC1`\>        | -                                                    |
+| `c2`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC2`\>        | -                                                    |
+| `c3`      | [`Capability`](../type-aliases/Capability.md)\<`TMachine`, `TC3`\>        | -                                                    |
+
+### Returns
+
+[`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`, `TC1` & `TC2` & `TC3`\>
+
+### Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+```
+
+Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it
+applies them from left to right.

package/api/@xmachines/play-xstate/index/functions/definePlayer.md

@@ -0,0 +1,158 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / definePlayer
+
+# Function: definePlayer()
+
+## Call Signature
+
+```ts
+function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/define-player.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/define-player.ts#L62)
+
+Creates a player factory from an XState machine
+
+This factory function accepts an XState v5 machine. It returns a function that
+makes [PlayerActor](../classes/PlayerActor.md) instances. One configuration can therefore make more
+than one actor instance, and this helps with a test, with an application of
+several instances, and with a render on the server.
+
+### Type Parameters
+
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
+
+### Parameters
+
+| Parameter | Type                                                                               | Description                            |
+| --------- | ---------------------------------------------------------------------------------- | -------------------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`, `object`\> & `object` | The configuration object of the player |
+
+### Returns
+
+[`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`\>
+
+The factory function. It makes an actor instance, with an optional input context
+
+### Examples
+
+A basic player factory
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: { meta: { route: "/" } },
+		active: { meta: { route: "/active" } },
+	},
+});
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+```
+
+More than one actor instance from one factory
+
+```typescript
+const createPlayer = definePlayer({ machine });
+
+// Create an actor for each user
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
+
+alice.start();
+bob.start();
+
+// The two state machines are independent
+console.log(alice.state.get() !== bob.state.get());
+```
+
+### See
+
+- [Play RFC](../../../../../rfc/play.md)
+- [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
+- [PlayerConfig](../interfaces/PlayerConfig.md) for the configuration options
+- [PlayerFactory](../type-aliases/PlayerFactory.md) for the signature of the factory function
+
+## Call Signature
+
+```ts
+function definePlayer<TMachine, TCapabilities>(config): PlayerFactory<TMachine, TCapabilities>;
+```
+
+Defined in: [packages/play-xstate/src/define-player.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/define-player.ts#L65)
+
+Creates a player factory from an XState machine
+
+This factory function accepts an XState v5 machine. It returns a function that
+makes [PlayerActor](../classes/PlayerActor.md) instances. One configuration can therefore make more
+than one actor instance, and this helps with a test, with an application of
+several instances, and with a render on the server.
+
+### Type Parameters
+
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
+| `TCapabilities` _extends_ `object`                                                             | -                                       |
+
+### Parameters
+
+| Parameter | Type                                                                                      | Description                            |
+| --------- | ----------------------------------------------------------------------------------------- | -------------------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`, `TCapabilities`\> & `object` | The configuration object of the player |
+
+### Returns
+
+[`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`, `TCapabilities`\>
+
+The factory function. It makes an actor instance, with an optional input context
+
+### Examples
+
+A basic player factory
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: { meta: { route: "/" } },
+		active: { meta: { route: "/active" } },
+	},
+});
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+```
+
+More than one actor instance from one factory
+
+```typescript
+const createPlayer = definePlayer({ machine });
+
+// Create an actor for each user
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
+
+alice.start();
+bob.start();
+
+// The two state machines are independent
+console.log(alice.state.get() !== bob.state.get());
+```
+
+### See
+
+- [Play RFC](../../../../../rfc/play.md)
+- [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
+- [PlayerConfig](../interfaces/PlayerConfig.md) for the configuration options
+- [PlayerFactory](../type-aliases/PlayerFactory.md) for the signature of the factory function

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

@@ -0,0 +1,22 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerConfig
+
+# Interface: PlayerConfig\<TMachine, TCapabilities\>
+
+Defined in: [packages/play-xstate/src/types.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L8)
+
+The configuration of definePlayer()
+
+## Type Parameters
+
+| Type Parameter                                                                                 | Default type |
+| ---------------------------------------------------------------------------------------------- | ------------ |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | -            |
+| `TCapabilities` _extends_ `object`                                                             | `object`     |
+
+## Properties
+
+| Property                                 | Type                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                        | Defined in                                                                                                                             |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor?`     | [`PlayerConstructor`](../type-aliases/PlayerConstructor.md)\<`TMachine`, `TCapabilities`\> | The actor class to build, which decides which CAPABILITIES the actor carries. `PlayerActor` is the default, and it holds `state` and `send` alone. Compose a class to add a capability, and the factory then answers an actor with it: `definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });` An application that declares no route, and renders no view, passes nothing and loads neither body of code. | [packages/play-xstate/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L31) |
+| <a id="property-machine"></a> `machine`  | `TMachine`                                                                                 | The XState v5 state machine                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L13) |
+| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\>                                          | The lifecycle hooks and the configuration                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-xstate/src/types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L16) |

package/api/@xmachines/play-xstate/{interfaces → index/interfaces}/PlayerFactoryResumeOptions.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactoryResumeOptions
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerFactoryResumeOptions
 
 # Interface: PlayerFactoryResumeOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L115)
+Defined in: [packages/play-xstate/src/types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L134)
 
 The optional restore arguments of the player factory.
 
@@ -19,4 +19,4 @@ The shape follows the options object of `createActor` in XState. It also keeps t
 
 | Property                                   | Type                                                                     | Description                                                                                                                                                                                                                                                                                     | Defined in                                                                                                                               |
 | ------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-snapshot"></a> `snapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\> | The persisted XState snapshot. The factory restores the actor state from it. Its type is the `ActorOptions["snapshot"]` type of XState, which is the exact type that `createActor` accepts and that `getPersistedSnapshot()` returns. The restore of a stored snapshot therefore needs no cast. | [packages/play-xstate/src/types.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L123) |
+| <a id="property-snapshot"></a> `snapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\> | The persisted XState snapshot. The factory restores the actor state from it. Its type is the `ActorOptions["snapshot"]` type of XState, which is the exact type that `createActor` accepts and that `getPersistedSnapshot()` returns. The restore of a stored snapshot therefore needs no cast. | [packages/play-xstate/src/types.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L142) |

package/api/@xmachines/play-xstate/{interfaces → index/interfaces}/PlayerOptions.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerOptions
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerOptions
 
 # Interface: PlayerOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L18)
+Defined in: [packages/play-xstate/src/types.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L37)
 
 The lifecycle hooks of the player — the observability surface around the actor.
 
@@ -16,9 +16,9 @@ The lifecycle hooks of the player — the observability surface around the actor
 
 | Property                                             | Type                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                               |
 | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-inspect"></a> `inspect?`             | \| [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<`InspectionEvent`\> \| ((`inspectionEvent`) => `void`) | The inspection observer. The factory gives it to `createActor` of XState without a change. This is the attachment at the moment of the creation, and it is the only route that observes the construction events of the actor. An attachment later, with `actor.system.inspect(fn)`, also works, but it sees only the events after that moment. A `PlayerActor` is the XState actor itself. Therefore its own events carry `actorRef === playerActor`, and you can recognize it by its identity. Each `PlayerActor` is also its own root system. Therefore `event.rootId === actor.sessionId` separates the complete tree, and this includes the events of an invoked child and of a spawned child, whose `actorRef` is the child. That identity brings one point to note: the `@xstate.actor` event fires from inside the constructor of the actor. Its `actorRef` value is therefore the instance during the construction, and `state`, `currentRoute`, `currentView`, and `initialRoute` do not exist yet. A read of one of them there throws. Keep the reference, and read the signals from a later event, or outside the observer. **Example** `import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } });` For an inspector that you create after the factory, for example behind a dev-tools switch, give the factory a function that forwards each event: `inspect: (event) => currentInspector?.(event)`. | [packages/play-xstate/src/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L106) |
-| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                                                                                           | The actor calls it on an actor error: a snapshot restore that fails at `start()`, an action or a guard that throws, and a failure of the view derivation. The actor reads this field at the moment of the delivery of an error, and not at its construction. The options object is shared by its reference. Therefore a handler on that object still receives each actor error, also after a later attachment, and the removal of the handler restores the loud default below. With a handler in place, the actor sends the error there, and the error counts as handled. XState decides its own global rethrow for each observer, and this option does not reach that decision: a subscription of your own without an `error` listener still forces the rethrow, with an `onError` handler and without one. Without `onError`, each actor error stays loud, with an unhandled rethrow through `setTimeout`. No error therefore disappears in silence. Your own `error` subscribers stop that default not: `onError` alone stops it. A failure of the actor that is an `Error` already arrives without a change, and it keeps the identity of the machine. A machine that throws a value that is not an `Error` arrives as an `ActorThrewNonErrorError`, with the value from the throw on its `cause` field.                                                                                                                                                                                                                            | [packages/play-xstate/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L71)   |
-| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                                                                                                    | The actor calls it on each real start, which is every transition from "not running" to "running". A start after a stop is such a transition. A second `start()` call while the actor runs fires the hook not again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-xstate/src/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L24)   |
-| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                                                                                           | The actor calls it when the state signal changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L46)   |
-| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                                                                                                    | The actor calls it on each real stop, which means only after it tore a running actor down. A second `stop()` call, a second `dispose()` call, and a stop of an actor that never started fire the hook not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L31)   |
-| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void`                                                                          | The actor calls it after every event that `send()` processes. This includes an event that the machine ignores, and `prevState` and `nextState` are then the same snapshot. Compare the two values when only a real transition is important to you.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [packages/play-xstate/src/types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L39)   |
+| <a id="property-inspect"></a> `inspect?`             | \| [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<`InspectionEvent`\> \| ((`inspectionEvent`) => `void`) | The inspection observer. The factory gives it to `createActor` of XState without a change. This is the attachment at the moment of the creation, and it is the only route that observes the construction events of the actor. An attachment later, with `actor.system.inspect(fn)`, also works, but it sees only the events after that moment. A `PlayerActor` is the XState actor itself. Therefore its own events carry `actorRef === playerActor`, and you can recognize it by its identity. Each `PlayerActor` is also its own root system. Therefore `event.rootId === actor.sessionId` separates the complete tree, and this includes the events of an invoked child and of a spawned child, whose `actorRef` is the child. That identity brings one point to note: the `@xstate.actor` event fires from inside the constructor of the actor. Its `actorRef` value is therefore the instance during the construction, and `state`, `currentRoute`, `currentView`, and `initialRoute` do not exist yet. A read of one of them there throws. Keep the reference, and read the signals from a later event, or outside the observer. **Example** `import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } });` For an inspector that you create after the factory, for example behind a dev-tools switch, give the factory a function that forwards each event: `inspect: (event) => currentInspector?.(event)`. | [packages/play-xstate/src/types.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L125) |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                                                                                           | The actor calls it on an actor error: a snapshot restore that fails at `start()`, an action or a guard that throws, and a failure of the view derivation. The actor reads this field at the moment of the delivery of an error, and not at its construction. The options object is shared by its reference. Therefore a handler on that object still receives each actor error, also after a later attachment, and the removal of the handler restores the loud default below. With a handler in place, the actor sends the error there, and the error counts as handled. XState decides its own global rethrow for each observer, and this option does not reach that decision: a subscription of your own without an `error` listener still forces the rethrow, with an `onError` handler and without one. Without `onError`, each actor error stays loud, with an unhandled rethrow through `setTimeout`. No error therefore disappears in silence. Your own `error` subscribers stop that default not: `onError` alone stops it. A failure of the actor that is an `Error` already arrives without a change, and it keeps the identity of the machine. A machine that throws a value that is not an `Error` arrives as an `ActorThrewNonErrorError`, with the value from the throw on its `cause` field.                                                                                                                                                                                                                            | [packages/play-xstate/src/types.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L90)   |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                                                                                                    | The actor calls it on each real start, which is every transition from "not running" to "running". A start after a stop is such a transition. A second `start()` call while the actor runs fires the hook not again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-xstate/src/types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L43)   |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                                                                                           | The actor calls it when the state signal changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L65)   |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                                                                                                    | The actor calls it on each real stop, which means only after it tore a running actor down. A second `stop()` call, and a stop of an actor that never started fire the hook not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-xstate/src/types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L50)   |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void`                                                                          | The actor calls it after every event that `send()` processes. This includes an event that the machine ignores, and `prevState` and `nextState` are then the same snapshot. Compare the two values when only a real transition is important to you.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [packages/play-xstate/src/types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L58)   |

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

@@ -0,0 +1,33 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / Capability
+
+# Type Alias: Capability\<TMachine, TAdded\>
+
+```ts
+type Capability<TMachine, TAdded> = (Base) => PlayerConstructor<TMachine, TAdded>;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L69)
+
+One capability of an actor: a function that takes an actor class and answers the same
+class with `TAdded` on the instance.
+
+`withRouting` of `@xmachines/play-xstate/routing` and `withView` of
+`@xmachines/play-xstate/view` are the two that this package ships. Write your own with
+the same shape, and [compose](../functions/compose.md) takes it beside them.
+
+## Type Parameters
+
+| Type Parameter                                                                                 | Description                                                       |
+| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The machine of the actor.                                         |
+| `TAdded` _extends_ `object`                                                                    | What the capability adds to the instance, for example `Routable`. |
+
+## Parameters
+
+| Parameter | Type                                                      |
+| --------- | --------------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](PlayerConstructor.md)\<`TMachine`\> |
+
+## Returns
+
+[`PlayerConstructor`](PlayerConstructor.md)\<`TMachine`, `TAdded`\>

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

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerConstructor
+
+# Type Alias: PlayerConstructor\<TMachine, TCapabilities\>
+
+```ts
+type PlayerConstructor<TMachine, TCapabilities> = (
+	machine,
+	options,
+	input?,
+	restoredSnapshot?,
+) => PlayerActor<TMachine> & TCapabilities;
+```
+
+Defined in: [packages/play-xstate/src/capabilities.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/capabilities.ts#L48)
+
+The constructor of a `PlayerActor`, with every capability that it carries already.
+
+The argument list is the one that `PlayerActor` declares, so `definePlayer` builds an
+actor with the arguments checked, whatever the composition added to the instance.
+
+## Type Parameters
+
+| Type Parameter                                                                                 | Default type | Description                                                     |
+| ---------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | -            | The machine of the actor.                                       |
+| `TCapabilities` _extends_ `object`                                                             | `object`     | What the capabilities added, for example `Routable & Viewable`. |
+
+## Parameters
+
+| Parameter           | Type                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| `machine`           | `TMachine`                                                                                        |
+| `options`           | [`PlayerOptions`](../interfaces/PlayerOptions.md)\<`TMachine`\>                                   |
+| `input?`            | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\>                       |
+| `restoredSnapshot?` | [`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TMachine`\>\[`"snapshot"`\] |
+
+## Returns
+
+[`PlayerActor`](../classes/PlayerActor.md)\<`TMachine`\> & `TCapabilities`

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

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerFactory
+
+# Type Alias: PlayerFactory\<TMachine, TCapabilities\>
+
+```ts
+type PlayerFactory<TMachine, TCapabilities> =
+	undefined extends InputFrom<TMachine>
+		? (input?, options?) => PlayerActor<TMachine> & TCapabilities
+		: (input, options?) => PlayerActor<TMachine> & TCapabilities;
+```
+
+Defined in: [packages/play-xstate/src/types.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/types.ts#L154)
+
+The factory function that definePlayer() returns. Each call makes an independent
+actor instance from the same configuration.
+
+The `input` argument follows the rule of `createActor` in XState. If the input of
+a machine cannot be `undefined`, the first argument of the factory is necessary.
+An absent input is then a compile error, and not an actor that starts in an error
+status with a `null` initial route.
+
+## Type Parameters
+
+| Type Parameter                                                                                 | Default type |
+| ---------------------------------------------------------------------------------------------- | ------------ |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | -            |
+| `TCapabilities` _extends_ `object`                                                             | `object`     |

package/api/@xmachines/{play-router → play-xstate/index}/variables/DISPOSE.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / DISPOSE
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / DISPOSE
 
 # Variable: DISPOSE
 
@@ -6,7 +6,7 @@
 const DISPOSE: DisposeKey;
 ```
 
-Defined in: [play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L94)
+Defined in: [packages/play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L94)
 
 The key that a release is stored under.
 
@@ -25,7 +25,7 @@ The type assertion states what the fallback IS. `Symbol.for` returns a plain `sy
 TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
 a `unique symbol` other than the declaration itself.
 
-This binding resolves ONE time, when the module evaluates. [asCleanup](../../play/functions/asCleanup.md) therefore
+This binding resolves ONE time, when the module evaluates. [asCleanup](../../../play/index/functions/asCleanup.md) therefore
 reads `Symbol.dispose` again at each call and stores the release under both keys, so a
 polyfill that installs the well-known symbol after this module evaluates still finds
 the release. A class or an object literal that writes `[DISPOSE]()` has no such second