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

package/dist/player-actor.js

@@ -1,125 +1,67 @@
-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.
+ * 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.
  */
-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.
+ * Normalize an actor failure for `onError`.
  *
- * @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.
- *
- * @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" }
- * ```
+ * 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`.
  */
-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 {
+        // Classification itself can throw for hostile values (a revoked Proxy
+        // traps both instanceof and brand inspection) — fall through and wrap.
     }
-    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:
+ * Bounded structural equality for derived view specs.
  *
- * - 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).
+ * 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.
  */
-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 ?? {};
+    // Derived specs spread the same static meta.view, so elements is usually
+    // reference-identical — skip the per-element walk when it is.
     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,126 +72,29 @@ 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
- * ```
+ * 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.
  */
-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
  *
- * 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.
+ * 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.
  *
  * **Capabilities:** Implements both {@link @xmachines/play-actor!Routable} and
  * {@link @xmachines/play-actor!Viewable} interfaces, providing routing and view
@@ -260,7 +105,7 @@ const deriveCurrentView = (snapshot) => {
  * the actor's signals (`state`, `currentRoute`, `currentView`) but cannot directly
  * manipulate state—all mutations flow through the state machine's event handlers.
  *
- * @typeParam TMachine - XState v6 state machine type
+ * @typeParam TMachine - XState v5 state machine type
  *
  * @example
  * Basic actor creation and lifecycle
@@ -272,7 +117,14 @@ const deriveCurrentView = (snapshot) => {
  *   initial: 'idle',
  *   states: {
  *     idle: {
- *       meta: { route: '/', view: { component: 'HomePage' } }
+ *       meta: {
+ *         route: '/',
+ *         // A view spec needs `root` and `elements` — other shapes derive null.
+ *         view: {
+ *           root: 'home',
+ *           elements: { home: { type: 'HomePage', props: {}, children: [] } },
+ *         },
+ *       },
  *     }
  *   }
  * });
@@ -282,8 +134,8 @@ const deriveCurrentView = (snapshot) => {
  * actor.start();
  *
  * // Observe signals
- * console.log(actor.currentRoute.get()); // '/'
- * console.log(actor.currentView.get());  // { component: 'HomePage' }
+ * console.log(actor.currentRoute.get());          // '/'
+ * console.log(actor.currentView.get()?.root);     // 'home'
  * ```
  *
  * @example
@@ -319,20 +171,42 @@ const deriveCurrentView = (snapshot) => {
  * cached and updated at state entry, not computed on every 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;
+    /**
+     * The caller's live options bag, or an empty one during 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.
+     *
+     * 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.
+     */
+    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.
+     */
+    lastViewSnapshot = undefined;
     // 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.
     state;
     /**
      * Returns whether the actor's current state can accept 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.
+     * compile error. Evaluated against the current snapshot signal.
      *
      * @example
      * ```typescript
@@ -340,26 +214,28 @@ 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);
+        // 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.
+        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.
      *
      * 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`.
+     * 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
+     * snapshot.
      *
      * @example
      * ```typescript
-     * // Returns "/profile/alice" when context.userId === "alice"
+     * // Returns "/profile/alice" when context.params.userId === "alice",
+     * // and null while the param is still missing.
      * const route = actor.currentRoute.get();
      * ```
      */
@@ -390,12 +266,19 @@ export class PlayerActor extends AbstractActor {
      * 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 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 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.
      *
      * 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.
+     *
      * @example
      * ```typescript
      * const view = actor.currentView.get();
@@ -405,97 +288,155 @@ export class PlayerActor extends AbstractActor {
      * }
      * ```
      */
-    currentView;
+    currentView = new Signal.State(null);
     constructor(machine, options, input, restoredSnapshot) {
-        // Defensive check: Validate machine before passing to createActor
+        // Defensive check before super(): a non-object machine fails deep inside
+        // XState's constructor with an opaque TypeError instead of 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
+        // 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.
+        //
+        // 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.
-        const xstateActor = createActor(machine, {
+        // Track XState typing improvements: 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 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.
+        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);
+        this.state = new Signal.State(this.getSnapshot());
         // Initialize 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 our own transitions. `super` rather than `this` so the
+        // next-only bookkeeping in the subscribe override stays about userland
+        // subscriptions only.
+        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.
+                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
+                    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.
+            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.
+                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.
+        this.constructed = true;
     }
     /**
-     * Start the actor
+     * Start the actor.
      *
-     * Per RESEARCH.md Pitfall 1: Always call start() after creation
+     * 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.
      */
     start() {
-        this.xstateActor.start();
-        // Call onStart hook
-        if (this.playerOptions.onStart) {
-            this.playerOptions.onStart(this);
+        // See stop(): a call reaching in through the construction window would
+        // run a half-built actor.
+        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
+     * Stop the actor and clean 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.
      */
     stop() {
-        this.xstateActor.stop();
-        // Call onStop hook
-        if (this.playerOptions.onStop) {
-            this.playerOptions.onStop(this);
+        // 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.
+        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.
+     * Send 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.
@@ -519,82 +460,125 @@ export class PlayerActor extends AbstractActor {
         if (!event || typeof event !== "object") {
             throw new InvalidEventError(event);
         }
-        // Store previous state for onTransition hook
-        const prevSnapshot = this.xstateActor.getSnapshot();
+        // Inside the construction window there is no readable snapshot, and no
+        // hook can have been registered yet: deliver 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.
+        const prevSnapshot = this.getSnapshot();
         // Send to XState actor
-        // EventFromLogic<TMachine> is exactly what xstateActor.send expects — no cast needed.
-        this.xstateActor.send(event);
+        // `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.
+        Actor.prototype.send.call(this, event);
         // Call onTransition hook
-        if (this.playerOptions.onTransition) {
-            const nextSnapshot = this.xstateActor.getSnapshot();
-            this.playerOptions.onTransition(this, prevSnapshot, nextSnapshot);
+        const onTransition = this.hooks.onTransition;
+        if (onTransition) {
+            const nextSnapshot = this.getSnapshot();
+            onTransition(this, prevSnapshot, nextSnapshot);
         }
     }
     /**
      * Get 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);
+        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).
+        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.
+     * Listen for events this actor emits via 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.
      */
     on(type, handler) {
-        return this.xstateActor.on(type, handler);
+        return super.on(type, handler);
     }
     /**
-     * Get the persisted snapshot of the wrapped XState actor.
+     * Get this actor's persisted snapshot.
      *
      * Suitable for serialization and later restoration via the factory's
      * `restore.snapshot` option.
      */
-    getPersistedSnapshot() {
-        return this.xstateActor.getPersistedSnapshot();
+    getPersistedSnapshot(options) {
+        const forward = super.getPersistedSnapshot;
+        return forward.call(this, options);
     }
     /**
-     * Validate view at state entry and cache result
-     *
-     * Per CONTEXT.md: "Prop validation: At state entry (when state becomes active)"
-     * Validates once per transition and stores result in signal.
+     * Derive and cache the view at state entry — once per transition, stored in
+     * the signal rather than recomputed per read.
      *
      * @param snapshot - 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 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.
+            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.
+            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)
         }
     }
     /**
-     * Convenience dispose method for cleanup
-     *
-     * Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
+     * Convenience dispose method for cleanup — an alias for {@link stop}.
      */
     dispose() {
         this.stop();