@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,13 +2,14 @@
 
 # Interface: BaseViewContextValue\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L123)
+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:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L127) |
-| <a id="property-registry"></a> `registry` | `TRegistry`                           | Component registry from registryResult.registry.                                                          | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/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.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L125) |
-| <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:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L131) |
+| 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,17 +2,15 @@
 
 # Interface: PlaySpec
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L48)
+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`.
 
-Adds `contextProps` — an explicit allowlist of machine context fields that
-`deriveCurrentView` merges into element props as low-priority slots. Only
-fields named here are ever exposed to components; nothing leaks from context
-without an opt-in declaration.
-
-Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps`
-entries against your machine's context type at compile time.
+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
 
@@ -20,9 +18,9 @@ entries against your machine's context type at compile time.
 
 ## Properties
 
-| Property                                           | Modifier   | Type                              | Description                                                                                                                                                                                                                                                                                             | Inherited from  | Defined in                                                                                                                                                     |
-| -------------------------------------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-contextprops"></a> `contextProps?` | `readonly` | readonly `string`[]               | Explicit allowlist of machine context field names to expose as prop slots. Each named field is merged into every spec element's `props` at view derivation time, filling any slot whose current value is `undefined`. Use `typedSpec<TContext>(...)` to constrain entries to `keyof TContext & string`. | -               | [packages/play-actor/src/abstract-actor.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L56) |
-| <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`    | -                                                                                                                                                              |
+| 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

@@ -0,0 +1,11 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / ResolveViewStoreOptions
+
+# Interface: ResolveViewStoreOptions
+
+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` | 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-alpha.1/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-alpha.1/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-alpha.1/packages/play-actor/src/abstract-actor.ts#L34) |
+| 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: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

@@ -0,0 +1,50 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / ViewStoreLifecycle
+
+# Interface: ViewStoreLifecycle
+
+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
+
+### reset()
+
+```ts
+reset(): void;
+```
+
+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)
+
+Drops everything, on an unmount or a disconnect. The next resolve makes a new seed.
+
+#### Returns
+
+`void`
+
+---
+
+### resolve()
+
+```ts
+resolve(
+   actor,
+   view,
+   externalStore?,
+   options?): ViewStoreResolution;
+```
+
+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)
+
+Brings the store in line with an emission, and returns it with its guard.
+
+#### Parameters
+
+| 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
+
+[`ViewStoreResolution`](ViewStoreResolution.md)

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

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / ViewStoreResolution
+
+# Interface: ViewStoreResolution
+
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L38)
+
+The result of a resolve — see [ViewStoreLifecycle.resolve](ViewStoreLifecycle.md#resolve).
+
+## Properties
+
+| Property                                          | Type         | Description                                                                                                                                                                                                                                                                       | Defined in                                                                                                                                                         |
+| ------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-guardedstore"></a> `guardedStore` | `StateStore` | The store to give to the children ($bindState, setState, and a chained set): a write under /context throws. There is one wrapper for each store below it, and the code caches the identity. Therefore a consumer in the style of `useSyncExternalStore` stays stable.             | [packages/play-actor/src/view-store-lifecycle.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L47) |
+| <a id="property-reseeded"></a> `reseeded`         | `boolean`    | It is true when this resolve made a new store: at the first resolve, on a change of the viewKey, in the fallback for each emission, and on a change of the actor. A provider that mounts a subtree again for each store, such as the storeKey of Vue, uses this field as its key. | [packages/play-actor/src/view-store-lifecycle.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L54) |
+| <a id="property-store"></a> `store`               | `StateStore` | The store WITHOUT the guard — the reference of the machinery for its own refresh.                                                                                                                                                                                                 | [packages/play-actor/src/view-store-lifecycle.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L40) |

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

@@ -2,17 +2,17 @@
 
 # Interface: Viewable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L104)
+Defined in: [packages/play-actor/src/abstract-actor.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L103)
 
-Actor capability for exposing renderable view state.
+The actor capability that exposes a renderable view state.
 
-`Viewable` marks actors that publish a `currentView` signal.
-Renderers such as `PlayRenderer` consume this contract to resolve the
-current view description into concrete UI without embedding view logic inside the
-framework adapter.
+`Viewable` marks an actor that publishes a `currentView` signal.
+A renderer, such as `PlayRenderer`, reads this contract. It converts the
+description of the current view into a concrete UI, and the framework adapter
+therefore holds no view logic.
 
 ## Properties
 
-| Property                                        | Modifier   | Type                                                                                                    | Description                                                                                                                                                                    | Defined in                                                                                                                                                       |
-| ----------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](PlaySpec.md) \| `null`\> | Current view signal. Contains the json-render PlaySpec for the current machine state, or null when no view is active. Infrastructure renders view — Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L111) |
+| Property                                        | Modifier   | Type                                                                                                    | Description                                                                                                                                                                                                 | Defined in                                                                                                                                               |
+| ----------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](PlaySpec.md) \| `null`\> | The signal of the current view. It holds the json-render PlaySpec of the current machine state, or null when no view is active. The infrastructure renders the view. This is the Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L110) |

package/api/@xmachines/play-actor/variables/CONTEXT_STATE_KEY.md

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / CONTEXT\_STATE\_KEY
+
+# Variable: CONTEXT\_STATE\_KEY
+
+```ts
+const CONTEXT_STATE_KEY: "context" = "context";
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L32)
+
+The reserved top-level state key of the projection.
+
+The `spec.state` object of a view must not declare this key. When it does, the
+derivation skips the projection for that view, the authored state wins, and the
+code writes a warning in development. See [composePlayState](../functions/composePlayState.md).