@xmachines/play-actor 1.0.0-beta.1

package/README.md

@@ -0,0 +1,218 @@
+# @xmachines/play-actor
+
+**Abstract Actor base class with signal protocol for XMachines Play Architecture**
+
+Foundation for all actor implementations, enforcing XState compatibility and reactive signal contracts.
+
+## 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)).
+
+## Installation
+
+```bash
+npm install xstate@^5.0.0
+npm install @xmachines/play-actor
+```
+
+## Current Exports
+
+- `AbstractActor`
+- `Routable` (type)
+- `Viewable` (type)
+
+**Peer dependencies:**
+
+- `xstate` ^5.0.0 - State machine runtime (XState compatibility)
+- `@xmachines/play-signals` - TC39 Signals primitives
+- `@xmachines/play` - Protocol types (PlayEvent, etc.)
+
+## Quick Start
+
+**Usage:** This is an abstract base class — use concrete implementations:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+
+// definePlayer returns PlayerActor (extends AbstractActor)
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+actor.start();
+
+// 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
+```
+
+## API Reference
+
+### AbstractActor<TLogic>
+
+Abstract base class defining signal protocol:
+
+**Abstract Properties (must implement):**
+
+- `state: Signal.State<any>` - Reactive snapshot of current state
+- `currentRoute: Signal.Computed<string | null>` - Derived navigation path
+- `currentView: Signal.Computed<Record<string, any> | null>` - Derived UI structure
+- `catalog: any` - Component catalog
+
+**Inherited from XState Actor:**
+
+- `send(event: PlayEvent): void` - Send event to actor
+- `start(): void` - Start the actor
+- `stop(): void` - Stop the actor
+- `getSnapshot(): Snapshot` - Get current XState snapshot
+
+**Example implementation pattern:**
+
+```typescript
+import { AbstractActor } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+
+class PlayerActor<TLogic extends AnyActorLogic> extends AbstractActor<TLogic> {
+	// Implement required signal properties
+	state = new Signal.State(this.internalActor.getSnapshot());
+
+	currentRoute = new Signal.Computed(() => {
+		const snapshot = this.state.get();
+		return deriveRoute(snapshot);
+	});
+
+	currentView = new Signal.Computed(() => {
+		const snapshot = this.state.get();
+		return snapshot.meta?.view ?? null;
+	});
+
+	catalog = this.config.catalog;
+
+	// Internal XState actor
+	private internalActor: Actor<TLogic>;
+
+	constructor(logic: TLogic, catalog: any) {
+		super(logic);
+		this.internalActor = createActor(logic);
+
+		// Subscribe to XState transitions
+		this.internalActor.subscribe((snapshot) => {
+			this.state.set(snapshot); // Update signal
+		});
+	}
+
+	override start(): void {
+		this.internalActor.start();
+	}
+
+	override stop(): void {
+		this.internalActor.stop();
+	}
+
+	override send(event: PlayEvent): void {
+		this.internalActor.send(event as any);
+	}
+}
+```
+
+**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-actor)
+
+## Examples
+
+### Infrastructure Observing Signals
+
+```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);
+}
+```
+
+### Browser Navigation Sending Events
+
+```typescript
+import { AbstractActor } from "@xmachines/play-actor";
+
+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);
+
+	return () => {
+		window.removeEventListener("popstate", handlePopstate);
+	};
+}
+```
+
+## Architecture
+
+This base class enforces three architectural invariants:
+
+1. **Actor Authority (INV-01):**
+    - Actor decides all state transitions via guards
+    - Infrastructure sends events, actor validates and processes
+    - Actor's decision is final — no override by infrastructure
+
+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)
+
+3. **Passive Infrastructure (INV-04):**
+    - Infrastructure reflects actor state (via signals)
+    - Infrastructure never decides transitions
+    - Browser/router events sent as commands to actor
+
+## XState Compatibility
+
+`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+
+- **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
+
+**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate)** - Concrete PlayerActor implementation
+- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
+- **[@xmachines/play](../play)** - Protocol types (PlayEvent, RouterBridge)
+
+## License
+
+MIT

package/dist/abstract-actor.d.ts

@@ -0,0 +1,204 @@
+/**
+ * AbstractActor base class for Play Architecture
+ *
+ * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
+ * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ *
+ * Per RFC section 5.3, the Actor exposes a minimal protocol:
+ * - state: Current machine state snapshot
+ * - send: Event dispatch method
+ *
+ * Optional capabilities are provided via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ *
+ * @packageDocumentation
+ */
+import { Actor, type AnyActorLogic } from "xstate";
+import type { Signal } from "@xmachines/play-signals";
+/**
+ * Optional capability: Routing support
+ *
+ * Actors implementing this interface can derive a route from their state.
+ * Router adapters observe the currentRoute signal to sync browser URLs.
+ *
+ * @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);
+ * }
+ * ```
+ */
+export interface Routable {
+    /**
+     * Current route signal
+     *
+     * Computed signal derived from state machine. Infrastructure observes to sync browser URL.
+     *
+     * Invariant: Passive Infrastructure - Infrastructure reflects route, never decides.
+     *
+     * @example
+     * ```typescript
+     * const watcher = new Signal.subtle.Watcher(() => {
+     *   const route = actor.currentRoute.get();
+     *   console.log('Route changed:', route);
+     * });
+     * watcher.watch(actor.currentRoute);
+     * ```
+     */
+    readonly currentRoute: Signal.Computed<string | null>;
+}
+/**
+ * Optional capability: View rendering support
+ *
+ * Actors implementing this interface can derive view structures from their state.
+ * Renderers observe the currentView signal to update the UI.
+ *
+ * @example
+ * ```typescript
+ * class MyActor extends AbstractActor implements Viewable {
+ *   currentView = new Signal.State(null);
+ *   catalog = { HomePage: HomeComponent };
+ * }
+ *
+ * // Renderer requires Viewable
+ * function renderView<T extends AbstractActor & Viewable>(actor: T) {
+ *   const view = actor.currentView.get();
+ *   return catalog[view.component];
+ * }
+ * ```
+ */
+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<any>;
+    /**
+     * Component catalog for view resolution
+     *
+     * Maps component names to actual component implementations.
+     * Used by renderers to resolve view.component to actual UI components.
+     */
+    readonly catalog: any;
+}
+/**
+ * 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
+ *
+ * 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 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.
+ *
+ * @example
+ * Simple actor (no routing, no view)
+ * ```typescript
+ * class SimpleActor extends AbstractActor<any> {
+ *   state = new Signal.State({...});
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Routable actor
+ * ```typescript
+ * class RoutableActor extends AbstractActor<any> implements Routable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Full-featured actor (routing + view)
+ * ```typescript
+ * class PlayerActor extends AbstractActor<any> implements Routable, Viewable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   currentView = new Signal.State(null);
+ *   catalog = {};
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @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
+ */
+export declare abstract class AbstractActor<TLogic extends AnyActorLogic> extends Actor<TLogic> {
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * // Infrastructure observes state signal
+     * const watcher = new Signal.subtle.Watcher(() => {
+     *   console.log('Actor state changed:', actor.state.get());
+     * });
+     * watcher.watch(actor.state);
+     * ```
+     */
+    abstract state: Signal.State<any>;
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * // Infrastructure forwards user intent
+     * actor.send({ type: 'auth.login', userId: '123' });
+     * // Actor's guards determine if event is allowed
+     * ```
+     *
+     * @remarks
+     * Accepts any event object with a type property. Core events (PlayEvent) are in
+     * @xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
+     */
+    abstract send(event: {
+        readonly type: string;
+    } & Record<string, any>): void;
+}
+//# sourceMappingURL=abstract-actor.d.ts.map

package/dist/abstract-actor.d.ts.map

@@ -0,0 +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,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,8BAAsB,aAAa,CAAC,MAAM,SAAS,aAAa,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtF;;;;;;;;;;;;;;OAcG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;OAqBG;aACsB,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;CAC3F"}

package/dist/abstract-actor.js

@@ -0,0 +1,79 @@
+/**
+ * AbstractActor base class for Play Architecture
+ *
+ * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
+ * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ *
+ * Per RFC section 5.3, the Actor exposes a minimal protocol:
+ * - state: Current machine state snapshot
+ * - send: Event dispatch method
+ *
+ * Optional capabilities are provided via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ *
+ * @packageDocumentation
+ */
+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
+ *
+ * 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 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.
+ *
+ * @example
+ * Simple actor (no routing, no view)
+ * ```typescript
+ * class SimpleActor extends AbstractActor<any> {
+ *   state = new Signal.State({...});
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Routable actor
+ * ```typescript
+ * class RoutableActor extends AbstractActor<any> implements Routable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Full-featured actor (routing + view)
+ * ```typescript
+ * class PlayerActor extends AbstractActor<any> implements Routable, Viewable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   currentView = new Signal.State(null);
+ *   catalog = {};
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @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
+ */
+export class AbstractActor extends Actor {
+}
+//# sourceMappingURL=abstract-actor.js.map

package/dist/abstract-actor.js.map

@@ -0,0 +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;AAyFnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,OAAgB,aAA4C,SAAQ,KAAa;CAyCtF"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @xmachines/play-actor - Abstract Actor base class for Play Architecture
+ *
+ * This package provides AbstractActor, a minimal base class that extends XState Actor
+ * while enforcing the Play Architecture's signal protocol (RFC section 5.3).
+ *
+ * The core protocol is minimal (state + send). Optional capabilities are provided
+ * via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Maintains XState ecosystem compatibility (inspection, devtools) while exposing
+ * 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}
+ */
+export { AbstractActor, type Routable, type Viewable } from "./abstract-actor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @xmachines/play-actor - Abstract Actor base class for Play Architecture
+ *
+ * This package provides AbstractActor, a minimal base class that extends XState Actor
+ * while enforcing the Play Architecture's signal protocol (RFC section 5.3).
+ *
+ * The core protocol is minimal (state + send). Optional capabilities are provided
+ * via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Maintains XState ecosystem compatibility (inspection, devtools) while exposing
+ * 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}
+ */
+export { AbstractActor } from "./abstract-actor.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@xmachines/play-actor",
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "description": "Abstract Actor base class for XMachines Play Architecture",
+  "keywords": [
+    "actor",
+    "play-architecture",
+    "signals",
+    "xmachines",
+    "xstate"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "xstate": "^5.28.0"
+  },
+  "peerDependencies": {
+    "@xmachines/play": "1.0.0-beta.1",
+    "@xmachines/play-signals": "1.0.0-beta.1",
+    "xstate": "^5.28.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/abstract-actor.ts

@@ -0,0 +1,207 @@
+/**
+ * AbstractActor base class for Play Architecture
+ *
+ * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
+ * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ *
+ * Per RFC section 5.3, the Actor exposes a minimal protocol:
+ * - state: Current machine state snapshot
+ * - send: Event dispatch method
+ *
+ * Optional capabilities are provided via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ *
+ * @packageDocumentation
+ */
+
+import { Actor, type AnyActorLogic } from "xstate";
+import type { Signal } from "@xmachines/play-signals";
+
+/**
+ * Optional capability: Routing support
+ *
+ * Actors implementing this interface can derive a route from their state.
+ * Router adapters observe the currentRoute signal to sync browser URLs.
+ *
+ * @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);
+ * }
+ * ```
+ */
+export interface Routable {
+	/**
+	 * Current route signal
+	 *
+	 * Computed signal derived from state machine. Infrastructure observes to sync browser URL.
+	 *
+	 * Invariant: Passive Infrastructure - Infrastructure reflects route, never decides.
+	 *
+	 * @example
+	 * ```typescript
+	 * const watcher = new Signal.subtle.Watcher(() => {
+	 *   const route = actor.currentRoute.get();
+	 *   console.log('Route changed:', route);
+	 * });
+	 * watcher.watch(actor.currentRoute);
+	 * ```
+	 */
+	readonly currentRoute: Signal.Computed<string | null>;
+}
+
+/**
+ * Optional capability: View rendering support
+ *
+ * Actors implementing this interface can derive view structures from their state.
+ * Renderers observe the currentView signal to update the UI.
+ *
+ * @example
+ * ```typescript
+ * class MyActor extends AbstractActor implements Viewable {
+ *   currentView = new Signal.State(null);
+ *   catalog = { HomePage: HomeComponent };
+ * }
+ *
+ * // Renderer requires Viewable
+ * function renderView<T extends AbstractActor & Viewable>(actor: T) {
+ *   const view = actor.currentView.get();
+ *   return catalog[view.component];
+ * }
+ * ```
+ */
+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<any>;
+
+	/**
+	 * Component catalog for view resolution
+	 *
+	 * Maps component names to actual component implementations.
+	 * Used by renderers to resolve view.component to actual UI components.
+	 */
+	readonly catalog: any;
+}
+
+/**
+ * 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
+ *
+ * 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 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.
+ *
+ * @example
+ * Simple actor (no routing, no view)
+ * ```typescript
+ * class SimpleActor extends AbstractActor<any> {
+ *   state = new Signal.State({...});
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Routable actor
+ * ```typescript
+ * class RoutableActor extends AbstractActor<any> implements Routable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @example
+ * Full-featured actor (routing + view)
+ * ```typescript
+ * class PlayerActor extends AbstractActor<any> implements Routable, Viewable {
+ *   state = new Signal.State({...});
+ *   currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+ *   currentView = new Signal.State(null);
+ *   catalog = {};
+ *   send(event) { ... }
+ * }
+ * ```
+ *
+ * @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
+ */
+export abstract class AbstractActor<TLogic extends AnyActorLogic> extends Actor<TLogic> {
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Infrastructure observes state signal
+	 * const watcher = new Signal.subtle.Watcher(() => {
+	 *   console.log('Actor state changed:', actor.state.get());
+	 * });
+	 * watcher.watch(actor.state);
+	 * ```
+	 */
+	public abstract state: Signal.State<any>;
+
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Infrastructure forwards user intent
+	 * actor.send({ type: 'auth.login', userId: '123' });
+	 * // Actor's guards determine if event is allowed
+	 * ```
+	 *
+	 * @remarks
+	 * Accepts any event object with a type property. Core events (PlayEvent) are in
+	 * @xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
+	 */
+	public abstract override send(event: { readonly type: string } & Record<string, any>): void;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @xmachines/play-actor - Abstract Actor base class for Play Architecture
+ *
+ * This package provides AbstractActor, a minimal base class that extends XState Actor
+ * while enforcing the Play Architecture's signal protocol (RFC section 5.3).
+ *
+ * The core protocol is minimal (state + send). Optional capabilities are provided
+ * via interfaces:
+ * - Routable: For actors that support routing
+ * - Viewable: For actors that support view rendering
+ *
+ * Maintains XState ecosystem compatibility (inspection, devtools) while exposing
+ * 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}
+ */
+
+export { AbstractActor, type Routable, type Viewable } from "./abstract-actor.js";