@xmachines/play-actor 2.0.0 → 2.1.0

package/README.md

@@ -2,9 +2,7 @@
 
 Abstract Actor base class for XMachines Play Architecture.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
-
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
 
 ## Installation
 
@@ -12,7 +10,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-actor
 ```
 
-**Peer dependencies** — install alongside the package:
+**Peer dependencies.** Install them with the package:
 
 ```bash
 pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
@@ -20,35 +18,35 @@ pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-c
 
 ## Overview
 
-`@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).
+`@xmachines/play-actor` gives you `AbstractActor`, a minimal base class. The class extends the XState `Actor` class, and it enforces the **signal protocol** of the Play Architecture (RFC section 5.3). It exposes reactive TC39 Signals for the infrastructure layer. It also keeps the complete compatibility with the XState ecosystem, which includes the devtools and the inspection.
 
-The core protocol is deliberately minimal:
+The core protocol is small on purpose:
 
 | Property | Type                      | Description                              |
 | -------- | ------------------------- | ---------------------------------------- |
 | `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
 | `send`   | `(event: TEvent) => void` | Event dispatch method                    |
 
-Optional capabilities are declared as separate interfaces — a concrete actor opts in only to what it needs:
+Separate interfaces declare the optional capabilities. A concrete actor implements only the interfaces that it needs:
 
 | Interface  | Property                                        | Description                           |
 | ---------- | ----------------------------------------------- | ------------------------------------- |
 | `Routable` | `currentRoute: Signal.Computed<string \| null>` | Current route path derived from state |
-| `Routable` | `initialRoute: string \| null`                  | Route the actor starts on             |
+| `Routable` | `initialRoute: string \| null`                  | The route where the actor starts      |
 | `Viewable` | `currentView: Signal.State<PlaySpec \| null>`   | Current JSON-render view spec         |
 
-Concrete implementations are created by adapters such as [`@xmachines/play-xstate`](../play-xstate/README.md).
+An adapter, such as [`@xmachines/play-xstate`](../play-xstate/README.md), makes the concrete implementations.
 
 ## API Summary
 
 ### `AbstractActor<TLogic, TEvent>`
 
-Abstract base class extending XState `Actor<TLogic>`.
+The abstract base class extends the XState `Actor<TLogic>` class.
 
-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.
+A subclass **is** the actor. Give the logic and its options to `super()`, so that one
+instance holds the running machine. Reach the `send` method of XState through the
+prototype. This class declares `send` as abstract for one reason only: to narrow the
+event type. TypeScript forbids a `super` call to an abstract member.
 
 ```ts
 import { AbstractActor } from "@xmachines/play-actor";
@@ -75,6 +73,7 @@ class MyActor extends AbstractActor<AnyActorLogic> {
 With a typed event union:
 
 ```ts
+// imports as in the previous example
 type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
 
 class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
@@ -88,9 +87,10 @@ class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
 
 ### `typedSpec(spec)`
 
-Identity helper that types a view-spec literal as `PlaySpec` at the definition site. XState's
-`meta` field is `Record<string, unknown>`, so this is where the spec shape gets compile-time
-validation and IDE autocomplete — without any runtime cost.
+This identity helper gives a view-spec literal the type `PlaySpec` at the definition site. The
+XState `meta` field has the type `Record<string, unknown>`. Therefore this helper is the place
+where the spec shape receives the compile-time check and the IDE autocomplete. The helper has no
+cost at run time.
 
 ```ts
 import { typedSpec } from "@xmachines/play-actor";
@@ -112,28 +112,33 @@ meta: {
 
 ### `PlaySpec`
 
-Extends `@xmachines/json-render-core`'s `Spec`. The machine's whole context is projected into
-every derived view's state store under the read-only **`/context` subtree**, so specs read it
-through the ordinary `{ $state: "/context/…" }` grammar — in props, `visible` conditions, and
-`repeat.statePath` alike.
-
-`/context` is read-only by design — never writable. Machine context changes only through events;
-a `$bindState` or `setState` write under `/context` throws with an error naming the event to
-send instead. This is the model: bindable ephemeral state lives at the store root (seeded from
-`spec.state`), domain state lives in the machine and changes via meaningful, inspectable events.
-
-Provenance is legible in the path: `/context/params/username` is visibly URL-derived, while
-`/context/username` is machine-owned — one can never shadow the other.
-
-Two consequences of the everything-is-projected model are worth knowing. First, **exposure**:
-the whole context is client-visible in the view store (debug panels, inspectors, validators) —
-context is a client-side value either way, so keep secrets out of it. Second, **emission
-granularity**: the emit gate compares context per top-level field, so an event that changes any
-field re-emits the view with the same `viewKey`. Providers refresh `/context` in the live store
-rather than reseeding it — no remount, ephemeral view state and focus survive — but a
-re-emission is still a render pass in the framework layer. Keep high-frequency ephemeral data
-(per-keystroke drafts, timers) in the view store (`spec.state` + `$bindState`) or a child actor
-rather than in machine context; domain state belongs in context, keystrokes do not.
+This type extends the `Spec` type of `@xmachines/json-render-core`. Each derived view receives
+the complete machine context in its state store, under the read-only **`/context` subtree**. A
+spec therefore reads the context through the ordinary `{ $state: "/context/…" }` grammar: in a
+prop, in a `visible` condition, and in `repeat.statePath`.
+
+`/context` is read-only by design. Nothing can write to it. The machine context changes through
+an event only. A `$bindState` write or a `setState` write under `/context` throws an error, and
+the error names the event to send. This is the model: the bindable ephemeral state is at the
+root of the store, from `spec.state`; the domain state is in the machine, and it changes through
+events that are meaningful and easy to inspect.
+
+The path shows the origin of each value. `/context/params/username` comes from the URL.
+`/context/username` belongs to the machine. One value can never hide the other.
+
+The model projects everything, and this has two consequences. The first consequence is
+**exposure**. The complete context is visible to the client in the view store, which includes a
+debug panel, an inspector, and a validator. The context is a client-side value in each case, so
+keep a secret out of it.
+
+The second consequence is **emission granularity**. The emit gate compares the context field by
+field, at the top level only. Therefore an event that changes any field emits the view again
+with the same `viewKey`. A provider refreshes `/context` in the live store, and it does not seed
+the store again. The component does not remount, and the ephemeral view state and the focus
+stay. However, a new emission is still a render pass in the framework layer. Keep
+high-frequency ephemeral data, such as a draft for each keystroke or a timer, in the view store
+(`spec.state` with `$bindState`) or in a child actor. The domain state belongs in the context. A
+keystroke does not.
 
 ```ts
 import type { PlaySpec } from "@xmachines/play-actor";
@@ -150,31 +155,33 @@ const spec: PlaySpec = {
 };
 ```
 
-> Historical note: earlier versions had a `contextProps` field. It first drove an implicit
-> prop-enrichment pass that merged allowlisted context fields and URL params into every
-> element's props (removed — it injected values into components that never asked for them and
-> let user-manipulable URL data silently shadow machine-owned state), and was then briefly a
-> projection filter (removed — filtering what a view may read added machinery without a real
-> problem to solve). Validate the **derived** view (`actor.currentView.get()`), not the raw
-> `meta.view`: the derived spec's `state` carries the projection, so tools like `validateSpec`
-> see a self-consistent spec.
+> Historical note: an earlier version had a `contextProps` field. At first the field drove an
+> implicit prop-enrichment pass. That pass merged the allowlisted context fields and the URL
+> params into the props of every element. We removed it, because it put values into components
+> that never asked for them, and it let URL data from the user hide machine-owned state. The
+> field was then a projection filter for a short time. We removed that filter too, because a
+> limit on what a view can read added machinery without a real problem to solve. Always
+> validate the **derived** view (`actor.currentView.get()`), not the raw `meta.view`. The
+> `state` of the derived spec carries the projection, so a tool such as `validateSpec` sees a
+> spec that is consistent with itself.
 
 ### `Routable`
 
 Interface for actors that support routing.
 
 ```ts
-import type { Routable } from "@xmachines/play-actor";
+import { AbstractActor, type Routable } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
+import type { AnyActorLogic, EventObject } from "xstate";
 
 // 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);
+	state = new Signal.State<{ path?: string }>({});
+	currentRoute = new Signal.Computed<string | null>(() => this.state.get().path ?? null);
 	initialRoute = "/";
-	send = (event) => {
+	override send(event: EventObject): void {
 		/* dispatch */
-	};
+	}
 }
 ```
 
@@ -194,7 +201,7 @@ const viewable: Viewable = { currentView: signal };
 
 ### `BaseActorProviderProps<TRegistry>`
 
-Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
+The framework-agnostic base props. Every `ActorProvider` implementation shares them: React, Vue, Solid, and Svelte. Each framework renderer package extends this interface.
 
 ```ts
 import type { BaseActorProviderProps } from "@xmachines/play-actor";
@@ -208,7 +215,7 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 ### `BaseViewContextValue<TRegistry>`
 
-Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
+The framework-agnostic base of the `ViewContextValue` type in each framework. It holds the `spec`, `handlers`, `registry`, and `store` fields. These fields are identical in React, Vue, Solid, and Svelte.
 
 ## Testing
 

package/dist/abstract-actor.d.ts

@@ -1,18 +1,19 @@
 /**
- * AbstractActor base class for Play Architecture
+ * The AbstractActor base class of the Play Architecture
  *
- * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
- * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ * It extends the XState Actor class, which keeps the compatibility with the
+ * ecosystem, such as the inspection and the devtools. It also enforces the signal
+ * protocol of the communication between the Actor and the infrastructure.
  *
- * Per RFC section 5.3, the Actor exposes a minimal protocol:
- * - state: Current machine state snapshot
- * - send: Event dispatch method
+ * RFC section 5.3 gives the minimal protocol of the Actor:
+ * - state: the snapshot of the current machine state
+ * - send: the method that sends an event
  *
- * Optional capabilities are provided via interfaces:
- * - Routable: For actors that support routing
- * - Viewable: For actors that support view rendering
+ * Two interfaces give the optional capabilities:
+ * - Routable: for an actor with a routing support
+ * - Viewable: for an actor with a view rendering
  *
- * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ * An adapter, such as @xmachines/play-xstate, makes the concrete implementations.
  *
  * @packageDocumentation
  */
@@ -20,46 +21,47 @@ import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type { Signal } from "@xmachines/play-signals";
 import type { Spec, StateStore, RenderErrorHandler, ActionHandler } from "@xmachines/json-render-core";
 /**
- * Optional capability: Routing support
+ * An optional capability: the routing support
  */
 export interface Routable {
     readonly currentRoute: Signal.Computed<string | null>;
     readonly initialRoute: string | null;
 }
 /**
- * XMachines extension of `@xmachines/json-render-core` `Spec`.
+ * The XMachines extension of the `Spec` type of `@xmachines/json-render-core`.
  *
- * The machine's context is projected into every derived view's state store
- * under the read-only `/context` subtree, so specs read it through the
- * ordinary `{ $state: "/context/…" }` grammar — in props, `visible`
- * conditions, and `repeat.statePath` alike. The whole context is always
- * projected; a spec simply reads the paths it needs.
+ * Each derived view receives the machine context in its state store, under the
+ * read-only `/context` subtree. A spec therefore reads the context through the
+ * ordinary `{ $state: "/context/…" }` grammar: in a prop, in a `visible` condition,
+ * and in `repeat.statePath`. The store always holds the complete context, and a
+ * spec reads only the paths that it needs.
  */
 export interface PlaySpec extends Spec {
     /**
-     * Identity of the view this derived spec came from — set by
-     * `deriveCurrentView` from the meta entry the derivation actually selected.
-     * Providers key their store lifecycle on it: a changed `viewKey` reseeds the
-     * store; an unchanged one refreshes `/context` in place, preserving
-     * ephemeral view state. Never author this field in `meta.view`.
+     * The identity of the view of this derived spec. `deriveCurrentView` sets it from
+     * the meta entry that the derivation selected. A provider uses it as the key of its
+     * store lifecycle: a new `viewKey` seeds the store again, and the same `viewKey`
+     * refreshes `/context` in place, which keeps the ephemeral view state. Never write
+     * this field in `meta.view`.
      */
     readonly viewKey?: string;
 }
 /**
- * Identity helper that types a view spec literal as `PlaySpec` at the
- * definition site, giving compile-time validation and IDE autocomplete.
+ * The identity helper gives a view spec literal the type `PlaySpec` at the
+ * definition site. The compiler therefore checks the spec, and the IDE completes it.
  *
- * XState's `meta` field is typed as `Record<string, unknown>`, so TypeScript
- * cannot infer the spec shape from context. `typedSpec(...)` is the opt-in
- * mechanism that activates checking where the spec is written. `viewKey` is
- * excluded from the parameter — derivation stamps it and would silently
- * overwrite an authored value, so authoring one is rejected at compile time.
+ * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
+ * therefore infers no spec shape from the context. `typedSpec(...)` is the
+ * mechanism that starts the check where you write the spec. The parameter holds no
+ * `viewKey`: the derivation stamps that field, and it overwrites a value from an
+ * author without a notice. Therefore the compiler refuses a `viewKey` here.
  *
- * Excess-property checking only applies to an inline object literal; for a
- * spec built in a variable or through spreads, use `satisfies PlaySpec` at
+ * The check of an excess property works on an inline object literal only. For a
+ * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
  * the literal instead.
  *
- * At runtime this is a no-op — the spec object is returned unchanged.
+ * At run time this function does nothing: it returns the spec object without a
+ * change.
  *
  * @example
  * ```ts
@@ -79,50 +81,55 @@ export interface PlaySpec extends Spec {
  */
 export declare function typedSpec(spec: Omit<PlaySpec, "viewKey">): PlaySpec;
 /**
- * Actor capability for exposing renderable view state.
+ * The actor capability that exposes a renderable view state.
  *
- * `Viewable` marks actors that publish a `currentView` signal.
- * Renderers such as `PlayRenderer` consume this contract to resolve the
- * current view description into concrete UI without embedding view logic inside the
- * framework adapter.
+ * `Viewable` marks an actor that publishes a `currentView` signal.
+ * A renderer, such as `PlayRenderer`, reads this contract. It converts the
+ * description of the current view into a concrete UI, and the framework adapter
+ * therefore holds no view logic.
  */
 export interface Viewable {
     /**
-     * Current view signal. Contains the json-render PlaySpec for the current machine
-     * state, or null when no view is active.
+     * The signal of the current view. It holds the json-render PlaySpec of the current
+     * machine state, or null when no view is active.
      *
-     * Infrastructure renders view — Logic-Driven UI invariant.
+     * The infrastructure renders the view. This is the Logic-Driven UI invariant.
      */
     readonly currentView: Signal.State<PlaySpec | null>;
 }
 /**
- * Framework-agnostic base for every framework's `ViewContextValue`.
+ * The framework-agnostic base of the `ViewContextValue` type in each framework.
  *
- * Holds the three fields that are identical across React, Vue, Solid, and Svelte.
- * `registry` is framework-specific (each framework has its own `ComponentRegistry`
- * type) so it is typed via `TRegistry` — the same generic used in `BaseActorProviderProps`.
+ * It holds the three fields that are identical in React, Vue, Solid, and Svelte.
+ * The `registry` field belongs to one framework, because each framework has its own
+ * `ComponentRegistry` type. Therefore `TRegistry` gives its type, and this is the
+ * same generic parameter as in `BaseActorProviderProps`.
  *
- * @typeParam TRegistry - The framework's component registry type (e.g. `ComponentRegistry` from `@xmachines/json-render-react`).
+ * @typeParam TRegistry - The registry type of the component of the framework, for example `ComponentRegistry` from `@xmachines/json-render-react`.
  */
 export interface BaseViewContextValue<TRegistry extends object> {
     /** The current PlaySpec to render. */
     spec: PlaySpec;
-    /** Action handlers resolved against the live StateStore. */
+    /** The action handlers, resolved against the live StateStore. */
     handlers: Record<string, ActionHandler>;
-    /** Component registry from registryResult.registry. */
+    /** The component registry, from registryResult.registry. */
     registry: TRegistry;
-    /** The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. */
+    /**
+     * The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state.
+     */
     store: StateStore;
 }
 /**
- * Framework-agnostic base props shared by every `ActorProvider` implementation
- * (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
- * `DefineRegistryResult` type; `RenderErrorHandler` is sourced from
- * `@xmachines/json-render-core` so no second generic is needed.
+ * The framework-agnostic base props. Every `ActorProvider` implementation shares
+ * them: React, Vue, Solid, and Svelte. `TRegistry` holds the
+ * `DefineRegistryResult` type of the framework. `RenderErrorHandler` comes from
+ * `@xmachines/json-render-core`, and a second generic parameter is therefore not
+ * necessary.
  *
- * Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+ * Each framework package extends this interface with its `fallback` field, its
+ * `onError` field, and its `children` field.
  *
- * @typeParam TRegistry - The framework's `DefineRegistryResult` type.
+ * @typeParam TRegistry - The `DefineRegistryResult` type of the framework.
  *
  * @example
  * ```ts
@@ -139,60 +146,61 @@ export interface BaseActorProviderProps<TRegistry extends {
     registry: object;
     handlers: (...args: never[]) => unknown;
 }> {
-    /** Actor instance with currentView signal (requires Viewable capability). */
+    /** The actor instance with the currentView signal. It requires the Viewable capability. */
     actor: AbstractActor<AnyActorLogic> & Viewable;
-    /** Full result from defineRegistry() — contains the component registry and action handlers factory. */
+    /** The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers. */
     registryResult: TRegistry;
     /**
-     * Optional external StateStore (controlled mode).
-     * When provided, spec.state is ignored and this store is the single source of truth.
-     * When omitted, a fresh @xstate/store atom is created per view transition from spec.state.
+     * The optional external StateStore, which is the controlled mode.
+     * With this option, the provider ignores spec.state, and this store is the single
+     * source of truth. Without it, the provider makes a new @xstate/store atom for each
+     * view transition, with the values of spec.state.
      */
     store?: StateStore;
     /**
-     * Called when an individual catalog component throws during render.
-     * Takes precedence over any onRenderError set via defineRegistry.
+     * The provider calls it when one catalog component throws during a render.
+     * This handler replaces every onRenderError of defineRegistry.
      */
     onRenderError?: RenderErrorHandler;
 }
 /**
- * Abstract base class for Play Architecture actors.
- *
- * Provides signal-driven state observation that integrates with XState ecosystem
- * tooling (devtools, inspection) while exposing reactive signals for
- * Infrastructure layer communication.
- *
- * **A subclass IS the actor.** Forward the logic *and* its options to
- * `super(logic, options)`, then observe `this`. Holding a separately
- * constructed actor alongside leaves this instance running as an empty second
- * actor, and every inherited member — `system`, `sessionId`, `clock`, the
- * internal `_send` that receives `sendTo()` traffic, and anything a future
- * XState version adds — answers from that empty one until it is individually
- * forwarded.
- *
- * @typeParam TLogic - XState actor logic type
- * @typeParam TEvent - Event type constraint (defaults to EventObject)
+ * The abstract base class of an actor of the Play Architecture.
+ *
+ * It observes the state through the signals, and it works with the tools of the
+ * XState ecosystem, such as the devtools and the inspection. It also exposes the
+ * reactive signals of the communication with the infrastructure layer.
+ *
+ * **A subclass IS the actor.** Give the logic *and* its options to
+ * `super(logic, options)`, then observe `this`. A separate actor beside this
+ * instance leaves this instance as an empty second actor. Every inherited member
+ * then answers from that empty actor, until you forward each one: `system`,
+ * `sessionId`, `clock`, the internal `_send` that receives the traffic of
+ * `sendTo()`, and each member that a later XState version adds.
+ *
+ * @typeParam TLogic - The type of the XState actor logic
+ * @typeParam TEvent - The constraint of the event type. The default is EventObject
  */
 export declare abstract class AbstractActor<TLogic extends AnyActorLogic, TEvent extends EventObject = EventObject> extends Actor<TLogic> {
     /**
-     * Reactive snapshot of current actor state.
+     * The reactive snapshot of the current actor state.
      *
-     * Infrastructure observes this signal to react to state changes without
-     * directly coupling to the actor's internal state machine implementation.
+     * The infrastructure observes this signal, and it reacts to each state change. It
+     * therefore holds no coupling to the internal state machine of the actor.
      */
     abstract state: Signal.State<unknown>;
     /**
-     * Send event to Actor.
+     * Sends an event to the Actor.
      *
-     * Constrained to TEvent for type safety in concrete implementations.
+     * The constraint is TEvent, which gives the type safety of a concrete
+     * implementation.
      *
-     * 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.
+     * A note for an implementation that wraps `send`, to check the event or to notify a
+     * hook around it: this declaration is abstract for one reason only, to narrow the
+     * event type, and TypeScript forbids a `super` call to an abstract member. Reach
+     * the implementation of XState with `Actor.prototype.send.call(this, event)`
+     * instead. A concrete declaration permits `super.send()`, but it also forces an
+     * `override` modifier in every subclass that exists now, and that is a breaking
+     * change for an adapter outside this repository.
      */
     abstract send(event: TEvent): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,QAAQ,CAEnE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,uDAAuD;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,gHAAgH;IAChH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,6EAA6E;IAC7E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uGAAuG;IACvG,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;OAYG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}
+{"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,QAAQ,CAEnE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,4DAA4D;IAC5D,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,2FAA2F;IAC3F,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uHAAuH;IACvH,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;;OAaG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}

package/dist/abstract-actor.js

@@ -1,37 +1,39 @@
 /**
- * AbstractActor base class for Play Architecture
+ * The AbstractActor base class of the Play Architecture
  *
- * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
- * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ * It extends the XState Actor class, which keeps the compatibility with the
+ * ecosystem, such as the inspection and the devtools. It also enforces the signal
+ * protocol of the communication between the Actor and the infrastructure.
  *
- * Per RFC section 5.3, the Actor exposes a minimal protocol:
- * - state: Current machine state snapshot
- * - send: Event dispatch method
+ * RFC section 5.3 gives the minimal protocol of the Actor:
+ * - state: the snapshot of the current machine state
+ * - send: the method that sends an event
  *
- * Optional capabilities are provided via interfaces:
- * - Routable: For actors that support routing
- * - Viewable: For actors that support view rendering
+ * Two interfaces give the optional capabilities:
+ * - Routable: for an actor with a routing support
+ * - Viewable: for an actor with a view rendering
  *
- * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ * An adapter, such as @xmachines/play-xstate, makes the concrete implementations.
  *
  * @packageDocumentation
  */
 import { Actor } from "xstate";
 /**
- * Identity helper that types a view spec literal as `PlaySpec` at the
- * definition site, giving compile-time validation and IDE autocomplete.
+ * The identity helper gives a view spec literal the type `PlaySpec` at the
+ * definition site. The compiler therefore checks the spec, and the IDE completes it.
  *
- * XState's `meta` field is typed as `Record<string, unknown>`, so TypeScript
- * cannot infer the spec shape from context. `typedSpec(...)` is the opt-in
- * mechanism that activates checking where the spec is written. `viewKey` is
- * excluded from the parameter — derivation stamps it and would silently
- * overwrite an authored value, so authoring one is rejected at compile time.
+ * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
+ * therefore infers no spec shape from the context. `typedSpec(...)` is the
+ * mechanism that starts the check where you write the spec. The parameter holds no
+ * `viewKey`: the derivation stamps that field, and it overwrites a value from an
+ * author without a notice. Therefore the compiler refuses a `viewKey` here.
  *
- * Excess-property checking only applies to an inline object literal; for a
- * spec built in a variable or through spreads, use `satisfies PlaySpec` at
+ * The check of an excess property works on an inline object literal only. For a
+ * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
  * the literal instead.
  *
- * At runtime this is a no-op — the spec object is returned unchanged.
+ * At run time this function does nothing: it returns the spec object without a
+ * change.
  *
  * @example
  * ```ts
@@ -53,22 +55,21 @@ export function typedSpec(spec) {
     return spec;
 }
 /**
- * Abstract base class for Play Architecture actors.
+ * The abstract base class of an actor of the Play Architecture.
  *
- * Provides signal-driven state observation that integrates with XState ecosystem
- * tooling (devtools, inspection) while exposing reactive signals for
- * Infrastructure layer communication.
+ * It observes the state through the signals, and it works with the tools of the
+ * XState ecosystem, such as the devtools and the inspection. It also exposes the
+ * reactive signals of the communication with the infrastructure layer.
  *
- * **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.
+ * **A subclass IS the actor.** Give the logic *and* its options to
+ * `super(logic, options)`, then observe `this`. A separate actor beside this
+ * instance leaves this instance as an empty second actor. Every inherited member
+ * then answers from that empty actor, until you forward each one: `system`,
+ * `sessionId`, `clock`, the internal `_send` that receives the traffic of
+ * `sendTo()`, and each member that a later XState version adds.
  *
- * @typeParam TLogic - XState actor logic type
- * @typeParam TEvent - Event type constraint (defaults to EventObject)
+ * @typeParam TLogic - The type of the XState actor logic
+ * @typeParam TEvent - The constraint of the event type. The default is EventObject
  */
 export class AbstractActor extends Actor {
 }

package/dist/abstract-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAqCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,SAAS,CAAC,IAA+B;IACxD,OAAO,IAAI,CAAC;AACb,CAAC;AAiFD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAuBtB"}
+{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAqCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,SAAS,CAAC,IAA+B;IACxD,OAAO,IAAI,CAAC;AACb,CAAC;AAuFD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAwBtB"}