@xmachines/play-xstate 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,9 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-xstate
 
 > XState v5 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.0.0--beta.51-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 Part of the [XMachines Play](../../README.md) monorepo.
 
@@ -84,6 +82,7 @@ const createPlayer = definePlayer({
 		onTransition: (actor, prev, next) => console.log("transitioned"),
 		onStateChange: (actor, state) => console.log("state changed"),
 		onError: (actor, err) => console.error(err),
+		inspect: (event) => console.log(event.type), // handed to XState's actor constructor — enables @statelyai/inspect
 	},
 });
 
@@ -94,17 +93,27 @@ const bob = createPlayer({ userId: "bob" });
 
 #### `PlayerFactory` signature
 
+`input` requiredness mirrors XState's `createActor`: a machine whose input type
+cannot be `undefined` makes the factory's first argument required, so forgetting
+it is a compile error instead of an actor stuck in an error status.
+
 ```typescript
-type PlayerFactory<TMachine> = (
-	input?: InputFrom<TMachine>,
-	options?: PlayerFactoryResumeOptions<TMachine>,
-) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> =
+	undefined extends InputFrom<TMachine>
+		? (
+				input?: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>
+		: (
+				input: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>;
 ```
 
 #### Restoring from a snapshot
 
 ```typescript
-const snapshot = actor.getSnapshot();
+const snapshot = actor.getPersistedSnapshot();
 actor.stop();
 
 // Restore to the exact saved state
@@ -113,11 +122,15 @@ restored.start();
 console.log(restored.currentRoute.get()); // same route as when saved
 ```
 
+> **Note:** Persist with `getPersistedSnapshot()`, not `getSnapshot()` — it is
+> the form `createActor` accepts, and the only one that round-trips machines
+> with invoked or spawned children.
+
 ---
 
 ### `PlayerActor<TMachine>`
 
-Concrete actor class that wraps an XState v5 actor and exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
+Concrete actor class: an XState v5 actor that also exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
 
 #### Signals
 
@@ -158,6 +171,10 @@ actor.start();
 
 ### Guard utilities
 
+> **Deprecated:** the guard helpers wrap XState's own `and()` / `or()` / `not()`
+> combinators without composing with `setup()`-typed guard slots. Use XState's
+> combinators directly; this module will be removed in the next major.
+
 Composable guard helpers that wrap XState's built-in `and()`, `or()`, and `not()` for use in machine `setup({ guards })` definitions.
 
 ```typescript
@@ -241,12 +258,12 @@ const machine = setup({}).createMachine(config);
 ```typescript
 import type {
 	PlayerConfig, // definePlayer() config argument shape
-	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError)
+	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // Single XState guard predicate
-	GuardArray, // Array of guards for compose helpers
-	ComposedGuard, // Return type of composeGuards / composeGuardsOr / negateGuard
+	Guard, // deprecated with the guard utilities — removed in the next major
+	GuardArray, // deprecated with the guard utilities — removed in the next major
+	ComposedGuard, // deprecated with the guard utilities — removed in the next major
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
@@ -264,10 +281,11 @@ Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // context.params present but context.query missing
+	MissingQueryContextError, // deprecated: no longer thrown
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
+	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
 	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
 } from "@xmachines/play-xstate/errors";

package/dist/errors.d.ts

@@ -8,16 +8,17 @@ import { PlayError } from "@xmachines/play";
  *
  * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
  *
+ * Note: `actor.currentRoute.get()` never surfaces this error — route
+ * derivation catches it and returns `null` for the transient mid-transition
+ * case. It only escapes direct `buildRouteUrl()` calls.
+ *
  * @example
  * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
- * // The route template "/profile/:userId" requires "userId" in context.
- * // If userId is absent, MissingRouteParamError is thrown when the
- * // actor.currentRoute signal is read.
- *
  * try {
- *   actor.currentRoute.get();
+ *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
  * } catch (err) {
  *   if (err instanceof MissingRouteParamError) {
  *     console.error(
@@ -35,36 +36,18 @@ export declare class MissingRouteParamError extends PlayError {
     constructor(param: string, template: string);
 }
 /**
- * Thrown by `buildRouteUrl()` when the context has a `params` field (indicating a
- * routing-aware machine context) but no `query` field.
- *
- * The `params` field signals the context was set up for routing (either manually or via
- * `formatPlayRouteTransitions`). A routing-aware context without `query` will silently
- * drop any query parameters carried by `play.route` events, producing incorrect URLs.
+ * @deprecated Never thrown any more. `buildRouteUrl` treats a missing `query`
+ * field as `query: {}` — the generated `play.route` transitions assign
+ * `query` on every navigation, so the loss this error guarded against cannot
+ * occur through route derivation. Machines that handle `play.route` by hand
+ * and want query forwarding must assign `event.query` to context themselves.
+ * Kept exported so existing `instanceof` handlers keep compiling; remove them
+ * at leisure.
  *
- * **Fix:** Ensure the machine context type includes `query: Record<string, string>`
- * and that the context initializer sets `query: {}` (or a populated value).
- * If using `formatPlayRouteTransitions`, the field is assigned automatically on each
- * `play.route` event — but the machine's initial context must still declare it.
+ * Formerly thrown by `buildRouteUrl()` when the context had a `params` field
+ * (a routing-aware machine context) but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- *
- * @example
- * ```typescript
- * import { MissingQueryContextError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   // params present but no query field — throws
- *   buildRouteUrl("/profile/:userId", { params: { userId: "42" } });
- * } catch (err) {
- *   if (err instanceof MissingQueryContextError) {
- *     console.error("Machine context missing query field");
- *   }
- * }
- *
- * // Correct — both params and query declared
- * buildRouteUrl("/profile/:userId", { params: { userId: "42" }, query: {} });
- * ```
  */
 export declare class MissingQueryContextError extends PlayError {
     constructor();
@@ -167,4 +150,35 @@ export declare class InvalidEventError extends PlayError {
     readonly detail: unknown;
     constructor(detail: unknown);
 }
+/**
+ * Passed to `PlayerOptions.onError` when the actor failed with a value that is
+ * not an `Error` — e.g. a machine action ran `throw { code: 42 }`.
+ *
+ * An actor error that *is* an `Error` reaches `onError` untouched, keeping the
+ * identity the machine gave it. Only this case constructs a new error, so it
+ * carries a matchable code instead of a `String(value)` message such as
+ * `"[object Object]"`. The thrown value is preserved on `cause`.
+ *
+ * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
+ *
+ * @example
+ * ```typescript
+ * import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
+ *
+ * definePlayer({
+ *   machine,
+ *   options: {
+ *     onError: (actor, err) => {
+ *       if (err instanceof ActorThrewNonErrorError) {
+ *         // err.cause is the value the machine actually threw
+ *         console.error("Machine threw a non-Error:", err.cause);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare class ActorThrewNonErrorError extends PlayError {
+    constructor(value: unknown);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAqB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}

package/dist/errors.js

@@ -1,4 +1,24 @@
 import { PlayError } from "@xmachines/play";
+/**
+ * Stringify a thrown value without trusting it: `String()` itself throws for
+ * a null-prototype object or a value whose `toString`/`Symbol.toPrimitive`
+ * throw, and this runs inside the error path — a second throw here would
+ * replace the machine's real failure with a `TypeError` and bypass `onError`.
+ */
+const safeString = (value) => {
+    try {
+        return String(value);
+    }
+    catch {
+        try {
+            return Object.prototype.toString.call(value);
+        }
+        catch {
+            // A revoked Proxy throws even on brand inspection.
+            return "[unrepresentable value]";
+        }
+    }
+};
 /**
  * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
  * actor's context.
@@ -8,16 +28,17 @@ import { PlayError } from "@xmachines/play";
  *
  * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
  *
+ * Note: `actor.currentRoute.get()` never surfaces this error — route
+ * derivation catches it and returns `null` for the transient mid-transition
+ * case. It only escapes direct `buildRouteUrl()` calls.
+ *
  * @example
  * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
- * // The route template "/profile/:userId" requires "userId" in context.
- * // If userId is absent, MissingRouteParamError is thrown when the
- * // actor.currentRoute signal is read.
- *
  * try {
- *   actor.currentRoute.get();
+ *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
  * } catch (err) {
  *   if (err instanceof MissingRouteParamError) {
  *     console.error(
@@ -40,36 +61,18 @@ export class MissingRouteParamError extends PlayError {
     }
 }
 /**
- * Thrown by `buildRouteUrl()` when the context has a `params` field (indicating a
- * routing-aware machine context) but no `query` field.
- *
- * The `params` field signals the context was set up for routing (either manually or via
- * `formatPlayRouteTransitions`). A routing-aware context without `query` will silently
- * drop any query parameters carried by `play.route` events, producing incorrect URLs.
+ * @deprecated Never thrown any more. `buildRouteUrl` treats a missing `query`
+ * field as `query: {}` — the generated `play.route` transitions assign
+ * `query` on every navigation, so the loss this error guarded against cannot
+ * occur through route derivation. Machines that handle `play.route` by hand
+ * and want query forwarding must assign `event.query` to context themselves.
+ * Kept exported so existing `instanceof` handlers keep compiling; remove them
+ * at leisure.
  *
- * **Fix:** Ensure the machine context type includes `query: Record<string, string>`
- * and that the context initializer sets `query: {}` (or a populated value).
- * If using `formatPlayRouteTransitions`, the field is assigned automatically on each
- * `play.route` event — but the machine's initial context must still declare it.
+ * Formerly thrown by `buildRouteUrl()` when the context had a `params` field
+ * (a routing-aware machine context) but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- *
- * @example
- * ```typescript
- * import { MissingQueryContextError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   // params present but no query field — throws
- *   buildRouteUrl("/profile/:userId", { params: { userId: "42" } });
- * } catch (err) {
- *   if (err instanceof MissingQueryContextError) {
- *     console.error("Machine context missing query field");
- *   }
- * }
- *
- * // Correct — both params and query declared
- * buildRouteUrl("/profile/:userId", { params: { userId: "42" }, query: {} });
- * ```
  */
 export class MissingQueryContextError extends PlayError {
     constructor() {
@@ -199,4 +202,38 @@ export class InvalidEventError extends PlayError {
         this.detail = detail;
     }
 }
+/**
+ * Passed to `PlayerOptions.onError` when the actor failed with a value that is
+ * not an `Error` — e.g. a machine action ran `throw { code: 42 }`.
+ *
+ * An actor error that *is* an `Error` reaches `onError` untouched, keeping the
+ * identity the machine gave it. Only this case constructs a new error, so it
+ * carries a matchable code instead of a `String(value)` message such as
+ * `"[object Object]"`. The thrown value is preserved on `cause`.
+ *
+ * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
+ *
+ * @example
+ * ```typescript
+ * import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
+ *
+ * definePlayer({
+ *   machine,
+ *   options: {
+ *     onError: (actor, err) => {
+ *       if (err instanceof ActorThrewNonErrorError) {
+ *         // err.cause is the value the machine actually threw
+ *         console.error("Machine threw a non-Error:", err.cause);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export class ActorThrewNonErrorError extends PlayError {
+    constructor(value) {
+        super("PlayerActor", "PLAY_XSTATE_NON_ERROR_THROWN", `PlayerActor failed with a non-Error value: ${safeString(value)}.`, { cause: value });
+        this.name = "ActorThrewNonErrorError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/guards/compose.d.ts

@@ -8,6 +8,8 @@ import type { MachineContext, EventObject, ParameterizedObject } from "xstate";
  * widest-compatible concrete XState guard type that does not use `any`.
  *
  * @public
+ * @deprecated The guard utilities will be removed in the next major — use
+ * XState's own combinator types directly.
  */
 export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 /**
@@ -64,6 +66,8 @@ export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown,
  *
  * @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.
  */
 export declare const composeGuards: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
@@ -105,6 +109,8 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  *
  * @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.
  */
 export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
@@ -142,6 +148,8 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  *
  * @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.
  */
 export declare const negateGuard: <TContext = any, TEvent = any>(guard: Guard<TContext, TEvent> | string) => ComposedGuard;
 //# sourceMappingURL=compose.d.ts.map

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,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"}
+{"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;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CACzC,cAAc,EACd,WAAW,EACX,OAAO,EACP,mBAAmB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAoBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAmBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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

@@ -54,6 +54,8 @@ import { EmptyGuardArrayError } from "../errors.js";
  *
  * @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) => {
@@ -67,8 +69,7 @@ export const composeGuards = (guards) => {
         // 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
+    // Use XState's built-in and() for type inference and serialization.
     // 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.
@@ -115,6 +116,8 @@ 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) => {
@@ -170,6 +173,8 @@ 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) => {

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;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"}
+{"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;AAmBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,sFAAsF;QACtF,sFAAsF;QACtF,mEAAmE;QACnE,8DAA8D;QAC9D,OAAO,MAAM,CAAC,CAAC,CAA6B,CAAC;IAC9C,CAAC;IAED,oEAAoE;IACpE,6FAA6F;IAC7F,sFAAsF;IACtF,qDAAqD;IACrD,+EAA+E;IAC/E,8DAA8D;IAC9D,OAAO,GAAG,CAAC,MAA8C,CAAC,CAAC;AAC5D,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,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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

@@ -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"}