@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -1,68 +1,26 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / AbstractActor
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / AbstractActor
 
-# Abstract Class: AbstractActor\<TLogic\>
+# Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L179)
+Defined in: [packages/play-actor/src/abstract-actor.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L193)
 
 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.
+Provides signal-driven state observation that integrates with XState ecosystem
+tooling (devtools, inspection) while exposing reactive signals for
+Infrastructure layer 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
-
-Concrete implementations created by @xmachines/play-xstate adapter.
-
-## Examples
-
-Simple actor (no routing, no view)
-
-```typescript
-class SimpleActor extends AbstractActor<AnyActorLogic> {
-  state = new Signal.State({...});
-  send(event) { ... }
-}
-```
-
-Routable actor
-
-```typescript
-class RoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
-  state = new Signal.State({...});
-  currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-  send(event) { ... }
-}
-```
-
-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) { ... }
-}
-```
-
-## See
-
-- [RFC Play v1 Section 5.3](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol)
-- [Routable](../interfaces/Routable.md) for routing capability
-- [Viewable](../interfaces/Viewable.md) 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.
 
 ## Extends
 
-- `Actor`\<`TLogic`\>
+- [`Actor`](https://www.jsdocs.io/package/xstate#Actor)\<`TLogic`\>
 
 ## Extended by
 
@@ -70,33 +28,34 @@ class PlayerActor extends AbstractActor<AnyActorLogic> implements Routable, View
 
 ## Type Parameters
 
-| Type Parameter                     | Description                                                                                                                                                                                                                                                                                     |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TLogic` _extends_ `AnyActorLogic` | 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. |
+| Type Parameter                                                                           | Default type                                                      | Description                                     |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type                         |
+| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type constraint (defaults to EventObject) |
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new AbstractActor<TLogic>(logic, options?): AbstractActor<TLogic>;
+new AbstractActor<TLogic, TEvent>(logic, options?): AbstractActor<TLogic, TEvent>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:50
+Defined in: `xstate`
 
 Creates a new actor instance for the given logic with the provided options,
 if any.
 
 #### Parameters
 
-| Parameter  | Type                       | Description                       |
-| ---------- | -------------------------- | --------------------------------- |
-| `logic`    | `TLogic`                   | The logic to create an actor from |
-| `options?` | `ActorOptions`\<`TLogic`\> | Actor options                     |
+| Parameter  | Type                                                                            | Description                       |
+| ---------- | ------------------------------------------------------------------------------- | --------------------------------- |
+| `logic`    | `TLogic`                                                                        | The logic to create an actor from |
+| `options?` | [`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\> | Actor options                     |
 
 #### Returns
 
-`AbstractActor`\<`TLogic`\>
+`AbstractActor`\<`TLogic`, `TEvent`\>
 
 #### Inherited from
 
@@ -106,19 +65,19 @@ Actor<TLogic>.constructor
 
 ## Properties
 
-| Property                                    | Modifier   | Type                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from    | Defined in                                                                                                                                                                                 |
-| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-_parent"></a> `_parent?`    | `public`   | `AnyActorRef`                                                                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor._parent`   | node_modules/xstate/dist/declarations/src/createActor.d.ts:33                                                                                                                              |
-| <a id="property-clock"></a> `clock`         | `public`   | `Clock`                                                                                           | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Actor.clock`     | node_modules/xstate/dist/declarations/src/createActor.d.ts:25                                                                                                                              |
-| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                          | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `Actor.id`        | node_modules/xstate/dist/declarations/src/createActor.d.ts:28                                                                                                                              |
-| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.logic`     | node_modules/xstate/dist/declarations/src/createActor.d.ts:18                                                                                                                              |
-| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<`ActorOptions`\<`TLogic`\>\>                                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.options`   | node_modules/xstate/dist/declarations/src/createActor.d.ts:26                                                                                                                              |
-| <a id="property-ref"></a> `ref`             | `public`   | `ActorRef`\<`SnapshotFrom`\<`TLogic`\>, `EventFromLogic`\<`TLogic`\>, `EmittedFrom`\<`TLogic`\>\> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.ref`       | node_modules/xstate/dist/declarations/src/createActor.d.ts:34                                                                                                                              |
-| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                          | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `Actor.sessionId` | node_modules/xstate/dist/declarations/src/createActor.d.ts:38                                                                                                                              |
-| <a id="property-src"></a> `src`             | `public`   | `string` \| `AnyActorLogic`                                                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.src`       | node_modules/xstate/dist/declarations/src/createActor.d.ts:42                                                                                                                              |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                     | 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** `// Infrastructure observes state signal const watcher = new Signal.subtle.Watcher(() => { console.log('Actor state changed:', actor.state.get()); }); watcher.watch(actor.state);` | -                 | [packages/play-actor/src/abstract-actor.ts:199](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L199) |
-| <a id="property-system"></a> `system`       | `public`   | `AnyActorSystem`                                                                                  | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `Actor.system`    | node_modules/xstate/dist/declarations/src/createActor.d.ts:40                                                                                                                              |
-| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.systemId`  | node_modules/xstate/dist/declarations/src/createActor.d.ts:36                                                                                                                              |
+| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                             | Inherited from    | Defined in                                                                                                                                               |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                       | `Actor._parent`   | -                                                                                                                                                        |
+| <a id="property-clock"></a> `clock`         | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                              | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                | `Actor.clock`     | -                                                                                                                                                        |
+| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                            | `Actor.id`        | -                                                                                                                                                        |
+| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                       | `Actor.logic`     | -                                                                                                                                                        |
+| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                       | `Actor.options`   | -                                                                                                                                                        |
+| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`       | -                                                                                                                                                        |
+| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId` | -                                                                                                                                                        |
+| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor.src`       | -                                                                                                                                                        |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | 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. | -                 | [packages/play-actor/src/abstract-actor.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L203) |
+| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`    | -                                                                                                                                                        |
+| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.systemId`  | -                                                                                                                                                        |
 
 ## Methods
 
@@ -128,11 +87,11 @@ Actor<TLogic>.constructor
 observable: InteropSubscribable<SnapshotFrom<TLogic>>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
+Defined in: `xstate`
 
 #### Returns
 
-`InteropSubscribable`\<`SnapshotFrom`\<`TLogic`\>\>
+[`InteropSubscribable`](https://www.jsdocs.io/package/xstate#InteropSubscribable)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>\>
 
 #### Inherited from
 
@@ -148,13 +107,13 @@ Actor.[observable]
 getPersistedSnapshot(): Snapshot<unknown>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:152
+Defined in: `xstate`
 
 Obtain the internal state of the actor, which can be persisted.
 
 #### Returns
 
-`Snapshot`\<`unknown`\>
+[`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>
 
 #### Remarks
 
@@ -164,7 +123,7 @@ Note that the persisted state is not the same as the snapshot from
 [Actor.getSnapshot](#getsnapshot). Persisted state represents the internal state of
 the actor, while snapshots represent the actor's last emitted value.
 
-Can be restored with [ActorOptions.state](#)
+Can be restored with [ActorOptions.state](https://www.jsdocs.io/package/xstate#ActorOptions.state)
 
 #### See
 
@@ -184,13 +143,13 @@ Actor.getPersistedSnapshot;
 getSnapshot(): SnapshotFrom<TLogic>;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:168
+Defined in: `xstate`
 
 Read an actor’s snapshot synchronously.
 
 #### Returns
 
-`SnapshotFrom`\<`TLogic`\>
+[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>
 
 #### Remarks
 
@@ -221,7 +180,7 @@ Actor.getSnapshot;
 on<TType>(type, handler): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:115
+Defined in: `xstate`
 
 #### Type Parameters
 
@@ -238,7 +197,7 @@ Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:115
 
 #### Returns
 
-`Subscription`
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
 #### Inherited from
 
@@ -248,42 +207,68 @@ Actor.on;
 
 ---
 
-### send()
+### select()
 
 ```ts
-abstract send(event): void;
+select<TSelected>(selector, equalityFn?): Readable<TSelected>;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L223)
+Defined in: `xstate`
 
-Send event to Actor
+#### Type Parameters
 
-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.
+| Type Parameter |
+| -------------- |
+| `TSelected`    |
 
 #### Parameters
 
-| Parameter | Type                                       | Description                                                                                                                                  |
-| --------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `event`   | `object` & `Record`\<`string`, `unknown`\> | Event object with type property (e.g., PlayEvent, PlayRouteEvent) Invariant: Actor Authority - Only Actor decides whether an event is valid. |
+| Parameter     | Type                        |
+| ------------- | --------------------------- |
+| `selector`    | (`snapshot`) => `TSelected` |
+| `equalityFn?` | (`a`, `b`) => `boolean`     |
 
 #### Returns
 
-`void`
+`Readable`\<`TSelected`\>
 
-#### Example
+#### Inherited from
 
-```typescript
-// Infrastructure forwards user intent
-actor.send({ type: "auth.login", userId: "123" });
-// Actor's guards determine if event is allowed
+```ts
+Actor.select;
 ```
 
-#### Remarks
+---
+
+### send()
+
+```ts
+abstract send(event): void;
+```
 
-Accepts any event object with a type property. Core events (PlayEvent) are in
-@xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
+Defined in: [packages/play-actor/src/abstract-actor.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L218)
+
+Send event to Actor.
+
+Constrained to TEvent for type safety in concrete implementations.
+
+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.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `TEvent` |
+
+#### Returns
+
+`void`
 
 #### Overrides
 
@@ -299,7 +284,7 @@ Actor.send;
 start(): this;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:119
+Defined in: `xstate`
 
 Starts the Actor from the initial state
 
@@ -321,7 +306,7 @@ Actor.start;
 stop(): this;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:123
+Defined in: `xstate`
 
 Stops the Actor and unsubscribe all listeners.
 
@@ -345,19 +330,19 @@ Actor.stop;
 subscribe(observer): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:113
+Defined in: `xstate`
 
 Subscribe an observer to an actor’s snapshot values.
 
 ##### Parameters
 
-| Parameter  | Type                                     | Description                                                                                                                                  |
-| ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observer` | `Observer`\<`SnapshotFrom`\<`TLogic`\>\> | Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot |
+| Parameter  | Type                                                                                                                                           | Description                                                                                                                                  |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observer` | [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>\> | Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot |
 
 ##### Returns
 
-`Subscription`
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
 ##### Remarks
 
@@ -423,7 +408,7 @@ subscribe(
    completeListener?): Subscription;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:114
+Defined in: `xstate`
 
 Subscribe an observer to an actor’s snapshot values.
 
@@ -437,7 +422,7 @@ Subscribe an observer to an actor’s snapshot values.
 
 ##### Returns
 
-`Subscription`
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
 
 ##### Remarks
 
@@ -502,16 +487,16 @@ Actor.subscribe;
 toJSON(): object;
 ```
 
-Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:135
+Defined in: `xstate`
 
 #### Returns
 
 `object`
 
-| Name           | Type     | Defined in                                                     |
-| -------------- | -------- | -------------------------------------------------------------- |
-| `id`           | `string` | node_modules/xstate/dist/declarations/src/createActor.d.ts:137 |
-| `xstate$$type` | `number` | node_modules/xstate/dist/declarations/src/createActor.d.ts:136 |
+| Name           | Type     | Defined in |
+| -------------- | -------- | ---------- |
+| `id`           | `string` | -          |
+| `xstate$$type` | `number` | -          |
 
 #### Inherited from
 

package/api/@xmachines/play-actor/functions/attachRenderErrorHandler.md

@@ -0,0 +1,40 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / attachRenderErrorHandler
+
+# Function: attachRenderErrorHandler()
+
+```ts
+function attachRenderErrorHandler<TRegistry>(registry, handler): TRegistry;
+```
+
+Defined in: [packages/play-actor/src/provider-guards.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/provider-guards.ts#L64)
+
+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.
+
+## Type Parameters
+
+| Type Parameter                 | Description                                     |
+| ------------------------------ | ----------------------------------------------- |
+| `TRegistry` _extends_ `object` | The framework-specific component registry type. |
+
+## Parameters
+
+| Parameter  | Type                                                                      | Description                                                                         |
+| ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `registry` | `TRegistry`                                                               | The component registry from `defineRegistry().registry`.                            |
+| `handler`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md) | Called with `(error, componentName)` when a catalog component throws during render. |
+
+## Returns
+
+`TRegistry`
+
+A shallow clone of `registry` with `onRenderError` attached.

package/api/@xmachines/play-actor/functions/toAtomState.md

@@ -0,0 +1,33 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / toAtomState
+
+# Function: toAtomState()
+
+```ts
+function toAtomState(state): Record<string, unknown>;
+```
+
+Defined in: [packages/play-actor/src/provider-guards.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/provider-guards.ts#L36)
+
+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.
+
+## Parameters
+
+| Parameter | Type      | Description                                   |
+| --------- | --------- | --------------------------------------------- |
+| `state`   | `unknown` | The raw `spec.state` value from a `PlaySpec`. |
+
+## Returns
+
+`Record`\<`string`, `unknown`\>
+
+`state` itself when it is a plain object, otherwise a new empty object.

package/api/@xmachines/play-actor/functions/typedSpec.md

@@ -0,0 +1,54 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / typedSpec
+
+# Function: typedSpec()
+
+```ts
+function typedSpec<TContext>(spec): PlaySpec;
+```
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L88)
+
+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.
+
+At runtime this is a no-op — the spec object is returned unchanged.
+
+## Type Parameters
+
+| Type Parameter                |
+| ----------------------------- |
+| `TContext` _extends_ `object` |
+
+## Parameters
+
+| Parameter | Type                                                                           |
+| --------- | ------------------------------------------------------------------------------ |
+| `spec`    | `Omit`\<[`PlaySpec`](../interfaces/PlaySpec.md), `"contextProps"`\> & `object` |
+
+## Returns
+
+[`PlaySpec`](../interfaces/PlaySpec.md)
+
+## Example
+
+```ts
+interface DashboardCtx {
+  username: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+}
+
+meta: {
+  view: typedSpec<DashboardCtx>({
+    root: "root",
+    contextProps: ["username"],    // ✓ key of DashboardCtx
+    // contextProps: ["usernaem"], // ✗ compile error
+    elements: { root: { type: "Dashboard", props: {}, children: [] } },
+  }),
+}
+```

package/api/@xmachines/play-actor/interfaces/BaseActorProviderProps.md

@@ -0,0 +1,46 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / BaseActorProviderProps
+
+# Interface: BaseActorProviderProps\<TRegistry\>
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L155)
+
+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.
+
+Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+
+## Example
+
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
+
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
+
+## Extended by
+
+- [`ActorProviderProps`](../../play-react/interfaces/ActorProviderProps.md)
+- [`ActorProviderProps`](../../play-solid/interfaces/ActorProviderProps.md)
+- [`ActorProviderProps`](../../play-svelte/interfaces/ActorProviderProps.md)
+- [`ActorProviderProps`](../../play-vue/interfaces/ActorProviderProps.md)
+
+## Type Parameters
+
+| Type Parameter                 | Description                                  |
+| ------------------------------ | -------------------------------------------- |
+| `TRegistry` _extends_ `object` | The framework's `DefineRegistryResult` type. |
+
+## Properties
+
+| Property                                              | Type                                                                                                                                                                                                                   | Description                                                                                                                                                                                                                 | Defined in                                                                                                                                               |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L159) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                              | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L172) |
+| <a id="property-registryresult"></a> `registryResult` | `TRegistry`                                                                                                                                                                                                            | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L161) |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                           | 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. | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L167) |