@xmachines/play-actor 1.0.0-beta.16 → 1.0.0-beta.18

package/README.md

@@ -28,6 +28,7 @@ npm install @xmachines/play-actor
 - `AbstractActor`
 - `Routable` (type)
 - `Viewable` (type)
+- `ViewMetadata` (type)
 
 **Peer dependencies:**
 
@@ -43,7 +44,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();
 
@@ -71,8 +72,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:**
 
@@ -84,39 +84,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...
+		});
+	}
 }
 ```
 

package/dist/abstract-actor.d.ts

@@ -16,8 +16,9 @@
  *
  * @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 } from "@json-render/core";
 /**
  * Optional capability: Routing support
  *
@@ -54,6 +55,18 @@ export interface Routable {
      * ```
      */
     readonly currentRoute: Signal.Computed<string | null>;
+    /**
+     * The route derived from the machine's **initial** state — fixed at construction
+     * and never changes, even after `start()` with a restored snapshot.
+     *
+     * Router bridges use this to distinguish a deep-link (browser URL differs from
+     * the initial route because the user navigated there) from a restore (browser is
+     * at the machine's default starting URL while the actor was restored to a
+     * different route from a snapshot).
+     *
+     * `null` when the machine's initial state has no `meta.route`.
+     */
+    readonly initialRoute: string | null;
 }
 /**
  * Optional capability: View rendering support
@@ -65,41 +78,75 @@ export interface Routable {
  * ```typescript
  * class MyActor extends AbstractActor implements Viewable {
  *   currentView = new Signal.State(null);
- *   catalog = { HomePage: HomeComponent };
  * }
  *
  * // Renderer requires Viewable
  * function renderView<T extends AbstractActor & Viewable>(actor: T) {
  *   const view = actor.currentView.get();
- *   return catalog[view.component];
+ *   // view.component is the component name; view.spec is the json-render spec
+ * }
+ * ```
+ */
+/**
+ * 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: [] },
+ *   },
  * }
  * ```
  */
+export interface PlaySpec extends Spec {
+    /**
+     * 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.
+     */
+    contextProps?: string[];
+}
 /**
  * View metadata for rendering
  *
- * Describes the component to be rendered and the props to pass to it.
+ * Describes the component to be rendered and the json-render Spec to use.
  * Used by PlayRenderer to dynamically render UI based on actor state.
  */
 export interface ViewMetadata {
-    /** Name of the component to render from the catalog */
+    /** Root element type name (for diagnostics and component resolution) */
     component: string;
-    /** Props to pass to the component */
-    props: Record<string, unknown>;
+    /**
+     * XMachines view spec — extends `@json-render/core` Spec with `contextProps`
+     * for explicit context field exposure.
+     */
+    spec: PlaySpec;
 }
 /**
  * Actor capability for exposing renderable view state.
  *
- * `Viewable` marks actors that publish a `currentView` signal plus a component
- * catalog. Renderers such as `PlayRenderer` consume this contract to resolve the
+ * `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.
+ * framework adapter. Component lookup is handled by the json-render registry
+ * passed to PlayRenderer, not stored on the actor.
  */
 export interface Viewable {
     /**
      * Current view signal
      *
-     * State signal containing UI structure schema from meta.view. Infrastructure renders view.
+     * State signal containing view.component and view.spec from meta.view. Infrastructure renders view.
      *
      * Invariant: Logic-Driven UI - View structure is defined by business logic, not JSX.
      *
@@ -107,19 +154,12 @@ export interface Viewable {
      * ```typescript
      * const watcher = new Signal.subtle.Watcher(() => {
      *   const view = actor.currentView.get();
-     *   console.log('View changed:', view);
+     *   console.log('View changed:', view.component, view.spec);
      * });
      * watcher.watch(actor.currentView);
      * ```
      */
     readonly currentView: Signal.State<ViewMetadata | null>;
-    /**
-     * Component catalog for view resolution
-     *
-     * Maps component names to actual component implementations.
-     * Used by renderers to resolve view.component to actual UI components.
-     */
-    readonly catalog: Record<string, unknown>;
 }
 /**
  * Abstract base class for Play Architecture actors.
@@ -138,13 +178,17 @@ export interface Viewable {
  * Concrete implementations created by @xmachines/play-xstate adapter.
  *
  * @typeParam TLogic - XState actor logic type (maintains type safety)
+ * @typeParam TEvent - 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.
  *
  * @example
- * Simple actor (no routing, no view)
+ * Simple actor (no routing, no view) - single type param, backward compat
  * ```typescript
  * class SimpleActor extends AbstractActor<AnyActorLogic> {
  *   state = new Signal.State({...});
@@ -153,23 +197,23 @@ export interface Viewable {
  * ```
  *
  * @example
- * 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) { ... }
  * }
  * ```
  *
  * @example
  * 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) { ... }
  * }
  * ```
@@ -178,7 +222,7 @@ export interface Viewable {
  * @see {@link Routable} for routing capability
  * @see {@link Viewable} for view rendering capability
  */
-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.
      *
@@ -221,8 +265,6 @@ export declare abstract class AbstractActor<TLogic extends AnyActorLogic> extend
      * Accepts any event object with a type property. Core events (PlayEvent) are in
      * @xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
      */
-    abstract send(event: {
-        readonly type: string;
-    } & Record<string, unknown>): 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;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAExD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,8BAAsB,aAAa,CAAC,MAAM,SAAS,aAAa,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtF;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;OAqBG;aACsB,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAC/F"}
+{"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,MAAM,mBAAmB,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;OAqBG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}

package/dist/abstract-actor.js

@@ -34,13 +34,17 @@ import { Actor } from "xstate";
  * Concrete implementations created by @xmachines/play-xstate adapter.
  *
  * @typeParam TLogic - XState actor logic type (maintains type safety)
+ * @typeParam TEvent - 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.
  *
  * @example
- * Simple actor (no routing, no view)
+ * Simple actor (no routing, no view) - single type param, backward compat
  * ```typescript
  * class SimpleActor extends AbstractActor<AnyActorLogic> {
  *   state = new Signal.State({...});
@@ -49,23 +53,23 @@ import { Actor } from "xstate";
  * ```
  *
  * @example
- * 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) { ... }
  * }
  * ```
  *
  * @example
  * 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) { ... }
  * }
  * ```

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;AA8GnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,OAAgB,aAA4C,SAAQ,KAAa;CA6CtF"}
+{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAsJrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CA6CtB"}

package/dist/index.d.ts

@@ -15,5 +15,5 @@
  * @packageDocumentation
  * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol | RFC Play v1 Section 5.3}
  */
-export { AbstractActor, type Routable, type Viewable, type ViewMetadata, } from "./abstract-actor.js";
+export { AbstractActor, type Routable, type Viewable, type ViewMetadata, type PlaySpec, } 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,EACN,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,GACjB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,QAAQ,GACb,MAAM,qBAAqB,CAAC"}

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.18",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -31,6 +31,7 @@
     "build": "tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
     "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
@@ -38,15 +39,18 @@
     "format:check": "oxfmt --check .",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "@json-render/core": "^0.16.0"
+  },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.16",
+    "@xmachines/shared": "1.0.0-beta.18",
     "vitest": "^4.1.2",
     "xstate": "^5.30.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.16",
-    "@xmachines/play-signals": "1.0.0-beta.16",
+    "@xmachines/play": "1.0.0-beta.18",
+    "@xmachines/play-signals": "1.0.0-beta.18",
     "xstate": "^5.30.0"
   },
   "engines": {