@xmachines/play-xstate 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/index.d.ts

@@ -2,9 +2,9 @@
  * @xmachines/play-xstate - XState v5 adapter for Play Architecture
  *
  * Provides definePlayer() API for binding XState state machines to the
- * actor base with catalog binding, signal lifecycle, and DevTools integration.
+ * actor base with signal lifecycle and DevTools integration.
  *
- * Per RFC Play v1, this package implements the Logic Layer adapter that
+ * Per the Play RFC, this package implements the Logic Layer adapter that
  * transforms declarative machine definitions into live actors with signal-driven
  * reactivity.
  *
@@ -12,11 +12,10 @@
  */
 export { definePlayer } from "./define-player.js";
 export { PlayerActor } from "./player-actor.js";
-export type { PlayerConfig, PlayerOptions, PlayerFactory } from "./types.js";
-export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, stateMatches, } from "./guards/index.js";
-export type { Guard, GuardArray } from "./guards/types.js";
+export type { PlayerConfig, PlayerOptions, PlayerFactory, PlayerFactoryResumeOptions, } from "./types.js";
+export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
+export type { Guard, GuardArray, ComposedGuard } from "./guards/index.js";
 export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
-export type { RouteMetadata, RouteObject, RouteContext } from "./routing/types.js";
-export { validateComponentBinding, validateViewProps, mergeViewProps } from "./catalog/index.js";
-export type { Catalog, CatalogEntry, ViewMetadata } from "./catalog/types.js";
+export type { RouteMachineConfig, RouteStateNode } from "./routing/index.js";
+export type { RouteContext } from "./routing/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,GACZ,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGnF,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,0BAA0B,GAC1B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -2,9 +2,9 @@
  * @xmachines/play-xstate - XState v5 adapter for Play Architecture
  *
  * Provides definePlayer() API for binding XState state machines to the
- * actor base with catalog binding, signal lifecycle, and DevTools integration.
+ * actor base with signal lifecycle and DevTools integration.
  *
- * Per RFC Play v1, this package implements the Logic Layer adapter that
+ * Per the Play RFC, this package implements the Logic Layer adapter that
  * transforms declarative machine definitions into live actors with signal-driven
  * reactivity.
  *
@@ -13,9 +13,7 @@
 export { definePlayer } from "./define-player.js";
 export { PlayerActor } from "./player-actor.js";
 // Guard utilities
-export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, stateMatches, } from "./guards/index.js";
+export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
 // Routing utilities
 export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
-// Catalog utilities
-export { validateComponentBinding, validateViewProps, mergeViewProps } from "./catalog/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,kBAAkB;AAClB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,GACZ,MAAM,mBAAmB,CAAC;AAG3B,oBAAoB;AACpB,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAG5B,oBAAoB;AACpB,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,kBAAkB;AAClB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,oBAAoB;AACpB,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC"}

package/dist/player-actor.d.ts

@@ -1,7 +1,6 @@
-import { type AnyStateMachine, type AnyActorLogic } from "xstate";
-import { AbstractActor, type Routable, type Viewable } from "@xmachines/play-actor";
+import { type AnyStateMachine, type Actor, type AnyActorLogic, type AnyMachineSnapshot, type InputFrom, type SnapshotFrom, type EventFromLogic } from "xstate";
+import { AbstractActor, type Routable, type Viewable, type ViewMetadata } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
-import type { PlayEvent } from "@xmachines/play";
 import type { PlayerOptions } from "./types.js";
 /**
  * Concrete XState actor implementing Play Architecture signal protocol
@@ -63,7 +62,7 @@ import type { PlayerOptions } from "./types.js";
  * // Watcher notification scheduled via microtask
  * ```
  *
- * @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
@@ -78,20 +77,66 @@ import type { PlayerOptions } from "./types.js";
  * `Signal.Computed`) to ensure proper watcher propagation in PlayRenderer. Views are
  * cached and updated at state entry, not computed on every read.
  */
-export declare class PlayerActor<TMachine extends AnyStateMachine> extends AbstractActor<AnyActorLogic> implements Routable, Viewable, Record<string, any> {
+export declare class PlayerActor<TMachine extends AnyStateMachine> extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>> implements Routable, Viewable {
     private _xstateActor;
     private _stateManager;
     private _options;
-    private _catalog;
     private _viewSignal;
-    state: Signal.State<any>;
+    state: Signal.State<AnyMachineSnapshot>;
+    /**
+     * 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: Signal.Computed<string | null>;
-    currentView: Signal.State<{
-        component: string;
-        props: any;
-    } | null>;
-    catalog: any;
-    constructor(machine: TMachine, catalog: any, options: PlayerOptions, input?: any);
+    /**
+     * 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).
+     */
+    readonly initialRoute: string | null;
+    /**
+     * Reactive signal containing the current view spec derived from the active state's
+     * `meta.view` metadata.
+     *
+     * Always emits a **fresh object reference** on every state transition (including
+     * self-transitions with `reenter: true`) so TC39 Signal equality checks reliably
+     * detect changes.
+     *
+     * The emitted `ViewMetadata` has its spec element `props` enriched with
+     * `context.routeParams` 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.component); // e.g. "Dashboard"
+     *   console.log(view.spec);      // @json-render/core Spec object
+     * }
+     * ```
+     */
+    currentView: Signal.State<ViewMetadata | null>;
+    constructor(machine: TMachine, options: PlayerOptions<TMachine>, input?: InputFrom<TMachine>, snapshot?: SnapshotFrom<TMachine>);
     /**
      * Start the actor
      *
@@ -103,27 +148,30 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      */
     stop(): this;
     /**
-     * Send event to actor
+     * Send an event to the underlying XState 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.
      *
-     * Forwards events to the underlying XState actor. The actor's state machine
-     * guards determine whether each event is valid from the current state.
+     * @param event - An event from the machine's `EventFromLogic<TMachine>` union.
      *
-     * @param event - Any event object with a type property
+     * @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: PlayEvent): void;
+    send(event: EventFromLogic<TMachine>): void;
     /**
      * Get current snapshot
      */
-    getSnapshot(): any;
+    getSnapshot(): ReturnType<Actor<TMachine>["getSnapshot"]>;
     /**
      * Validate view at state entry and cache result
      *

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

@@ -1 +1 @@
-{"version":3,"file":"player-actor.d.ts","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,eAAe,EAAc,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,qBAAa,WAAW,CAAC,QAAQ,SAAS,eAAe,CACxD,SAAQ,aAAa,CAAC,aAAa,CACnC,YAAW,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAElD,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,WAAW,CAAyD;IAGrE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACpE,OAAO,EAAE,GAAG,CAAC;gBAER,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,GAAG;IA+EhF;;;;OAIG;IACM,KAAK,IAAI,IAAI;IAWtB;;OAEG;IACM,IAAI,IAAI,IAAI;IAYrB;;;;;;;;;;;;;;;;OAgBG;IACM,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAsBrC;;OAEG;IACM,WAAW,IAAI,GAAG;IAI3B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAwE7B;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAGf"}
+{"version":3,"file":"player-actor.d.ts","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EAEd,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACN,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA2OhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,qBAAa,WAAW,CAAC,QAAQ,SAAS,eAAe,CACxD,SAAQ,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,QAAQ,CAAC,CAC7D,YAAW,QAAQ,EAAE,QAAQ;IAE7B,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,WAAW,CAAoC;IAGhD,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;OAiBG;IACI,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpD;;;;;;;OAOG;IACH,SAAgB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;gBAGrD,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAChC,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC;IAqElC;;;;OAIG;IACM,KAAK,IAAI,IAAI;IAWtB;;OAEG;IACM,IAAI,IAAI,IAAI;IAYrB;;;;;;;;;;;;;;;;;;;OAmBG;IACM,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,IAAI;IAoBpD;;OAEG;IACM,WAAW,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC;IAIlE;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAGf"}