@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-actor/README.md

@@ -1,222 +1,207 @@
-[Documentation](../../README.md) / @xmachines/play-actor
+[API](../../README.md) / @xmachines/play-actor
 
 # @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/README.md)).
+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: [] },
+    },
+  }),
 }
 ```
 
-## Examples
+### `PlaySpec`
 
-### Infrastructure Observing Signals
+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.
 
-```typescript
-import { AbstractActor } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
+```ts
+import type { PlaySpec } from "@xmachines/play-actor";
 
-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`
+
+Interface for actors that expose a renderable view signal.
+
+```ts
+import type { Viewable } from "@xmachines/play-actor";
+import type { PlaySpec } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
 
-This base class enforces three architectural invariants:
+// currentView carries PlaySpec | null
+const signal = new Signal.State<PlaySpec | null>(null);
+const viewable: Viewable = { currentView: 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
+### `BaseActorProviderProps<TRegistry>`
 
-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)
+Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
 
-3. **Passive Infrastructure (INV-04):**
-    - Infrastructure reflects actor state (via signals)
-    - Infrastructure never decides transitions
-    - Browser/router events sent as commands to actor
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
 
-## XState Compatibility
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
 
-`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+### `BaseViewContextValue<TRegistry>`
 
-- **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
+Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
 
-**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+## Testing
 
-## Related Packages
+Run the test suite for this package in isolation:
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - Concrete PlayerActor implementation
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
-- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent, RouterBridge)
+```bash
+# From the package directory
+pnpm test
 
-## License
+# From the monorepo root (workspace-scoped)
+pnpm --filter @xmachines/play-actor test
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+# Watch mode
+pnpm --filter @xmachines/play-actor run test:watch
+```
+
+## 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"`
 
 @xmachines/play-actor - Abstract Actor base class for Play Architecture
 
@@ -234,7 +219,7 @@ reactive signals for Infrastructure layer communication.
 
 ## See
 
-[RFC Play v1 Section 5.3](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol)
+[Play RFC](../../../rfc/play.md)
 
 ## Classes
 
@@ -242,6 +227,14 @@ reactive signals for Infrastructure layer communication.
 
 ## Interfaces
 
+- [BaseActorProviderProps](interfaces/BaseActorProviderProps.md)
+- [BaseViewContextValue](interfaces/BaseViewContextValue.md)
+- [PlaySpec](interfaces/PlaySpec.md)
 - [Routable](interfaces/Routable.md)
 - [Viewable](interfaces/Viewable.md)
-- [ViewMetadata](interfaces/ViewMetadata.md)
+
+## Functions
+
+- [attachRenderErrorHandler](functions/attachRenderErrorHandler.md)
+- [toAtomState](functions/toAtomState.md)
+- [typedSpec](functions/typedSpec.md)