@xmachines/play-actor 1.0.0-beta.4 → 1.0.0-beta.41

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

@@ -8,7 +8,7 @@ Foundation for all actor implementations, enforcing XState compatibility and rea
 
 `@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:
+Per [Play RFC](../docs/rfc/play.md), this package implements:
 
 - **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
@@ -28,10 +28,14 @@ npm install @xmachines/play-actor
 - `AbstractActor`
 - `Routable` (type)
 - `Viewable` (type)
+- `PlaySpec` (type)
+- `typedSpec`
+- `BaseActorProviderProps` (type)
+- `BaseViewContextValue` (type)
 
 **Peer dependencies:**
 
-- `xstate` ^5.0.0 - State machine runtime (XState compatibility)
+- `xstate` ^5.0.0 — State machine runtime (XState compatibility)
 - `@xmachines/play-signals` - TC39 Signals primitives
 - `@xmachines/play` - Protocol types (PlayEvent, etc.)
 
@@ -43,7 +47,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();
 
@@ -61,69 +65,59 @@ Abstract base class defining signal protocol:
 
 **Abstract Properties (must implement):**
 
-- `state: Signal.State<any>` - Reactive snapshot of current state
+- `state: Signal.State<unknown>` - Reactive snapshot of current state
+
+**Optional capability interfaces:**
+
+Implement `Routable` to add routing support:
+
 - `currentRoute: Signal.Computed<string | null>` - Derived navigation path
-- `currentView: Signal.Computed<Record<string, any> | null>` - Derived UI structure
-- `catalog: any` - Component catalog
+
+Implement `Viewable` to add view rendering support:
+
+- `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.
 
 **Inherited from XState Actor:**
 
-- `send(event: PlayEvent): void` - Send event to actor
+- `send(event): void` - Send event to actor
 - `start(): void` - Start the actor
 - `stop(): void` - Stop the actor
-- `getSnapshot(): Snapshot` - Get current XState snapshot
+- `getSnapshot()` - Get current XState snapshot (typed as `SnapshotFrom<TLogic>`)
 
 **Example implementation pattern:**
 
 ```typescript
-import { AbstractActor } from "@xmachines/play-actor";
+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> {
-	// Implement required signal properties
-	state = new Signal.State(this.internalActor.getSnapshot());
+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(() => {
-		const snapshot = this.state.get();
-		return deriveRoute(snapshot);
-	});
-
-	currentView = new Signal.Computed(() => {
-		const snapshot = this.state.get();
-		return snapshot.meta?.view ?? null;
+		return deriveRoute(this.state.get());
 	});
 
-	catalog = this.config.catalog;
-
-	// Internal XState actor
-	private internalActor: Actor<TLogic>;
+	// Viewable: current view spec — Signal.State, updated on every state transition
+	currentView = new Signal.State<PlaySpec | null>(null);
 
-	constructor(logic: TLogic, catalog: any) {
+	constructor(logic: TLogic) {
 		super(logic);
-		this.internalActor = createActor(logic);
 
-		// Subscribe to XState transitions
-		this.internalActor.subscribe((snapshot) => {
-			this.state.set(snapshot); // Update signal
+		// 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...
 		});
 	}
-
-	override start(): void {
-		this.internalActor.start();
-	}
-
-	override stop(): void {
-		this.internalActor.stop();
-	}
-
-	override send(event: PlayEvent): void {
-		this.internalActor.send(event as any);
-	}
 }
 ```
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-actor)
-
 ## Examples
 
 ### Infrastructure Observing Signals
@@ -215,4 +209,7 @@ This base class enforces three architectural invariants:
 
 ## License
 
-MIT
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.

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.4",
+  "version": "1.0.0-beta.41",
   "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.4",
-    "xstate": "^5.28.0"
+    "@types/node": "^25.6.0",
+    "@xmachines/shared": "1.0.0-beta.41",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
+    "vitest": "^4.1.4",
+    "xstate": "^5.30.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.4",
-    "@xmachines/play-signals": "1.0.0-beta.4",
-    "xstate": "^5.28.0"
+    "@xmachines/play": "1.0.0-beta.41",
+    "@xmachines/play-signals": "1.0.0-beta.41",
+    "xstate": "^5.30.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."
 }