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

package/dist/guards/compose.js

@@ -1,60 +1,37 @@
-import { EmptyGuardArrayError, InvalidGuardEntryError, UnresolvableGuardNameError, } from "../errors.js";
+import { and, or, not } from "xstate";
+import { EmptyGuardArrayError } from "../errors.js";
 /**
- * Resolve a guard entry (predicate or setup guard name) to an evaluator thunk.
- *
- * The predicate-vs-name discrimination happens once at compose time; only the
- * `args.guards` lookup for string names stays at call time, preserving the
- * documented late-binding semantics. `origin` names the combinator that built
- * the guard, so thrown errors report the correct `scope`.
- *
- * @internal
+ * PRODUCTION code's single unsound boundary, scoped to XState's guard typings.
+ * (Test code uses `unsafeCast` from `@xmachines/shared/test-support` instead —
+ * the two are counterparts; a grep-based cast audit must cover both names.)
+ *
+ * These deprecated helpers bridge two known gaps in XState 5.28's types: our
+ * `Guard<TContext, TEvent>` does not structurally match `ComposedGuard`
+ * (generic event mismatch), and `and()`/`or()` require `readonly [...tuple]`
+ * where `GuardArray` is a mutable array. The runtime values are identical in
+ * every case. The parameter is `unknown`, so the one `as` lives here instead
+ * of double-casts at each call site.
+ * Track XState typing improvements: https://github.com/statelyai/xstate/issues
  */
-const toEvaluator = (guard, origin) => {
-    if (typeof guard === "function") {
-        return (args) => Boolean(guard(args));
-    }
-    if (typeof guard === "string") {
-        return (args) => {
-            const named = args?.guards?.[guard];
-            if (typeof named !== "function") {
-                throw new UnresolvableGuardNameError(guard, origin);
-            }
-            return Boolean(named(args));
-        };
-    }
-    // XState v5 failed loudly when EVALUATING a nullish guard entry — silently
-    // treating it as never-passing would turn negateGuard(undefined) into an
-    // always-allow. Composition stays lazy; evaluation throws.
-    return () => {
-        throw new InvalidGuardEntryError(typeof guard, origin);
-    };
-};
+const asXStateGuard = (value) => value;
 /**
- * Compose guards with AND logic.
+ * Compose guards with AND logic using XState's and() helper
  *
  * Combines multiple guard predicates using AND semantics—all guards must pass for
- * the composition to succeed. Evaluation is short-circuiting, left to right.
+ * the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
+ * type inference and machine serialization.
  *
  * **Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
  * declarative guard composition in state machine transitions. Guards enforce business
  * logic rules that determine whether navigation or actions are valid.
  *
- * **XState v6:** the composed value is a plain predicate. Call it inside a
- * transition function and return early to block the transition:
- *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
+ * @typeParam TContext - State machine context type
  * @typeParam TEvent - Event type
  *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @typeParam TEvent - Event type
+ * @param guards - Array of guard predicates or guard names (string references)
+ * @returns XState and() guard composition
  *
- * @param guards - Array of guard predicates or guard names (string references
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` only when every guard passes
- *
- * @throws {EmptyGuardArrayError} If guards array is empty
+ * @throws {Error} If guards array is empty
  *
  * @example
  * AND composition with named guards
@@ -62,8 +39,6 @@ const toEvaluator = (guard, origin) => {
  * import { setup } from "xstate";
  * import { composeGuards } from "@xmachines/play-xstate";
  *
- * const canAccessAdmin = composeGuards(['isLoggedIn', 'hasPermission']);
- *
  * const machine = setup({
  *   guards: {
  *     isLoggedIn: ({ context }) => !!context.userId,
@@ -71,9 +46,10 @@ const toEvaluator = (guard, origin) => {
  *   }
  * }).createMachine({
  *   on: {
- *     accessAdmin: (args) => {
- *       if (!canAccessAdmin(args)) return;
- *       return { target: 'adminPanel' };
+ *     accessAdmin: {
+ *       // Both guards must pass
+ *       guard: composeGuards(['isLoggedIn', 'hasPermission']),
+ *       target: 'adminPanel'
  *     }
  *   }
  * });
@@ -84,43 +60,43 @@ const toEvaluator = (guard, origin) => {
  * ```typescript
  * import { composeGuards } from "@xmachines/play-xstate";
  *
- * const isEligible = composeGuards([
+ * guard: composeGuards([
  *   ({ context }) => context.age >= 18,
  *   ({ context }) => context.verified
- * ]);
+ * ])
  * ```
  *
  * @see {@link composeGuardsOr} for OR composition
  * @see {@link negateGuard} for NOT logic
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuards = (guards) => {
     if (guards.length === 0) {
         throw new EmptyGuardArrayError("and");
     }
-    const evaluators = guards.map((guard) => toEvaluator(guard, "composeGuards"));
-    if (evaluators.length === 1) {
-        return evaluators[0];
+    if (guards.length === 1) {
+        // Single guard passthrough — see asXStateGuard for why the boundary exists.
+        return asXStateGuard(guards[0]);
     }
-    return (args) => {
-        for (const evaluate of evaluators) {
-            if (!evaluate(args))
-                return false;
-        }
-        return true;
-    };
+    // Use XState's built-in and() for type inference and serialization.
+    return and(asXStateGuard(guards));
 };
 /**
- * Compose guards with OR logic.
+ * Compose guards with OR logic using XState's or() helper
  *
  * Combines multiple guard predicates using OR semantics—at least one guard must pass
- * for the composition to succeed. Evaluation is short-circuiting, left to right.
+ * for the composition to succeed. Uses XState's built-in `or()` helper for proper
+ * type inference.
+ *
+ * @typeParam TContext - State machine context type
+ * @typeParam TEvent - Event type
  *
- * @param guards - Array of guard predicates or guard names (string references
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` when any guard passes
+ * @param guards - Array of guard predicates or guard names
+ * @returns XState or() guard composition
  *
- * @throws {EmptyGuardArrayError} If guards array is empty
+ * @throws {Error} If guards array is empty
  *
  * @example
  * OR composition with named guards
@@ -128,8 +104,6 @@ export const composeGuards = (guards) => {
  * import { setup } from "xstate";
  * import { composeGuardsOr } from "@xmachines/play-xstate";
  *
- * const canDelete = composeGuardsOr(['isOwner', 'isAdmin']);
- *
  * const machine = setup({
  *   guards: {
  *     isOwner: ({ context }) => context.role === 'owner',
@@ -137,9 +111,10 @@ export const composeGuards = (guards) => {
  *   }
  * }).createMachine({
  *   on: {
- *     deleteResource: (args, enq) => {
- *       if (!canDelete(args)) return;
- *       enq(() => deleteIt());
+ *     deleteResource: {
+ *       // Either guard can pass
+ *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
+ *       actions: 'delete'
  *     }
  *   }
  * });
@@ -147,36 +122,32 @@ export const composeGuards = (guards) => {
  *
  * @see {@link composeGuards} for AND composition
  * @see {@link negateGuard} for NOT logic
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuardsOr = (guards) => {
     if (guards.length === 0) {
         throw new EmptyGuardArrayError("or");
     }
-    const evaluators = guards.map((guard) => toEvaluator(guard, "composeGuardsOr"));
-    if (evaluators.length === 1) {
-        return evaluators[0];
+    if (guards.length === 1) {
+        // Single guard passthrough — see asXStateGuard for why the boundary exists.
+        return asXStateGuard(guards[0]);
     }
-    return (args) => {
-        for (const evaluate of evaluators) {
-            if (evaluate(args))
-                return true;
-        }
-        return false;
-    };
+    // Use XState's built-in or() for type inference and serialization.
+    return or(asXStateGuard(guards));
 };
 /**
- * Negate a guard.
+ * Negate a guard using XState's not() helper
  *
  * Inverts a guard's result—if the guard passes, NOT fails; if guard fails, NOT passes.
+ * Uses XState's built-in `not()` helper for proper serialization.
  *
- * @typeParam TContext - State machine context type (defaults to `any` so
- *   inline predicates compile without annotations)
+ * @typeParam TContext - State machine context type
  * @typeParam TEvent - Event type
  *
- * @param guard - Guard predicate or guard name (resolved against `args.guards`
- *   from `setup({ guards })`) to negate
- * @returns Predicate returning the inverted guard result
+ * @param guard - Guard predicate or guard name to negate
+ * @returns XState not() guard negation
  *
  * @example
  * NOT composition with named guard
@@ -184,17 +155,16 @@ export const composeGuardsOr = (guards) => {
  * import { setup } from "xstate";
  * import { negateGuard } from "@xmachines/play-xstate";
  *
- * const isAuthenticated = negateGuard('isGuest');
- *
  * const machine = setup({
  *   guards: {
  *     isGuest: ({ context }) => !context.userId
  *   }
  * }).createMachine({
  *   on: {
- *     accessDashboard: (args) => {
- *       if (!isAuthenticated(args)) return;
- *       return { target: 'dashboard' };
+ *     accessDashboard: {
+ *       // Allow if NOT a guest (i.e., authenticated)
+ *       guard: negateGuard('isGuest'),
+ *       target: 'dashboard'
  *     }
  *   }
  * });
@@ -202,10 +172,13 @@ export const composeGuardsOr = (guards) => {
  *
  * @see {@link composeGuards} for AND composition
  * @see {@link composeGuardsOr} for OR composition
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const negateGuard = (guard) => {
-    const evaluate = toEvaluator(guard, "negateGuard");
-    return (args) => !evaluate(args);
+    // XState 5.28.0: not() requires a specific SingleGuardArg shape, not our
+    // Guard type — see asXStateGuard.
+    return not(asXStateGuard(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":"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"}
+{"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;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,aAAa,GAAG,CAAI,KAAc,EAAK,EAAE,CAAC,KAAU,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;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,4EAA4E;QAC5E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,oEAAoE;IACpE,OAAO,GAAG,CAAC,aAAa,CAA4B,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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,4EAA4E;QAC5E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,mEAAmE;IACnE,OAAO,EAAE,CAAC,aAAa,CAA2B,MAAM,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACvB,EAAE;IAClB,yEAAyE;IACzE,kCAAkC;IAClC,OAAO,GAAG,CAAC,aAAa,CAA4B,KAAK,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC"}

package/dist/guards/helpers.d.ts

@@ -3,8 +3,6 @@ import type { PlayEvent } from "@xmachines/play";
 /**
  * Check if context has a truthy value at path
  *
- * Per CONTEXT.md: Convenience helper for common guard pattern
- *
  * @example
  * ```typescript
  * const machine = setup({
@@ -17,6 +15,8 @@ import type { PlayEvent } from "@xmachines/play";
  *
  * @param path - Dot-separated path to context property
  * @returns Guard predicate checking if property is truthy
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 export declare const hasContext: <TContext = Record<string, unknown>>(path: string) => Guard<TContext, PlayEvent>;
 /**
@@ -37,6 +37,8 @@ export declare const hasContext: <TContext = Record<string, unknown>>(path: stri
  *
  * @param eventType - Expected event type
  * @returns Guard predicate checking event type
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 export declare const eventMatches: <TEvent extends PlayEvent = PlayEvent>(eventType: string) => Guard<unknown, TEvent>;
 /**
@@ -53,6 +55,8 @@ export declare const eventMatches: <TEvent extends PlayEvent = PlayEvent>(eventT
  * @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
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 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":"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"}
+{"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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,SAAS,GAAG,SAAS,EAAE,WAAW,MAAM,KAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAG/E,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;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

@@ -2,8 +2,6 @@ import { dequal } from "dequal/lite";
 /**
  * Check if context has a truthy value at path
  *
- * Per CONTEXT.md: Convenience helper for common guard pattern
- *
  * @example
  * ```typescript
  * const machine = setup({
@@ -16,6 +14,8 @@ import { dequal } from "dequal/lite";
  *
  * @param path - Dot-separated path to context property
  * @returns Guard predicate checking if property is truthy
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 export const hasContext = (path) => ({ context }) => {
     const value = getNestedValue(context, path);
@@ -39,6 +39,8 @@ export const hasContext = (path) => ({ context }) => {
  *
  * @param eventType - Expected event type
  * @returns Guard predicate checking event type
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 export const eventMatches = (eventType) => ({ event }) => {
     return event.type === eventType;
@@ -57,6 +59,8 @@ export const eventMatches = (eventType) => ({ event }) => {
  * @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
+ * @deprecated Part of the guard utilities slated for removal in the next major —
+ * write a plain typed predicate instead.
  */
 export const contextFieldMatches = (fieldPath, expectedValue) => ({ context }) => {
     const actual = getNestedValue(context, fieldPath);

package/dist/guards/helpers.js.map

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;GAoBG;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;;;;;;;;;;;;;;;;GAgBG;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

@@ -4,6 +4,13 @@
  * Provides array-means-AND composition and convenience helpers
  * for common guard patterns in Play Architecture.
  *
+ * @deprecated The guard helpers wrap XState's own `and` / `or` / `not`
+ * combinators without composing with `setup()`-typed guard slots (the
+ * package's own example needs a cast to use them). Use XState's combinators
+ * directly; this module will be removed in the next major. Every exported
+ * symbol carries its own deprecation tag, since consumers import them through
+ * the package root rather than this barrel.
+ *
  * @packageDocumentation
  */
 export { composeGuards, composeGuardsOr, negateGuard } from "./compose.js";

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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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

@@ -4,6 +4,13 @@
  * Provides array-means-AND composition and convenience helpers
  * for common guard patterns in Play Architecture.
  *
+ * @deprecated The guard helpers wrap XState's own `and` / `or` / `not`
+ * combinators without composing with `setup()`-typed guard slots (the
+ * package's own example needs a cast to use them). Use XState's combinators
+ * directly; this module will be removed in the next major. Every exported
+ * symbol carries its own deprecation tag, since consumers import them through
+ * the package root rather than this barrel.
+ *
  * @packageDocumentation
  */
 export { composeGuards, composeGuardsOr, negateGuard } from "./compose.js";

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;AAE3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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

@@ -1,22 +1,21 @@
 import type { PlayEvent } from "@xmachines/play";
 /**
- * Standard XState guard function signature
- *
- * Per CONTEXT.md: Guards receive { context, event } per XState standard
+ * Standard XState guard function signature — guards receive `{ context, event }`.
  *
  * @param args - Guard arguments with context and event
  * @param args.context - Current machine context
  * @param args.event - Event that triggered the guard evaluation
  * @returns boolean indicating if guard passes
+ * @deprecated The guard utilities will be removed in the next major.
  */
 export type Guard<TContext = Record<string, unknown>, TEvent = PlayEvent> = (args: {
     context: TContext;
     event: TEvent;
 }) => boolean;
 /**
- * Array of guard predicates or guard names
+ * Array of guard predicates or guard names — an array means AND: all must pass.
  *
- * Per CONTEXT.md: Array means AND - all guards must pass
+ * @deprecated The guard utilities will be removed in the next major.
  */
 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,IAAI,KAAK,CACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAChC,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;;;;;;;;GAQG;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

@@ -1,5 +1,5 @@
 /**
- * @xmachines/play-xstate - XState v6 adapter for Play Architecture
+ * @xmachines/play-xstate - XState v5 adapter for Play Architecture
  *
  * Provides definePlayer() API for binding XState state machines to the
  * actor base with signal lifecycle and DevTools integration.
@@ -15,7 +15,6 @@ export { PlayerActor } from "./player-actor.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, createRoutedMachine, playMetaSchema, playRouteEventSchema, } from "./routing/index.js";
-export { emptyEventSchema } from "./schemas.js";
-export type { PlayRoutePayload, SetupLike, WithOptional, RouteMachineConfig, RouteStateNode, RouteContext, RouteObject, RouteMetadata, } from "./routing/index.js";
+export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.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,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,EAC1B,mBAAmB,EACnB,cAAc,EACd,oBAAoB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EACX,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACb,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

@@ -1,5 +1,5 @@
 /**
- * @xmachines/play-xstate - XState v6 adapter for Play Architecture
+ * @xmachines/play-xstate - XState v5 adapter for Play Architecture
  *
  * Provides definePlayer() API for binding XState state machines to the
  * actor base with signal lifecycle and DevTools integration.
@@ -15,7 +15,5 @@ export { PlayerActor } from "./player-actor.js";
 // Guard utilities
 export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
 // Routing utilities
-export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, createRoutedMachine, playMetaSchema, playRouteEventSchema, } from "./routing/index.js";
-// XState v6 schema constants (not routing-specific)
-export { emptyEventSchema } from "./schemas.js";
+export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/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;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,EAC1B,mBAAmB,EACnB,cAAc,EACd,oBAAoB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,oDAAoD;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,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"}