@xmachines/docs 2.0.0-alpha.1 → 2.0.0

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

@@ -0,0 +1,41 @@
+[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: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.
+
+## Parameters
+
+| Parameter | Type         | Description           |
+| --------- | ------------ | --------------------- |
+| `store`   | `StateStore` | The underlying store. |
+
+## Returns
+
+`StateStore`
+
+A store with guarded `set`/`update`.

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

@@ -0,0 +1,27 @@
+[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:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L203)
+
+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.
+
+## 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`                  | -                                                         |
+
+## Returns
+
+`void`

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

@@ -0,0 +1,41 @@
+[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: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.
+
+## 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,28 @@
+[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:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L56)
+
+Own-key shallow equality with `Object.is`, optionally ignoring 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)).
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `a`       | `object` |
+| `b`       | `object` |
+| `except?` | `string` |
+
+## Returns
+
+`boolean`

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

@@ -6,7 +6,7 @@
 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:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/provider-guards.ts#L36)
 
 Safely coerce a spec's `state` field to a plain object for `createAtom`.
 

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

@@ -3,32 +3,31 @@
 # 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:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L89)
 
-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.
+Identity helper that types a view spec literal as `PlaySpec` at the
+definition site, giving compile-time validation and IDE autocomplete.
 
 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.
+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.
 
-At runtime this is a no-op — the spec object is returned unchanged.
-
-## Type Parameters
+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 literal instead.
 
-| Type Parameter                |
-| ----------------------------- |
-| `TContext` _extends_ `object` |
+At runtime this is a no-op — the spec object is returned unchanged.
 
 ## Parameters
 
-| Parameter | Type                                                                           |
-| --------- | ------------------------------------------------------------------------------ |
-| `spec`    | `Omit`\<[`PlaySpec`](../interfaces/PlaySpec.md), `"contextProps"`\> & `object` |
+| Parameter | Type                                                           |
+| --------- | -------------------------------------------------------------- |
+| `spec`    | `Omit`\<[`PlaySpec`](../interfaces/PlaySpec.md), `"viewKey"`\> |
 
 ## Returns
 
@@ -37,18 +36,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,7 +2,7 @@
 
 # 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:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L152)
 
 Framework-agnostic base props shared by every `ActorProvider` implementation
 (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
@@ -38,9 +38,9 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 ## 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) | 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) |

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

@@ -2,7 +2,7 @@
 
 # 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:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L120)
 
 Framework-agnostic base for every framework's `ViewContextValue`.
 
@@ -25,9 +25,9 @@ type) so it is typed via `TRegistry` — the same generic used in `BaseActorProv
 
 ## 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`\> | 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) |

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:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L46)
 
 XMachines extension of `@xmachines/json-render-core` `Spec`.
 
-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.
+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.
 
 ## 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`                          | 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) |

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:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L52)
+
+## 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) |

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:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L32)
 
 Optional capability: 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: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) |

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:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L62)
+
+## Methods
+
+### reset()
+
+```ts
+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)
+
+Drop everything (unmount/disconnect) — the next resolve reseeds.
+
+#### Returns
+
+`void`
+
+---
+
+### resolve()
+
+```ts
+resolve(
+   actor,
+   view,
+   externalStore?,
+   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)
+
+Bring the store in line with an emission and return 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).                                                                        |
+
+#### 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:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L35)
+
+What a resolve produced — see [ViewStoreLifecycle.resolve](ViewStoreLifecycle.md#resolve).
+
+## Properties
+
+| Property                                          | Type         | Description                                                                                                                                                                                                   | Defined in                                                                                                                                                         |
+| ------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-guardedstore"></a> `guardedStore` | `StateStore` | The store to hand children ($bindState, setState, chained set): writes under /context throw. One wrapper per underlying store — the identity is cached so `useSyncExternalStore`-style consumers stay stable. | [packages/play-actor/src/view-store-lifecycle.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L43) |
+| <a id="property-reseeded"></a> `reseeded`         | `boolean`    | True when this resolve created a fresh store (first resolve, viewKey change, per-emission fallback, actor swap). Providers that remount a subtree per store (Vue's storeKey) key on it.                       | [packages/play-actor/src/view-store-lifecycle.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L49) |
+| <a id="property-store"></a> `store`               | `StateStore` | The UNGUARDED store — the machinery's own refresh reference.                                                                                                                                                  | [packages/play-actor/src/view-store-lifecycle.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L37) |

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

@@ -2,7 +2,7 @@
 
 # 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:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L101)
 
 Actor capability for exposing renderable view state.
 
@@ -13,6 +13,6 @@ framework adapter.
 
 ## 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`\> | 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:108](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L108) |

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:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L31)
+
+The reserved top-level state key the projection materializes under.
+
+A view's authored `spec.state` must not declare this key — when it does, the
+projection is skipped for that view (the authored state wins) and a dev
+warning is emitted. See [composePlayState](../functions/composePlayState.md).

package/api/@xmachines/play-dom/README.md

@@ -1,11 +1,11 @@
 [API](../../README.md) / @xmachines/play-dom
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-dom
 
 Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
+
 Part of the [XMachines Play monorepo](../../README.md).
 
 ## Installation
@@ -17,7 +17,7 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-xstate
+pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
 ```
 
 ## Quick Start
@@ -350,10 +350,12 @@ Public API split into two layers:
 - [DefineRegistryResult](interfaces/DefineRegistryResult.md)
 - [DomRenderContext](interfaces/DomRenderContext.md)
 - [EventHandle](interfaces/EventHandle.md)
+- [FieldValidationState](interfaces/FieldValidationState.md)
 - [MountOptions](interfaces/MountOptions.md)
 - [PlayDomOptions](interfaces/PlayDomOptions.md)
 - [RenderSpecOptions](interfaces/RenderSpecOptions.md)
 - [UIProviderOptions](interfaces/UIProviderOptions.md)
+- [ValidationRegistry](interfaces/ValidationRegistry.md)
 
 ## Type Aliases
 
@@ -380,5 +382,6 @@ Public API split into two layers:
 
 - [createPlayUI](functions/createPlayUI.md)
 - [createRenderer](functions/createRenderer.md)
+- [createValidationRegistry](functions/createValidationRegistry.md)
 - [defineRegistry](functions/defineRegistry.md)
 - [renderSpec](functions/renderSpec.md)

package/api/@xmachines/play-dom/classes/PlayRenderer.md

@@ -2,7 +2,7 @@
 
 # Class: PlayRenderer
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/PlayRenderer.ts#L67)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L68)
 
 PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
 
@@ -61,7 +61,7 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/PlayRenderer.ts#L102)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L126)
 
 #### Parameters
 
@@ -84,7 +84,7 @@ Defined in: [packages/play-dom/src/PlayRenderer.ts:102](https://gitlab.com/xmach
 connect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/PlayRenderer.ts#L118)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L142)
 
 Start watching actor.currentView and render to container.
 Renders the initial view synchronously, then subscribes to signal changes.
@@ -106,7 +106,7 @@ change. Guard against this by auto-disconnecting first.
 disconnect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/PlayRenderer.ts#L127)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L151)
 
 Stop watching and clear the container.
 

package/api/@xmachines/play-dom/functions/createPlayUI.md

@@ -6,7 +6,7 @@
 function createPlayUI(registryResult, options?): MountFn;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/create-play-ui.ts#L93)
+Defined in: [packages/play-dom/src/create-play-ui.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L93)
 
 Create a batteries-included DOM renderer mount function.
 

package/api/@xmachines/play-dom/functions/createRenderer.md

@@ -6,7 +6,7 @@
 function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-renderer.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/create-renderer.ts#L84)
+Defined in: [packages/play-dom/src/create-renderer.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-renderer.ts#L84)
 
 Create a reusable DOM renderer factory from a catalog and component map.