@xmachines/docs 2.0.0 → 2.1.0

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

@@ -6,15 +6,15 @@
 function createViewStoreLifecycle(createStore): ViewStoreLifecycle;
 ```
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L89)
+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)
 
-Create a lifecycle coordinator.
+Creates a coordinator of the lifecycle.
 
 ## Parameters
 
-| Parameter     | Type                     | Description                                                                                                                               |
-| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `createStore` | (`seed`) => `StateStore` | Framework-supplied store factory; receives the proto-safe seed (`toAtomState(view.state)` — the composed state already carries /context). |
+| 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
 

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

@@ -6,36 +6,38 @@
 function guardContextWrites(store): StateStore;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L146)
-
-Wrap a StateStore so writes under `/context` are rejected.
-
-Applied by providers to the store they hand to bindings and action handlers
-(`$bindState`, `setState`, chained `set`). The provider keeps the unwrapped
-store and refreshes the projection through it — read-only to the spec, not
-to the machinery.
-
-A write whose value is **identical** to the current one passes silently:
-`setState`-style handlers read the full snapshot, transform it, and write
-the whole object back — the untouched `context` key flowing through that
-round-trip is not a mutation attempt. Only a write that would actually
-change the subtree throws.
-
-Reads pass through untouched, and every member is delegated explicitly
-rather than spread: a consumer-supplied store may be a class instance, whose
-methods live on the prototype and would not survive `{ ...store }` — the
-first render would die on `store.getSnapshot is not a function`. The wrapper
-is built once per resolved store, so the delegating `getSnapshot`/`subscribe`
-identities stay stable for `useSyncExternalStore`-style consumers.
+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 underlying store. |
+| Parameter | Type         | Description                  |
+| --------- | ------------ | ---------------------------- |
+| `store`   | `StateStore` | The store below the wrapper. |
 
 ## Returns
 
 `StateStore`
 
-A store with guarded `set`/`update`.
+A store with a guard on `set` and on `update`.

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

@@ -6,21 +6,22 @@
 function refreshContextSubtree(store, view): void;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L203)
+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)
 
-Refresh a live store's `/context` subtree from a derived view's composed
-state. A same-`viewKey` emission means only the projection changed — the
-subtree is replaced wholesale (never merged per-field: `update` cannot
-delete keys) and every ephemeral root-level value is left untouched.
-No-op when the view carries no slice or the store already holds it.
+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 UNGUARDED store (providers refresh through it).       |
-| `view`        | \{ `state?`: `unknown`; \} | The derived view whose `state.context` carries the slice. |
-| `view.state?` | `unknown`                  | -                                                         |
+| 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
 

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

@@ -6,28 +6,29 @@
 function reuseComposedState(prev, next): PlaySpec | null;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L89)
-
-Reuse the previous emission's composed `state` — or the whole previous spec
-— when the projection is value-unchanged.
-
-`deriveCurrentView` composes `state: { ...meta.view.state, context: slice }`
-fresh per call, and XState's `assign` produces a fresh context object on
-every event — so without reuse, every event would present a new `state`
-reference and the emit gate's per-field `Object.is` would re-emit (and
-remount) constantly. Slices are compared per field ([shallowEqualExcept](shallowEqualExcept.md) —
-XState's `assign` produces a fresh context object per event, so whole-object
-identity would report a change every time); the authored fields are spread
-from the static `meta.view.state`, so for an unchanged `viewKey` their
-references are stable and plain `Object.is` holds.
-
-Returns, in order of preference:
-
-- `prev` itself when nothing observable changed — the emit gate then
-  short-circuits on reference identity with no element walk;
-- `{ ...next, state: prev.state }` when the state is value-unchanged but
-  some other top-level field differs;
-- `next` when something actually changed.
+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
 

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

@@ -6,14 +6,15 @@
 function shallowEqualExcept(a, b, except?): boolean;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L56)
+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)
 
-Own-key shallow equality with `Object.is`, optionally ignoring one key on
+The shallow equality of the own keys, with `Object.is`. It can ignore one key on
 both sides.
 
-The single comparison rule behind every emission-dedup decision: slice
-equality and the player's emit gate alike (spec-field comparison in
-`viewSpecsEquivalent`, composed-state reuse in [reuseComposedState](reuseComposedState.md)).
+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
 

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/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

@@ -6,22 +6,23 @@
 function typedSpec(spec): PlaySpec;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L89)
+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 types a view spec literal as `PlaySpec` at the
-definition site, giving compile-time validation and IDE autocomplete.
+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 spec shape from context. `typedSpec(...)` is the opt-in
-mechanism that activates checking where the spec is written. `viewKey` is
-excluded from the parameter — derivation stamps it and would silently
-overwrite an authored value, so authoring one is rejected at compile time.
+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.
 
-Excess-property checking only applies to an inline object literal; for a
-spec built in a variable or through spreads, use `satisfies PlaySpec` at
+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.
 
-At runtime this is a no-op — the spec object is returned unchanged.
+At run time this function does nothing: it returns the spec object without a
+change.
 
 ## Parameters
 

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

@@ -2,14 +2,16 @@
 
 # Interface: BaseActorProviderProps\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L152)
+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:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L156) |
-| <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:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L169) |
-| <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:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L158) |
-| <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:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L164) |
+| 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) |

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

@@ -2,13 +2,14 @@
 
 # Interface: BaseViewContextValue\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L120)
+Defined in: [packages/play-actor/src/abstract-actor.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L123)
 
-Framework-agnostic base for every framework's `ViewContextValue`.
+The framework-agnostic base of the `ViewContextValue` type in each framework.
 
-Holds the three fields that are identical across React, Vue, Solid, and Svelte.
-`registry` is framework-specific (each framework has its own `ComponentRegistry`
-type) so it is typed via `TRegistry` — the same generic used in `BaseActorProviderProps`.
+It holds the three fields that are identical in React, Vue, Solid, and Svelte.
+The `registry` field belongs to one framework, because each framework has its own
+`ComponentRegistry` type. Therefore `TRegistry` gives its type, and this is the
+same generic parameter as in `BaseActorProviderProps`.
 
 ## Extended by
 
@@ -19,15 +20,15 @@ type) so it is typed via `TRegistry` — the same generic used in `BaseActorProv
 
 ## Type Parameters
 
-| Type Parameter                 | Description                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `TRegistry` _extends_ `object` | The framework's component registry type (e.g. `ComponentRegistry` from `@xmachines/json-render-react`). |
+| Type Parameter                 | Description                                                                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `TRegistry` _extends_ `object` | The registry type of the component of the framework, for example `ComponentRegistry` from `@xmachines/json-render-react`. |
 
 ## Properties
 
-| Property                                  | Type                                  | Description                                                                                               | Defined in                                                                                                                                               |
-| ----------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\> | Action handlers resolved against the live StateStore.                                                     | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L124) |
-| <a id="property-registry"></a> `registry` | `TRegistry`                           | Component registry from registryResult.registry.                                                          | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L126) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](PlaySpec.md)             | The current PlaySpec to render.                                                                           | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L122) |
-| <a id="property-store"></a> `store`       | `StateStore`                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [packages/play-actor/src/abstract-actor.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L128) |
+| Property                                  | Type                                  | Description                                                                                                            | Defined in                                                                                                                                               |
+| ----------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\> | The action handlers, resolved against the live StateStore.                                                             | [packages/play-actor/src/abstract-actor.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                           | The component registry, from registryResult.registry.                                                                  | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L129) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](PlaySpec.md)             | The current PlaySpec to render.                                                                                        | [packages/play-actor/src/abstract-actor.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                          | The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state. | [packages/play-actor/src/abstract-actor.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L133) |

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

@@ -2,15 +2,15 @@
 
 # Interface: PlaySpec
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L46)
+Defined in: [packages/play-actor/src/abstract-actor.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L47)
 
-XMachines extension of `@xmachines/json-render-core` `Spec`.
+The XMachines extension of the `Spec` type of `@xmachines/json-render-core`.
 
-The machine's context is projected into every derived view's state store
-under the read-only `/context` subtree, so specs read it through the
-ordinary `{ $state: "/context/…" }` grammar — in props, `visible`
-conditions, and `repeat.statePath` alike. The whole context is always
-projected; a spec simply reads the paths it needs.
+Each derived view receives the machine context in its state store, under the
+read-only `/context` subtree. A spec therefore reads the context through the
+ordinary `{ $state: "/context/…" }` grammar: in a prop, in a `visible` condition,
+and in `repeat.statePath`. The store always holds the complete context, and a
+spec reads only the paths that it needs.
 
 ## Extends
 
@@ -18,9 +18,9 @@ projected; a spec simply reads the paths it needs.
 
 ## Properties
 
-| Property                                  | Modifier   | Type                              | Description                                                                                                                                                                                                                                                                                                                                    | Inherited from  | Defined in                                                                                                                                             |
-| ----------------------------------------- | ---------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-elements"></a> `elements` | `public`   | `Record`\<`string`, `UIElement`\> | Flat map of elements by key                                                                                                                                                                                                                                                                                                                    | `Spec.elements` | -                                                                                                                                                      |
-| <a id="property-root"></a> `root`         | `public`   | `string`                          | Root element key                                                                                                                                                                                                                                                                                                                               | `Spec.root`     | -                                                                                                                                                      |
-| <a id="property-state"></a> `state?`      | `public`   | `Record`\<`string`, `unknown`\>   | Optional initial state to seed the state model. Components using statePath will read from / write to this state.                                                                                                                                                                                                                               | `Spec.state`    | -                                                                                                                                                      |
-| <a id="property-viewkey"></a> `viewKey?`  | `readonly` | `string`                          | Identity of the view this derived spec came from — set by `deriveCurrentView` from the meta entry the derivation actually selected. Providers key their store lifecycle on it: a changed `viewKey` reseeds the store; an unchanged one refreshes `/context` in place, preserving ephemeral view state. Never author this field in `meta.view`. | -               | [packages/play-actor/src/abstract-actor.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L54) |
+| Property                                  | Modifier   | Type                              | Description                                                                                                                                                                                                                                                                                                                                                  | Inherited from  | Defined in                                                                                                                                             |
+| ----------------------------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-elements"></a> `elements` | `public`   | `Record`\<`string`, `UIElement`\> | Flat map of elements by key                                                                                                                                                                                                                                                                                                                                  | `Spec.elements` | -                                                                                                                                                      |
+| <a id="property-root"></a> `root`         | `public`   | `string`                          | Root element key                                                                                                                                                                                                                                                                                                                                             | `Spec.root`     | -                                                                                                                                                      |
+| <a id="property-state"></a> `state?`      | `public`   | `Record`\<`string`, `unknown`\>   | Optional initial state to seed the state model. Components using statePath will read from / write to this state.                                                                                                                                                                                                                                             | `Spec.state`    | -                                                                                                                                                      |
+| <a id="property-viewkey"></a> `viewKey?`  | `readonly` | `string`                          | The identity of the view of this derived spec. `deriveCurrentView` sets it from the meta entry that the derivation selected. A provider uses it as the key of its store lifecycle: a new `viewKey` seeds the store again, and the same `viewKey` refreshes `/context` in place, which keeps the ephemeral view state. Never write this field in `meta.view`. | -               | [packages/play-actor/src/abstract-actor.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L55) |

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

@@ -2,10 +2,10 @@
 
 # Interface: ResolveViewStoreOptions
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L52)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L57)
 
 ## Properties
 
-| Property                                                           | Type      | Description                                                                                                                                                                                                                            | Defined in                                                                                                                                                         |
-| ------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-refreshexternalstore"></a> `refreshExternalStore?` | `boolean` | Controlled mode only: refresh the external store's /context during this resolve (default true). Pass false where notifying store subscribers is not allowed at the call site (React's render path) and refresh from an effect instead. | [packages/play-actor/src/view-store-lifecycle.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L59) |
+| Property                                                           | Type      | Description                                                                                                                                                                                                                                                                    | Defined in                                                                                                                                                         |
+| ------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-refreshexternalstore"></a> `refreshExternalStore?` | `boolean` | The controlled mode only: refresh the /context subtree of the external store during this resolve. The default is true. Give false where the call site permits no notification of the store subscribers, which is the render path of React, and refresh from an effect instead. | [packages/play-actor/src/view-store-lifecycle.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L64) |

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

@@ -2,13 +2,13 @@
 
 # Interface: Routable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L32)
+Defined in: [packages/play-actor/src/abstract-actor.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L33)
 
-Optional capability: Routing support
+An optional capability: the routing support
 
 ## Properties
 
 | Property                                          | Modifier   | Type                                                                                         | Defined in                                                                                                                                             |
 | ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [packages/play-actor/src/abstract-actor.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L33) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L34) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [packages/play-actor/src/abstract-actor.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L34) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L35) |

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

@@ -2,7 +2,7 @@
 
 # Interface: ViewStoreLifecycle
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L62)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L67)
 
 ## Methods
 
@@ -12,9 +12,9 @@ Defined in: [packages/play-actor/src/view-store-lifecycle.ts:62](https://gitlab.
 reset(): void;
 ```
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L79)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L84)
 
-Drop everything (unmount/disconnect) — the next resolve reseeds.
+Drops everything, on an unmount or a disconnect. The next resolve makes a new seed.
 
 #### Returns
 
@@ -32,18 +32,18 @@ resolve(
    options?): ViewStoreResolution;
 ```
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L72)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L77)
 
-Bring the store in line with an emission and return it (with its guard).
+Brings the store in line with an emission, and returns it with its guard.
 
 #### Parameters
 
-| Parameter        | Type                                                    | Description                                                                                                                       |
-| ---------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `actor`          | `unknown`                                               | The actor the emission came from — a swap drops the kept store.                                                                   |
-| `view`           | [`PlaySpec`](PlaySpec.md)                               | The derived view (non-null; a null emission is a GAP, not a new view — callers simply do not resolve on null, keeping the store). |
-| `externalStore?` | `StateStore`                                            | Controlled mode: the caller-owned store.                                                                                          |
-| `options?`       | [`ResolveViewStoreOptions`](ResolveViewStoreOptions.md) | See [ResolveViewStoreOptions](ResolveViewStoreOptions.md).                                                                        |
+| Parameter        | Type                                                    | Description                                                                                                                                        |
+| ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`          | `unknown`                                               | The actor of the emission. A different actor drops the store that the code kept.                                                                   |
+| `view`           | [`PlaySpec`](PlaySpec.md)                               | The derived view. It is not null: a null emission is a GAP, and not a new view. A caller resolves nothing on a null value, and it keeps the store. |
+| `externalStore?` | `StateStore`                                            | The controlled mode: the store of the caller.                                                                                                      |
+| `options?`       | [`ResolveViewStoreOptions`](ResolveViewStoreOptions.md) | See [ResolveViewStoreOptions](ResolveViewStoreOptions.md).                                                                                         |
 
 #### Returns