@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/player-actor.js

@@ -5,11 +5,13 @@ import { ActorThrewNonErrorError, InvalidEventError, InvalidMachineError } from
 import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
 import { deriveCurrentView } from "./view/derive-current-view.js";
 /**
- * An `Error` by identity or by brand: `instanceof` misses errors constructed
- * in another realm (an iframe, `node:vm`). Prefer `Error.isError` where the
- * runtime has it (Node >= 24, Baseline-2025 browsers) — it rejects
- * `Symbol.toStringTag` spoofs — and fall back to the brand check elsewhere.
- * Typed structurally: the repo's lib target predates the API.
+ * Tells you if a value is an `Error`, by its identity or by its brand: `instanceof`
+ * misses an error from another realm, such as an iframe or `node:vm`. The function
+ * prefers `Error.isError` where the runtime has it (Node >= 24, and a
+ * Baseline-2025 browser), because that function refuses a false
+ * `Symbol.toStringTag`. In every other runtime the function tests the brand. The
+ * type is structural, because the lib target of this repository is older than the
+ * API.
  */
 const isRealError = (value) => {
     if (value instanceof Error)
@@ -20,12 +22,13 @@ const isRealError = (value) => {
     return Object.prototype.toString.call(value) === "[object Error]";
 };
 /**
- * Normalize an actor failure for `onError`.
+ * Normalizes a failure of the actor for `onError`.
  *
- * An `Error` is handed over unchanged so the machine's own error keeps its
- * identity (a consumer's `instanceof` check still works, and the no-`onError`
- * path rethrows that same object). Anything else is ours to construct, so it
- * becomes a coded `PlayError` carrying the thrown value as `cause`.
+ * The function gives an `Error` to the handler without a change. The error of the
+ * machine therefore keeps its identity: an `instanceof` test of a consumer still
+ * works, and the path without an `onError` throws that same object again. Every
+ * other value is ours to build, and it becomes a `PlayError` with a code. That
+ * error carries the value from the throw as its `cause`.
  */
 const toError = (value) => {
     try {
@@ -34,20 +37,22 @@ const toError = (value) => {
         }
     }
     catch {
-        // Classification itself can throw for hostile values (a revoked Proxy
-        // traps both instanceof and brand inspection) — fall through and wrap.
+        // The classification itself can throw for a hostile value, because a revoked
+        // Proxy traps instanceof and also the inspection of the brand. Continue, and wrap
+        // the value.
     }
     return new ActorThrewNonErrorError(value);
 };
 /**
- * Bounded structural equality for derived view specs.
+ * The structural equality of two derived view specs, with a limit on its depth.
  *
- * Walks exactly the shape `deriveCurrentView` builds — spec fields, then
- * `elements`, then each element's `props` — comparing every leaf with
- * `Object.is`. Prop VALUES are never entered: a changed reference re-emits
- * even when contents are equal, which keeps container props (Map/Set/class
- * instances, invisible to structural comparison) and cyclic values (unbounded
- * recursion for it) correct by construction.
+ * The function walks exactly the shape that `deriveCurrentView` builds: the spec
+ * fields, then `elements`, then the `props` object of each element. It compares
+ * each leaf with `Object.is`. It never enters the VALUE of a prop: a new reference
+ * therefore emits the view again, also when the contents are equal. This design
+ * keeps two things correct: a prop of a container (a Map, a Set, or an instance of a
+ * class, which a structural comparison cannot see), and a cyclic value, which gives
+ * a structural comparison a recursion without an end.
  */
 const viewSpecsEquivalent = (a, b) => {
     if (a === b)
@@ -58,8 +63,9 @@ const viewSpecsEquivalent = (a, b) => {
         return false;
     const aElements = a.elements ?? {};
     const bElements = b.elements ?? {};
-    // Derived specs spread the same static meta.view, so elements is usually
-    // reference-identical — skip the per-element walk when it is.
+    // A derived spec spreads the same static meta.view. Therefore the elements
+    // usually have the same reference, and the walk over each element is then not
+    // necessary.
     if (aElements === bElements)
         return true;
     const elementKeys = Object.keys(aElements);
@@ -80,35 +86,39 @@ const viewSpecsEquivalent = (a, b) => {
     return true;
 };
 /**
- * A snapshot worth propagating to signals: an active snapshot or a "done"
- * snapshot (top-level final state reached). Error and stopped snapshots are
- * skipped so signals keep the last observable state instead of surfacing
- * teardown/error artifacts.
+ * Tells you if a snapshot is worth a propagation to the signals: an active
+ * snapshot, or a "done" snapshot, which means that the machine reached a final state
+ * at the top level. The code skips an error snapshot and a stopped snapshot.
+ * Therefore the signals keep the last observable state, and they show no artifact of
+ * a teardown or of an error.
  */
 const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snapshot.status === "done";
 /**
- * Concrete XState actor implementing Play Architecture signal protocol
+ * The concrete XState actor. It implements the signal protocol of the Play Architecture
  *
- * Extends {@link @xmachines/play-actor!AbstractActor} — and so XState's own `Actor` —
- * to provide XState v5 integration while maintaining ecosystem compatibility (XState
- * inspection, devtools). The machine is handed to the base constructor, so a
- * `PlayerActor` **is** the XState actor rather than a wrapper around one: everything
- * XState's `Actor` exposes operates on this instance's own state, and the class adds
- * TC39 Signal-based reactive state for Infrastructure observation on top.
+ * The class extends {@link @xmachines/play-actor!AbstractActor}, and therefore the
+ * `Actor` class of XState. It gives you the XState v5 integration, and it keeps the
+ * compatibility with the ecosystem, such as the XState inspection and the devtools.
+ * The constructor of the base class receives the machine. Therefore a `PlayerActor`
+ * **is** the XState actor, and it is no wrapper around one: every member of the
+ * XState `Actor` class works on the state of this instance, and this class adds the
+ * reactive state on the TC39 Signals for the observation by the infrastructure.
  *
- * **Capabilities:** Implements both {@link @xmachines/play-actor!Routable} and
- * {@link @xmachines/play-actor!Viewable} interfaces, providing routing and view
- * rendering support.
+ * **Capabilities:** the class implements both the
+ * {@link @xmachines/play-actor!Routable} interface and the
+ * {@link @xmachines/play-actor!Viewable} interface. It therefore supports the
+ * routing and the view rendering.
  *
- * **Architectural Context:** Implements **Actor Authority (INV-01)** by ensuring the
- * XState machine's guards control all navigation decisions. Infrastructure observes
- * the actor's signals (`state`, `currentRoute`, `currentView`) but cannot directly
- * manipulate state—all mutations flow through the state machine's event handlers.
+ * **Architectural context:** the class implements **Actor Authority (INV-01)**,
+ * because the guards of the XState machine control every decision of the
+ * navigation. The infrastructure observes the signals of the actor (`state`,
+ * `currentRoute`, and `currentView`), but it changes no state directly: every
+ * change goes through the event handlers of the state machine.
  *
- * @typeParam TMachine - XState v5 state machine type
+ * @typeParam TMachine - The type of the XState v5 state machine
  *
  * @example
- * Basic actor creation and lifecycle
+ * The creation of an actor, and its lifecycle
  * ```typescript
  * import { setup } from "xstate";
  * import { definePlayer } from "@xmachines/play-xstate";
@@ -119,7 +129,7 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  *     idle: {
  *       meta: {
  *         route: '/',
- *         // A view spec needs `root` and `elements` — other shapes derive null.
+ *         // A view spec needs `root` and `elements`. Every other shape derives null.
  *         view: {
  *           root: 'home',
  *           elements: { home: { type: 'HomePage', props: {}, children: [] } },
@@ -133,13 +143,13 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  * const actor = createPlayer();
  * actor.start();
  *
- * // Observe signals
+ * // Observe the signals
  * console.log(actor.currentRoute.get());          // '/'
  * console.log(actor.currentView.get()?.root);     // 'home'
  * ```
  *
  * @example
- * Signal lifecycle with watchers
+ * The signal lifecycle with a watcher
  * ```typescript
  * import { Signal } from "@xmachines/play-signals";
  *
@@ -152,61 +162,63 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  *
  * watcher.watch(actor.state);
  * actor.send({ type: 'play.route', to: '#about' });
- * // Watcher notification scheduled via microtask by the watcher itself
+ * // The watcher schedules its own notification in a microtask
  * ```
  *
  * @see [Play RFC](../../docs/rfc/play.md)
- * @see {@link definePlayer} for factory creation
- * @see {@link @xmachines/play-actor!AbstractActor} for signal protocol
- * @see {@link @xmachines/play-actor!Routable} for routing capability
- * @see {@link @xmachines/play-actor!Viewable} for view rendering capability
+ * @see {@link definePlayer} for the creation through a factory
+ * @see {@link @xmachines/play-actor!AbstractActor} for the signal protocol
+ * @see {@link @xmachines/play-actor!Routable} for the routing capability
+ * @see {@link @xmachines/play-actor!Viewable} for the view rendering capability
  *
  * @remarks
- * **Routing:** This actor supports both XState's `route: {}` config pattern
- * and `play.route` events with parameters. The `deriveRoute()` function checks
- * `meta.route` (Stately pattern) for URL templates with parameter substitution support.
+ * **The routing:** this actor supports the `route: {}` config pattern of XState and
+ * also a `play.route` event with parameters. The `deriveRoute()` function reads
+ * `meta.route`, which is the Stately pattern, for a URL template, and it substitutes
+ * each parameter.
  *
- * **View Signal Pattern:** The `currentView` signal is a direct `Signal.State` (not
- * `Signal.Computed`) to ensure proper watcher propagation in PlayRenderer. Views are
- * cached and updated at state entry, not computed on every read.
+ * **The pattern of the view signal:** the `currentView` signal is a direct
+ * `Signal.State`, and not a `Signal.Computed`. The propagation to a watcher in
+ * PlayRenderer is therefore correct. The class derives each view at the entry of a
+ * state and keeps it, and it computes no view on a read.
  */
 export class PlayerActor extends AbstractActor {
     playerOptions;
     /**
-     * The caller's live options bag, or an empty one during construction.
+     * The live options object of the caller, or an empty object during the construction.
      *
-     * XState hands this actor to a context factory as `self` and to an
-     * `inspect` observer as `actorRef` from inside its own constructor, before
-     * any field here is assigned. Reading hooks through this accessor keeps
-     * that window from throwing — a throw would be caught by XState's
-     * initialization and parked as an error snapshot — while preserving the
-     * read-at-delivery-time behaviour the bag's own docs promise.
+     * XState gives this actor to a context factory as `self`, and to an `inspect`
+     * observer as `actorRef`, from inside its own constructor, before the code assigns
+     * any field here. A read of a hook through this accessor therefore does not throw
+     * in that window. A throw goes to the initialization of XState, which parks it as
+     * an error snapshot. The accessor also keeps the behavior that the documentation of
+     * the object promises: a read at the moment of the delivery.
      *
-     * The window-sensitive fields below are `declare`d for the same reason.
-     * This target compiles class fields to `Object.defineProperty`, which runs
-     * after `super()` returns: a plain declaration — initializer or not — would
-     * reset anything the window had written back to `undefined`. `declare`
-     * emits nothing, so those writes survive.
+     * The fields below that this window touches have a `declare` modifier for the same
+     * reason. This target compiles a class field into `Object.defineProperty`, which
+     * runs after `super()` returns. A plain declaration, with an initializer or without
+     * one, therefore resets each value of the window to `undefined`. A `declare`
+     * modifier emits nothing, and those values survive.
      */
     get hooks() {
         return this.playerOptions ?? {};
     }
     /**
-     * The last snapshot the view pipeline processed. XState notifies observers
-     * on EVERY processed event — an ignored event redelivers the identical
-     * snapshot — and deriveCurrentView is pure in the snapshot, so an identical
-     * reference cannot change the outcome. Seeded with undefined (never a
-     * snapshot): the construction-time snapshot is reference-identical to the
-     * one start() replays, and seeding with it would suppress the initial view.
+     * The last snapshot of the view pipeline. XState notifies each observer on EVERY
+     * event that it processes, and an event that it ignores delivers the identical
+     * snapshot again. deriveCurrentView is pure in the snapshot. Therefore an identical
+     * reference can change no result. The first value is undefined, and never a
+     * snapshot: the snapshot of the construction has the same reference as the snapshot
+     * that start() replays, and that value therefore stops the first view.
      */
     lastViewSnapshot = undefined;
-    // AbstractActor protocol requirements
+    // The requirements of the AbstractActor protocol
     state;
     /**
-     * Returns whether the actor's current state can accept the given event.
+     * Tells you if the current state of the actor accepts the given event.
      *
-     * Typed to the machine's event union — passing an unknown event type is a
-     * compile error. Evaluated against the current snapshot signal.
+     * The type is the event union of the machine. An unknown event type is therefore a
+     * compile error. The method evaluates the event against the snapshot signal.
      *
      * @example
      * ```typescript
@@ -214,186 +226,195 @@ export class PlayerActor extends AbstractActor {
      * ```
      */
     can(event) {
-        // Reading the signal keeps can() reactive: a Signal.Computed over it
-        // recomputes on transitions. Two states have no answer to give: the
-        // construction window, where no snapshot is readable yet, and an actor
-        // whose initialization failed — XState parks an error snapshot there,
-        // which is a truthy object with no `can` on it.
+        // A read of the signal keeps can() reactive: a Signal.Computed over the signal
+        // computes its value again on each transition. Two states have no answer: the
+        // construction window, where the code can read no snapshot, and an actor with a
+        // failed initialization, where XState parks an error snapshot. That snapshot is
+        // a truthy object, and it has no `can` method.
         const snapshot = this.state?.get();
         return typeof snapshot?.can === "function" ? snapshot.can(event) : false;
     }
     /**
-     * A TC39 `Signal.Computed` that derives the current URL path from the active
-     * machine state's `meta.route` template and the actor's context.
+     * A TC39 `Signal.Computed`. It derives the current URL path from the `meta.route`
+     * template of the active machine state and from the context of the actor.
      *
-     * Returns `null` when the current state has no `meta.route`, or when the route
-     * template cannot be fully resolved — a required `:param` absent from context
-     * is caught internally (`MissingRouteParamError` never escapes `get()`): the
-     * condition is transient mid-transition and the signal recomputes on the next
+     * It returns `null` when the current state has no `meta.route` field, and also when
+     * it cannot resolve the complete route template. A necessary `:param` that the
+     * context does not hold is caught inside the signal, and a
+     * `MissingRouteParamError` therefore never leaves `get()`: that condition is
+     * temporary during a transition, and the signal computes the value again on the next
      * snapshot.
      *
      * @example
      * ```typescript
-     * // Returns "/profile/alice" when context.params.userId === "alice",
-     * // and null while the param is still missing.
+     * // It returns "/profile/alice" when context.params.userId === "alice",
+     * // and null while the param is still absent.
      * const route = actor.currentRoute.get();
      * ```
      */
     currentRoute;
     /**
-     * The route derived from the machine's initial state — fixed at construction,
-     * never changes even when the actor is restored from a snapshot.
+     * The route of the initial state of the machine. The constructor fixes it, and it
+     * never changes, also when the code restores the actor from a snapshot.
      *
-     * Router bridges compare this against the browser URL to distinguish a deep-link
-     * (non-initial URL → router wins) from a restore (initial URL + actor at a
-     * different restored route → actor wins).
+     * A router bridge compares it with the browser URL, and it therefore separates a
+     * deep link (a URL that is not the initial one → the router wins) from a restore
+     * (the initial URL, and the actor at a different route from the restore → the actor
+     * wins).
      *
-     * Derived statically from the machine definition via `deriveInitialRoute`
-     * (XState's pure `initialTransition` helper): the initial state chain and its
-     * `meta.route` templates are fixed at machine definition time, while `:param`
-     * substitution uses the machine's real initial context for this actor's `input`.
-     * No extra actor is ever created, and a restored snapshot never influences the
-     * value — it is always the machine's **default** initial route.
+     * `deriveInitialRoute` derives the value statically from the machine definition,
+     * with the pure `initialTransition` helper of XState: the chain of the initial states
+     * and their `meta.route` templates are fixed at the moment of the machine
+     * definition, and the substitution of a `:param` uses the real initial context of
+     * the machine for the `input` of this actor. The code makes no second actor, and a
+     * snapshot of a restore changes the value never: it is always the **default**
+     * initial route of the machine.
      */
     initialRoute;
     /**
-     * Reactive signal containing the current view spec derived from the active state's
-     * `meta.view` metadata.
+     * The reactive signal of the current view spec. The signal derives the spec from
+     * the `meta.view` metadata of the active state.
      *
-     * Emits a **fresh object reference** whenever the rendered view actually changes —
-     * a different state's view, or a param/context change that alters the resolved
-     * spec (including `reenter: true` re-entries with new params). Snapshots that do
-     * not change the rendered view (e.g. context-only assigns) keep the previous
-     * reference so downstream providers do not remount the UI on every event.
+     * It emits a **new object reference** on each real change of the view on the
+     * screen: the view of a different state, or a change of a param or of the context
+     * that changes the resolved spec. A re-entry with `reenter: true` and new params
+     * also changes the spec. A snapshot that changes no view on the screen, such as an
+     * assign of the context alone, keeps the previous reference. A provider below the
+     * signal therefore mounts the UI again not on every event.
      *
-     * The emitted `PlaySpec` carries the machine's context in its composed
-     * `state` under the read-only `/context` subtree, so specs read context —
-     * URL params included — through the ordinary state grammar
-     * (`{ $state: "/context/params/section" }`). See `@xmachines/play-actor`'s
-     * context-projection module for the full contract.
+     * The `PlaySpec` of the emission carries the context of the machine in its composed
+     * `state` field, under the read-only `/context` subtree. A spec therefore reads the
+     * context, and also each URL param, through the ordinary state grammar
+     * (`{ $state: "/context/params/section" }`). The context-projection module of
+     * `@xmachines/play-actor` holds the complete contract.
      *
-     * Returns `null` when the current state has no `meta.view` metadata.
+     * The signal returns `null` when the current state has no `meta.view` metadata.
      *
-     * Two states declaring separate but structurally identical `meta.view`
-     * literals emit distinct references on a transition between them (a
-     * provider remount); hoist the shared literal into one `typedSpec` constant
-     * to deduplicate by identity.
+     * Two states can declare two separate `meta.view` literals with an identical
+     * structure. A transition between those two states then emits two different
+     * references, and a provider mounts the UI again. Move the shared literal into one
+     * `typedSpec` constant, and the identity then removes the duplicate.
      *
      * @example
      * ```typescript
      * const view = actor.currentView.get();
      * if (view) {
-     *   console.log(view.root);     // e.g. "root"
-     *   console.log(view.elements); // @xmachines/json-render-core Spec elements
+     *   console.log(view.root);     // for example "root"
+     *   console.log(view.elements); // the Spec elements of @xmachines/json-render-core
      * }
      * ```
      */
     currentView = new Signal.State(null);
     constructor(machine, options, input, restoredSnapshot) {
-        // Defensive check before super(): a non-object machine fails deep inside
-        // XState's constructor with an opaque TypeError instead of a coded error.
+        // A defensive check before super(): a machine that is not an object fails deep
+        // inside the constructor of XState, with an opaque TypeError, and not with a coded
+        // error.
         if (!machine || typeof machine !== "object") {
             throw new InvalidMachineError();
         }
-        // THIS is the actor. The machine and its runtime options go straight to
-        // XState's Actor constructor — the same arguments `createActor` forwards
-        // — so there is no second instance to answer for the real one, and every
-        // Actor member we do not override operates on real state.
+        // THIS is the actor. The machine and its runtime options go directly to the Actor
+        // constructor of XState, which receives the same arguments as `createActor`
+        // forwards. Therefore no second instance answers for the real one, and every
+        // Actor member without an override here works on the real state.
         //
-        // XState 5.28.0: the options bag has a conditional type constraint on
-        // `input` that TypeScript cannot resolve against an unbound generic
-        // TMachine. The cast stays inside the XState type system, and `input` is
-        // typed on this constructor's own signature, so callers keep their
-        // compile-time validation.
-        // Track XState typing improvements: https://github.com/statelyai/xstate/issues
+        // XState 5.28.0: the options object has a conditional type constraint on `input`,
+        // and TypeScript cannot resolve that constraint against an unbound generic
+        // TMachine. The cast stays inside the type system of XState, and the signature of
+        // this constructor gives `input` its type. Therefore each caller keeps the check
+        // at the compile time.
+        // Follow the improvements of the XState types: https://github.com/statelyai/xstate/issues
         super(machine, {
             input,
             snapshot: restoredSnapshot,
             inspect: options?.inspect,
         });
-        // Derive the machine's initial route for restore-vs-deeplink detection —
-        // always the machine's DEFAULT initial route, never the restored state's.
-        // Without a restored snapshot this actor's own pre-start snapshot IS that
-        // default initial state, so derive from it directly; only a restore needs
-        // XState's pure `initialTransition` helper, whose inert actor scope runs
-        // the machine's initial transition twice more (once with `input`
-        // undefined) — an XState quirk worth paying only when required.
+        // Derive the initial route of the machine, for the detection of a restore or a
+        // deep link. The value is always the DEFAULT initial route of the machine, and
+        // never the route of the restored state. Without a snapshot of a restore, the
+        // pre-start snapshot of this actor IS that default initial state, and the code
+        // derives the route from it directly. A restore alone needs the pure
+        // `initialTransition` helper of XState. The inert actor scope of that helper runs
+        // the initial transition of the machine two more times, and one of them has an
+        // undefined `input`. This is a quirk of XState, and it costs too much for each
+        // other case.
         this.initialRoute =
             restoredSnapshot === undefined
                 ? deriveCurrentRoute(this.getSnapshot())
                 : deriveInitialRoute(machine, input);
         this.playerOptions = options || {};
-        // Initialize state signal. Updates are synchronous (no microtask batching):
-        // XState already coalesces multiple transitions within a single send() into
-        // one subscription callback, and synchronous updates ensure guard-triggered
-        // redirects are immediately visible to router bridges.
+        // Initialize the state signal. Each update is synchronous, with no batching in a
+        // microtask: XState groups the transitions of one send() call into one
+        // subscription callback already, and a synchronous update shows each guard
+        // redirect to a router bridge at once.
         this.state = new Signal.State(this.getSnapshot());
-        // Initialize currentRoute computed signal
+        // Initialize the currentRoute computed signal
         this.currentRoute = new Signal.Computed(() => {
             const snapshot = this.state.get();
             return deriveCurrentRoute(snapshot);
         });
-        // Observe our own transitions. `super` rather than `this` so the
-        // next-only bookkeeping in the subscribe override stays about userland
-        // subscriptions only.
+        // Observe the transitions of this actor. The code uses `super`, and not `this`, so
+        // that the bookkeeping of the next-only subscriptions in the subscribe override
+        // stays about the subscriptions of the user code.
         super.subscribe({
             next: (snapshot) => {
-                // Only update on stable states: active snapshots and the
-                // "done" snapshot from a top-level final state. Error/stopped snapshots
-                // are skipped so signals never freeze on teardown artifacts.
+                // Update on a stable state only: an active snapshot, and the "done" snapshot of a
+                // final state at the top level. The code skips an error snapshot and a stopped
+                // snapshot. Therefore a signal never freezes on an artifact of a teardown.
                 if (isObservableSnapshot(snapshot)) {
-                    // State updates are synchronous so router bridges see guard redirects immediately.
+                    // Each state update is synchronous. Therefore a router bridge sees a guard redirect at once.
                     this.state.set(snapshot);
-                    // Validate and cache the view after state/currentRoute are current, before hooks.
-                    // Hook ordering is intentional:
-                    // 1. state/currentRoute updated
-                    // 2. currentView cached
-                    // 3. onStateChange hook
-                    // 4. send() then invokes onTransition
+                    // Check the view and keep it after state and currentRoute hold their new values,
+                    // and before the hooks.
+                    // The order of the hooks is deliberate:
+                    // 1. state and currentRoute receive their new values
+                    // 2. currentView holds the new view
+                    // 3. the onStateChange hook runs
+                    // 4. send() then calls onTransition
                     this.validateAndCacheView(snapshot);
-                    // Call onStateChange hook
+                    // Call the onStateChange hook
                     const onStateChange = this.hooks.onStateChange;
                     if (onStateChange) {
                         onStateChange(this, snapshot);
                     }
                 }
             },
-            // Always registered, handler read at DELIVERY time: the options bag is
-            // shared by reference, so an onError attached after construction still
-            // receives actor errors, and one removed later stops swallowing them.
-            // Without a handler the listener rethrows, which XState's observer
-            // dispatch routes to its global unhandled rethrow — the same loud
-            // default as not registering an error listener at all.
+            // The code registers the listener always, and it reads the handler at the moment
+            // of the DELIVERY: the options object is shared by its reference. Therefore an
+            // onError handler on that object after the construction still receives each actor
+            // error, and the removal of a handler stops the silence again.
+            // Without a handler, the listener throws the error again. The observer dispatch of
+            // XState then sends it to its global unhandled rethrow, which is the same loud
+            // default as a listener that the code registers not.
             error: (error) => {
                 const handler = this.hooks.onError;
                 if (handler) {
                     handler(this, toError(error));
                     return;
                 }
-                // A userland next-only subscription already makes XState report
-                // this delivery globally; rethrowing here too would double it.
+                // A next-only subscription of the user code makes XState report this delivery
+                // globally already. A second throw here reports it two times.
                 if ((this.nextOnlySubscriptions ?? 0) > 0) {
                     return;
                 }
                 throw error;
             },
         });
-        // Everything above is reachable from XState's own constructor callbacks;
-        // past this point the instance is whole.
+        // The callbacks of the constructor of XState can reach everything above. After this
+        // point the instance is complete.
         this.constructed = true;
     }
     /**
-     * Start the actor.
+     * Starts the actor.
      *
-     * Fires `onStart` on each real start — every transition from not-running to
-     * running, including a start after a stop, which XState allows (its own
-     * `start()` bails only while the actor is already RUNNING). A repeated call
-     * while running does not re-fire it, so a defensive double mount does not
-     * re-run `onStart` side effects for one actual start.
+     * The method fires `onStart` on each real start, which is every transition from
+     * "not running" to "running". A start after a stop is such a transition, and XState
+     * permits it: its own `start()` stops only while the actor RUNS already. A second
+     * call while the actor runs fires no hook. Therefore a defensive double mount runs
+     * the side effects of `onStart` one time for one real start.
      */
     start() {
-        // See stop(): a call reaching in through the construction window would
-        // run a half-built actor.
+        // See stop(): a call that reaches in through the construction window runs an actor
+        // that is not complete.
         if (!this.constructed) {
             return this;
         }
@@ -408,21 +429,21 @@ export class PlayerActor extends AbstractActor {
         return this;
     }
     /**
-     * Stop the actor and clean up.
+     * Stops the actor and cleans up.
      *
-     * Fires `onStop` only when the actor was actually running — mirroring
-     * XState, where stopping a never-started or already-stopped actor is a
-     * no-op with zero teardown — so paired cleanup never runs twice, nor
-     * against resources `onStart` never acquired. Stopping does not close the
-     * actor for good: a later `start()` is a fresh lifecycle and fires
-     * `onStart` again.
+     * The method fires `onStop` only when the actor ran. This matches XState, where a
+     * stop of an actor that never started, or of an actor that stopped already, does
+     * nothing and tears nothing down. Therefore the paired cleanup runs never two
+     * times, and it runs never against a resource that `onStart` did not take. A stop
+     * does not close the actor for ever: a later `start()` is a new lifecycle, and it
+     * fires `onStart` again.
      */
     stop() {
-        // A call reaching in through the construction window (a context factory
-        // stopping its own `self`) would mark the actor stopped before its
-        // internal subscription is registered — XState drops observers added to
-        // a stopped actor, so the signals would never move again. There is
-        // nothing to tear down mid-construction, so ignore it.
+        // A call that reaches in through the construction window, for example a context
+        // factory that stops its own `self`, marks the actor as stopped before the code
+        // registers its internal subscription. XState drops each observer of a stopped
+        // actor. The signals therefore move never again. There is nothing to tear down
+        // during the construction, and the code ignores such a call.
         if (!this.constructed) {
             return this;
         }
@@ -436,49 +457,52 @@ export class PlayerActor extends AbstractActor {
         return this;
     }
     /**
-     * Send an event to this actor.
+     * Sends an event to this actor.
      *
-     * The actor's state machine guards decide whether the event causes a transition.
-     * Pass any event from the machine's event union — domain events, routing events, etc.
+     * The guards of the state machine of the actor decide if the event causes a
+     * transition. Give any event of the event union of the machine: a domain event, a
+     * routing event, and so on.
      *
-     * @param event - An event from the machine's `EventFromLogic<TMachine>` union.
+     * @param event - An event of the `EventFromLogic<TMachine>` union of the machine.
      *
-     * @throws {InvalidEventError} When `event` is not a plain object (`null`, `undefined`,
-     *   a string, number, etc.). Import the class from `@xmachines/play-xstate/errors`.
+     * @throws {InvalidEventError} When `event` is not a plain object, for example
+     *   `null`, `undefined`, a string, or a number. Import the class from
+     *   `@xmachines/play-xstate/errors`.
      *
      * @example
      * ```typescript
-     * // Domain event (typed to machine's event union)
+     * // A domain event, with the type of the event union of the machine
      * actor.send({ type: "auth.login", userId: "123" });
      *
-     * // Routing event
+     * // A routing event
      * actor.send({ type: "play.route", to: "#home" });
      * ```
      */
     send(event) {
-        // Defensive check: Validate event is not null/undefined
+        // A defensive check: the event must not be null and not undefined
         if (!event || typeof event !== "object") {
             throw new InvalidEventError(event);
         }
-        // Inside the construction window there is no readable snapshot, and no
-        // hook can have been registered yet: deliver and return.
+        // Inside the construction window there is no readable snapshot, and no hook can
+        // exist yet: deliver the event and return.
         if (!this.constructed) {
             Actor.prototype.send.call(this, event);
             return;
         }
-        // Captured unconditionally — getSnapshot() is a single property read, and
-        // the options bag is live: an onTransition installed while this event is
-        // being processed (e.g. from onStateChange) must still fire for it with
-        // the correct pre-send snapshot.
+        // The code captures the snapshot always, because getSnapshot() is one property
+        // read, and because the options object is live: an onTransition handler that
+        // arrives during the processing of this event, for example from onStateChange,
+        // must still run for it, with the correct snapshot from before the send.
         const prevSnapshot = this.getSnapshot();
-        // Send to XState actor
-        // `AbstractActor` re-declares send() as abstract purely to narrow the
-        // event type, and TypeScript forbids super calls to an abstract member,
-        // so reach XState's implementation directly. `this` IS the actor, so this
-        // is exactly the call `super.send(event)` would make: the relay that
-        // emits the @xstate.event inspection event and enqueues on our mailbox.
+        // Send the event to the XState actor.
+        // `AbstractActor` declares send() as abstract for one reason only, to narrow the
+        // event type, and TypeScript forbids a super call to an abstract member.
+        // Therefore the code reaches the implementation of XState directly. `this` IS the
+        // actor. This call is therefore exactly the call of `super.send(event)`: the relay
+        // that emits the @xstate.event inspection event and puts the event in the mailbox
+        // of this actor.
         Actor.prototype.send.call(this, event);
-        // Call onTransition hook
+        // Call the onTransition hook
         const onTransition = this.hooks.onTransition;
         if (onTransition) {
             const nextSnapshot = this.getSnapshot();
@@ -486,19 +510,19 @@ export class PlayerActor extends AbstractActor {
         }
     }
     /**
-     * Get current snapshot
+     * Returns the current snapshot
      */
     getSnapshot() {
         return super.getSnapshot();
     }
     subscribe(nextListenerOrObserver, errorListener, completeListener) {
-        // XState's subscribe() normalizes function-or-observer internally; the cast
-        // only reconciles the overload signatures.
+        // The subscribe() method of XState accepts a function and also an observer, and it
+        // normalizes them internally. The cast joins the two overload signatures only.
         const subscription = super.subscribe(nextListenerOrObserver, errorListener, completeListener);
-        // Observers without an error listener make XState rethrow actor errors
-        // globally on their behalf; count them so the internal listener's own
-        // loud-default rethrow stands down while one is active (see the
-        // constructor's error listener).
+        // An observer without an error listener makes XState throw each actor error again,
+        // globally, for that observer. The code counts those observers. Therefore the loud
+        // default of the internal listener, which also throws again, stands down while one
+        // of them is active. See the error listener of the constructor.
         const hasErrorListener = typeof nextListenerOrObserver === "object" && nextListenerOrObserver !== null
             ? typeof nextListenerOrObserver.error === "function"
             : typeof errorListener === "function";
@@ -518,30 +542,31 @@ export class PlayerActor extends AbstractActor {
         };
     }
     /**
-     * Listen for events this actor emits via the `emit` action.
+     * Listens for the events that this actor emits with the `emit` action.
      *
-     * @param type - Emitted event type to listen for, or `"*"` for all.
-     * @param handler - Called with each matching emitted event.
-     * @returns Subscription with an `unsubscribe()` method.
+     * @param type - The type of the emitted event to listen for, or `"*"` for every event.
+     * @param handler - The actor calls it with each emitted event that matches.
+     * @returns The subscription, with an `unsubscribe()` method.
      */
     on(type, handler) {
         return super.on(type, handler);
     }
     /**
-     * Get this actor's persisted snapshot.
+     * Returns the persisted snapshot of this actor.
      *
-     * Suitable for serialization and later restoration via the factory's
-     * `restore.snapshot` option.
+     * Use it to serialize the state, and to restore it later with the
+     * `restore.snapshot` option of the factory.
      */
     getPersistedSnapshot(options) {
         const forward = super.getPersistedSnapshot;
         return forward.call(this, options);
     }
     /**
-     * Derive and cache the view at state entry — once per transition, stored in
-     * the signal rather than recomputed per read.
+     * Derives the view at the entry of a state, and keeps it. This happens one time for
+     * each transition. The signal holds the view, and the code computes it not on each
+     * read.
      *
-     * @param snapshot - Current XState snapshot
+     * @param snapshot - The current XState snapshot
      */
     validateAndCacheView(snapshot) {
         if (snapshot === this.lastViewSnapshot) {
@@ -550,19 +575,20 @@ export class PlayerActor extends AbstractActor {
         this.lastViewSnapshot = snapshot;
         try {
             const view = deriveCurrentView(snapshot);
-            // Emit only when the rendered view actually changed: deriveCurrentView
-            // returns a fresh object per call, so reference identity cannot tell,
-            // and re-emitting a fresh reference for a snapshot that does not alter
-            // the view (e.g. a context-only assign) would make downstream providers
-            // remount the UI, wiping in-view state. Deep equality is deliberately
-            // NOT used here — it cannot see inside Maps/Sets (suppressing genuine
-            // changes) and recurses forever on cyclic props. The last emitted spec
-            // IS the signal's current value; read it untracked so the gate never
-            // registers currentView as a dependency of a surrounding computation.
+            // Emit only after a real change of the view on the screen: deriveCurrentView
+            // returns a fresh object on each call, and the identity of the reference therefore
+            // tells nothing. A new reference for a snapshot that changes the view not, for
+            // example a context-only assign, makes a provider below mount the UI again, and
+            // that removes the state of the view. A deep equality test is deliberately NOT
+            // here: it sees nothing inside a Map or a Set, and it therefore stops a real
+            // change, and it recurses without an end on a cyclic prop. The last spec of an
+            // emission IS the current value of the signal. Read it without a track, so that
+            // the gate registers currentView never as a dependency of a computation around
+            // it.
             const lastEmittedView = Signal.subtle.untrack(() => this.currentView.get());
-            // Reuse the previous composed state reference when the /context
-            // projection is value-unchanged, so a context-only assign that does
-            // not alter projected values cannot churn state identity.
+            // Use the reference of the previous composed state again when the value of the
+            // /context projection did not change. A context-only assign that changes no
+            // projected value therefore changes the identity of the state not.
             const nextView = reuseComposedState(lastEmittedView, view);
             if (viewSpecsEquivalent(lastEmittedView, nextView)) {
                 return;
@@ -574,11 +600,13 @@ export class PlayerActor extends AbstractActor {
             if (onError) {
                 onError(this, toError(error));
             }
-            // On error: keep the last valid view (don't clear)
+            // On an error: keep the last valid view, and clear it not
         }
     }
     /**
-     * Convenience dispose method for cleanup — an alias for {@link stop}.
+     * The dispose method, for the cleanup. It is the alias of {@link stop}.
+     *
+     * @deprecated Use {@link stop}. Will be removed in the next major.
      */
     dispose() {
         this.stop();