@xmachines/play-actor 1.0.0-beta.1 → 1.0.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -14,8 +14,8 @@
   "author": "XMachines Contributors",
   "files": [
     "dist",
-    "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "type": "module",
   "exports": {
@@ -40,8 +40,8 @@
     "xstate": "^5.28.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.1",
-    "@xmachines/play-signals": "1.0.0-beta.1",
+    "@xmachines/play": "1.0.0-beta.2",
+    "@xmachines/play-signals": "1.0.0-beta.2",
     "xstate": "^5.28.0"
   },
   "engines": {

package/src/abstract-actor.ts

@@ -1,207 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * @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";