@xmachines/play-actor 1.0.0-beta.9 → 1.1.0

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,219 +1,202 @@
 # @xmachines/play-actor
 
-**Abstract Actor base class with signal protocol for XMachines Play Architecture**
+Abstract Actor base class for XMachines Play Architecture.
 
-Foundation for all actor implementations, enforcing XState compatibility and reactive signal contracts.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
 
-## Overview
-
-`@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:
-
-- **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
-
-**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
+pnpm add @xmachines/play-actor
 ```
 
-## Current Exports
+**Peer dependencies** — install alongside the package:
 
-- `AbstractActor`
-- `Routable` (type)
-- `Viewable` (type)
-
-**Peer dependencies:**
+```bash
+pnpm add xstate @xmachines/play @xmachines/play-signals
+```
 
-- `xstate` ^5.0.0 — State machine runtime (XState compatibility)
-- `@xmachines/play-signals` - TC39 Signals primitives
-- `@xmachines/play` - Protocol types (PlayEvent, etc.)
+## Overview
 
-## Quick Start
+`@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).
 
-**Usage:** This is an abstract base class — use concrete implementations:
+The core protocol is deliberately minimal:
 
-```typescript
-import { definePlayer } from "@xmachines/play-xstate";
+| Property | Type                      | Description                              |
+| -------- | ------------------------- | ---------------------------------------- |
+| `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
+| `send`   | `(event: TEvent) => void` | Event dispatch method                    |
 
-// definePlayer returns PlayerActor (extends AbstractActor)
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer();
-actor.start();
+Optional capabilities are declared as separate interfaces — a concrete actor opts in only to what it needs:
 
-// 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
-```
+| 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         |
 
-## API Reference
+Concrete implementations are created by adapters such as [`@xmachines/play-xstate`](../play-xstate/README.md).
 
-### AbstractActor<TLogic>
+## API Summary
 
-Abstract base class defining signal protocol:
+### `AbstractActor<TLogic, TEvent>`
 
-**Abstract Properties (must implement):**
+Abstract base class extending XState `Actor<TLogic>`.
 
-- `state: Signal.State<unknown>` - Reactive snapshot of current state
+A subclass **is** the actor: hand the logic and its options to `super()` so one
+instance holds the running machine, and reach XState's own `send` through the
+prototype — `send` is declared abstract here only to narrow the event type, and
+TypeScript forbids `super` calls to an abstract member.
 
-**Optional capability interfaces:**
+```ts
+import { AbstractActor } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+import { Actor, type ActorOptions, type AnyActorLogic } from "xstate";
+
+class MyActor extends AbstractActor<AnyActorLogic> {
+	// Required: reactive state signal
+	state: Signal.State<unknown>;
+
+	constructor(logic: AnyActorLogic, options?: ActorOptions<AnyActorLogic>) {
+		super(logic, options);
+		this.state = new Signal.State(this.getSnapshot());
+		super.subscribe((snapshot) => this.state.set(snapshot));
+	}
+
+	// Required: typed event dispatch
+	override send(event: { type: string }): void {
+		Actor.prototype.send.call(this, event);
+	}
+}
+```
 
-Implement `Routable` to add routing support:
+With a typed event union:
 
-- `currentRoute: Signal.Computed<string | null>` - Derived navigation path
+```ts
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
 
-Implement `Viewable` to add view rendering support:
+class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
+	state = new Signal.State({ isAuthenticated: false, username: null });
 
-- `currentView: Signal.State<ViewMetadata | null>` - Current UI structure (updated at state entry)
-- `catalog: Record<string, unknown>` - Component catalog
+	override send(event: AuthEvent): void {
+		Actor.prototype.send.call(this, event);
+	}
+}
+```
 
-**Inherited from XState Actor:**
+### `typedSpec<TContext>(spec)`
 
-- `send(event): void` - Send event to actor
-- `start(): void` - Start the actor
-- `stop(): void` - Stop the actor
-- `getSnapshot()` - Get current XState snapshot (typed as `SnapshotFrom<TLogic>`)
+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.
 
-**Example implementation pattern:**
+```ts
+import { typedSpec } from "@xmachines/play-actor";
 
-```typescript
-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
-{
-    // 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...
-        });
-    }
+interface DashboardCtx {
+  username: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
 }
+
+// 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: [] },
+    },
+  }),
 }
 ```
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-actor)
+### `PlaySpec`
 
-## Examples
+Extends `@xmachines/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.
 
-### Infrastructure Observing Signals
+```ts
+import type { PlaySpec } from "@xmachines/play-actor";
 
-```typescript
-import { AbstractActor } 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);
-}
+const spec: PlaySpec = {
+	root: "root",
+	contextProps: ["username"], // only these keys are exposed to components
+	elements: {
+		root: { type: "Profile", props: { username: undefined }, children: [] },
+	},
+};
 ```
 
-### Browser Navigation Sending Events
+### `Routable`
 
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
+Interface for actors that support routing.
 
-function connectBrowserNavigation(actor: AbstractActor<any>) {
-	const handlePopstate = () => {
-		const path = window.location.pathname;
-
-		// 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 { Routable } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
 
-	return () => {
-		window.removeEventListener("popstate", handlePopstate);
+// Implement in a concrete actor (note: RoutableActor interface is exported from @xmachines/play-router):
+class MyRoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
+	state = new Signal.State({});
+	currentRoute = new Signal.Computed(() => this.state.get().path ?? null);
+	initialRoute = "/";
+	send = (event) => {
+		/* dispatch */
 	};
 }
 ```
 
-## Architecture
+### `Viewable`
 
-This base class enforces three architectural invariants:
+Interface for actors that expose a renderable view signal.
 
-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 { Viewable } from "@xmachines/play-actor";
+import type { PlaySpec } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+
+// currentView carries PlaySpec | null
+const signal = new Signal.State<PlaySpec | null>(null);
+const viewable: Viewable = { currentView: signal };
+```
 
-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)
+### `BaseActorProviderProps<TRegistry>`
 
-3. **Passive Infrastructure (INV-04):**
-    - Infrastructure reflects actor state (via signals)
-    - Infrastructure never decides transitions
-    - Browser/router events sent as commands to actor
+Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
 
-## XState Compatibility
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
 
-`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
 
-- **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
+### `BaseViewContextValue<TRegistry>`
 
-**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
 
-## Related Packages
+## Testing
 
-- **[@xmachines/play-xstate](../play-xstate)** - Concrete PlayerActor implementation
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
-- **[@xmachines/play](../play)** - Protocol types (PlayEvent, RouterBridge)
+Run the test suite for this package in isolation:
 
-## License
+```bash
+# From the package directory
+pnpm test
+
+# From the monorepo root (workspace-scoped)
+pnpm --filter @xmachines/play-actor test
+
+# Watch mode
+pnpm --filter @xmachines/play-actor run test:watch
+```
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+## Requirements
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+- **Node.js** `>=22.0.0`
+- **TypeScript** `>=5.7` (strict mode)
+- **ESM only** — `"type": "module"`

package/dist/abstract-actor.d.ts

@@ -16,205 +16,185 @@
  *
  * @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 "@xmachines/json-render-core";
 /**
  * Optional capability: Routing support
+ */
+export interface Routable {
+    readonly currentRoute: Signal.Computed<string | null>;
+    readonly initialRoute: string | null;
+}
+/**
+ * XMachines extension of `@xmachines/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;
 /**
- * View metadata for rendering
+ * Actor capability for exposing renderable view state.
  *
- * Describes the component to be rendered and the props to pass to it.
- * Used by PlayRenderer to dynamically render UI based on actor 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 ViewMetadata {
-    /** Name of the component to render from the catalog */
-    component: string;
-    /** Props to pass to the component */
-    props: Record<string, unknown>;
-}
 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<ViewMetadata | null>;
-    /**
-     * 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: Record<string, unknown>;
+    readonly currentView: Signal.State<PlaySpec | null>;
 }
 /**
- * Abstract base class for Play Architecture actors.
+ * Framework-agnostic base for every framework's `ViewContextValue`.
  *
- * 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
+ * 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`.
  *
- * Optional capabilities (routing, view rendering) are provided via interfaces:
- * - Implement Routable for routing support
- * - Implement Viewable for view rendering support
- *
- * Concrete implementations created by @xmachines/play-xstate adapter.
+ * @typeParam TRegistry - The framework's component registry type (e.g. `ComponentRegistry` from `@xmachines/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
+ * `@xmachines/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<AnyActorLogic> {
- *   state = new Signal.State({...});
- *   send(event) { ... }
- * }
- * ```
+ * ```ts
+ * import type { BaseActorProviderProps } from "@xmachines/play-actor";
+ * import type { DefineRegistryResult } from "@xmachines/json-render-react";
  *
- * @example
- * Routable actor
- * ```typescript
- * class RoutableActor extends AbstractActor<AnyActorLogic> 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<AnyActorLogic> 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
+ * **A subclass IS the actor.** Forward the logic *and* its options to
+ * `super(logic, options)`, then observe `this`. Holding a separately
+ * constructed actor alongside leaves this instance running as an empty second
+ * actor, and every inherited member — `system`, `sessionId`, `clock`, the
+ * internal `_send` that receives `sendTo()` traffic, and anything a future
+ * XState version adds — answers from that empty one until it is individually
+ * forwarded.
+ *
+ * @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.
      *
-     * Typed as `Signal.State<unknown>` at the abstract level; concrete implementations
-     * narrow this to the actual snapshot type (e.g., `Signal.State<AnyMachineSnapshot>`
-     * in `@xmachines/play-xstate`'s `PlayerActor`).
-     *
      * Infrastructure observes this signal to react to state changes without
-     * directly coupling to the Actor's internal state machine implementation.
-     *
-     * @example
-     * ```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<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.
+     * Send event to Actor.
      *
-     * @example
-     * ```typescript
-     * // Infrastructure forwards user intent
-     * actor.send({ type: 'auth.login', userId: '123' });
-     * // Actor's guards determine if event is allowed
-     * ```
+     * Constrained to TEvent for type safety in concrete implementations.
      *
-     * @remarks
-     * Accepts any event object with a type property. Core events (PlayEvent) are in
-     * @xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
+     * Note for implementations that wrap `send` (validating the event, or
+     * notifying hooks around it): this declaration is abstract purely to narrow
+     * the event type, and TypeScript forbids `super` calls to an abstract
+     * member. Reach XState's own implementation with
+     * `Actor.prototype.send.call(this, event)` instead. Making this concrete
+     * would allow `super.send()` but would force every existing subclass to add
+     * an `override` modifier — a breaking change for adapters outside this repo.
      */
-    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,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,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;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;;;;;;;;;;;;;;;;;GAiBG;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;;;;;;;;;;;;OAYG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}

package/dist/abstract-actor.js

@@ -18,61 +18,54 @@
  */
 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
+ * 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.
  *
- * Optional capabilities (routing, view rendering) are provided via interfaces:
- * - Implement Routable for routing support
- * - Implement Viewable for view rendering support
+ * 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.
  *
- * Concrete implementations created by @xmachines/play-xstate adapter.
- *
- * @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<AnyActorLogic> {
- *   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<AnyActorLogic> 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<AnyActorLogic> 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.
+ *
+ * **A subclass IS the actor.** Forward the logic *and* its options to
+ * `super(logic, options)`, then observe `this`. Holding a separately
+ * constructed actor alongside leaves this instance running as an empty second
+ * actor, and every inherited member — `system`, `sessionId`, `clock`, the
+ * internal `_send` that receives `sendTo()` traffic, and anything a future
+ * XState version adds — answers from that empty one until it is individually
+ * forwarded.
  *
- * @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;AAsGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AAuCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAiFD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAuBtB"}

package/dist/index.d.ts

@@ -13,7 +13,8 @@
  * 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, type ViewMetadata, } from "./abstract-actor.js";
+export { AbstractActor, typedSpec, type Routable, type Viewable, type PlaySpec, type BaseActorProviderProps, type BaseViewContextValue, } from "./abstract-actor.js";
+export { toAtomState, attachRenderErrorHandler } from "./provider-guards.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,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -13,7 +13,8 @@
  * 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";
+export { toAtomState, attachRenderErrorHandler } from "./provider-guards.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,EACN,aAAa,GAIb,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;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/provider-guards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared provider guards for framework ActorProvider implementations.
+ *
+ * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
+ * two rituals when bridging an actor's view to a json-render tree:
+ *
+ * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ *    ({@link toAtomState}).
+ * 2. Inject a component-level `onRenderError` handler into the component
+ *    registry without mutating the caller's registry
+ *    ({@link attachRenderErrorHandler}).
+ *
+ * Centralising them here keeps the guard semantics identical across frameworks.
+ *
+ * @packageDocumentation
+ */
+import type { RenderErrorHandler } from "@xmachines/json-render-core";
+/**
+ * Safely coerce a spec's `state` field to a plain object for `createAtom`.
+ *
+ * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
+ * `null`, `undefined`, a primitive, or a plain object depending on what the
+ * machine author put in the view spec. `createAtom` requires a plain object as
+ * its initial value — anything else produces a broken store at runtime.
+ *
+ * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
+ * and returned as-is. Everything else — `null`, `undefined`, primitives,
+ * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
+ * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+ *
+ * @param state - The raw `spec.state` value from a `PlaySpec`.
+ * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ */
+export declare function toAtomState(state: unknown): Record<string, unknown>;
+/**
+ * Clone a component registry and inject an `onRenderError` handler.
+ *
+ * The handler is defined as a non-enumerable, configurable own property on the
+ * clone (per D-19 — one injection convention for all framework renderers), so
+ * it overrides any handler set at `defineRegistry` level without showing up
+ * when the registry's component entries are enumerated.
+ *
+ * The caller's registry is never mutated — a shallow clone is returned. Callers
+ * that need per-instance handlers (e.g. an `onRenderError` prop on
+ * `ActorProvider`) can therefore share one `defineRegistry` result across
+ * providers safely.
+ *
+ * @typeParam TRegistry - The framework-specific component registry type.
+ * @param registry - The component registry from `defineRegistry().registry`.
+ * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
+ * @returns A shallow clone of `registry` with `onRenderError` attached.
+ */
+export declare function attachRenderErrorHandler<TRegistry extends object>(registry: TRegistry, handler: RenderErrorHandler): TRegistry;
+//# sourceMappingURL=provider-guards.d.ts.map

package/dist/provider-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-guards.d.ts","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,MAAM,EAChE,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,kBAAkB,GACzB,SAAS,CAQX"}

package/dist/provider-guards.js

@@ -0,0 +1,69 @@
+/**
+ * Shared provider guards for framework ActorProvider implementations.
+ *
+ * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
+ * two rituals when bridging an actor's view to a json-render tree:
+ *
+ * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ *    ({@link toAtomState}).
+ * 2. Inject a component-level `onRenderError` handler into the component
+ *    registry without mutating the caller's registry
+ *    ({@link attachRenderErrorHandler}).
+ *
+ * Centralising them here keeps the guard semantics identical across frameworks.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Safely coerce a spec's `state` field to a plain object for `createAtom`.
+ *
+ * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
+ * `null`, `undefined`, a primitive, or a plain object depending on what the
+ * machine author put in the view spec. `createAtom` requires a plain object as
+ * its initial value — anything else produces a broken store at runtime.
+ *
+ * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
+ * and returned as-is. Everything else — `null`, `undefined`, primitives,
+ * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
+ * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+ *
+ * @param state - The raw `spec.state` value from a `PlaySpec`.
+ * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ */
+export function toAtomState(state) {
+    if (state !== null && typeof state === "object" && !Array.isArray(state)) {
+        const proto = Object.getPrototypeOf(state);
+        if (proto === Object.prototype || proto === null) {
+            return state;
+        }
+    }
+    return {};
+}
+/**
+ * Clone a component registry and inject an `onRenderError` handler.
+ *
+ * The handler is defined as a non-enumerable, configurable own property on the
+ * clone (per D-19 — one injection convention for all framework renderers), so
+ * it overrides any handler set at `defineRegistry` level without showing up
+ * when the registry's component entries are enumerated.
+ *
+ * The caller's registry is never mutated — a shallow clone is returned. Callers
+ * that need per-instance handlers (e.g. an `onRenderError` prop on
+ * `ActorProvider`) can therefore share one `defineRegistry` result across
+ * providers safely.
+ *
+ * @typeParam TRegistry - The framework-specific component registry type.
+ * @param registry - The component registry from `defineRegistry().registry`.
+ * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
+ * @returns A shallow clone of `registry` with `onRenderError` attached.
+ */
+export function attachRenderErrorHandler(registry, handler) {
+    const clone = { ...registry };
+    Object.defineProperty(clone, "onRenderError", {
+        value: handler,
+        enumerable: false,
+        configurable: true,
+    });
+    return clone;
+}
+//# sourceMappingURL=provider-guards.js.map

package/dist/provider-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-guards.js","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;QACtD,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAClD,OAAO,KAAgC,CAAC;QACzC,CAAC;IACF,CAAC;IACD,OAAO,EAAE,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmB,EACnB,OAA2B;IAE3B,MAAM,KAAK,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC9B,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE;QAC7C,KAAK,EAAE,OAAO;QACd,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KAClB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "1.0.0-beta.9",
+  "version": "1.1.0",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -12,12 +12,18 @@
   ],
   "license": "MIT",
   "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "directory": "packages/play-actor"
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -29,28 +35,31 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
-    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
     "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
-    "format:check": "oxfmt --check .",
-    "prepublishOnly": "npm run build"
+    "format:check": "oxfmt --check ."
+  },
+  "dependencies": {
+    "@xmachines/json-render-core": "^0.19.0-xm.2"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.9",
-    "vitest": "^4.1.0",
-    "xstate": "^5.0.0"
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/node": "^26.2.0",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.79.0",
+    "vitest": "^4.1.11",
+    "xstate": "^5.31.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.9",
-    "@xmachines/play-signals": "1.0.0-beta.9",
-    "xstate": "^5.0.0"
+    "@xmachines/play": "1.1.0",
+    "@xmachines/play-signals": "1.1.0",
+    "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.28.0 to prevent drift."
+  "_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."
 }