@xmachines/play-actor 1.0.0-beta.5 → 1.0.0-beta.51

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,218 +1,190 @@
-# @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 [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.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)).
+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)
+```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, catalog });
-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<any>` - Reactive snapshot of current state
-- `currentRoute: Signal.Computed<string | null>` - Derived navigation path
-- `currentView: Signal.Computed<Record<string, any> | null>` - Derived UI structure
-- `catalog: any` - Component catalog
+class MyActor extends AbstractActor<AnyActorLogic> {
+	// Required: reactive state signal
+	state = new Signal.State({});
 
-**Inherited from XState Actor:**
+	// Required: typed event dispatch
+	send = (event: { type: string }) => {
+		/* dispatch to XState */
+	};
+}
+```
 
-- `send(event: PlayEvent): void` - Send event to actor
-- `start(): void` - Start the actor
-- `stop(): void` - Stop the actor
-- `getSnapshot(): Snapshot` - Get current XState snapshot
+With a typed event union:
 
-**Example implementation pattern:**
+```ts
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
 
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
+class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
+	state = new Signal.State({ isAuthenticated: false, username: null });
 
-class PlayerActor<TLogic extends AnyActorLogic> extends AbstractActor<TLogic> {
-	// Implement required signal properties
-	state = new Signal.State(this.internalActor.getSnapshot());
+	send = (event: AuthEvent) => {
+		/* dispatch */
+	};
+}
+```
 
-	currentRoute = new Signal.Computed(() => {
-		const snapshot = this.state.get();
-		return deriveRoute(snapshot);
-	});
+### `typedSpec<TContext>(spec)`
 
-	currentView = new Signal.Computed(() => {
-		const snapshot = this.state.get();
-		return snapshot.meta?.view ?? null;
-	});
+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.
 
-	catalog = this.config.catalog;
+```ts
+import { typedSpec } from "@xmachines/play-actor";
 
-	// Internal XState actor
-	private internalActor: Actor<TLogic>;
+interface DashboardCtx {
+  username: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+}
 
-	constructor(logic: TLogic, catalog: any) {
-		super(logic);
-		this.internalActor = createActor(logic);
+// 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: [] },
+    },
+  }),
+}
+```
 
-		// Subscribe to XState transitions
-		this.internalActor.subscribe((snapshot) => {
-			this.state.set(snapshot); // Update signal
-		});
-	}
+### `PlaySpec`
 
-	override start(): void {
-		this.internalActor.start();
-	}
+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.
 
-	override stop(): void {
-		this.internalActor.stop();
-	}
+```ts
+import type { PlaySpec } from "@xmachines/play-actor";
 
-	override send(event: PlayEvent): void {
-		this.internalActor.send(event as any);
-	}
-}
+const spec: PlaySpec = {
+	root: "root",
+	contextProps: ["username"], // only these keys are exposed to components
+	elements: {
+		root: { type: "Profile", props: { username: undefined }, children: [] },
+	},
+};
 ```
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-actor)
+### `Routable`
 
-## Examples
+Interface for actors that support routing.
 
-### Infrastructure Observing Signals
-
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
+```ts
+import type { Routable } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
 
-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);
+// 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 */
+	};
 }
 ```
 
-### Browser Navigation Sending Events
-
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
+### `Viewable`
 
-function connectBrowserNavigation(actor: AbstractActor<any>) {
-	const handlePopstate = () => {
-		const path = window.location.pathname;
+Interface for actors that expose a renderable view signal.
 
-		// 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 { Viewable } from "@xmachines/play-actor";
+import type { PlaySpec } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
 
-	return () => {
-		window.removeEventListener("popstate", handlePopstate);
-	};
-}
+// currentView carries PlaySpec | null
+const signal = new Signal.State<PlaySpec | null>(null);
+const viewable: Viewable = { currentView: signal };
 ```
 
-## Architecture
+### `BaseActorProviderProps<TRegistry>`
 
-This base class enforces three architectural invariants:
+Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
 
-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 { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@json-render/react";
 
-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)
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
 
-3. **Passive Infrastructure (INV-04):**
-    - Infrastructure reflects actor state (via signals)
-    - Infrastructure never decides transitions
-    - Browser/router events sent as commands to actor
+### `BaseViewContextValue<TRegistry>`
 
-## XState Compatibility
+Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
 
-`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+## Testing
 
-- **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
+Run the test suite for this package in isolation:
 
-**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+```bash
+# From the package directory
+npm test
 
-## Related Packages
+# From the monorepo root (workspace-scoped)
+npm test -w packages/play-actor
 
-- **[@xmachines/play-xstate](../play-xstate)** - Concrete PlayerActor implementation
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
-- **[@xmachines/play](../play)** - Protocol types (PlayEvent, RouterBridge)
+# Watch mode
+npm run test:watch -w packages/play-actor
+```
 
-## License
+## Requirements
 
-MIT
+- **Node.js** `>=22.0.0`
+- **TypeScript** `>=5.7` (strict mode)
+- **ESM only** — `"type": "module"`

package/dist/abstract-actor.d.ts

@@ -16,189 +16,169 @@
  *
  * @packageDocumentation
  */
-import { Actor, type AnyActorLogic } from "xstate";
+import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type { Signal } from "@xmachines/play-signals";
+import type { Spec, StateStore, RenderErrorHandler, ActionHandler } from "@json-render/core";
 /**
  * Optional capability: Routing support
+ */
+export interface Routable {
+    readonly currentRoute: Signal.Computed<string | null>;
+    readonly initialRoute: string | null;
+}
+/**
+ * XMachines extension of `@json-render/core` `Spec`.
  *
- * Actors implementing this interface can derive a route from their state.
- * Router adapters observe the currentRoute signal to sync browser URLs.
+ * 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
- * ```typescript
- * class MyActor extends AbstractActor implements Routable {
- *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
- * }
- *
- * // Router requires Routable
- * function connectRouter<T extends AbstractActor & Routable>(actor: T) {
- *   watcher.watch(actor.currentRoute);
- * }
- * ```
+ * Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps`
+ * entries against your machine's context type at compile time.
  */
-export interface Routable {
+export interface PlaySpec extends Spec {
     /**
-     * Current route signal
-     *
-     * Computed signal derived from state machine. Infrastructure observes to sync browser URL.
-     *
-     * Invariant: Passive Infrastructure - Infrastructure reflects route, never decides.
+     * 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`.
      *
-     * @example
-     * ```typescript
-     * const watcher = new Signal.subtle.Watcher(() => {
-     *   const route = actor.currentRoute.get();
-     *   console.log('Route changed:', route);
-     * });
-     * watcher.watch(actor.currentRoute);
-     * ```
+     * Use `typedSpec<TContext>(...)` to constrain entries to `keyof TContext & string`.
      */
-    readonly currentRoute: Signal.Computed<string | null>;
+    readonly contextProps?: readonly string[];
 }
 /**
- * Optional capability: View rendering support
+ * 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.
+ *
+ * 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.
  *
- * Actors implementing this interface can derive view structures from their state.
- * Renderers observe the currentView signal to update the UI.
+ * At runtime this is a no-op — the spec object is returned unchanged.
  *
  * @example
- * ```typescript
- * class MyActor extends AbstractActor implements Viewable {
- *   currentView = new Signal.State(null);
- *   catalog = { HomePage: HomeComponent };
+ * ```ts
+ * interface DashboardCtx {
+ *   username: string;
+ *   params: Record<string, string>;
+ *   query: Record<string, string>;
  * }
  *
- * // Renderer requires Viewable
- * function renderView<T extends AbstractActor & Viewable>(actor: T) {
- *   const view = actor.currentView.get();
- *   return catalog[view.component];
+ * meta: {
+ *   view: typedSpec<DashboardCtx>({
+ *     root: "root",
+ *     contextProps: ["username"],    // ✓ key of DashboardCtx
+ *     // contextProps: ["usernaem"], // ✗ compile error
+ *     elements: { root: { type: "Dashboard", props: {}, children: [] } },
+ *   }),
  * }
  * ```
  */
+export declare function typedSpec<TContext extends object>(spec: Omit<PlaySpec, "contextProps"> & {
+    readonly contextProps?: readonly (keyof TContext & string)[];
+}): PlaySpec;
+/**
+ * Actor capability for exposing renderable view state.
+ *
+ * `Viewable` marks actors that publish a `currentView` signal.
+ * Renderers such as `PlayRenderer` consume this contract to resolve the
+ * current view description into concrete UI without embedding view logic inside the
+ * framework adapter.
+ */
 export interface Viewable {
     /**
-     * Current view signal
-     *
-     * State signal containing UI structure schema from meta.view. Infrastructure renders view.
-     *
-     * Invariant: Logic-Driven UI - View structure is defined by business logic, not JSX.
-     *
-     * @example
-     * ```typescript
-     * const watcher = new Signal.subtle.Watcher(() => {
-     *   const view = actor.currentView.get();
-     *   console.log('View changed:', view);
-     * });
-     * watcher.watch(actor.currentView);
-     * ```
-     */
-    readonly currentView: Signal.State<any>;
-    /**
-     * Component catalog for view resolution
+     * Current view signal. Contains the json-render PlaySpec for the current machine
+     * state, or null when no view is active.
      *
-     * Maps component names to actual component implementations.
-     * Used by renderers to resolve view.component to actual UI components.
+     * Infrastructure renders view — Logic-Driven UI invariant.
      */
-    readonly catalog: any;
+    readonly currentView: Signal.State<PlaySpec | null>;
 }
 /**
- * Abstract base class for Play Architecture actors.
- *
- * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
- * while enforcing minimal signal protocol for Actor ↔ Infrastructure communication.
- *
- * The core protocol contains only:
- * - state: Reactive state snapshot
- * - send: Event dispatch method
+ * Framework-agnostic base for every framework's `ViewContextValue`.
  *
- * Optional capabilities (routing, view rendering) are provided via interfaces:
- * - Implement Routable for routing support
- * - Implement Viewable for view rendering support
+ * Holds the three fields that are identical across React, Vue, Solid, and Svelte.
+ * `registry` is framework-specific (each framework has its own `ComponentRegistry`
+ * type) so it is typed via `TRegistry` — the same generic used in `BaseActorProviderProps`.
  *
- * Concrete implementations created by @xmachines/play-xstate adapter.
+ * @typeParam TRegistry - The framework's component registry type (e.g. `ComponentRegistry` from `@json-render/react`).
+ */
+export interface BaseViewContextValue<TRegistry extends object> {
+    /** The current PlaySpec to render. */
+    spec: PlaySpec;
+    /** Action handlers resolved against the live StateStore. */
+    handlers: Record<string, ActionHandler>;
+    /** Component registry from registryResult.registry. */
+    registry: TRegistry;
+    /** The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. */
+    store: StateStore;
+}
+/**
+ * Framework-agnostic base props shared by every `ActorProvider` implementation
+ * (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
+ * `DefineRegistryResult` type; `RenderErrorHandler` is sourced from
+ * `@json-render/core` so no second generic is needed.
  *
- * @typeParam TLogic - XState actor logic type (maintains type safety)
+ * Framework packages extend this with their `fallback`, `onError`, and `children` fields.
  *
- * 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.
+ * @typeParam TRegistry - The framework's `DefineRegistryResult` type.
  *
  * @example
- * Simple actor (no routing, no view)
- * ```typescript
- * class SimpleActor extends AbstractActor<any> {
- *   state = new Signal.State({...});
- *   send(event) { ... }
- * }
- * ```
+ * ```ts
+ * import type { BaseActorProviderProps } from "@xmachines/play-actor";
+ * import type { DefineRegistryResult } from "@json-render/react";
  *
- * @example
- * Routable actor
- * ```typescript
- * class RoutableActor extends AbstractActor<any> implements Routable {
- *   state = new Signal.State({...});
- *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
- *   send(event) { ... }
+ * interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+ *   fallback?: React.ReactNode;
+ *   children: React.ReactNode;
  * }
  * ```
+ */
+export interface BaseActorProviderProps<TRegistry extends {
+    registry: object;
+    handlers: (...args: never[]) => unknown;
+}> {
+    /** Actor instance with currentView signal (requires Viewable capability). */
+    actor: AbstractActor<AnyActorLogic> & Viewable;
+    /** Full result from defineRegistry() — contains the component registry and action handlers factory. */
+    registryResult: TRegistry;
+    /**
+     * 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.
+     */
+    store?: StateStore;
+    /**
+     * Called when an individual catalog component throws during render.
+     * Takes precedence over any onRenderError set via defineRegistry.
+     */
+    onRenderError?: RenderErrorHandler;
+}
+/**
+ * Abstract base class for Play Architecture actors.
  *
- * @example
- * Full-featured actor (routing + view)
- * ```typescript
- * class PlayerActor extends AbstractActor<any> implements Routable, Viewable {
- *   state = new Signal.State({...});
- *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
- *   currentView = new Signal.State(null);
- *   catalog = {};
- *   send(event) { ... }
- * }
- * ```
+ * Provides signal-driven state observation that integrates with XState ecosystem
+ * tooling (devtools, inspection) while exposing reactive signals for
+ * Infrastructure layer communication.
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol | RFC Play v1 Section 5.3}
- * @see {@link Routable} for routing capability
- * @see {@link Viewable} for view rendering capability
+ * @typeParam TLogic - XState actor logic type
+ * @typeParam TEvent - Event type constraint (defaults to EventObject)
  */
-export declare abstract class AbstractActor<TLogic extends AnyActorLogic> extends Actor<TLogic> {
+export declare abstract class AbstractActor<TLogic extends AnyActorLogic, TEvent extends EventObject = EventObject> extends Actor<TLogic> {
     /**
      * 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.
-     *
-     * @example
-     * ```typescript
-     * // Infrastructure observes state signal
-     * const watcher = new Signal.subtle.Watcher(() => {
-     *   console.log('Actor state changed:', actor.state.get());
-     * });
-     * watcher.watch(actor.state);
-     * ```
+     * directly coupling to the actor's internal state machine implementation.
      */
-    abstract state: Signal.State<any>;
+    abstract state: Signal.State<unknown>;
     /**
-     * Send event to Actor
-     *
-     * Infrastructure forwards user intents (navigation, domain events, custom events)
-     * as events to the Actor. The Actor's state machine guards determine whether
-     * each event is valid from the current state.
-     *
-     * @param event - Event object with type property (e.g., PlayEvent, PlayRouteEvent)
-     *
-     * Invariant: Actor Authority - Only Actor decides whether an event is valid.
-     *
-     * @example
-     * ```typescript
-     * // Infrastructure forwards user intent
-     * actor.send({ type: 'auth.login', userId: '123' });
-     * // Actor's guards determine if event is allowed
-     * ```
+     * Send event to Actor.
      *
-     * @remarks
-     * Accepts any event object with a type property. Core events (PlayEvent) are in
-     * @xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
+     * Constrained to TEvent for type safety in concrete implementations.
      */
-    abstract send(event: {
-        readonly type: string;
-    } & Record<string, any>): void;
+    abstract send(event: TEvent): void;
 }
 //# sourceMappingURL=abstract-actor.d.ts.map

package/dist/abstract-actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,8BAAsB,aAAa,CAAC,MAAM,SAAS,aAAa,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtF;;;;;;;;;;;;;;OAcG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;OAqBG;aACsB,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;CAC3F"}
+{"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,QAAQ,SAAS,MAAM,EAChD,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,GAAG;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7D,GACC,QAAQ,CAEV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,uDAAuD;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,gHAAgH;IAChH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,6EAA6E;IAC7E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uGAAuG;IACvG,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;OAIG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}

package/dist/abstract-actor.js

@@ -18,61 +18,46 @@
  */
 import { Actor } from "xstate";
 /**
- * Abstract base class for Play Architecture actors.
- *
- * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
- * while enforcing minimal signal protocol for Actor ↔ Infrastructure communication.
- *
- * The core protocol contains only:
- * - state: Reactive state snapshot
- * - send: Event dispatch method
- *
- * Optional capabilities (routing, view rendering) are provided via interfaces:
- * - Implement Routable for routing support
- * - Implement Viewable for view rendering support
+ * 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.
  *
- * Concrete implementations created by @xmachines/play-xstate adapter.
+ * 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.
  *
- * @typeParam TLogic - 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.
+ * At runtime this is a no-op — the spec object is returned unchanged.
  *
  * @example
- * Simple actor (no routing, no view)
- * ```typescript
- * class SimpleActor extends AbstractActor<any> {
- *   state = new Signal.State({...});
- *   send(event) { ... }
+ * ```ts
+ * interface DashboardCtx {
+ *   username: string;
+ *   params: Record<string, string>;
+ *   query: Record<string, string>;
  * }
- * ```
  *
- * @example
- * Routable actor
- * ```typescript
- * class RoutableActor extends AbstractActor<any> implements Routable {
- *   state = new Signal.State({...});
- *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
- *   send(event) { ... }
+ * meta: {
+ *   view: typedSpec<DashboardCtx>({
+ *     root: "root",
+ *     contextProps: ["username"],    // ✓ key of DashboardCtx
+ *     // contextProps: ["usernaem"], // ✗ compile error
+ *     elements: { root: { type: "Dashboard", props: {}, children: [] } },
+ *   }),
  * }
  * ```
+ */
+export function typedSpec(spec) {
+    return spec;
+}
+/**
+ * Abstract base class for Play Architecture actors.
  *
- * @example
- * Full-featured actor (routing + view)
- * ```typescript
- * class PlayerActor extends AbstractActor<any> implements Routable, Viewable {
- *   state = new Signal.State({...});
- *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
- *   currentView = new Signal.State(null);
- *   catalog = {};
- *   send(event) { ... }
- * }
- * ```
+ * Provides signal-driven state observation that integrates with XState ecosystem
+ * tooling (devtools, inspection) while exposing reactive signals for
+ * Infrastructure layer communication.
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol | RFC Play v1 Section 5.3}
- * @see {@link Routable} for routing capability
- * @see {@link Viewable} for view rendering capability
+ * @typeParam TLogic - XState actor logic type
+ * @typeParam TEvent - Event type constraint (defaults to EventObject)
  */
 export class AbstractActor extends Actor {
 }

package/dist/abstract-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAsB,MAAM,QAAQ,CAAC;AAyFnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,OAAgB,aAA4C,SAAQ,KAAa;CAyCtF"}
+{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAkCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAiFD;;;;;;;;;GASG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAetB"}

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  * reactive signals for Infrastructure layer communication.
  *
  * @packageDocumentation
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol | RFC Play v1 Section 5.3}
+ * @see [Play RFC](../../docs/rfc/play.md)
  */
-export { AbstractActor, type Routable, type Viewable } from "./abstract-actor.js";
+export { AbstractActor, typedSpec, type Routable, type Viewable, type PlaySpec, type BaseActorProviderProps, type BaseViewContextValue, } from "./abstract-actor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -13,7 +13,7 @@
  * reactive signals for Infrastructure layer communication.
  *
  * @packageDocumentation
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol | RFC Play v1 Section 5.3}
+ * @see [Play RFC](../../docs/rfc/play.md)
  */
-export { AbstractActor } from "./abstract-actor.js";
+export { AbstractActor, typedSpec, } from "./abstract-actor.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAgC,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.51",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -20,6 +20,7 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
@@ -29,26 +30,32 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-*",
+    "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "@json-render/core": "^0.18.0"
+  },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.5",
-    "xstate": "^5.28.0"
+    "@types/node": "^25.6.0",
+    "@xmachines/shared": "1.0.0-beta.51",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
+    "vitest": "^4.1.5",
+    "xstate": "^5.31.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.5",
-    "@xmachines/play-signals": "1.0.0-beta.5",
-    "xstate": "^5.28.0"
+    "@xmachines/play": "1.0.0-beta.51",
+    "@xmachines/play-signals": "1.0.0-beta.51",
+    "xstate": "^5.31.0"
   },
   "engines": {
     "node": ">=22.0.0"
-  }
+  },
+  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds and tests. peerDependencies declares the consumer version constraint. Both are pinned to ^5.30.0 to prevent drift."
 }