@xmachines/play-xstate 1.0.0-beta.8 → 1.0.0

package/dist/player-actor.js

@@ -1,9 +1,8 @@
 import { createActor, } from "xstate";
-import { AbstractActor, } from "@xmachines/play-actor";
+import { AbstractActor } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
-import { StateSignalManager } from "./signals/state-signal.js";
-import { deriveRoute, buildRouteUrl } from "./routing/index.js";
-import { validateComponentBinding, validateViewProps, mergeViewProps, createMemoSignature, } from "./catalog/index.js";
+import { InvalidEventError, InvalidMachineError } from "./errors.js";
+import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
 const hasSnapshotStatus = (snapshot) => {
     if (!snapshot || typeof snapshot !== "object") {
         return false;
@@ -13,8 +12,236 @@ const hasSnapshotStatus = (snapshot) => {
     }
     return typeof snapshot.status === "string";
 };
-const isActiveSnapshot = (snapshot) => {
-    return hasSnapshotStatus(snapshot) && snapshot.status === "active";
+/**
+ * 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 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;
+};
+/**
+ * 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.
+ *
+ * @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" }
+ * ```
+ */
+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
+    }
+    // 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
+    }
+    return merged;
+}
+/**
+ * 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:
+ *
+ * - 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).
+ */
+const areViewSpecsEquivalent = (a, b) => {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    const aRecord = a;
+    const bRecord = b;
+    const topKeys = Object.keys(aRecord);
+    if (topKeys.length !== Object.keys(bRecord).length)
+        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);
+    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;
+    for (const key of elementKeys) {
+        const aElement = aElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        const bElement = bElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        if (aElement === bElement)
+            continue;
+        if (!aElement || !bElement)
+            return false;
+        const fieldKeys = Object.keys(aElement);
+        if (fieldKeys.length !== Object.keys(bElement).length)
+            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)
+            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
+ * ```
+ */
+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;
 };
 /**
  * Concrete XState actor implementing Play Architecture signal protocol
@@ -60,7 +287,7 @@ const isActiveSnapshot = (snapshot) => {
  * ```
  *
  * @example
- * Signal lifecycle with watchers (microtask batching)
+ * Signal lifecycle with watchers
  * ```typescript
  * import { Signal } from "@xmachines/play-signals";
  *
@@ -73,10 +300,10 @@ const isActiveSnapshot = (snapshot) => {
  *
  * watcher.watch(actor.state);
  * actor.send({ type: 'play.route', to: '#about' });
- * // Watcher notification scheduled via microtask
+ * // Watcher notification scheduled via microtask by the watcher itself
  * ```
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
+ * @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
@@ -92,75 +319,147 @@ const isActiveSnapshot = (snapshot) => {
  * cached and updated at state entry, not computed on every read.
  */
 export class PlayerActor extends AbstractActor {
-    _xstateActor;
-    _stateManager;
-    _options;
-    _catalog;
-    _viewSignal;
-    _lastViewMemo;
+    xstateActor;
+    playerOptions;
+    viewSignal;
+    /** Last spec emitted on the view signal — used to skip no-change re-emissions. */
+    lastEmittedView = null;
     // AbstractActor protocol requirements
     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.
+     *
+     * @example
+     * ```typescript
+     * if (actor.can({ type: "auth.logout" })) { ... }
+     * ```
+     */
+    can(event) {
+        return this.state.get().can(event);
+    }
+    /**
+     * 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`.
+     *
+     * @example
+     * ```typescript
+     * // Returns "/profile/alice" when context.userId === "alice"
+     * 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.
+     *
+     * 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).
+     *
+     * 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.
+     */
+    initialRoute;
+    /**
+     * Reactive signal containing the current view spec derived from the active state's
+     * `meta.view` metadata.
+     *
+     * 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 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.
+     *
+     * Returns `null` when the current state has no `meta.view` metadata.
+     *
+     * @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
+     * }
+     * ```
+     */
     currentView;
-    catalog;
-    constructor(machine, catalog, options, input) {
+    constructor(machine, options, input, restoredSnapshot) {
         // Defensive check: Validate machine before passing to createActor
         if (!machine || typeof machine !== "object") {
-            throw new Error("PlayerActor requires a valid XState machine");
+            throw new InvalidMachineError();
         }
         // Create XState actor
-        const xstateActor = createActor(machine, { input });
-        // Defensive check: Validate actor was created successfully
-        if (!xstateActor) {
-            throw new Error("Failed to create XState actor - machine may be null or invalid");
-        }
+        // XState 5.28.0: createActor() options has a conditional type constraint on `input` that
+        // TypeScript cannot resolve against an unbound generic TMachine parameter.
+        // Option B: 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.
+        // Track XState typing improvements: https://github.com/statelyai/xstate/issues
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const xstateActor = createActor(machine, {
+            input,
+            snapshot: restoredSnapshot,
+        });
         // Call AbstractActor constructor with actor logic
         super(xstateActor.logic);
-        this._xstateActor = xstateActor;
-        this._options = options || {};
-        this._catalog = catalog ?? {};
-        this.catalog = this._catalog;
-        // Initialize state signal manager
-        this._stateManager = new StateSignalManager(xstateActor.getSnapshot());
-        this.state = this._stateManager.signal;
+        // 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;
+        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._lastViewMemo = null;
+        this.viewSignal = new Signal.State(null);
         // Initialize currentRoute computed signal
         this.currentRoute = new Signal.Computed(() => {
             const snapshot = this.state.get();
-            // Defensive check: Validate snapshot exists and has getMeta
-            if (!snapshot || typeof snapshot.getMeta !== "function") {
-                return null;
-            }
-            const meta = snapshot.getMeta();
-            // Defensive check: Validate meta is an object
-            if (!meta || typeof meta !== "object") {
-                return null;
-            }
-            // Derive route from meta.route per Plan 04
-            const routeTemplate = deriveRoute(meta);
-            if (!routeTemplate) {
-                return null;
-            }
-            // Build full URL with params, query, hash
-            // Per CONTEXT.md: "Full URL generation including query params, hash, base path from context"
-            return buildRouteUrl(routeTemplate, snapshot.context ?? {});
+            return deriveCurrentRoute(snapshot);
         });
         // Expose view signal directly for proper watcher propagation
-        this.currentView = this._viewSignal;
+        this.currentView = this.viewSignal;
         // Subscribe to XState actor transitions
-        this._xstateActor.subscribe((snapshot) => {
-            // Only update on stable/active states per CONTEXT.md
-            if (isActiveSnapshot(snapshot)) {
-                // Update state signal with microtask batching
-                this._stateManager.scheduleUpdate(snapshot);
-                // Validate view at state entry per CONTEXT.md: "Prop validation: At state entry"
-                // This runs once per transition, not on every signal read
-                this._validateAndCacheView(snapshot);
+        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._options.onStateChange) {
-                    this._options.onStateChange(this, snapshot);
+                if (this.playerOptions.onStateChange) {
+                    this.playerOptions.onStateChange(this, snapshot);
                 }
             }
         });
@@ -171,10 +470,10 @@ export class PlayerActor extends AbstractActor {
      * Per RESEARCH.md Pitfall 1: Always call start() after creation
      */
     start() {
-        this._xstateActor.start();
+        this.xstateActor.start();
         // Call onStart hook
-        if (this._options.onStart) {
-            this._options.onStart(this);
+        if (this.playerOptions.onStart) {
+            this.playerOptions.onStart(this);
         }
         return this;
     }
@@ -182,54 +481,78 @@ export class PlayerActor extends AbstractActor {
      * Stop the actor and cleanup
      */
     stop() {
-        this._xstateActor.stop();
-        this._stateManager.dispose();
+        this.xstateActor.stop();
         // Call onStop hook
-        if (this._options.onStop) {
-            this._options.onStop(this);
+        if (this.playerOptions.onStop) {
+            this.playerOptions.onStop(this);
         }
         return this;
     }
     /**
-     * Send event to actor
+     * Send an event to the underlying XState actor.
      *
-     * Forwards events to the underlying XState actor. The actor's state machine
-     * guards determine whether each event is valid from the current state.
+     * 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.
      *
-     * @param event - Any event object with a type property
+     * @param event - An event from the machine's `EventFromLogic<TMachine>` union.
+     *
+     * @throws {InvalidEventError} When `event` is not a plain object (`null`, `undefined`,
+     *   a string, number, etc.). Import the class from `@xmachines/play-xstate/errors`.
      *
      * @example
      * ```typescript
-     * // Domain event
-     * actor.send({ type: 'auth.login', userId: '123' });
+     * // Domain event (typed to machine's event union)
+     * actor.send({ type: "auth.login", userId: "123" });
      *
      * // Routing event
-     * actor.send({ type: 'play.route', to: '#home' });
+     * actor.send({ type: "play.route", to: "#home" });
      * ```
      */
     send(event) {
         // Defensive check: Validate event is not null/undefined
         if (!event || typeof event !== "object") {
-            console.warn("PlayerActor.send() called with invalid event:", event);
-            return;
+            throw new InvalidEventError(event);
         }
         // Store previous state for onTransition hook
-        const prevSnapshot = this._xstateActor.getSnapshot();
+        const prevSnapshot = this.xstateActor.getSnapshot();
         // Send to XState actor
-        // EventFromLogic<TMachine> is narrower than PlayEvent at the type level,
-        // but at runtime both are plain { type: string, ...fields } objects.
-        this._xstateActor.send(event);
+        // EventFromLogic<TMachine> is exactly what xstateActor.send expects — no cast needed.
+        this.xstateActor.send(event);
         // Call onTransition hook
-        if (this._options.onTransition) {
-            const nextSnapshot = this._xstateActor.getSnapshot();
-            this._options.onTransition(this, prevSnapshot, nextSnapshot);
+        if (this.playerOptions.onTransition) {
+            const nextSnapshot = this.xstateActor.getSnapshot();
+            this.playerOptions.onTransition(this, prevSnapshot, nextSnapshot);
         }
     }
     /**
      * Get current snapshot
      */
     getSnapshot() {
-        return this._xstateActor.getSnapshot();
+        return this.xstateActor.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);
+    }
+    /**
+     * Listen for events emitted by the wrapped XState actor 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);
+    }
+    /**
+     * Get the persisted snapshot of the wrapped XState actor.
+     *
+     * Suitable for serialization and later restoration via the factory's
+     * `restore.snapshot` option.
+     */
+    getPersistedSnapshot() {
+        return this.xstateActor.getPersistedSnapshot();
     }
     /**
      * Validate view at state entry and cache result
@@ -239,86 +562,28 @@ export class PlayerActor extends AbstractActor {
      *
      * @param snapshot - Current XState snapshot
      */
-    _validateAndCacheView(snapshot) {
-        // Defensive check: Validate snapshot exists
-        if (!snapshot) {
-            this._lastViewMemo = null;
-            this._viewSignal.set(null);
-            return;
-        }
-        const meta = snapshot.getMeta();
-        // Defensive check: Validate meta is an object
-        if (!meta || typeof meta !== "object") {
-            this._lastViewMemo = null;
-            this._viewSignal.set(null);
-            return;
-        }
-        // Find meta.view in active state nodes
-        let viewMeta = null;
-        for (const [_stateId, stateMeta] of Object.entries(meta)) {
-            const maybeView = stateMeta && typeof stateMeta === "object"
-                ? stateMeta.view
-                : undefined;
-            if (maybeView && typeof maybeView === "object") {
-                viewMeta = maybeView;
-                break;
-            }
-        }
-        if (!viewMeta) {
-            this._lastViewMemo = null;
-            this._viewSignal.set(null);
-            return;
-        }
-        // Validate component binding
+    validateAndCacheView(snapshot) {
         try {
-            validateComponentBinding(viewMeta, this._catalog);
-        }
-        catch (error) {
-            // Call onError hook if validation fails
-            if (this._options.onError) {
-                this._options.onError(this, error);
+            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)) {
+                return;
             }
-            console.error("Catalog binding validation failed:", error);
-            this._viewSignal.set(null);
-            return;
-        }
-        // Merge meta.view with context for props
-        const props = mergeViewProps(viewMeta, snapshot.context);
-        const stateSignature = createMemoSignature(snapshot.value);
-        const propsSignature = createMemoSignature(props);
-        if (this._lastViewMemo &&
-            this._lastViewMemo.stateSignature === stateSignature &&
-            this._lastViewMemo.component === viewMeta.component &&
-            this._lastViewMemo.propsSignature === propsSignature) {
-            this._viewSignal.set({
-                component: this._lastViewMemo.view.component,
-                props: this._lastViewMemo.view.props,
-            });
-            return;
+            this.lastEmittedView = view;
+            this.viewSignal.set(view);
         }
-        // Validate props against Zod schema
-        const validation = validateViewProps(viewMeta.component, props, this._catalog);
-        if (!validation.success) {
-            // Call onError hook if prop validation fails
-            if (this._options.onError) {
-                this._options.onError(this, new Error(`Invalid props for component "${viewMeta.component}": ${validation.error?.message || "Unknown error"}`));
+        catch (error) {
+            if (this.playerOptions.onError) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.playerOptions.onError(this, err);
             }
-            console.error("View props validation failed:", validation.error);
-            // Store view structure even if validation fails (allow app to handle gracefully)
-            // Per RESEARCH.md open question: prefer error events over throwing in production
+            // On error: keep the last valid view (don't clear)
         }
-        // Cache validated view structure (validated once at state entry)
-        const newView = {
-            component: viewMeta.component,
-            props: validation.success ? validation.data : props,
-        };
-        this._lastViewMemo = {
-            stateSignature,
-            component: viewMeta.component,
-            propsSignature,
-            view: newView,
-        };
-        this._viewSignal.set(newView);
     }
     /**
      * Convenience dispose method for cleanup