@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -2,13 +2,20 @@
 
 # Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L185)
+Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L197)
 
-Abstract base class for Play Architecture actors.
+The abstract base class of an actor of the Play Architecture.
 
-Provides signal-driven state observation that integrates with XState ecosystem
-tooling (devtools, inspection) while exposing reactive signals for
-Infrastructure layer communication.
+It observes the state through the signals, and it works with the tools of the
+XState ecosystem, such as the devtools and the inspection. It also exposes the
+reactive signals of the communication with the infrastructure layer.
+
+**A subclass IS the actor.** Give the logic _and_ its options to
+`super(logic, options)`, then observe `this`. A separate actor beside this
+instance leaves this instance as an empty second actor. Every inherited member
+then answers from that empty actor, until you forward each one: `system`,
+`sessionId`, `clock`, the internal `_send` that receives the traffic of
+`sendTo()`, and each member that a later XState version adds.
 
 ## Extends
 
@@ -20,10 +27,10 @@ Infrastructure layer communication.
 
 ## Type Parameters
 
-| Type Parameter                                                                           | Default type                                                      | Description                                     |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type                         |
-| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type constraint (defaults to EventObject) |
+| Type Parameter                                                                           | Default type                                                      | Description                                                  |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | The type of the XState actor logic                           |
+| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | The constraint of the event type. The default is EventObject |
 
 ## Constructors
 
@@ -57,20 +64,19 @@ Actor<TLogic>.constructor
 
 ## Properties
 
-| Property                                        | Modifier   | Type                                                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                             | Inherited from      | Defined in                                                                                                                                                       |
-| ----------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-_parent"></a> `_parent?`        | `public`   | `AnyActor`                                                                                                                                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor._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.                                                                                | `Actor.clock`       | -                                                                                                                                                                |
-| <a id="property-id"></a> `id`                   | `public`   | `string`                                                                                                                                                                                                                                                                                                                                                 | The unique identifier for this actor relative to its parent.                                                                                                                            | `Actor.id`          | -                                                                                                                                                                |
-| <a id="property-logic"></a> `logic`             | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                                                                       | `Actor.logic`       | -                                                                                                                                                                |
-| <a id="property-options"></a> `options`         | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.options`     | -                                                                                                                                                                |
-| <a id="property-ref"></a> `ref`                 | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>, `SendableEventFromLogic`\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`         | -                                                                                                                                                                |
-| <a id="property-registrykey"></a> `registryKey` | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                                                                  | -                                                                                                                                                                                       | `Actor.registryKey` | -                                                                                                                                                                |
-| <a id="property-sessionid"></a> `sessionId`     | `public`   | `string`                                                                                                                                                                                                                                                                                                                                                 | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId`   | -                                                                                                                                                                |
-| <a id="property-src"></a> `src`                 | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                                                                     | -                                                                                                                                                                                       | `Actor.src`         | -                                                                                                                                                                |
-| <a id="property-state"></a> `state`             | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                                                            | 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. | -                   | [packages/play-actor/src/abstract-actor.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L195) |
-| <a id="property-system"></a> `system`           | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                                                                  | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`      | -                                                                                                                                                                |
-| <a id="property-trigger"></a> `trigger`         | `public`   | `ActorTrigger`\<`SendableEventFromLogic`\<`TLogic`\>\>                                                                                                                                                                                                                                                                                                   | -                                                                                                                                                                                       | `Actor.trigger`     | -                                                                                                                                                                |
+| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                                               | Inherited from    | Defined in                                                                                                                                               |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                                         | `Actor._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.                                                                                                  | `Actor.clock`     | -                                                                                                                                                        |
+| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                                              | `Actor.id`        | -                                                                                                                                                        |
+| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                                         | `Actor.logic`     | -                                                                                                                                                        |
+| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                                         | `Actor.options`   | -                                                                                                                                                        |
+| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                                         | `Actor.ref`       | -                                                                                                                                                        |
+| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                                       | `Actor.sessionId` | -                                                                                                                                                        |
+| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                                         | `Actor.src`       | -                                                                                                                                                        |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | 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. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L207) |
+| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                   | `Actor.system`    | -                                                                                                                                                        |
+| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                                         | `Actor.systemId`  | -                                                                                                                                                        |
 
 ## Methods
 
@@ -152,7 +158,7 @@ When an actor receives an event, its internal state may change. An actor
 may emit a snapshot when a state transition occurs.
 
 Note that some actors, such as callback actors generated with
-`createCallbackLogic`, will not emit snapshots.
+`fromCallback`, will not emit snapshots.
 
 #### See
 
@@ -177,9 +183,9 @@ Defined in: `xstate`
 
 #### Type Parameters
 
-| Type Parameter             |
-| -------------------------- |
-| `TType` _extends_ `string` |
+| Type Parameter          |
+| ----------------------- |
+| `TType` _extends_ `any` |
 
 #### Parameters
 
@@ -239,11 +245,20 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L202)
+Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L223)
+
+Sends an event to the Actor.
 
-Send event to Actor.
+The constraint is TEvent, which gives the type safety of a concrete
+implementation.
 
-Constrained to TEvent for type safety in concrete implementations.
+A note for an implementation that wraps `send`, to check the event or to notify a
+hook around it: this declaration is abstract for one reason only, to narrow the
+event type, and TypeScript forbids a `super` call to an abstract member. Reach
+the implementation of XState with `Actor.prototype.send.call(this, event)`
+instead. A concrete declaration permits `super.send()`, but it also forces an
+`override` modifier in every subclass that exists now, and that is a breaking
+change for an adapter outside this repository.
 
 #### Parameters
 

package/api/@xmachines/play-actor/functions/attachRenderErrorHandler.md

@@ -6,35 +6,36 @@
 function attachRenderErrorHandler<TRegistry>(registry, handler): TRegistry;
 ```
 
-Defined in: [packages/play-actor/src/provider-guards.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/provider-guards.ts#L64)
+Defined in: [packages/play-actor/src/provider-guards.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/provider-guards.ts#L68)
 
-Clone a component registry and inject an `onRenderError` handler.
+Copies a component registry, and puts an `onRenderError` handler into the copy.
 
-The handler is defined as a non-enumerable, configurable own property on the
-clone (per D-19 — one injection convention for all framework renderers), so
-it overrides any handler set at `defineRegistry` level without showing up
-when the registry's component entries are enumerated.
+The function defines the handler as an own property of the copy. That property is
+not enumerable, and it is configurable (D-19 gives one convention of the
+injection for every framework renderer). The handler therefore replaces each
+handler of the `defineRegistry` level, and it does not appear in an enumeration of
+the component entries of the registry.
 
-The caller's registry is never mutated — a shallow clone is returned. Callers
-that need per-instance handlers (e.g. an `onRenderError` prop on
-`ActorProvider`) can therefore share one `defineRegistry` result across
-providers safely.
+The function never changes the registry of the caller: it returns a shallow copy.
+Therefore a caller that needs a handler for each instance, such as an
+`onRenderError` prop of `ActorProvider`, can share one result of `defineRegistry`
+between the providers in a safe way.
 
 ## Type Parameters
 
-| Type Parameter                 | Description                                     |
-| ------------------------------ | ----------------------------------------------- |
-| `TRegistry` _extends_ `object` | The framework-specific component registry type. |
+| Type Parameter                 | Description                                   |
+| ------------------------------ | --------------------------------------------- |
+| `TRegistry` _extends_ `object` | The component registry type of the framework. |
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `registry` | `TRegistry`                                                               | The component registry from `defineRegistry().registry`.                            |
-| `handler`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md) | Called with `(error, componentName)` when a catalog component throws during render. |
+| Parameter  | Type                                                                      | Description                                                                                          |
+| ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `registry` | `TRegistry`                                                               | The component registry from `defineRegistry().registry`.                                             |
+| `handler`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md) | The renderer calls it with `(error, componentName)` when a catalog component throws during a render. |
 
 ## Returns
 
 `TRegistry`
 
-A shallow clone of `registry` with `onRenderError` attached.
+A shallow copy of `registry`, with `onRenderError` on it.

package/api/@xmachines/play-actor/functions/composePlayState.md

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / composePlayState
+
+# Function: composePlayState()
+
+```ts
+function composePlayState(authoredState, slice): Record<string, unknown> | undefined;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L228)
+
+Composes the effective state of a view: the authored `spec.state` and the
+`/context` slice.
+
+When the authored state declares the reserved key already, the function skips the
+projection, the authored state wins, and the code writes a warning in
+development. No spec that exists now therefore fails.
+
+## Parameters
+
+| Parameter       | Type                                           | Description                                                                                   |
+| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `authoredState` | `Record`\<`string`, `unknown`\> \| `undefined` | The raw `meta.view.state` value. It can be anything, and the caller or toAtomState cleans it. |
+| `slice`         | `Record`\<`string`, `unknown`\> \| `undefined` | The context of the machine, as one complete value.                                            |
+
+## Returns
+
+`Record`\<`string`, `unknown`\> \| `undefined`

package/api/@xmachines/play-actor/functions/createViewStoreLifecycle.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / createViewStoreLifecycle
+
+# Function: createViewStoreLifecycle()
+
+```ts
+function createViewStoreLifecycle(createStore): ViewStoreLifecycle;
+```
+
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L94)
+
+Creates a coordinator of the lifecycle.
+
+## Parameters
+
+| Parameter     | Type                     | Description                                                                                                                                                           |
+| ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createStore` | (`seed`) => `StateStore` | The store factory of the framework. It receives the seed that is safe for the prototype (`toAtomState(view.state)`), and the composed state carries /context already. |
+
+## Returns
+
+[`ViewStoreLifecycle`](../interfaces/ViewStoreLifecycle.md)

package/api/@xmachines/play-actor/functions/guardContextWrites.md

@@ -0,0 +1,43 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / guardContextWrites
+
+# Function: guardContextWrites()
+
+```ts
+function guardContextWrites(store): StateStore;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L151)
+
+Wraps a StateStore, and the wrapper refuses each write under `/context`.
+
+A provider applies it to the store that it gives to the bindings and to the
+action handlers (`$bindState`, `setState`, and a chained `set`). The provider
+keeps the store without the wrapper, and it refreshes the projection through that
+store. The subtree is therefore read-only to the spec, and not to the machinery.
+
+A write with a value that is **identical** to the current value passes in
+silence. A handler in the style of `setState` reads the complete snapshot,
+changes it, and writes the whole object back. The `context` key that goes through
+that round trip without a change is no attempt of a mutation. Only a write that
+changes the subtree throws.
+
+Each read passes through without a change. The wrapper delegates every member
+explicitly, and it does not use a spread: a store from a consumer can be an
+instance of a class, and the methods of that instance are on the prototype. Those
+methods do not survive `{ ...store }`, and the first render then fails with
+`store.getSnapshot is not a function`. The code builds the wrapper one time for
+each resolved store. Therefore the identity of the delegating `getSnapshot` and
+of the delegating `subscribe` stays stable for a consumer in the style of
+`useSyncExternalStore`.
+
+## Parameters
+
+| Parameter | Type         | Description                  |
+| --------- | ------------ | ---------------------------- |
+| `store`   | `StateStore` | The store below the wrapper. |
+
+## Returns
+
+`StateStore`
+
+A store with a guard on `set` and on `update`.

package/api/@xmachines/play-actor/functions/refreshContextSubtree.md

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / refreshContextSubtree
+
+# Function: refreshContextSubtree()
+
+```ts
+function refreshContextSubtree(store, view): void;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L210)
+
+Refreshes the `/context` subtree of a live store from the composed state of a
+derived view. An emission with the same `viewKey` means that only the projection
+changed. The function therefore replaces the complete subtree, and it never
+merges it field by field, because `update` cannot delete a key. Every ephemeral
+value at the root level stays. The function does nothing when the view carries no
+slice, or when the store holds the slice already.
+
+## Parameters
+
+| Parameter     | Type                       | Description                                                    |
+| ------------- | -------------------------- | -------------------------------------------------------------- |
+| `store`       | `StateStore`               | The store WITHOUT the guard. A provider refreshes through it.  |
+| `view`        | \{ `state?`: `unknown`; \} | The derived view. Its `state.context` field carries the slice. |
+| `view.state?` | `unknown`                  | -                                                              |
+
+## Returns
+
+`void`

package/api/@xmachines/play-actor/functions/reuseComposedState.md

@@ -0,0 +1,42 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / reuseComposedState
+
+# Function: reuseComposedState()
+
+```ts
+function reuseComposedState(prev, next): PlaySpec | null;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L92)
+
+Reuses the composed `state` of the previous emission, or the complete previous
+spec, when the value of the projection did not change.
+
+`deriveCurrentView` composes `state: { ...meta.view.state, context: slice }` new
+on each call, and the XState function `assign` makes a new context object on
+every event. Without this reuse, every event therefore presents a new `state`
+reference, and the `Object.is` test of each field in the emit gate emits the view
+again and remounts it, without an end. The function compares the slices field by
+field ([shallowEqualExcept](shallowEqualExcept.md)), because the XState function `assign` makes a
+new context object for each event, and a test of the identity of the whole object
+therefore reports a change every time. The authored fields come from the static
+`meta.view.state` through a spread. Therefore their references are stable for an
+unchanged `viewKey`, and a plain `Object.is` test is correct for them.
+
+The function returns one of three values, in this order of preference:
+
+- `prev` itself, when nothing observable changed. The emit gate then stops at the
+  identity of the reference, and it walks no element;
+- `{ ...next, state: prev.state }`, when the value of the state did not change
+  but another top-level field is different;
+- `next`, when something changed.
+
+## Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `prev`    | [`PlaySpec`](../interfaces/PlaySpec.md) \| `null` |
+| `next`    | [`PlaySpec`](../interfaces/PlaySpec.md) \| `null` |
+
+## Returns
+
+[`PlaySpec`](../interfaces/PlaySpec.md) \| `null`

package/api/@xmachines/play-actor/functions/shallowEqualExcept.md

@@ -0,0 +1,29 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / shallowEqualExcept
+
+# Function: shallowEqualExcept()
+
+```ts
+function shallowEqualExcept(a, b, except?): boolean;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L58)
+
+The shallow equality of the own keys, with `Object.is`. It can ignore one key on
+both sides.
+
+This is the one comparison rule behind every decision of the emission dedup: the
+equality of a slice, and also the emit gate of the player, which compares the
+spec fields in `viewSpecsEquivalent` and reuses the composed state in
+[reuseComposedState](reuseComposedState.md).
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `a`       | `object` |
+| `b`       | `object` |
+| `except?` | `string` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-actor/functions/toAtomState.md

@@ -6,28 +6,30 @@
 function toAtomState(state): Record<string, unknown>;
 ```
 
-Defined in: [packages/play-actor/src/provider-guards.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/provider-guards.ts#L36)
+Defined in: [packages/play-actor/src/provider-guards.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/provider-guards.ts#L39)
 
-Safely coerce a spec's `state` field to a plain object for `createAtom`.
+Converts the `state` field of a spec into a plain object for `createAtom`, in a safe way.
 
-`spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
-`null`, `undefined`, a primitive, or a plain object depending on what the
-machine author put in the view spec. `createAtom` requires a plain object as
-its initial value — anything else produces a broken store at runtime.
+`spec.state` has the type `unknown` in `PlaySpec`. At run time it is `null`,
+`undefined`, a primitive, or a plain object, and this depends on the value that
+the author of the machine put in the view spec. `createAtom` requires a plain
+object as its first value, because every other value makes a broken store at run
+time.
 
-Only plain objects (prototype is `Object.prototype` or `null`) are accepted
-and returned as-is. Everything else — `null`, `undefined`, primitives,
-arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
-back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+The function accepts a plain object only, which means that its prototype is
+`Object.prototype` or `null`, and it returns that object without a change. Every
+other value becomes a new `{}`: `null`, `undefined`, a primitive, an array, an
+instance of a class, and a built-in object such as a Date, a Map, or a Set. A
+broken store therefore never appears at run time.
 
 ## Parameters
 
-| Parameter | Type      | Description                                   |
-| --------- | --------- | --------------------------------------------- |
-| `state`   | `unknown` | The raw `spec.state` value from a `PlaySpec`. |
+| Parameter | Type      | Description                                 |
+| --------- | --------- | ------------------------------------------- |
+| `state`   | `unknown` | The raw `spec.state` value of a `PlaySpec`. |
 
 ## Returns
 
 `Record`\<`string`, `unknown`\>
 
-`state` itself when it is a plain object, otherwise a new empty object.
+`state` itself when it is a plain object. In every other case, a new empty object.

package/api/@xmachines/play-actor/functions/typedSpec.md

@@ -3,32 +3,32 @@
 # Function: typedSpec()
 
 ```ts
-function typedSpec<TContext>(spec): PlaySpec;
+function typedSpec(spec): PlaySpec;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L88)
+Defined in: [packages/play-actor/src/abstract-actor.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L91)
 
-Identity helper that constrains a `PlaySpec` object's `contextProps` to keys
-of a specific machine context type, giving compile-time validation and IDE
-autocomplete at the definition site.
+The identity helper gives a view spec literal the type `PlaySpec` at the
+definition site. The compiler therefore checks the spec, and the IDE completes it.
 
-XState's `meta` field is typed as `Record<string, unknown>`, so TypeScript
-cannot infer the constraint from context. `typedSpec<MyCtx>(...)` is the
-opt-in mechanism that activates enforcement where the spec is written.
+The XState `meta` field has the type `Record<string, unknown>`. TypeScript
+therefore infers no spec shape from the context. `typedSpec(...)` is the
+mechanism that starts the check where you write the spec. The parameter holds no
+`viewKey`: the derivation stamps that field, and it overwrites a value from an
+author without a notice. Therefore the compiler refuses a `viewKey` here.
 
-At runtime this is a no-op — the spec object is returned unchanged.
+The check of an excess property works on an inline object literal only. For a
+spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
+the literal instead.
 
-## Type Parameters
-
-| Type Parameter                |
-| ----------------------------- |
-| `TContext` _extends_ `object` |
+At run time this function does nothing: it returns the spec object without a
+change.
 
 ## Parameters
 
-| Parameter | Type                                                                           |
-| --------- | ------------------------------------------------------------------------------ |
-| `spec`    | `Omit`\<[`PlaySpec`](../interfaces/PlaySpec.md), `"contextProps"`\> & `object` |
+| Parameter | Type                                                           |
+| --------- | -------------------------------------------------------------- |
+| `spec`    | `Omit`\<[`PlaySpec`](../interfaces/PlaySpec.md), `"viewKey"`\> |
 
 ## Returns
 
@@ -37,18 +37,16 @@ At runtime this is a no-op — the spec object is returned unchanged.
 ## Example
 
 ```ts
-interface DashboardCtx {
-  username: string;
-  params: Record<string, string>;
-  query: Record<string, string>;
-}
-
 meta: {
-  view: typedSpec<DashboardCtx>({
+  view: typedSpec({
     root: "root",
-    contextProps: ["username"],    // ✓ key of DashboardCtx
-    // contextProps: ["usernaem"], // ✗ compile error
-    elements: { root: { type: "Dashboard", props: {}, children: [] } },
+    elements: {
+      root: {
+        type: "Dashboard",
+        props: { username: { $state: "/context/username" } },
+        children: [],
+      },
+    },
   }),
 }
 ```

package/api/@xmachines/play-actor/interfaces/BaseActorProviderProps.md

@@ -2,14 +2,16 @@
 
 # Interface: BaseActorProviderProps\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L155)
+Defined in: [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L159)
 
-Framework-agnostic base props shared by every `ActorProvider` implementation
-(React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
-`DefineRegistryResult` type; `RenderErrorHandler` is sourced from
-`@xmachines/json-render-core` so no second generic is needed.
+The framework-agnostic base props. Every `ActorProvider` implementation shares
+them: React, Vue, Solid, and Svelte. `TRegistry` holds the
+`DefineRegistryResult` type of the framework. `RenderErrorHandler` comes from
+`@xmachines/json-render-core`, and a second generic parameter is therefore not
+necessary.
 
-Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+Each framework package extends this interface with its `fallback` field, its
+`onError` field, and its `children` field.
 
 ## Example
 
@@ -32,15 +34,15 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 ## Type Parameters
 
-| Type Parameter                 | Description                                  |
-| ------------------------------ | -------------------------------------------- |
-| `TRegistry` _extends_ `object` | The framework's `DefineRegistryResult` type. |
+| Type Parameter                 | Description                                       |
+| ------------------------------ | ------------------------------------------------- |
+| `TRegistry` _extends_ `object` | The `DefineRegistryResult` type of the framework. |
 
 ## Properties
 
-| Property                                              | Type                                                                                                                                                                                                                   | Description                                                                                                                                                                                                                 | Defined in                                                                                                                                                       |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L159) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                              | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L172) |
-| <a id="property-registryresult"></a> `registryResult` | `TRegistry`                                                                                                                                                                                                            | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L161) |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                           | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L167) |
+| Property                                              | Type                                                                                                                                                                                                                   | Description                                                                                                                                                                                                                                                                       | Defined in                                                                                                                                               |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](Viewable.md) | The actor instance with the currentView signal. It requires the Viewable capability.                                                                                                                                                                                              | [packages/play-actor/src/abstract-actor.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L163) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                              | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                             | [packages/play-actor/src/abstract-actor.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L177) |
+| <a id="property-registryresult"></a> `registryResult` | `TRegistry`                                                                                                                                                                                                            | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                  | [packages/play-actor/src/abstract-actor.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L165) |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                           | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state. | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L172) |