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

package/dist/guards/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,GAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,GAUF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACvD,OAAO,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,KACrC,GAEF,CAAC"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAG/E;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CACzC,cAAc,EACd,WAAW,EACX,OAAO,EACP,mBAAmB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAqBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAmBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACvD,OAAO,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,KACrC,aAOF,CAAC"}

package/dist/guards/compose.js

@@ -1,4 +1,5 @@
 import { and, or, not } from "xstate";
+import { EmptyGuardArrayError } from "../errors.js";
 /**
  * Compose guards with AND logic using XState's and() helper
  *
@@ -54,15 +55,25 @@ import { and, or, not } from "xstate";
  * @see {@link composeGuardsOr} for OR composition
  * @see {@link negateGuard} for NOT logic
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuards = (guards) => {
     if (guards.length === 0) {
-        throw new Error("composeGuards requires at least one guard");
+        throw new EmptyGuardArrayError("and");
     }
     if (guards.length === 1) {
+        // Single guard passthrough — cast through unknown because our Guard<TContext, TEvent>
+        // does not structurally match ComposedGuard at compile time (generic event mismatch).
+        // At runtime both are plain function objects with identical shape.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return guards[0];
     }
     // Use XState's built-in and() for type inference and serialization
     // Per RESEARCH.md: Don't hand-roll guard composition
+    // XState 5.28.0: and() requires `readonly [...tuple]` but our GuardArray is a mutable array.
+    // We cast through unknown to express the narrowest possible type boundary rather than
+    // escaping to `any`. The runtime value is identical.
+    // Track XState typing improvements: https://github.com/statelyai/xstate/issues
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return and(guards);
 };
 /**
@@ -105,13 +116,23 @@ export const composeGuards = (guards) => {
  * @see {@link composeGuards} for AND composition
  * @see {@link negateGuard} for NOT logic
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuardsOr = (guards) => {
     if (guards.length === 0) {
-        throw new Error("composeGuardsOr requires at least one guard");
+        throw new EmptyGuardArrayError("or");
     }
     if (guards.length === 1) {
+        // Single guard passthrough — cast through unknown because our Guard<TContext, TEvent>
+        // does not structurally match ComposedGuard at compile time (generic event mismatch).
+        // At runtime both are plain function objects with identical shape.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return guards[0];
     }
+    // XState 5.28.0: or() requires `readonly [...tuple]` but our GuardArray is a mutable array.
+    // We cast through unknown to express the narrowest possible type boundary rather than
+    // escaping to `any`. The runtime value is identical.
+    // Track XState typing improvements: https://github.com/statelyai/xstate/issues
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return or(guards);
 };
 /**
@@ -150,7 +171,13 @@ export const composeGuardsOr = (guards) => {
  * @see {@link composeGuards} for AND composition
  * @see {@link composeGuardsOr} for OR composition
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const negateGuard = (guard) => {
+    // XState 5.28.0: not() requires a specific SingleGuardArg shape, not our Guard type.
+    // We cast through unknown to express the narrowest possible type boundary rather than
+    // escaping to `any`. The runtime value is identical.
+    // Track XState typing improvements: https://github.com/statelyai/xstate/issues
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return not(guard);
 };
 //# sourceMappingURL=compose.js.map

package/dist/guards/compose.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,MAAoC,EAC9B,EAAE;IACR,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,mEAAmE;IACnE,qDAAqD;IACrD,OAAO,GAAG,CAAC,MAAa,CAAC,CAAC;AAC3B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,MAAoC,EAC9B,EAAE;IACR,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,CAAC,MAAa,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACjC,EAAE;IACR,OAAO,GAAG,CAAC,KAAY,CAAC,CAAC;AAC1B,CAAC,CAAC"}
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAiBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,sFAAsF;QACtF,sFAAsF;QACtF,mEAAmE;QACnE,8DAA8D;QAC9D,OAAO,MAAM,CAAC,CAAC,CAA6B,CAAC;IAC9C,CAAC;IAED,mEAAmE;IACnE,qDAAqD;IACrD,6FAA6F;IAC7F,sFAAsF;IACtF,qDAAqD;IACrD,+EAA+E;IAC/E,8DAA8D;IAC9D,OAAO,GAAG,CAAC,MAA8C,CAAC,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,sFAAsF;QACtF,sFAAsF;QACtF,mEAAmE;QACnE,8DAA8D;QAC9D,OAAO,MAAM,CAAC,CAAC,CAA6B,CAAC;IAC9C,CAAC;IAED,4FAA4F;IAC5F,sFAAsF;IACtF,qDAAqD;IACrD,+EAA+E;IAC/E,8DAA8D;IAC9D,OAAO,EAAE,CAAC,MAA6C,CAAC,CAAC;AAC1D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACvB,EAAE;IAClB,qFAAqF;IACrF,sFAAsF;IACtF,qDAAqD;IACrD,+EAA+E;IAC/E,8DAA8D;IAC9D,OAAO,GAAG,CAAC,KAA6C,CAAC,CAAC;AAC3D,CAAC,CAAC"}

package/dist/guards/helpers.d.ts

@@ -39,5 +39,20 @@ export declare const hasContext: <TContext = Record<string, unknown>>(path: stri
  * @returns Guard predicate checking event type
  */
 export declare const eventMatches: <TEvent extends PlayEvent = PlayEvent>(eventType: string) => Guard<unknown, TEvent>;
-export declare const stateMatches: <TContext = Record<string, unknown>>(stateValue: string) => Guard<TContext, PlayEvent>;
+/**
+ * Check if a context field matches an expected value.
+ *
+ * - Accepts an explicit dot-separated field path (e.g. `"user.role"`)
+ * - Uses strict equality for primitives, deep structural equality for objects
+ * - Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
+ * - Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
+ * - Does NOT use substring matching — `"a"` will not match `"active"`
+ *
+ * For XState state-node matching, use the built-in `in:` guard syntax instead.
+ *
+ * @param fieldPath - Dot-separated path to context property (e.g., "status", "user.role")
+ * @param expectedValue - Value to compare against (string, object, Date, etc.)
+ * @returns Guard predicate checking if context field matches
+ */
+export declare const contextFieldMatches: <TContext = Record<string, unknown>>(fieldPath: string, expectedValue: unknown) => Guard<TContext, PlayEvent>;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/guards/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,KAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI5E,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,SAAS,GAAG,SAAS,EAAE,WAAW,MAAM,KAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAG/E,CAAC;AAsBH,eAAO,MAAM,YAAY,GACvB,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,MAAM,KAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAqBlF,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,KAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI5E,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,SAAS,GAAG,SAAS,EAAE,WAAW,MAAM,KAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAG/E,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,WAAW,MAAM,EACjB,eAAe,OAAO,KACpB,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI3B,CAAC"}

package/dist/guards/helpers.js

@@ -1,3 +1,4 @@
+import { dequal } from "dequal/lite";
 /**
  * Check if context has a truthy value at path
  *
@@ -43,43 +44,23 @@ export const eventMatches = (eventType) => ({ event }) => {
     return event.type === eventType;
 };
 /**
- * Check if current state matches expected value
+ * Check if a context field matches an expected value.
  *
- * @example
- * ```typescript
- * const machine = setup({
- *   guards: {
- *     isLoggedIn: stateMatches('authenticated'),
- *     isDashboard: stateMatches('authenticated.dashboard')
- *   }
- * });
- * ```
+ * - Accepts an explicit dot-separated field path (e.g. `"user.role"`)
+ * - Uses strict equality for primitives, deep structural equality for objects
+ * - Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
+ * - Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
+ * - Does NOT use substring matching — `"a"` will not match `"active"`
+ *
+ * For XState state-node matching, use the built-in `in:` guard syntax instead.
  *
- * @param stateValue - Expected state value (string or object)
- * @returns Guard predicate checking state value
+ * @param fieldPath - Dot-separated path to context property (e.g., "status", "user.role")
+ * @param expectedValue - Value to compare against (string, object, Date, etc.)
+ * @returns Guard predicate checking if context field matches
  */
-const isRecord = (value) => {
-    return typeof value === "object" && value !== null;
-};
-export const stateMatches = (stateValue) => ({ context }) => {
-    // Note: This helper checks context for state info
-    // For actual XState state matching, use machine.matches() in actions
-    // This is a simplified version for context-based state checks
-    let currentState;
-    if (isRecord(context) && "_state" in context) {
-        currentState = context._state;
-    }
-    else if (isRecord(context) && "state" in context) {
-        currentState = context.state;
-    }
-    if (!currentState)
-        return false;
-    // Simple string matching (can be enhanced for nested states)
-    if (typeof currentState === "string") {
-        return currentState === stateValue;
-    }
-    // Object state matching
-    return JSON.stringify(currentState).includes(stateValue);
+export const contextFieldMatches = (fieldPath, expectedValue) => ({ context }) => {
+    const actual = getNestedValue(context, fieldPath);
+    return dequal(actual, expectedValue);
 };
 /**
  * Get nested value from object using dot-separated path
@@ -93,7 +74,7 @@ const getNestedValue = (obj, path) => {
         if (value === null || value === undefined || typeof value !== "object") {
             return undefined;
         }
-        value = value[key];
+        value = value[key]; // nosemgrep: gitlab.eslint.detect-object-injection
     }
     return value;
 };

package/dist/guards/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GACtB,CAAqC,IAAY,EAA8B,EAAE,CACjF,CAAC,EAAE,OAAO,EAAyB,EAAE,EAAE;IACtC,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;AAC9D,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,YAAY,GACxB,CAAuC,SAAiB,EAA0B,EAAE,CACpF,CAAC,EAAE,KAAK,EAAqB,EAAE,EAAE;IAChC,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;AACjC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE;IACrE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACpD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GACxB,CAAqC,UAAkB,EAA8B,EAAE,CACvF,CAAC,EAAE,OAAO,EAAyB,EAAE,EAAE;IACtC,kDAAkD;IAClD,qEAAqE;IACrE,8DAA8D;IAC9D,IAAI,YAAqB,CAAC;IAC1B,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC9C,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;SAAM,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QACpD,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhC,6DAA6D;IAC7D,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,YAAY,KAAK,UAAU,CAAC;IACpC,CAAC;IAED,wBAAwB;IACxB,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC1D,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,GAAY,EAAE,IAAY,EAAW,EAAE;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,GAAG,GAAG,CAAC;IAEhB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxE,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,KAAK,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GACtB,CAAqC,IAAY,EAA8B,EAAE,CACjF,CAAC,EAAE,OAAO,EAAyB,EAAE,EAAE;IACtC,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;AAC9D,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,YAAY,GACxB,CAAuC,SAAiB,EAA0B,EAAE,CACpF,CAAC,EAAE,KAAK,EAAqB,EAAE,EAAE;IAChC,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;AACjC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC/B,CACC,SAAiB,EACjB,aAAsB,EACO,EAAE,CAChC,CAAC,EAAE,OAAO,EAAyB,EAAE,EAAE;IACtC,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACtC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,GAAY,EAAE,IAAY,EAAW,EAAE;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,GAAG,GAAG,CAAC;IAEhB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxE,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,KAAK,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,mDAAmD;IACrG,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC,CAAC"}

package/dist/guards/index.d.ts

@@ -7,6 +7,7 @@
  * @packageDocumentation
  */
 export { composeGuards, composeGuardsOr, negateGuard } from "./compose.js";
-export { hasContext, eventMatches, stateMatches } from "./helpers.js";
+export type { ComposedGuard } from "./compose.js";
+export { hasContext, eventMatches, contextFieldMatches } from "./helpers.js";
 export type { Guard, GuardArray } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/guards/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/guards/index.js

@@ -7,5 +7,5 @@
  * @packageDocumentation
  */
 export { composeGuards, composeGuardsOr, negateGuard } from "./compose.js";
-export { hasContext, eventMatches, stateMatches } from "./helpers.js";
+export { hasContext, eventMatches, contextFieldMatches } from "./helpers.js";
 //# sourceMappingURL=index.js.map

package/dist/guards/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/guards/types.d.ts

@@ -18,5 +18,5 @@ export type Guard<TContext = Record<string, unknown>, TEvent = PlayEvent> = (arg
  *
  * Per CONTEXT.md: Array means AND - all guards must pass
  */
-export type GuardArray<TContext = Record<string, unknown>, TEvent = PlayEvent> = Array<Guard<TContext, TEvent>> | Array<string>;
+export type GuardArray<TContext = Record<string, unknown>, TEvent = PlayEvent> = Array<Guard<TContext, TEvent> | string>;
 //# sourceMappingURL=types.d.ts.map

package/dist/guards/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,CAAC,IAAI,EAAE;IAClF,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAC1E,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,GAC9B,KAAK,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,CAAC,IAAI,EAAE;IAClF,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,KAAK,CACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAChC,CAAC"}

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,13 +12,9 @@
  */
 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 { RouteMachineConfig, RouteStateNode } from "./routing/index.js";
-export type { RouteContext } from "./routing/types.js";
-export { validateComponentBinding, validateViewProps, mergeViewProps } from "./catalog/index.js";
-export type { ValidationResult, ViewMergeContext } from "./catalog/index.js";
-export type { Catalog, CatalogEntry } from "./catalog/types.js";
+export type { RouteMachineConfig, RouteStateNode, RouteContext, RouteObject, RouteMetadata, } from "./routing/index.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,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,YAAY,EAAE,OAAO,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,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACb,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;AAI5B,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,9 +1,7 @@
-import { type AnyStateMachine, type Actor, type AnyActorLogic, type AnyMachineSnapshot } from "xstate";
-import { AbstractActor, type Routable, type Viewable, type ViewMetadata } from "@xmachines/play-actor";
+import { type AnyStateMachine, type Actor, type AnyActorLogic, type EmittedFrom, type InputFrom, 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 { PlayEvent } from "@xmachines/play";
 import type { PlayerOptions } from "./types.js";
-import type { Catalog } from "./catalog/types.js";
 /**
  * Concrete XState actor implementing Play Architecture signal protocol
  *
@@ -48,7 +46,7 @@ import type { Catalog } from "./catalog/types.js";
  * ```
  *
  * @example
- * Signal lifecycle with watchers (microtask batching)
+ * Signal lifecycle with watchers
  * ```typescript
  * import { Signal } from "@xmachines/play-signals";
  *
@@ -61,10 +59,10 @@ import type { Catalog } from "./catalog/types.js";
  *
  * 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
@@ -79,19 +77,87 @@ import type { Catalog } from "./catalog/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 {
-    [key: string]: unknown;
-    private _xstateActor;
-    private _stateManager;
-    private _options;
-    private _catalog;
-    private _viewSignal;
-    private _lastViewMemo;
-    state: Signal.State<AnyMachineSnapshot>;
+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<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.
+     *
+     * @example
+     * ```typescript
+     * if (actor.can({ type: "auth.logout" })) { ... }
+     * ```
+     */
+    can(event: EventFromLogic<TMachine>): boolean;
+    /**
+     * 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<ViewMetadata | null>;
-    catalog: Catalog;
-    constructor(machine: TMachine, catalog: Catalog | null | undefined, options: PlayerOptions<TMachine>, 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).
+     *
+     * 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.
+     */
+    readonly initialRoute: string | null;
+    /**
+     * 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: Signal.State<PlaySpec | null>;
+    constructor(machine: TMachine, options: PlayerOptions<TMachine>, input?: InputFrom<TMachine>, restoredSnapshot?: SnapshotFrom<TMachine>);
     /**
      * Start the actor
      *
@@ -103,27 +169,67 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      */
     stop(): 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: PlayEvent): void;
+    send(event: EventFromLogic<TMachine>): void;
     /**
      * Get current snapshot
      */
     getSnapshot(): ReturnType<Actor<TMachine>["getSnapshot"]>;
+    /**
+     * Subscribe to snapshot updates from the wrapped XState actor.
+     *
+     * Accepts an observer object, exactly like XState's `Actor.subscribe`.
+     *
+     * @param observer - Observer with `next`/`error`/`complete` handlers.
+     * @returns Subscription with an `unsubscribe()` method.
+     */
+    subscribe(observer: Observer<SnapshotFrom<TMachine>>): Subscription;
+    /**
+     * Subscribe to snapshot updates from the wrapped XState actor.
+     *
+     * Accepts listener functions, exactly like XState's `Actor.subscribe`.
+     *
+     * @param nextListener - Snapshot listener function.
+     * @param errorListener - Called when the actor errors.
+     * @param completeListener - Called when the actor completes (reaches a final state).
+     * @returns Subscription with an `unsubscribe()` method.
+     */
+    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.
+     *
+     * @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<TType extends EmittedFrom<TMachine>["type"] | "*">(type: TType, handler: (emitted: EmittedFrom<TMachine> & (TType extends "*" ? unknown : {
+        type: TType;
+    })) => void): Subscription;
+    /**
+     * Get the persisted snapshot of the wrapped XState actor.
+     *
+     * Suitable for serialization and later restoration via the factory's
+     * `restore.snapshot` option.
+     */
+    getPersistedSnapshot(): Snapshot<unknown>;
     /**
      * Validate view at state entry and cache result
      *
@@ -132,7 +238,7 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Abstr
      *
      * @param snapshot - Current XState snapshot
      */
-    private _validateAndCacheView;
+    private validateAndCacheView;
     /**
      * Convenience dispose method for cleanup
      *

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,EAEN,KAAK,eAAe,EACpB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,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;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAQhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAkBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,qBAAa,WAAW,CAAC,QAAQ,SAAS,eAAe,CACxD,SAAQ,aAAa,CAAC,aAAa,CACnC,YAAW,QAAQ,EAAE,QAAQ;IAE7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvB,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,aAAa,CAKZ;IAGF,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACxC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC/C,OAAO,EAAE,OAAO,CAAC;gBAGvB,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAChC,KAAK,CAAC,EAAE,GAAG;IAiFZ;;;;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,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC;IAIlE;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAsG7B;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAGf"}
+{"version":3,"file":"player-actor.d.ts","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"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"}