@xmachines/docs 1.1.0 → 2.0.0

package/README.md

@@ -4,8 +4,7 @@
 
 Part of the `XMachines Play monorepo`.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/docs)
+[![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/docs)
 
 ## Overview
 
@@ -84,6 +83,10 @@ Concept guides and tutorials for working with XMachines:
 - **[Understanding the Actor Model](guides/actor-model.md)** — Actor/infrastructure split, `AbstractActor`, and the reset invariant
 - **[Understanding TC39 Signals](guides/signals.md)** — Signal primitives and the five architectural invariants they enforce
 
+**Tooling:**
+
+- **[Inspecting a Running Actor](guides/inspector.md)** — `PlayerOptions.inspect`, the Stately inspector, late attachment, and browser-free transports
+
 ### Contributing & Operations
 
 Reference documentation for contributors and maintainers:

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

@@ -4,8 +4,7 @@
 
 > Core protocol layer for the Universal Player Architecture — defines `PlayEvent`, `PlayError`, and architectural contracts enabling loose coupling between business logic and runtime adapters.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play)
+[![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)
 
 Part of the [XMachines JS monorepo](../../README.md).
 

package/api/@xmachines/play/classes/NonNullableError.md

@@ -2,7 +2,7 @@
 
 # Class: NonNullableError
 
-Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L111)
+Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L111)
 
 Thrown by [assertNonNullable](../functions/assertNonNullable.md) when a value is `null` or `undefined`.
 
@@ -35,7 +35,7 @@ try {
 new NonNullableError(message, options?): NonNullableError;
 ```
 
-Defined in: [packages/play/src/errors.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L112)
+Defined in: [packages/play/src/errors.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L112)
 
 #### Parameters
 
@@ -57,10 +57,10 @@ Defined in: [packages/play/src/errors.ts:112](https://gitlab.com/xmachin-es/xmac
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                         | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`cause`](PlayError.md#property-cause)                     | -                                                                                                                          |
-| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L75) |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L75) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`message`](PlayError.md#property-message)                 | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`name`](PlayError.md#property-name)                       | -                                                                                                                          |
-| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L66) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L66) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`stack`](PlayError.md#property-stack)                     | -                                                                                                                          |
 | <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](PlayError.md).[`stackTraceLimit`](PlayError.md#property-stacktracelimit) | -                                                                                                                          |
 

package/api/@xmachines/play/classes/PlayError.md

@@ -2,7 +2,7 @@
 
 # Class: PlayError
 
-Defined in: [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L64)
+Defined in: [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L64)
 
 Base class for all typed runtime errors thrown by `@xmachines/*` packages.
 
@@ -87,7 +87,7 @@ new PlayError(
    options?): PlayError;
 ```
 
-Defined in: [packages/play/src/errors.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L83)
+Defined in: [packages/play/src/errors.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L83)
 
 #### Parameters
 
@@ -113,10 +113,10 @@ Error.constructor;
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from          | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.cause`           | -                                                                                                                          |
-| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L75) |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L75) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.message`         | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.name`            | -                                                                                                                          |
-| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L66) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L66) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.stack`           | -                                                                                                                          |
 | <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | -                                                                                                                          |
 

package/api/@xmachines/play/functions/assertNonNullable.md

@@ -6,7 +6,7 @@
 function assertNonNullable<V>(value, name?): NonNullable<V>;
 ```
 
-Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/utils.ts#L39)
+Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/utils.ts#L39)
 
 Assert that `value` is neither `null` nor `undefined`, and return it typed
 as `NonNullable<V>` — combining the guard and the narrowed value in a single

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/types.ts#L69)
+Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/types.ts#L69)
 
 Generic event type for Play Architecture
 
@@ -34,7 +34,7 @@ Robot, and other state machine libraries.
 
 | Name   | Type     | Defined in                                                                                                               |
 | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/types.ts#L70) |
+| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/types.ts#L70) |
 
 ## Type Parameters
 

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

@@ -4,8 +4,7 @@
 
 Abstract Actor base class for XMachines Play Architecture.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
+[![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-actor)
 
 Part of the [xmachines-js monorepo](../../README.md).
 
@@ -18,7 +17,7 @@ pnpm add @xmachines/play-actor
 **Peer dependencies** — install alongside the package:
 
 ```bash
-pnpm add xstate @xmachines/play @xmachines/play-signals
+pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
 ```
 
 ## Overview
@@ -89,27 +88,25 @@ class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
 }
 ```
 
-### `typedSpec<TContext>(spec)`
+### `typedSpec(spec)`
 
-Identity helper that constrains a `PlaySpec` object's `contextProps` to keys of a specific machine context type. This enables compile-time validation and IDE autocomplete without any runtime cost.
+Identity helper that types a view-spec literal as `PlaySpec` at the definition site. XState's
+`meta` field is `Record<string, unknown>`, so this is where the spec shape gets compile-time
+validation and IDE autocomplete — without any runtime cost.
 
 ```ts
 import { typedSpec } from "@xmachines/play-actor";
 
-interface DashboardCtx {
-  username: string;
-  params: Record<string, string>;
-  query: Record<string, string>;
-}
-
 // In an XState machine meta block:
 meta: {
-  view: typedSpec<DashboardCtx>({
+  view: typedSpec({
     root: "root",
-    contextProps: ["username"],      // ✓ key of DashboardCtx
-    // contextProps: ["usernaem"],   // ✗ compile error
     elements: {
-      root: { type: "Dashboard", props: {}, children: [] },
+      root: {
+        type: "Dashboard",
+        props: { username: { $state: "/context/username" } },
+        children: [],
+      },
     },
   }),
 }
@@ -117,20 +114,53 @@ meta: {
 
 ### `PlaySpec`
 
-Extends `@xmachines/json-render-core`'s `Spec` with an optional `contextProps` field — an explicit allowlist of machine context fields that are merged into element props at view derivation time.
+Extends `@xmachines/json-render-core`'s `Spec`. The machine's whole 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.
+
+`/context` is read-only by design — never writable. Machine context changes only through events;
+a `$bindState` or `setState` write under `/context` throws with an error naming the event to
+send instead. This is the model: bindable ephemeral state lives at the store root (seeded from
+`spec.state`), domain state lives in the machine and changes via meaningful, inspectable events.
+
+Provenance is legible in the path: `/context/params/username` is visibly URL-derived, while
+`/context/username` is machine-owned — one can never shadow the other.
+
+Two consequences of the everything-is-projected model are worth knowing. First, **exposure**:
+the whole context is client-visible in the view store (debug panels, inspectors, validators) —
+context is a client-side value either way, so keep secrets out of it. Second, **emission
+granularity**: the emit gate compares context per top-level field, so an event that changes any
+field re-emits the view with the same `viewKey`. Providers refresh `/context` in the live store
+rather than reseeding it — no remount, ephemeral view state and focus survive — but a
+re-emission is still a render pass in the framework layer. Keep high-frequency ephemeral data
+(per-keystroke drafts, timers) in the view store (`spec.state` + `$bindState`) or a child actor
+rather than in machine context; domain state belongs in context, keystrokes do not.
 
 ```ts
 import type { PlaySpec } from "@xmachines/play-actor";
 
 const spec: PlaySpec = {
 	root: "root",
-	contextProps: ["username"], // only these keys are exposed to components
 	elements: {
-		root: { type: "Profile", props: { username: undefined }, children: [] },
+		root: {
+			type: "Profile",
+			props: { username: { $state: "/context/username" } },
+			children: [],
+		},
 	},
 };
 ```
 
+> Historical note: earlier versions had a `contextProps` field. It first drove an implicit
+> prop-enrichment pass that merged allowlisted context fields and URL params into every
+> element's props (removed — it injected values into components that never asked for them and
+> let user-manipulable URL data silently shadow machine-owned state), and was then briefly a
+> projection filter (removed — filtering what a view may read added machinery without a real
+> problem to solve). Validate the **derived** view (`actor.currentView.get()`), not the raw
+> `meta.view`: the derived spec's `state` carries the projection, so tools like `validateSpec`
+> see a self-consistent spec.
+
 ### `Routable`
 
 Interface for actors that support routing.
@@ -230,11 +260,24 @@ reactive signals for Infrastructure layer communication.
 - [BaseActorProviderProps](interfaces/BaseActorProviderProps.md)
 - [BaseViewContextValue](interfaces/BaseViewContextValue.md)
 - [PlaySpec](interfaces/PlaySpec.md)
+- [ResolveViewStoreOptions](interfaces/ResolveViewStoreOptions.md)
 - [Routable](interfaces/Routable.md)
 - [Viewable](interfaces/Viewable.md)
+- [ViewStoreLifecycle](interfaces/ViewStoreLifecycle.md)
+- [ViewStoreResolution](interfaces/ViewStoreResolution.md)
+
+## Variables
+
+- [CONTEXT\_STATE\_KEY](variables/CONTEXT_STATE_KEY.md)
 
 ## Functions
 
 - [attachRenderErrorHandler](functions/attachRenderErrorHandler.md)
+- [composePlayState](functions/composePlayState.md)
+- [createViewStoreLifecycle](functions/createViewStoreLifecycle.md)
+- [guardContextWrites](functions/guardContextWrites.md)
+- [refreshContextSubtree](functions/refreshContextSubtree.md)
+- [reuseComposedState](functions/reuseComposedState.md)
+- [shallowEqualExcept](functions/shallowEqualExcept.md)
 - [toAtomState](functions/toAtomState.md)
 - [typedSpec](functions/typedSpec.md)

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L193)
+Defined in: [packages/play-actor/src/abstract-actor.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L190)
 
 Abstract base class for Play Architecture actors.
 
@@ -75,7 +75,7 @@ Actor<TLogic>.constructor
 | <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`       | -                                                                                                                                                        |
 | <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId` | -                                                                                                                                                        |
 | <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor.src`       | -                                                                                                                                                        |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L203) |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:200](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L200) |
 | <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`    | -                                                                                                                                                        |
 | <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.systemId`  | -                                                                                                                                                        |
 
@@ -246,7 +246,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L218)
+Defined in: [packages/play-actor/src/abstract-actor.ts:215](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L215)
 
 Send event to Actor.
 

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

@@ -6,7 +6,7 @@
 function attachRenderErrorHandler<TRegistry>(registry, handler): TRegistry;
 ```
 
-Defined in: [packages/play-actor/src/provider-guards.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/provider-guards.ts#L64)
+Defined in: [packages/play-actor/src/provider-guards.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/provider-guards.ts#L64)
 
 Clone a component registry and inject an `onRenderError` handler.
 

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

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / composePlayState
+
+# Function: composePlayState()
+
+```ts
+function composePlayState(authoredState, slice): Record<string, unknown> | undefined;
+```
+
+Defined in: [packages/play-actor/src/context-projection.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L220)
+
+Compose a view's effective state: the authored `spec.state` plus the
+`/context` slice.
+
+When the authored state already declares the reserved key, the projection is
+skipped (authored state wins) with a dev warning — no existing spec breaks.
+
+## Parameters
+
+| Parameter       | Type                                           | Description                                                                       |
+| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
+| `authoredState` | `Record`\<`string`, `unknown`\> \| `undefined` | The raw `meta.view.state` (may be anything; sanitized by the caller/toAtomState). |
+| `slice`         | `Record`\<`string`, `unknown`\> \| `undefined` | The machine's context, projected wholesale.                                       |
+
+## Returns
+
+`Record`\<`string`, `unknown`\> \| `undefined`

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

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / createViewStoreLifecycle
+
+# Function: createViewStoreLifecycle()
+
+```ts
+function createViewStoreLifecycle(createStore): ViewStoreLifecycle;
+```
+
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L89)
+
+Create a lifecycle coordinator.
+
+## 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). |
+
+## Returns
+
+[`ViewStoreLifecycle`](../interfaces/ViewStoreLifecycle.md)

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/v1.1.0/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/v1.1.0/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: [],
+      },
+    },
   }),
 }
 ```