@xmachines/play-actor 1.0.0-beta.32 → 1.0.0-beta.34

package/README.md

@@ -28,7 +28,10 @@ npm install @xmachines/play-actor
 - `AbstractActor`
 - `Routable` (type)
 - `Viewable` (type)
-- `ViewMetadata` (type)
+- `PlaySpec` (type)
+- `typedSpec`
+- `BaseActorProviderProps` (type)
+- `BaseViewContextValue` (type)
 
 **Peer dependencies:**
 
@@ -72,7 +75,7 @@ Implement `Routable` to add routing support:
 
 Implement `Viewable` to add view rendering support:
 
-- `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.
+- `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:**
 
@@ -84,12 +87,7 @@ 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 PlaySpec } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
 import type { AnyActorLogic, AnyMachineSnapshot } from "xstate";
 
@@ -106,7 +104,7 @@ class PlayerActor<TLogic extends AnyActorLogic>
 	});
 
 	// Viewable: current view spec — Signal.State, updated on every state transition
-	currentView = new Signal.State<ViewMetadata | null>(null);
+	currentView = new Signal.State<PlaySpec | null>(null);
 
 	constructor(logic: TLogic) {
 		super(logic);
@@ -178,19 +176,19 @@ function connectBrowserNavigation(actor: AbstractActor<any>) {
 This base class enforces three architectural invariants:
 
 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
+   - Actor decides all state transitions via guards
+   - Infrastructure sends events, actor validates and processes
+   - Actor's decision is final — no override by infrastructure
 
 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)
+   - All reactive state exposed via TC39 Signals
+   - Infrastructure uses `Signal.subtle.Watcher` to observe
+   - No direct queries (`getSnapshot()` for internal use only)
 
 3. **Passive Infrastructure (INV-04):**
-    - Infrastructure reflects actor state (via signals)
-    - Infrastructure never decides transitions
-    - Browser/router events sent as commands to actor
+   - Infrastructure reflects actor state (via signals)
+   - Infrastructure never decides transitions
+   - Browser/router events sent as commands to actor
 
 ## XState Compatibility
 

package/dist/abstract-actor.d.ts

@@ -18,7 +18,7 @@
  */
 import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type { Signal } from "@xmachines/play-signals";
-import type { Spec } from "@json-render/core";
+import type { Spec, StateStore, RenderErrorHandler, ActionHandler } from "@json-render/core";
 /**
  * Optional capability: Routing support
  */
@@ -67,39 +67,18 @@ export interface PlaySpec extends Spec {
  * }
  *
  * meta: {
- *   view: {
- *     component: "Dashboard",
- *     spec: typedSpec<DashboardCtx>({
- *       root: "root",
- *       contextProps: ["username"],    // ✓ key of DashboardCtx
- *       // contextProps: ["usernaem"], // ✗ compile error
- *       elements: { root: { type: "Dashboard", props: {}, children: [] } },
- *     }),
- *   },
+ *   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;
-/**
- * View metadata for rendering.
- *
- * 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 {
-    /** Root element type name (for diagnostics and component resolution) */
-    component: string;
-    /**
-     * XMachines view spec — extends `@json-render/core` Spec with `contextProps`
-     * for explicit context field exposure.
-     *
-     * Use `typedSpec<TContext>(...)` at the definition site to validate
-     * `contextProps` entries against the machine context type.
-     */
-    spec: PlaySpec;
-}
 /**
  * Actor capability for exposing renderable view state.
  *
@@ -110,12 +89,72 @@ export interface ViewMetadata {
  */
 export interface Viewable {
     /**
-     * Current view signal.
+     * Current view signal. Contains the json-render PlaySpec for the current machine
+     * state, or null when no view is active.
      *
-     * State signal containing view.component and view.spec from meta.view.
      * Infrastructure renders view — Logic-Driven UI invariant.
      */
-    readonly currentView: Signal.State<ViewMetadata | null>;
+    readonly currentView: Signal.State<PlaySpec | null>;
+}
+/**
+ * Framework-agnostic base for every framework's `ViewContextValue`.
+ *
+ * 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`.
+ *
+ * @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.
+ *
+ * Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+ *
+ * @typeParam TRegistry - The framework's `DefineRegistryResult` type.
+ *
+ * @example
+ * ```ts
+ * import type { BaseActorProviderProps } from "@xmachines/play-actor";
+ * import type { DefineRegistryResult } from "@json-render/react";
+ *
+ * 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.

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,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;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACxD;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"}
+{"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

@@ -37,15 +37,12 @@ import { Actor } from "xstate";
  * }
  *
  * meta: {
- *   view: {
- *     component: "Dashboard",
- *     spec: typedSpec<DashboardCtx>({
- *       root: "root",
- *       contextProps: ["username"],    // ✓ key of DashboardCtx
- *       // contextProps: ["usernaem"], // ✗ compile error
- *       elements: { root: { type: "Dashboard", props: {}, children: [] } },
- *     }),
- *   },
+ *   view: typedSpec<DashboardCtx>({
+ *     root: "root",
+ *     contextProps: ["username"],    // ✓ key of DashboardCtx
+ *     // contextProps: ["usernaem"], // ✗ compile error
+ *     elements: { root: { type: "Dashboard", props: {}, children: [] } },
+ *   }),
  * }
  * ```
  */

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,EAAwC,MAAM,QAAQ,CAAC;AAkCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAuCD;;;;;;;;;GASG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAetB"}
+{"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

@@ -15,5 +15,5 @@
  * @packageDocumentation
  * @see [Play RFC](../../docs/rfc/play.md)
  */
-export { AbstractActor, typedSpec, type Routable, type Viewable, type ViewMetadata, type PlaySpec, } 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,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,QAAQ,GACb,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.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAKT,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.32",
+  "version": "1.0.0-beta.34",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo coverage",
+    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-*",
     "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
@@ -43,15 +43,15 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.32",
+    "@xmachines/shared": "1.0.0-beta.34",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",
     "vitest": "^4.1.4",
     "xstate": "^5.30.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.32",
-    "@xmachines/play-signals": "1.0.0-beta.32",
+    "@xmachines/play": "1.0.0-beta.34",
+    "@xmachines/play-signals": "1.0.0-beta.34",
     "xstate": "^5.30.0"
   },
   "engines": {