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

package/dist/player-actor.d.ts

@@ -1,14 +1,16 @@
-import { type AnyStateMachine, type Actor, type AnyActorLogic, type EmittedFrom, type InputFrom, type Observer, type Snapshot, type SnapshotFrom, type Subscription, type EventFromLogic } from "xstate";
+import { Actor, type AnyStateMachine, type AnyActorLogic, type EmittedFrom, type InputFrom, type ActorOptions, type Observer, type Snapshot, type SnapshotFrom, type Subscription, type EventFromLogic } from "xstate";
 import { AbstractActor, type Routable, type Viewable, type PlaySpec } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
 import type { PlayerOptions } from "./types.js";
 /**
  * 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
@@ -19,7 +21,7 @@ import type { PlayerOptions } from "./types.js";
  * 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
@@ -31,7 +33,14 @@ import type { PlayerOptions } from "./types.js";
  *   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: [] } },
+ *         },
+ *       },
  *     }
  *   }
  * });
@@ -41,8 +50,8 @@ import type { PlayerOptions } from "./types.js";
  * 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
@@ -78,17 +87,63 @@ import type { PlayerOptions } from "./types.js";
  * cached and updated at state entry, not computed on every read.
  */
 export declare class PlayerActor<TMachine extends AnyStateMachine> extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>> implements Routable, Viewable {
-    private xstateActor;
-    private playerOptions;
-    private viewSignal;
-    /** Last spec emitted on the view signal — used to skip no-change re-emissions. */
-    private lastEmittedView;
-    state: Signal.State<SnapshotFrom<TMachine>>;
+    private playerOptions?;
+    /**
+     * Whether this constructor has returned.
+     *
+     * XState hands the actor to a context factory as `self`, and to an
+     * `inspect` observer as `actorRef`, from inside its own constructor — where
+     * none of this class's fields exist yet and XState itself refuses to read
+     * the snapshot ("Snapshot can't be read while the actor initializes
+     * itself"). Anything reachable from that window has to check this first.
+     */
+    private constructed?;
+    /**
+     * 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.
+     */
+    private get hooks();
+    /**
+     * Real lifecycle transitions, so onStart/onStop fire once each. XState's
+     * own status is internal, and a machine snapshot already reads "active"
+     * before start(), so neither can distinguish not-yet-started from running.
+     */
+    private lifecycle?;
+    /**
+     * Userland subscriptions without an error listener. XState's dispatch
+     * rethrows an actor error globally on their behalf (once per delivery, a
+     * shared flag), so while one is active the internal error listener's own
+     * loud-default rethrow must stand down — or the same error is reported
+     * twice.
+     */
+    private nextOnlySubscriptions?;
+    /**
+     * 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.
+     */
+    private lastViewSnapshot;
+    state: Signal.State<ReturnType<TMachine["transition"]>>;
     /**
      * 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
@@ -101,16 +156,15 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      * 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();
      * ```
      */
@@ -141,12 +195,19 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      * 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();
@@ -156,20 +217,31 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      * }
      * ```
      */
-    currentView: Signal.State<PlaySpec | null>;
-    constructor(machine: TMachine, options: PlayerOptions<TMachine>, input?: InputFrom<TMachine>, restoredSnapshot?: SnapshotFrom<TMachine>);
+    readonly currentView: Signal.State<PlaySpec | null>;
+    constructor(machine: TMachine, options: PlayerOptions<TMachine>, input?: InputFrom<TMachine>, restoredSnapshot?: ActorOptions<TMachine>["snapshot"]);
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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.
@@ -194,7 +266,7 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      */
     getSnapshot(): ReturnType<Actor<TMachine>["getSnapshot"]>;
     /**
-     * Subscribe to snapshot updates from the wrapped XState actor.
+     * Subscribe to this actor's snapshot updates.
      *
      * Accepts an observer object, exactly like XState's `Actor.subscribe`.
      *
@@ -203,7 +275,7 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      */
     subscribe(observer: Observer<SnapshotFrom<TMachine>>): Subscription;
     /**
-     * Subscribe to snapshot updates from the wrapped XState actor.
+     * Subscribe to this actor's snapshot updates.
      *
      * Accepts listener functions, exactly like XState's `Actor.subscribe`.
      *
@@ -214,7 +286,7 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      */
     subscribe(nextListener?: (snapshot: SnapshotFrom<TMachine>) => void, errorListener?: (error: unknown) => void, completeListener?: () => void): Subscription;
     /**
-     * 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.
@@ -224,25 +296,21 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
         type: TType;
     })) => void): Subscription;
     /**
-     * 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(): Snapshot<unknown>;
+    getPersistedSnapshot(options?: unknown): Snapshot<unknown>;
     /**
-     * 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
      */
     private validateAndCacheView;
     /**
-     * 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(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"player-actor.d.ts","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"player-actor.d.ts","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"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"}