@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

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

@@ -1,220 +1,195 @@
 [API](../../README.md) / @xmachines/play-actor
 
-# @xmachines/play-actor
-
-**Abstract Actor base class with signal protocol for XMachines Play Architecture**
-
-Foundation for all actor implementations, enforcing XState compatibility and reactive signal contracts.
-
-## Overview
+<!-- generated-by: gsd-doc-writer -->
 
-`@xmachines/play-actor` provides `AbstractActor`, a base class that extends XState's `Actor` while enforcing the Play Architecture's signal protocol. It maintains XState ecosystem compatibility (inspection tools, devtools) while exposing reactive signals for infrastructure layer communication.
-
-Per [Play RFC](../../../rfc/play.md), this package implements:
+# @xmachines/play-actor
 
-- **Actor Authority (INV-01):** Actor is sole source of truth for state transitions
-- **Signal-Only Reactivity (INV-05):** Infrastructure observes via TC39 Signals, never directly queries
-- **Passive Infrastructure (INV-04):** Infrastructure reflects, never decides
+Abstract Actor base class for XMachines Play Architecture.
 
-**Note:** This is an abstract base class. Concrete implementations are provided by adapters (see [@xmachines/play-xstate](../play-xstate/README.md)).
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install xstate@^5.0.0
 npm install @xmachines/play-actor
 ```
 
-## Current Exports
+**Peer dependencies** — install alongside the package:
 
-- `AbstractActor`
-- `Routable` (type)
-- `Viewable` (type)
-- `PlaySpec` (type)
-- `typedSpec`
-- `BaseActorProviderProps` (type)
-- `BaseViewContextValue` (type)
+```bash
+npm install xstate @xmachines/play @xmachines/play-signals
+```
 
-**Peer dependencies:**
+## Overview
 
-- `xstate` ^5.0.0 — State machine runtime (XState compatibility)
-- `@xmachines/play-signals` - TC39 Signals primitives
-- `@xmachines/play` - Protocol types (PlayEvent, etc.)
+`@xmachines/play-actor` provides `AbstractActor`, a minimal base class that extends the XState `Actor` class while enforcing the Play Architecture's **signal protocol** (RFC section 5.3). It exposes reactive TC39 Signals for infrastructure-layer communication while preserving full XState ecosystem compatibility (devtools, inspection).
 
-## Quick Start
+The core protocol is deliberately minimal:
 
-**Usage:** This is an abstract base class — use concrete implementations:
+| Property | Type                      | Description                              |
+| -------- | ------------------------- | ---------------------------------------- |
+| `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
+| `send`   | `(event: TEvent) => void` | Event dispatch method                    |
 
-```typescript
-import { definePlayer } from "@xmachines/play-xstate";
+Optional capabilities are declared as separate interfaces — a concrete actor opts in only to what it needs:
 
-// definePlayer returns PlayerActor (extends AbstractActor)
-const createPlayer = definePlayer({ machine });
-const actor = createPlayer();
-actor.start();
+| Interface  | Property                                        | Description                           |
+| ---------- | ----------------------------------------------- | ------------------------------------- |
+| `Routable` | `currentRoute: Signal.Computed<string \| null>` | Current route path derived from state |
+| `Routable` | `initialRoute: string \| null`                  | Route the actor starts on             |
+| `Viewable` | `currentView: Signal.State<PlaySpec \| null>`   | Current JSON-render view spec         |
 
-// Signal protocol properties (from AbstractActor)
-console.log(actor.state.get()); // Current snapshot
-console.log(actor.currentRoute.get()); // Derived route
-console.log(actor.currentView.get()); // Derived view structure
-```
+Concrete implementations are created by adapters such as [`@xmachines/play-xstate`](../play-xstate/README.md).
 
-## API Reference
+## API Summary
 
-### AbstractActor<TLogic>
+### `AbstractActor<TLogic, TEvent>`
 
-Abstract base class defining signal protocol:
+Abstract base class extending XState `Actor<TLogic>`.
 
-**Abstract Properties (must implement):**
+```ts
+import { AbstractActor } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+import type { AnyActorLogic } from "xstate";
 
-- `state: Signal.State<unknown>` - Reactive snapshot of current state
+class MyActor extends AbstractActor<AnyActorLogic> {
+	// Required: reactive state signal
+	state = new Signal.State({});
 
-**Optional capability interfaces:**
+	// Required: typed event dispatch
+	send = (event: { type: string }) => {
+		/* dispatch to XState */
+	};
+}
+```
 
-Implement `Routable` to add routing support:
+With a typed event union:
 
-- `currentRoute: Signal.Computed<string | null>` - Derived navigation path
+```ts
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
 
-Implement `Viewable` to add view rendering support:
+class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
+	state = new Signal.State({ isAuthenticated: false, username: null });
 
-- `currentView: Signal.State<PlaySpec | null>` - Current view spec (updated on every state transition). `PlaySpec` is a `@json-render/core` spec object (`{ root, elements }`) that drives the renderer directly.
+	send = (event: AuthEvent) => {
+		/* dispatch */
+	};
+}
+```
 
-**Inherited from XState Actor:**
+### `typedSpec<TContext>(spec)`
 
-- `send(event): void` - Send event to actor
-- `start(): void` - Start the actor
-- `stop(): void` - Stop the actor
-- `getSnapshot()` - Get current XState snapshot (typed as `SnapshotFrom<TLogic>`)
+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.
 
-**Example implementation pattern:**
+```ts
+import { typedSpec } from "@xmachines/play-actor";
 
-```typescript
-import { AbstractActor, type Routable, type Viewable, type PlaySpec } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
-import type { AnyActorLogic, AnyMachineSnapshot } from "xstate";
-
-class PlayerActor<TLogic extends AnyActorLogic>
-	extends AbstractActor<TLogic>
-	implements Routable, Viewable
-{
-	// Required: reactive state snapshot
-	state = new Signal.State<AnyMachineSnapshot>(this.getSnapshot() as AnyMachineSnapshot);
-
-	// Routable: derived navigation path
-	currentRoute = new Signal.Computed(() => {
-		return deriveRoute(this.state.get());
-	});
-
-	// Viewable: current view spec — Signal.State, updated on every state transition
-	currentView = new Signal.State<PlaySpec | null>(null);
-
-	constructor(logic: TLogic) {
-		super(logic);
-
-		// Subscribe to XState transitions and update signals
-		this.subscribe((snapshot) => {
-			this.state.set(snapshot as AnyMachineSnapshot);
-			// Derive currentView from snapshot meta and update the signal...
-		});
-	}
+interface DashboardCtx {
+  username: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+}
+
+// In an XState machine meta block:
+meta: {
+  view: typedSpec<DashboardCtx>({
+    root: "root",
+    contextProps: ["username"],      // ✓ key of DashboardCtx
+    // contextProps: ["usernaem"],   // ✗ compile error
+    elements: {
+      root: { type: "Dashboard", props: {}, children: [] },
+    },
+  }),
 }
 ```
 
-## Examples
+### `PlaySpec`
 
-### Infrastructure Observing Signals
+Extends `@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.
 
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
+```ts
+import type { PlaySpec } from "@xmachines/play-actor";
 
-function syncUrlToActor(actor: AbstractActor<any>) {
-	// Infrastructure passively observes actor's route signal
-	const watcher = new Signal.subtle.Watcher(() => {
-		queueMicrotask(() => {
-			const pending = watcher.getPending();
-			if (pending.length > 0) {
-				const route = actor.currentRoute.get();
-				if (route !== null) {
-					// Update browser URL (Passive Infrastructure)
-					window.history.replaceState(null, "", route);
-				}
-				watcher.watch(...pending); // Re-watch
-			}
-		});
-	});
-
-	watcher.watch(actor.currentRoute);
-	actor.currentRoute.get(); // Initial read
-
-	return () => watcher.unwatch(actor.currentRoute);
-}
+const spec: PlaySpec = {
+	root: "root",
+	contextProps: ["username"], // only these keys are exposed to components
+	elements: {
+		root: { type: "Profile", props: { username: undefined }, children: [] },
+	},
+};
 ```
 
-### Browser Navigation Sending Events
+### `Routable`
 
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
-
-function connectBrowserNavigation(actor: AbstractActor<any>) {
-	const handlePopstate = () => {
-		const path = window.location.pathname;
+Interface for actors that support routing.
 
-		// Browser event sent to actor (Actor Authority)
-		// Actor guards decide if navigation is valid
-		actor.send({ type: "play.route", to: path });
-	};
-
-	window.addEventListener("popstate", handlePopstate);
+```ts
+import type { Routable } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
 
-	return () => {
-		window.removeEventListener("popstate", handlePopstate);
+// Implement in a concrete actor:
+class RoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
+	state = new Signal.State({});
+	currentRoute = new Signal.Computed(() => this.state.get().path ?? null);
+	initialRoute = "/";
+	send = (event) => {
+		/* dispatch */
 	};
 }
 ```
 
-## Architecture
+### `Viewable`
 
-This base class enforces three architectural invariants:
+Interface for actors that expose a renderable view signal.
 
-1. **Actor Authority (INV-01):**
-    - Actor decides all state transitions via guards
-    - Infrastructure sends events, actor validates and processes
-    - Actor's decision is final — no override by infrastructure
+```ts
+import type { Viewable } from "@xmachines/play-actor";
+import type { PlaySpec } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+
+// currentView carries PlaySpec | null
+const signal = new Signal.State<PlaySpec | null>(null);
+const viewable: Viewable = { currentView: signal };
+```
 
-2. **Signal-Only Reactivity (INV-05):**
-    - All reactive state exposed via TC39 Signals
-    - Infrastructure uses `Signal.subtle.Watcher` to observe
-    - No direct queries (`getSnapshot()` for internal use only)
+### `BaseActorProviderProps<TRegistry>`
 
-3. **Passive Infrastructure (INV-04):**
-    - Infrastructure reflects actor state (via signals)
-    - Infrastructure never decides transitions
-    - Browser/router events sent as commands to actor
+Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
 
-## XState Compatibility
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@json-render/react";
 
-`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
 
-- **Type Safety:** Generic `TLogic extends AnyActorLogic` parameter
-- **Inspection API:** XState Inspector can attach to actors
-- **DevTools Integration:** Standard XState devtools work
-- **Ecosystem Tools:** Works with XState visualization, testing libraries
+### `BaseViewContextValue<TRegistry>`
 
-**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
 
-## Related Packages
+## Testing
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - Concrete PlayerActor implementation
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
-- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent, RouterBridge)
+Run the test suite for this package in isolation:
 
-## License
+```bash
+# From the package directory
+npm test
+
+# From the monorepo root (workspace-scoped)
+npm test -w packages/play-actor
+
+# Watch mode
+npm run test:watch -w packages/play-actor
+```
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+## Requirements
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+- **Node.js** `>=22.0.0`
+- **TypeScript** `>=5.7` (strict mode)
+- **ESM only** — `"type": "module"`
 
 @xmachines/play-actor - Abstract Actor base class for Play Architecture
 

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:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L180)
+Defined in: [packages/play-actor/src/abstract-actor.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L180)
 
 Abstract base class for Play Architecture actors.
 
@@ -67,7 +67,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:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L190) |
+| <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:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L190) |
 | <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`  | -                                                                                                                                                                |
 
@@ -238,7 +238,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L197)
+Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L197)
 
 Send event to Actor.
 

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

@@ -6,7 +6,7 @@
 function typedSpec<TContext>(spec): PlaySpec;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L83)
+Defined in: [packages/play-actor/src/abstract-actor.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L83)
 
 Identity helper that constrains a `PlaySpec` object's `contextProps` to keys
 of a specific machine context type, giving compile-time validation and IDE

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

@@ -2,7 +2,7 @@
 
 # Interface: BaseActorProviderProps\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L150)
+Defined in: [packages/play-actor/src/abstract-actor.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L150)
 
 Framework-agnostic base props shared by every `ActorProvider` implementation
 (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
@@ -40,7 +40,7 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 | 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:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L154) |
-| <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:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L167) |
-| <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:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L156) |
-| <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:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L162) |
+| <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:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L154) |
+| <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:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L167) |
+| <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:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L156) |
+| <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:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L162) |

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

@@ -2,7 +2,7 @@
 
 # Interface: BaseViewContextValue\<TRegistry\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L118)
+Defined in: [packages/play-actor/src/abstract-actor.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L118)
 
 Framework-agnostic base for every framework's `ViewContextValue`.
 
@@ -27,7 +27,7 @@ type) so it is typed via `TRegistry` — the same generic used in `BaseActorProv
 
 | 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:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L122) |
-| <a id="property-registry"></a> `registry` | `TRegistry`                           | Component registry from registryResult.registry.                                                          | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L124) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](PlaySpec.md)             | The current PlaySpec to render.                                                                           | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L120) |
-| <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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L126) |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\> | Action handlers resolved against the live StateStore.                                                     | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L122) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                           | Component registry from registryResult.registry.                                                          | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L124) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](PlaySpec.md)             | The current PlaySpec to render.                                                                           | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L120) |
+| <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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L126) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlaySpec
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L43)
+Defined in: [packages/play-actor/src/abstract-actor.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L43)
 
 XMachines extension of `@json-render/core` `Spec`.
 
@@ -22,7 +22,7 @@ entries against your machine's context type at compile time.
 
 | 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:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L51) |
+| <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:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L51) |
 | <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`    | -                                                                                                                                                              |

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

@@ -2,7 +2,7 @@
 
 # Interface: Routable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L27)
+Defined in: [packages/play-actor/src/abstract-actor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L27)
 
 Optional capability: Routing support
 
@@ -10,5 +10,5 @@ Optional capability: Routing support
 
 | 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:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L28) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L29) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [packages/play-actor/src/abstract-actor.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L28) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L29) |

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

@@ -2,7 +2,7 @@
 
 # Interface: Viewable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L99)
+Defined in: [packages/play-actor/src/abstract-actor.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L99)
 
 Actor capability for exposing renderable view state.
 
@@ -15,4 +15,4 @@ framework adapter.
 
 | 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:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L106) |
+| <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:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L106) |