@xmachines/play-xstate 2.0.0-alpha.1 → 2.1.0

package/dist/player-actor.js

@@ -1,125 +1,73 @@
-import { createActor, } from "xstate";
-import { AbstractActor } from "@xmachines/play-actor";
+import { Actor, } from "xstate";
+import { AbstractActor, reuseComposedState, shallowEqualExcept, } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
-import { InvalidEventError, InvalidMachineError } from "./errors.js";
+import { ActorThrewNonErrorError, InvalidEventError, InvalidMachineError } from "./errors.js";
 import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
-const hasSnapshotStatus = (snapshot) => {
-    if (!snapshot || typeof snapshot !== "object") {
-        return false;
-    }
-    if (!("status" in snapshot)) {
-        return false;
-    }
-    return typeof snapshot.status === "string";
-};
+import { deriveCurrentView } from "./view/derive-current-view.js";
 /**
- * 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 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 isObservableSnapshot = (snapshot) => {
-    return (hasSnapshotStatus(snapshot) && (snapshot.status === "active" || snapshot.status === "done"));
-};
-const resolveViewMeta = (meta) => {
-    // Iterate last-to-first: snapshot.getMeta() orders keys ancestors-first, so
-    // scanning from the end makes the deepest active state's meta.view win over
-    // an ancestor's instead of being shadowed by it.
-    const values = Object.values(meta);
-    for (let i = values.length - 1; i >= 0; i--) {
-        const stateMeta = values[i]; // nosemgrep: gitlab.eslint.detect-object-injection
-        const maybeView = stateMeta && typeof stateMeta === "object"
-            ? stateMeta.view
-            : undefined;
-        if (maybeView &&
-            typeof maybeView === "object" &&
-            "root" in maybeView &&
-            "elements" in maybeView) {
-            return maybeView;
-        }
-    }
-    return null;
+const isRealError = (value) => {
+    if (value instanceof Error)
+        return true;
+    const isError = Error.isError;
+    if (isError)
+        return isError(value);
+    return Object.prototype.toString.call(value) === "[object Error]";
 };
 /**
- * Merge route parameters and an explicit allowlist of context fields into a single
- * element's props.
- *
- * Priority rule (highest → lowest):
- * 1. Explicit non-`undefined` spec prop — always wins (static values are authoritative).
- * 2. URL route params (`context.params`) — fills `undefined` slots from the URL path.
- * 3. Allowlisted context fields (`contextProps`) — fills remaining `undefined` slots from
- *    the machine context (e.g. `context.username` on a state with no URL username param).
- *
- * The `contextProps` allowlist is the key safety mechanism: only fields the machine
- * explicitly opts in to are ever exposed to components.
- *
- * @param urlParams - Extracted URL path parameters from `context.params`.
- * @param contextValues - Object containing only the allowlisted context fields.
- * @param existingProps - The element's props as declared in the machine spec.
- * @returns Merged props object with URL params and allowlisted context values filling
- *   undefined slots.
+ * Normalizes a failure of the actor for `onError`.
  *
- * @example
- * ```ts
- * // spec:          { section: undefined, username: undefined, title: "Dashboard" }
- * // urlParams:     { section: "profile" }            ← from URL /:section
- * // contextValues: { username: "alice" }              ← from contextProps: ["username"]
- * // result:        { section: "profile", username: "alice", title: "Dashboard" }
- * ```
+ * 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`.
  */
-function mergeRouteParamsIntoProps(urlParams, contextValues, existingProps) {
-    // Layer 3 (lowest priority): allowlisted context values
-    const merged = { ...contextValues };
-    // Layer 2: URL params override context values for the same key
-    for (const [k, v] of Object.entries(urlParams)) {
-        merged[k] = v; // nosemgrep: gitlab.eslint.detect-object-injection
+const toError = (value) => {
+    try {
+        if (isRealError(value)) {
+            return value;
+        }
     }
-    // Layer 1 (highest priority): explicit non-undefined spec props always win
-    for (const [k, v] of Object.entries(existingProps)) {
-        if (v !== undefined)
-            merged[k] = v; // nosemgrep: gitlab.eslint.detect-object-injection
+    catch {
+        // 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 merged;
-}
+    return new ActorThrewNonErrorError(value);
+};
 /**
- * Compare two derived `PlaySpec` objects for rendered-view equivalence.
- *
- * `deriveCurrentView` returns a fresh object on every call, so reference equality
- * cannot tell whether the view actually changed. This helper performs a cheap
- * structural comparison over the inputs that determine the rendered output:
+ * The structural equality of two derived view specs, with a limit on its depth.
  *
- * - Top-level spec fields (`root`, `contextProps`, …) by identity — they are
- *   primitives or references copied unchanged from the machine's stable `meta.view`.
- * - Per-element fields other than `props` by identity — same reasoning.
- * - Element `props` by shallow `Object.is` per key — this is where URL params and
- *   allowlisted context values are merged in, so a param/context change that alters
- *   the rendered spec is detected here.
- *
- * Used by `PlayerActor.validateAndCacheView` to skip re-emitting the view signal
- * for snapshots that do not change the rendered view (e.g. context-only assigns).
+ * 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 areViewSpecsEquivalent = (a, b) => {
+const viewSpecsEquivalent = (a, b) => {
     if (a === b)
         return true;
-    if (a === null || b === null)
+    if (!a || !b)
         return false;
-    const aRecord = a;
-    const bRecord = b;
-    const topKeys = Object.keys(aRecord);
-    if (topKeys.length !== Object.keys(bRecord).length)
+    if (!shallowEqualExcept(a, b, "elements"))
         return false;
-    for (const key of topKeys) {
-        if (key === "elements")
-            continue;
-        if (!Object.is(aRecord[key], bRecord[key]))
-            return false; // nosemgrep: gitlab.eslint.detect-object-injection
-    }
-    const aElements = (aRecord.elements ?? null);
-    const bElements = (bRecord.elements ?? null);
+    const aElements = a.elements ?? {};
+    const bElements = b.elements ?? {};
+    // 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;
-    if (aElements === null || bElements === null)
-        return false;
     const elementKeys = Object.keys(aElements);
     if (elementKeys.length !== Object.keys(bElements).length)
         return false;
@@ -130,140 +78,47 @@ const areViewSpecsEquivalent = (a, b) => {
             continue;
         if (!aElement || !bElement)
             return false;
-        const fieldKeys = Object.keys(aElement);
-        if (fieldKeys.length !== Object.keys(bElement).length)
+        if (!shallowEqualExcept(aElement, bElement, "props"))
             return false;
-        for (const field of fieldKeys) {
-            if (field === "props")
-                continue;
-            if (!Object.is(aElement[field], bElement[field]))
-                return false; // nosemgrep: gitlab.eslint.detect-object-injection
-        }
-        const aProps = (aElement.props ?? {});
-        const bProps = (bElement.props ?? {});
-        const propKeys = Object.keys(aProps);
-        if (propKeys.length !== Object.keys(bProps).length)
+        if (!shallowEqualExcept(aElement.props ?? {}, bElement.props ?? {}))
             return false;
-        for (const prop of propKeys) {
-            if (!Object.is(aProps[prop], bProps[prop]))
-                return false; // nosemgrep: gitlab.eslint.detect-object-injection
-        }
     }
     return true;
 };
 /**
- * Derive the actor's current view from state metadata.
- *
- * Always returns a **fresh** `PlaySpec` object so a genuine view change is never
- * suppressed by `Signal.State`'s `Object.is` equality check. Whether that fresh
- * object is actually emitted is decided by `PlayerActor.validateAndCacheView`,
- * which compares against the last emitted spec (see {@link areViewSpecsEquivalent})
- * and skips emission when the rendered view is unchanged — preventing downstream
- * providers from remounting the UI on every event.
- *
- * ### Prop enrichment
- *
- * Each spec element's `props` are enriched before the view is emitted using two sources:
- *
- * **1. URL route params** (`context.params`, populated by `formatPlayRouteTransitions`):
- * Makes `:section?` / `:username` URL path parameters automatically available as component
- * props without manual wiring.
- *
- * **2. Context fields** (`spec.contextProps` allowlist):
- * Exposes selected context fields as component props for states where no URL param covers
- * the data (e.g. `context.username` on a `/dashboard` route). Only fields explicitly named
- * in `spec.contextProps: string[]` are ever exposed — nothing leaks from context implicitly.
- *
- * Merge priority (see `mergeRouteParamsIntoProps`):
- * 1. Explicit non-`undefined` spec prop — always wins (authoritative static value).
- * 2. URL route param (`context.params`) — fills `undefined` slots from the URL path.
- * 3. Allowlisted context field (`contextProps`) — fills remaining `undefined` slots.
- *
- * @param snapshot - Current XState machine snapshot.
- * @returns Enriched `PlaySpec`, or `null` if the current state has no view metadata.
- *
- * @example
- * ```ts
- * // spec: { contextProps: ["username"], elements: { root: { props: { username: undefined } } } }
- * // context.username = "alice", context.params = {}
- * // Derived props: { username: "alice" }
- *
- * // spec: { contextProps: ["username"], elements: { root: { props: { username: undefined } } } }
- * // context.username = "alice", context.params = { username: "demo" }
- * // Derived props: { username: "demo" }  ← URL param wins
- * ```
+ * 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 deriveCurrentView = (snapshot) => {
-    if (!snapshot) {
-        return null;
-    }
-    const meta = snapshot.getMeta();
-    if (!meta || typeof meta !== "object") {
-        return null;
-    }
-    const viewMeta = resolveViewMeta(meta);
-    if (!viewMeta) {
-        return null;
-    }
-    // Extract params from context (set by formatPlayRouteTransitions on play.route events)
-    const context = snapshot.context !== null &&
-        snapshot.context !== undefined &&
-        typeof snapshot.context === "object"
-        ? snapshot.context
-        : null;
-    const urlParams = context !== null && typeof context.params === "object" && context.params !== null
-        ? context.params
-        : {};
-    // Extract the allowlisted context fields declared in contextProps.
-    // Only fields explicitly named in the allowlist are ever exposed to components.
-    const contextPropsAllowlist = viewMeta?.contextProps ?? [];
-    const contextValues = {};
-    if (context !== null && contextPropsAllowlist.length > 0) {
-        for (const key of contextPropsAllowlist) {
-            // nosemgrep: gitlab.eslint.detect-object-injection
-            if (key in context && context[key] !== null && context[key] !== undefined) {
-                contextValues[key] = context[key]; // nosemgrep: gitlab.eslint.detect-object-injection
-            }
-        }
-    }
-    // Enrich element props when there is anything to merge.
-    if (viewMeta?.elements) {
-        const enrichedElements = Object.fromEntries(Object.entries(viewMeta.elements).map(([key, el]) => {
-            const element = el;
-            const existingProps = element.props ?? {};
-            return [
-                key,
-                {
-                    ...element,
-                    props: mergeRouteParamsIntoProps(urlParams, contextValues, existingProps),
-                },
-            ];
-        }));
-        return { ...viewMeta, elements: enrichedElements };
-    }
-    return viewMeta;
-};
+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} to provide XState v6 integration
- * while maintaining ecosystem compatibility (XState inspection, devtools). This actor
- * wraps an internal XState actor and exposes TC39 Signal-based reactive state for
- * Infrastructure observation.
+ * 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 v6 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";
@@ -272,7 +127,14 @@ const deriveCurrentView = (snapshot) => {
  *   initial: 'idle',
  *   states: {
  *     idle: {
- *       meta: { route: '/', view: { component: 'HomePage' } }
+ *       meta: {
+ *         route: '/',
+ *         // A view spec needs `root` and `elements`. Every other shape derives null.
+ *         view: {
+ *           root: 'home',
+ *           elements: { home: { type: 'HomePage', props: {}, children: [] } },
+ *         },
+ *       },
  *     }
  *   }
  * });
@@ -281,13 +143,13 @@ const deriveCurrentView = (snapshot) => {
  * const actor = createPlayer();
  * actor.start();
  *
- * // Observe signals
- * console.log(actor.currentRoute.get()); // '/'
- * console.log(actor.currentView.get());  // { component: 'HomePage' }
+ * // 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";
  *
@@ -300,39 +162,63 @@ const deriveCurrentView = (snapshot) => {
  *
  * 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 {
-    xstateActor;
     playerOptions;
-    viewSignal;
-    /** Last spec emitted on the view signal — used to skip no-change re-emissions. */
-    lastEmittedView = null;
-    // AbstractActor protocol requirements
-    // XState v6: machine.transition() returns a [snapshot, actions] tuple, so the
-    // snapshot type comes from SnapshotFrom<TMachine> instead of its return type.
+    /**
+     * The live options object of the caller, or an empty object during the construction.
+     *
+     * 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 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 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;
+    // 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. Delegates to the underlying XState actor's snapshot.
+     * 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
@@ -340,261 +226,387 @@ export class PlayerActor extends AbstractActor {
      * ```
      */
     can(event) {
-        // SnapshotFrom<TMachine> does not narrow to MachineSnapshot for an unbound
-        // generic TMachine, so widen to AnyMachineSnapshot for the .can() call. The
-        // public signature stays typed to the machine's event union.
-        return this.state.get().can(event);
+        // 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 (e.g. a required parameter is absent from
-     * context).
-     *
-     * @throws {MissingRouteParamError} When a required `:param` placeholder in the
-     *   route template has no matching value in the actor's context. Import the class
-     *   from `@xmachines/play-xstate/errors`.
+     * 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.userId === "alice"
+     * // 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.
+     *
+     * 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.
      *
-     * 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.
+     * 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.
      *
-     * The emitted `PlaySpec` has its element `props` enriched with `context.params`
-     * before emission — URL path parameters (e.g. `:section?`) flow into component props
-     * automatically. See `mergeRouteParamsIntoProps` for the merge priority rules.
+     * The signal returns `null` when the current state has no `meta.view` metadata.
      *
-     * Returns `null` when the current state has no `meta.view` metadata.
+     * 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;
+    currentView = new Signal.State(null);
     constructor(machine, options, input, restoredSnapshot) {
-        // Defensive check: Validate machine before passing to createActor
+        // 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();
         }
-        // Create XState actor
-        // XState v6: createActor() intersects ActorOptions with a mapped type over
-        // RequiredActorOptionsKeys<TLogic>, which TypeScript cannot resolve against
-        // an unbound generic TMachine — and under exactOptionalPropertyTypes an
-        // `input: InputFrom<TMachine> | undefined` property does not satisfy it.
-        // Cast to ActorOptions<TMachine> — narrower than `as any` because we remain
-        // within the XState type system. The `input` parameter is typed as
-        // InputFrom<TMachine> at the constructor call site, so consumers receive
-        // compile-time validation.
-        const xstateActor = createActor(machine, {
+        // 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 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,
         });
-        // Call AbstractActor constructor with actor logic
-        super(xstateActor.logic);
-        // Derive the machine's initial route for restore-vs-deeplink detection.
-        // Statically computed from the machine definition + this actor's input via
-        // XState's pure `initialTransition` helper — no extra actor, and independent
-        // of any restored snapshot, so bridges always see the machine's DEFAULT
-        // initial route rather than the restored state's.
-        this.initialRoute = deriveInitialRoute(machine, input);
-        this.xstateActor = xstateActor;
+        // 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.
-        this.state = new Signal.State(xstateActor.getSnapshot());
-        // Initialize view signal
-        this.viewSignal = new Signal.State(null);
-        // Initialize currentRoute computed signal
+        // 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 the currentRoute computed signal
         this.currentRoute = new Signal.Computed(() => {
             const snapshot = this.state.get();
             return deriveCurrentRoute(snapshot);
         });
-        // Expose view signal directly for proper watcher propagation
-        this.currentView = this.viewSignal;
-        // Subscribe to XState actor transitions
-        this.xstateActor.subscribe((snapshot) => {
-            // Only update on stable states per CONTEXT.md: active snapshots and the
-            // "done" snapshot from a top-level final state. Error/stopped snapshots
-            // are skipped so signals never freeze on teardown artifacts.
-            if (isObservableSnapshot(snapshot)) {
-                // State updates are synchronous so router bridges see guard redirects immediately.
-                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
-                this.validateAndCacheView(snapshot);
-                // Call onStateChange hook
-                if (this.playerOptions.onStateChange) {
-                    this.playerOptions.onStateChange(this, snapshot);
+        // 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) => {
+                // 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)) {
+                    // Each state update is synchronous. Therefore a router bridge sees a guard redirect at once.
+                    this.state.set(snapshot);
+                    // 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 the onStateChange hook
+                    const onStateChange = this.hooks.onStateChange;
+                    if (onStateChange) {
+                        onStateChange(this, snapshot);
+                    }
                 }
-            }
+            },
+            // 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 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;
+            },
         });
+        // 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.
      *
-     * Per RESEARCH.md Pitfall 1: Always call start() after creation
+     * 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() {
-        this.xstateActor.start();
-        // Call onStart hook
-        if (this.playerOptions.onStart) {
-            this.playerOptions.onStart(this);
+        // See stop(): a call that reaches in through the construction window runs an actor
+        // that is not complete.
+        if (!this.constructed) {
+            return this;
+        }
+        super.start();
+        if (this.lifecycle !== "running") {
+            this.lifecycle = "running";
+            const onStart = this.hooks.onStart;
+            if (onStart) {
+                onStart(this);
+            }
         }
         return this;
     }
     /**
-     * Stop the actor and cleanup
+     * Stops the actor and cleans up.
+     *
+     * 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() {
-        this.xstateActor.stop();
-        // Call onStop hook
-        if (this.playerOptions.onStop) {
-            this.playerOptions.onStop(this);
+        // 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;
+        }
+        super.stop();
+        const wasRunning = this.lifecycle === "running";
+        this.lifecycle = "stopped";
+        const onStop = this.hooks.onStop;
+        if (wasRunning && onStop) {
+            onStop(this);
         }
         return this;
     }
     /**
-     * Send an event to the underlying XState 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);
         }
-        // Store previous state for onTransition hook
-        const prevSnapshot = this.xstateActor.getSnapshot();
-        // Send to XState actor
-        // EventFromLogic<TMachine> is exactly what xstateActor.send expects — no cast needed.
-        this.xstateActor.send(event);
-        // Call onTransition hook
-        if (this.playerOptions.onTransition) {
-            const nextSnapshot = this.xstateActor.getSnapshot();
-            this.playerOptions.onTransition(this, prevSnapshot, nextSnapshot);
+        // 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;
+        }
+        // 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 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 the onTransition hook
+        const onTransition = this.hooks.onTransition;
+        if (onTransition) {
+            const nextSnapshot = this.getSnapshot();
+            onTransition(this, prevSnapshot, nextSnapshot);
         }
     }
     /**
-     * Get current snapshot
+     * Returns the current snapshot
      */
     getSnapshot() {
-        return this.xstateActor.getSnapshot();
+        return super.getSnapshot();
     }
     subscribe(nextListenerOrObserver, errorListener, completeListener) {
-        // XState's subscribe() normalizes function-or-observer internally; the cast
-        // only reconciles the overload signatures.
-        return this.xstateActor.subscribe(nextListenerOrObserver, errorListener, completeListener);
+        // 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);
+        // 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";
+        if (hasErrorListener) {
+            return subscription;
+        }
+        this.nextOnlySubscriptions = (this.nextOnlySubscriptions ?? 0) + 1;
+        let counted = true;
+        return {
+            unsubscribe: () => {
+                if (counted) {
+                    counted = false;
+                    this.nextOnlySubscriptions = (this.nextOnlySubscriptions ?? 1) - 1;
+                }
+                subscription.unsubscribe();
+            },
+        };
     }
     /**
-     * Listen for events emitted by the wrapped XState actor 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 this.xstateActor.on(type, handler);
+        return super.on(type, handler);
     }
     /**
-     * Get the persisted snapshot of the wrapped XState actor.
+     * 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() {
-        return this.xstateActor.getPersistedSnapshot();
+    getPersistedSnapshot(options) {
+        const forward = super.getPersistedSnapshot;
+        return forward.call(this, options);
     }
     /**
-     * Validate view at state entry and cache result
+     * 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.
      *
-     * Per CONTEXT.md: "Prop validation: At state entry (when state becomes active)"
-     * Validates once per transition and stores result in signal.
-     *
-     * @param snapshot - Current XState snapshot
+     * @param snapshot - The current XState snapshot
      */
     validateAndCacheView(snapshot) {
+        if (snapshot === this.lastViewSnapshot) {
+            return;
+        }
+        this.lastViewSnapshot = snapshot;
         try {
             const view = deriveCurrentView(snapshot);
-            // Emit only when the rendered view actually changed. deriveCurrentView
-            // returns a fresh object on every call (so genuine changes always pass
-            // Signal.State's Object.is gate), but re-emitting a fresh reference for
-            // snapshots that do not alter the view (e.g. context-only assigns) would
-            // make downstream providers treat every event as a view transition and
-            // remount the UI, wiping in-view state.
-            if (areViewSpecsEquivalent(this.lastEmittedView, view)) {
+            // 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());
+            // 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;
             }
-            this.lastEmittedView = view;
-            this.viewSignal.set(view);
+            this.currentView.set(nextView);
         }
         catch (error) {
-            if (this.playerOptions.onError) {
-                const err = error instanceof Error ? error : new Error(String(error));
-                this.playerOptions.onError(this, err);
+            const onError = this.hooks.onError;
+            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
+     * The dispose method, for the cleanup. It is the alias of {@link stop}.
      *
-     * Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
+     * @deprecated Use {@link stop}. Will be removed in the next major.
      */
     dispose() {
         this.stop();