@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.18

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

@@ -4,11 +4,13 @@
 
 **Protocol layer defining Actor ↔ Infrastructure event contracts for XMachines Play Architecture.**
 
-`@xmachines/play` is intentionally small. It provides the base event contract used across adapters and actor implementations while keeping framework/runtime concerns out of business logic.
+`@xmachines/play` is intentionally small. It provides the base event type and the base error
+class used across all adapters and actor implementations, while keeping framework and runtime
+concerns out of business logic.
 
 ## Overview
 
-This package exports protocol types only (no runtime behavior). It exists to preserve strict separation between:
+This package exports the shared Play protocol surface. It exists to preserve strict separation between:
 
 - **Actors** (business authority)
 - **Infrastructure adapters** (routers/renderers that observe and forward)
@@ -29,40 +31,73 @@ npm install @xmachines/play
 
 This package exports:
 
-- `PlayEvent<TPayload>`
+| Export      | Type  | Purpose                                           |
+| ----------- | ----- | ------------------------------------------------- |
+| `PlayEvent` | type  | Minimal event shape — `{ type: string, ...rest }` |
+| `PlayError` | class | Base class for all `@xmachines/*` typed errors    |
 
-`PlayEvent` is the minimal event shape:
+### `PlayEvent`
 
-```ts
-type PlayEvent<TPayload extends Record<string, any> = Record<string, any>> = {
-	readonly type: string;
-} & TPayload;
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+
+// Flexible (default):
+const event: PlayEvent = { type: "auth.login", userId: "123" };
+
+// Type-safe (with generic):
+type LoginEvent = PlayEvent<{ userId: string }>;
+const login: LoginEvent = { type: "auth.login", userId: "123" };
 ```
 
-## Usage
+### `PlayError`
 
-### Base event usage
+Base class for all typed runtime errors thrown by `@xmachines/*` packages.
 
-```ts
-import type { PlayEvent } from "@xmachines/play";
+Every `PlayError` carries two structured fields:
 
-type LoginEvent = PlayEvent<{ userId: string }>;
+- **`scope`** — the class or module that threw (e.g. `"RouterBridgeBase"`)
+- **`code`** — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
 
-const event: LoginEvent = {
-	type: "auth.login",
-	userId: "user-123",
-};
+```typescript
+import { PlayError } from "@xmachines/play";
+
+// Catching any @xmachines/* error:
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof PlayError) {
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	}
+}
 ```
 
+Package-specific subclasses are exported from each package's `./errors` subpath:
+
+```typescript
+import { RouterSyncError } from "@xmachines/play-router/errors";
+import { InvalidEventError, MissingRouteParamError } from "@xmachines/play-xstate/errors";
+import {
+	MissingCatalogError,
+	MissingComponentError,
+	RendererError,
+} from "@xmachines/play-react/errors";
+import { MissingCatalogError, MissingComponentError } from "@xmachines/play-solid/errors";
+import { VueRouterCorrectionError } from "@xmachines/play-vue-router/errors";
+```
+
+See each package's README for the full list of error classes and when they are thrown.
+
 ## Architecture Notes
 
 - Keep `@xmachines/play` as the base protocol boundary.
 - Keep actor implementation details in adapter packages such as `@xmachines/play-xstate`.
+- Never match on `.message` strings — always match on `instanceof` or `.code`.
 
 ## Related Packages
 
 - [@xmachines/play-actor](../play-actor/README.md)
 - [@xmachines/play-xstate](../play-xstate/README.md)
+- [@xmachines/play-router](../play-router/README.md)
 
 ## License
 
@@ -125,6 +160,10 @@ These protocols enforce the following invariants:
 4. **Signal-Only Reactivity**: All state changes flow through TC39 Signals
 5. **State-Driven Reset**: Navigation follows state machine transition rules
 
+## Classes
+
+- [PlayError](classes/PlayError.md)
+
 ## Type Aliases
 
 - [PlayEvent](type-aliases/PlayEvent.md)

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

@@ -0,0 +1,240 @@
+[Documentation](../../../README.md) / [@xmachines/play](../README.md) / PlayError
+
+# Class: PlayError
+
+Defined in: [packages/play/src/errors.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play/src/errors.ts#L63)
+
+Base class for all typed runtime errors thrown by `@xmachines/*` packages.
+
+`PlayError` gives every error two structured fields:
+
+- `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
+- `code` — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
+
+These fields let application code branch on error type without parsing `.message`
+strings, which change across releases.
+
+## Error codes
+
+Each `@xmachines/*` package exports its own typed subclasses from an
+`"./errors"` subpath:
+
+| Package                      | Import                              |
+| ---------------------------- | ----------------------------------- |
+| `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
+| `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
+| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
+| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
+
+`PlayError` itself is exported from the root `@xmachines/play` and is the base
+for all of those subclasses.
+
+## Catching errors by type
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof RouterSyncError) {
+		// err.scope === "RouterBridgeBase"
+		// err.code  === "PLAY_ROUTER_SYNC_FAILED"
+		// err.cause  — the original error that triggered the sync failure
+		reportToMonitoring(err);
+	} else if (err instanceof PlayError) {
+		// Any other @xmachines/* error
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	} else {
+		throw err; // Re-throw unknown errors
+	}
+}
+```
+
+## Extending PlayError
+
+```typescript
+import { PlayError } from "@xmachines/play";
+
+export class MyPackageError extends PlayError {
+	constructor(message: string, options?: ErrorOptions) {
+		super("MyScope", "MY_PACKAGE_ERROR_CODE", message, options);
+		this.name = "MyPackageError";
+	}
+}
+```
+
+## Extends
+
+- `Error`
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayError(
+   scope,
+   code,
+   message,
+   options?): PlayError;
+```
+
+Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play/src/errors.ts#L82)
+
+#### Parameters
+
+| Parameter  | Type           | Description                                                               |
+| ---------- | -------------- | ------------------------------------------------------------------------- |
+| `scope`    | `string`       | The class or module throwing this error.                                  |
+| `code`     | `string`       | Machine-readable error identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`).     |
+| `message`  | `string`       | Human-readable description. Do not match on this in code.                 |
+| `options?` | `ErrorOptions` | Standard `ErrorOptions`; pass `{ cause: originalError }` to chain errors. |
+
+#### Returns
+
+`PlayError`
+
+#### Overrides
+
+```ts
+Error.constructor;
+```
+
+## Properties
+
+| 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:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play/src/errors.ts#L74) |
+| <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:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play/src/errors.ts#L65) |
+| <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` | -                                                                                                                                  |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+```ts
+Error.captureStackTrace;
+```
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+```ts
+Error.isError;
+```
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+```ts
+Error.prepareStackTrace;
+```

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

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

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

@@ -30,6 +30,7 @@ npm install @xmachines/play-actor
 - `AbstractActor`
 - `Routable` (type)
 - `Viewable` (type)
+- `ViewMetadata` (type)
 
 **Peer dependencies:**
 
@@ -45,7 +46,7 @@ npm install @xmachines/play-actor
 import { definePlayer } from "@xmachines/play-xstate";
 
 // definePlayer returns PlayerActor (extends AbstractActor)
-const createPlayer = definePlayer({ machine, catalog });
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
@@ -73,8 +74,7 @@ Implement `Routable` to add routing support:
 
 Implement `Viewable` to add view rendering support:
 
-- `currentView: Signal.State<ViewMetadata | null>` - Current UI structure (updated at state entry)
-- `catalog: Record<string, unknown>` - Component catalog
+- `currentView: Signal.State<ViewMetadata | null>` - Current view spec (updated on every state transition). `ViewMetadata` has the shape `{ component: string; spec: Spec }` where `spec` is a `@json-render/core` spec object driving the renderer.
 
 **Inherited from XState Actor:**
 
@@ -86,39 +86,39 @@ Implement `Viewable` to add view rendering support:
 **Example implementation pattern:**
 
 ```typescript
-import { AbstractActor, type Routable, type Viewable, type ViewMetadata } from "@xmachines/play-actor";
+import {
+	AbstractActor,
+	type Routable,
+	type Viewable,
+	type ViewMetadata,
+} 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
+	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 UI structure — Signal.State, updated at state entry (not computed)
-    currentView = new Signal.State<ViewMetadata | null>(null);
-
-    // Viewable: component catalog
-    catalog: Record<string, unknown>;
-
-    constructor(logic: TLogic, catalog: Record<string, unknown>) {
-        super(logic);
-        this.catalog = catalog;
-
-        // Subscribe to XState transitions and update signals
-        this.subscribe((snapshot) => {
-            this.state.set(snapshot as AnyMachineSnapshot);
-            // Update currentView based on snapshot meta...
-        });
-    }
-}
+	// 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<ViewMetadata | 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...
+		});
+	}
 }
 ```
 
@@ -242,6 +242,7 @@ reactive signals for Infrastructure layer communication.
 
 ## Interfaces
 
+- [PlaySpec](interfaces/PlaySpec.md)
 - [Routable](interfaces/Routable.md)
 - [Viewable](interfaces/Viewable.md)
 - [ViewMetadata](interfaces/ViewMetadata.md)

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

@@ -1,8 +1,8 @@
 [Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / AbstractActor
 
-# Abstract Class: AbstractActor\<TLogic\>
+# Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-actor/src/abstract-actor.ts#L187)
+Defined in: [packages/play-actor/src/abstract-actor.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-actor/src/abstract-actor.ts#L231)
 
 Abstract base class for Play Architecture actors.
 
@@ -23,7 +23,7 @@ Concrete implementations created by @xmachines/play-xstate adapter.
 
 ## Examples
 
-Simple actor (no routing, no view)
+Simple actor (no routing, no view) - single type param, backward compat
 
 ```typescript
 class SimpleActor extends AbstractActor<AnyActorLogic> {
@@ -32,24 +32,24 @@ class SimpleActor extends AbstractActor<AnyActorLogic> {
 }
 ```
 
-Routable actor
+Typed event actor - two type params
 
 ```typescript
-class RoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
   state = new Signal.State({...});
-  currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-  send(event) { ... }
+  send(event: AuthEvent) { ... }
 }
 ```
 
 Full-featured actor (routing + view)
 
 ```typescript
-class PlayerActor extends AbstractActor<AnyActorLogic> implements Routable, Viewable {
+class PlayerActor extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
+  implements Routable, Viewable {
   state = new Signal.State({...});
   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
   currentView = new Signal.State(null);
-  catalog = {};
   send(event) { ... }
 }
 ```
@@ -70,16 +70,17 @@ class PlayerActor extends AbstractActor<AnyActorLogic> implements Routable, View
 
 ## Type Parameters
 
-| Type Parameter                                                                           | Description                                                                                                                                                                                                                                                                                     |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | XState actor logic type (maintains type safety) Invariant: Actor Authority - Actor is the sole source of truth for state transitions. Invariant: Signal-Only Reactivity - Infrastructure observes via TC39 Signals. Invariant: Passive Infrastructure - Infrastructure reflects, never decides. |
+| Type Parameter                                                                           | Default type                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type (maintains type safety)                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type union that this actor's send() accepts. Defaults to `EventObject` (`{ type: string }`) for backward compatibility. Use `EventFromLogic<TMachine>` from xstate to infer the exact event union from a state machine (e.g., in `PlayerActor`). Invariant: Actor Authority - Actor is the sole source of truth for state transitions. Invariant: Signal-Only Reactivity - Infrastructure observes via TC39 Signals. Invariant: Passive Infrastructure - Infrastructure reflects, never decides. |
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new AbstractActor<TLogic>(logic, options?): AbstractActor<TLogic>;
+new AbstractActor<TLogic, TEvent>(logic, options?): AbstractActor<TLogic, TEvent>;
 ```
 
 Creates a new actor instance for the given logic with the provided options,
@@ -94,7 +95,7 @@ if any.
 
 #### Returns
 
-`AbstractActor`\<`TLogic`\>
+`AbstractActor`\<`TLogic`, `TEvent`\>
 
 #### Inherited from
 
@@ -114,7 +115,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. Typed as `Signal.State<unknown>` at the abstract level; concrete implementations narrow this to the actual snapshot type (e.g., `Signal.State<AnyMachineSnapshot>` in `@xmachines/play-xstate`'s `PlayerActor`). Infrastructure observes this signal to react to state changes without directly coupling to the Actor's internal state machine implementation. **Example** `// Infrastructure observes state signal const watcher = new Signal.subtle.Watcher(() => { console.log('Actor state changed:', actor.state.get()); }); watcher.watch(actor.state);` | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-actor/src/abstract-actor.ts#L207) |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Typed as `Signal.State<unknown>` at the abstract level; concrete implementations narrow this to the actual snapshot type (e.g., `Signal.State<AnyMachineSnapshot>` in `@xmachines/play-xstate`'s `PlayerActor`). Infrastructure observes this signal to react to state changes without directly coupling to the Actor's internal state machine implementation. **Example** `// Infrastructure observes state signal const watcher = new Signal.subtle.Watcher(() => { console.log('Actor state changed:', actor.state.get()); }); watcher.watch(actor.state);` | -                 | [packages/play-actor/src/abstract-actor.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-actor/src/abstract-actor.ts#L254) |
 | <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`  | -                                                                                                                                                                |
 
@@ -275,7 +276,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-actor/src/abstract-actor.ts#L231)
+Defined in: [packages/play-actor/src/abstract-actor.ts:278](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-actor/src/abstract-actor.ts#L278)
 
 Send event to Actor
 
@@ -285,9 +286,9 @@ each event is valid from the current state.
 
 #### Parameters
 
-| Parameter | Type                                       | Description                                                                                                                                  |
-| --------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `event`   | `object` & `Record`\<`string`, `unknown`\> | Event object with type property (e.g., PlayEvent, PlayRouteEvent) Invariant: Actor Authority - Only Actor decides whether an event is valid. |
+| Parameter | Type     | Description                                                                                                                                  |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `event`   | `TEvent` | Event object with type property (e.g., PlayEvent, PlayRouteEvent) Invariant: Actor Authority - Only Actor decides whether an event is valid. |
 
 #### Returns
 

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

@@ -0,0 +1,37 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / PlaySpec
+
+# Interface: PlaySpec
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-actor/src/abstract-actor.ts#L112)
+
+XMachines extension of `@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.
+
+## Example
+
+```ts
+spec: {
+  root: "root",
+  contextProps: ["username"],   // expose context.username as a prop slot
+  elements: {
+    root: { type: "Dashboard", props: { username: undefined }, children: [] },
+  },
+}
+```
+
+## Extends
+
+- `Spec`
+
+## Properties
+
+| Property                                           | Type                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                          | Inherited from  | Defined in                                                                                                                                                       |
+| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-contextprops"></a> `contextProps?` | `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`. `null` and `undefined` context values are skipped. URL route params (from `context.routeParams`) take priority over `contextProps` values; explicit non-`undefined` spec props always take priority over both. | -               | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-actor/src/abstract-actor.ts#L122) |
+| <a id="property-elements"></a> `elements`          | `Record`\<`string`, `UIElement`\> | Flat map of elements by key                                                                                                                                                                                                                                                                                                                                                                                                          | `Spec.elements` | -                                                                                                                                                                |
+| <a id="property-root"></a> `root`                  | `string`                          | Root element key                                                                                                                                                                                                                                                                                                                                                                                                                     | `Spec.root`     | -                                                                                                                                                                |
+| <a id="property-state"></a> `state?`               | `Record`\<`string`, `unknown`\>   | Optional initial state to seed the state model. Components using statePath will read from / write to this state.                                                                                                                                                                                                                                                                                                                     | `Spec.state`    | -                                                                                                                                                                |