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

package/dist/define-player.d.ts

@@ -1,29 +1,23 @@
 import type { AnyStateMachine } from "xstate";
 import type { PlayerConfig, PlayerFactory } from "./types.js";
 /**
- * Create a player factory from XState machine and catalog
+ * Create a player factory from an XState machine
  *
- * Factory pattern that accepts an XState v5 machine and optional UI catalog,
+ * Factory pattern that accepts an XState v5 machine,
  * returning a function that creates {@link PlayerActor} instances. This enables
  * creating multiple actor instances from a single configuration, useful for
  * testing, multi-instance scenarios, or server-side rendering.
  *
- * **Architectural Context:** Implements **Strict Separation (INV-02)** by accepting
- * the machine definition (pure business logic) separately from the catalog (UI vocabulary).
- * The machine references component names in `meta.view` without importing React/framework code.
- *
  * @typeParam TMachine - XState v5 state machine type
- * @typeParam TCatalog - Optional UI component catalog type
  *
  * @param config - Player configuration object
  * @param config.machine - XState v5 state machine
- * @param config.catalog - Optional UI component catalog (allows machines without UI)
  * @param config.options - Optional lifecycle hooks (onStart, onTransition, etc.)
  *
  * @returns Factory function that creates actor instances with optional input context
  *
  * @example
- * Basic player factory without catalog
+ * Basic player factory
  * ```typescript
  * import { setup } from "xstate";
  * import { definePlayer } from "@xmachines/play-xstate";
@@ -42,53 +36,9 @@ import type { PlayerConfig, PlayerFactory } from "./types.js";
  * ```
  *
  * @example
- * Player factory with catalog and parameter-aware routing
- * ```typescript
- * import { setup } from "xstate";
- * import { defineCatalog } from "@xmachines/play-catalog";
- * import { definePlayer } from "@xmachines/play-xstate";
- * import { z } from "zod";
- *
- * const catalog = defineCatalog({
- *   HomePage: z.object({}),
- *   ProfilePage: z.object({ userId: z.string() })
- * });
- *
- * const machine = setup({
- *   types: {
- *     context: {} as { userId: string },
- *     events: {} as { type: 'play.route'; to: string; params?: Record<string, string> }
- *   }
- * }).createMachine({
- *   initial: 'home',
- *   context: { userId: '' },
- *   states: {
- *     home: {
- *       route: {},
- *       meta: {
- *         route: '/',
- *         view: { component: 'HomePage' }
- *       }
- *     },
- *     profile: {
- *       route: {},
- *       meta: {
- *         route: '/profile/:userId',
- *         view: { component: 'ProfilePage', userId: (ctx) => ctx.userId }
- *       }
- *     }
- *   }
- * });
- *
- * const createPlayer = definePlayer({ machine, catalog });
- * const actor = createPlayer({ userId: 'user123' });
- * actor.start();
- * ```
- *
- * @example
  * Multiple actor instances from single factory
  * ```typescript
- * const createPlayer = definePlayer({ machine, catalog });
+ * const createPlayer = definePlayer({ machine });
  *
  * // Create actors for different users
  * const alice = createPlayer({ userId: 'alice' });
@@ -101,10 +51,10 @@ import type { PlayerConfig, PlayerFactory } from "./types.js";
  * console.log(alice.state.get() !== bob.state.get());
  * ```
  *
- * @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 PlayerActor} for the concrete actor implementation
  * @see {@link PlayerConfig} for configuration options
  * @see {@link PlayerFactory} for factory function signature
  */
-export declare const definePlayer: <TMachine extends AnyStateMachine, TCatalog = Record<string, unknown>>(config: PlayerConfig<TMachine, TCatalog>) => PlayerFactory<TMachine>;
+export declare const definePlayer: <TMachine extends AnyStateMachine>(config: PlayerConfig<TMachine>) => PlayerFactory<TMachine>;
 //# sourceMappingURL=define-player.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"define-player.d.ts","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,eAAe,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChG,QAAQ,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,KACtC,aAAa,CAAC,QAAQ,CAQxB,CAAC"}
+{"version":3,"file":"define-player.d.ts","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAA8B,MAAM,YAAY,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,eAAe,EAC5D,QAAQ,YAAY,CAAC,QAAQ,CAAC,KAC5B,aAAa,CAAC,QAAQ,CAKxB,CAAC"}

package/dist/define-player.js

@@ -1,28 +1,22 @@
 import { PlayerActor } from "./player-actor.js";
 /**
- * Create a player factory from XState machine and catalog
+ * Create a player factory from an XState machine
  *
- * Factory pattern that accepts an XState v5 machine and optional UI catalog,
+ * Factory pattern that accepts an XState v5 machine,
  * returning a function that creates {@link PlayerActor} instances. This enables
  * creating multiple actor instances from a single configuration, useful for
  * testing, multi-instance scenarios, or server-side rendering.
  *
- * **Architectural Context:** Implements **Strict Separation (INV-02)** by accepting
- * the machine definition (pure business logic) separately from the catalog (UI vocabulary).
- * The machine references component names in `meta.view` without importing React/framework code.
- *
  * @typeParam TMachine - XState v5 state machine type
- * @typeParam TCatalog - Optional UI component catalog type
  *
  * @param config - Player configuration object
  * @param config.machine - XState v5 state machine
- * @param config.catalog - Optional UI component catalog (allows machines without UI)
  * @param config.options - Optional lifecycle hooks (onStart, onTransition, etc.)
  *
  * @returns Factory function that creates actor instances with optional input context
  *
  * @example
- * Basic player factory without catalog
+ * Basic player factory
  * ```typescript
  * import { setup } from "xstate";
  * import { definePlayer } from "@xmachines/play-xstate";
@@ -41,53 +35,9 @@ import { PlayerActor } from "./player-actor.js";
  * ```
  *
  * @example
- * Player factory with catalog and parameter-aware routing
- * ```typescript
- * import { setup } from "xstate";
- * import { defineCatalog } from "@xmachines/play-catalog";
- * import { definePlayer } from "@xmachines/play-xstate";
- * import { z } from "zod";
- *
- * const catalog = defineCatalog({
- *   HomePage: z.object({}),
- *   ProfilePage: z.object({ userId: z.string() })
- * });
- *
- * const machine = setup({
- *   types: {
- *     context: {} as { userId: string },
- *     events: {} as { type: 'play.route'; to: string; params?: Record<string, string> }
- *   }
- * }).createMachine({
- *   initial: 'home',
- *   context: { userId: '' },
- *   states: {
- *     home: {
- *       route: {},
- *       meta: {
- *         route: '/',
- *         view: { component: 'HomePage' }
- *       }
- *     },
- *     profile: {
- *       route: {},
- *       meta: {
- *         route: '/profile/:userId',
- *         view: { component: 'ProfilePage', userId: (ctx) => ctx.userId }
- *       }
- *     }
- *   }
- * });
- *
- * const createPlayer = definePlayer({ machine, catalog });
- * const actor = createPlayer({ userId: 'user123' });
- * actor.start();
- * ```
- *
- * @example
  * Multiple actor instances from single factory
  * ```typescript
- * const createPlayer = definePlayer({ machine, catalog });
+ * const createPlayer = definePlayer({ machine });
  *
  * // Create actors for different users
  * const alice = createPlayer({ userId: 'alice' });
@@ -100,17 +50,13 @@ import { PlayerActor } from "./player-actor.js";
  * console.log(alice.state.get() !== bob.state.get());
  * ```
  *
- * @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 PlayerActor} for the concrete actor implementation
  * @see {@link PlayerConfig} for configuration options
  * @see {@link PlayerFactory} for factory function signature
  */
 export const definePlayer = (config) => {
-    const { machine, catalog, options } = config;
-    // Return factory function
-    // Per CONTEXT.md: "Factory function for creating multiple actor instances"
-    return (input) => {
-        return new PlayerActor(machine, catalog ?? {}, options ?? {}, input);
-    };
+    const { machine, options } = config;
+    return (input, restore) => new PlayerActor(machine, options ?? {}, input, restore?.snapshot);
 };
 //# sourceMappingURL=define-player.js.map

package/dist/define-player.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-player.js","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC3B,MAAwC,EACd,EAAE;IAC5B,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE7C,0BAA0B;IAC1B,2EAA2E;IAC3E,OAAO,CAAC,KAA2B,EAAE,EAAE;QACtC,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"define-player.js","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC3B,MAA8B,EACJ,EAAE;IAC5B,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAEpC,OAAO,CAAC,KAA2B,EAAE,OAA8C,EAAE,EAAE,CACtF,IAAI,WAAW,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACpE,CAAC,CAAC"}

package/dist/define-player.typecheck.js

@@ -35,8 +35,14 @@ const createPlayer = definePlayer({
     },
 });
 const actor = createPlayer({ count: 1 });
+const snapshot = actor.getSnapshot();
+const restoredActor = createPlayer({ count: 1 }, { snapshot });
 const returnNotAny = false;
+const restoredReturnNotAny = false;
 void returnNotAny;
+void restoredReturnNotAny;
 // @ts-expect-error factory input must match machine input shape
 createPlayer("invalid");
+// @ts-expect-error snapshot must be nested under the `snapshot` key
+createPlayer({ count: 1 }, { persisted: snapshot });
 //# sourceMappingURL=define-player.typecheck.js.map

package/dist/define-player.typecheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-player.typecheck.js","sourceRoot":"","sources":["../src/define-player.typecheck.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKlD,MAAM,OAAO,GAAG,KAAK,CAAC;IACrB,KAAK,EAAE;QACN,OAAO,EAAE,EAAuB;QAChC,KAAK,EAAE,EAAuB;QAC9B,MAAM,EAAE,EAAqB;KAC7B;CACD,CAAC,CAAC,aAAa,CAAC;IAChB,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAChD,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE;QACP,MAAM,EAAE;YACP,EAAE,EAAE;gBACH,GAAG,EAAE;oBACJ,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;wBACxB,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;oBACpB,CAAC;iBACD;aACD;SACD;KACD;CACD,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,YAAY,CAAC;IACjC,OAAO;IACP,OAAO,EAAE;QACR,YAAY,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE;YAK7C,MAAM,WAAW,GAA4B,KAAK,CAAC;YACnD,MAAM,UAAU,GAA2B,KAAK,CAAC;YACjD,MAAM,UAAU,GAA2B,KAAK,CAAC;YAEjD,KAAK,WAAW,CAAC;YACjB,KAAK,UAAU,CAAC;YAChB,KAAK,UAAU,CAAC;QACjB,CAAC;KACD;CACD,CAAC,CAAC;AAEH,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AAGzC,MAAM,YAAY,GAA6B,KAAK,CAAC;AACrD,KAAK,YAAY,CAAC;AAElB,gEAAgE;AAChE,YAAY,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"define-player.typecheck.js","sourceRoot":"","sources":["../src/define-player.typecheck.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKlD,MAAM,OAAO,GAAG,KAAK,CAAC;IACrB,KAAK,EAAE;QACN,OAAO,EAAE,EAAuB;QAChC,KAAK,EAAE,EAAuB;QAC9B,MAAM,EAAE,EAAqB;KAC7B;CACD,CAAC,CAAC,aAAa,CAAC;IAChB,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAChD,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE;QACP,MAAM,EAAE;YACP,EAAE,EAAE;gBACH,GAAG,EAAE;oBACJ,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;wBACxB,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;oBACpB,CAAC;iBACD;aACD;SACD;KACD;CACD,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,YAAY,CAAC;IACjC,OAAO;IACP,OAAO,EAAE;QACR,YAAY,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE;YAK7C,MAAM,WAAW,GAA4B,KAAK,CAAC;YACnD,MAAM,UAAU,GAA2B,KAAK,CAAC;YACjD,MAAM,UAAU,GAA2B,KAAK,CAAC;YAEjD,KAAK,WAAW,CAAC;YACjB,KAAK,UAAU,CAAC;YAChB,KAAK,UAAU,CAAC;QACjB,CAAC;KACD;CACD,CAAC,CAAC;AAEH,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;AACrC,MAAM,aAAa,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAI/D,MAAM,YAAY,GAA6B,KAAK,CAAC;AACrD,MAAM,oBAAoB,GAAqC,KAAK,CAAC;AACrE,KAAK,YAAY,CAAC;AAClB,KAAK,oBAAoB,CAAC;AAE1B,gEAAgE;AAChE,YAAY,CAAC,SAAS,CAAC,CAAC;AAExB,oEAAoE;AACpE,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,170 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
+ * actor's context.
+ *
+ * Use the `param` and `template` fields to identify the missing parameter without
+ * parsing the `.message` string.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
+ *
+ * @example
+ * ```typescript
+ * 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();
+ * } catch (err) {
+ *   if (err instanceof MissingRouteParamError) {
+ *     console.error(
+ *       `Missing "${err.param}" for template "${err.template}"`
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class MissingRouteParamError extends PlayError {
+    /** The name of the route parameter that was missing (e.g. `"userId"`). */
+    readonly param: string;
+    /** The route template that required the missing parameter (e.g. `"/profile/:userId"`). */
+    readonly template: string;
+    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.
+ *
+ * **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.
+ *
+ * **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();
+}
+/**
+ * Thrown by `formatPlayRouteTransitions()` when a state node declares `meta.route`
+ * but omits an explicit `id`.
+ *
+ * Without `id`, the function cannot generate a `play.route` guard that targets the
+ * state — the guard compares `event.to` against `#<id>`, so a missing `id` means
+ * the state is silently unreachable via routing. This error surfaces the
+ * misconfiguration at machine-definition time rather than silently skipping the state.
+ *
+ * **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
+ *
+ * @example
+ * ```typescript
+ * // Bad — meta.route without id:
+ * states: {
+ *   profile: {
+ *     meta: { route: "/profile/:username" },
+ *     // ← missing id: "profile"
+ *   }
+ * }
+ *
+ * // Good:
+ * states: {
+ *   profile: {
+ *     id: "profile",
+ *     meta: { route: "/profile/:username" },
+ *   }
+ * }
+ * ```
+ */
+export declare class MissingStateIdError extends PlayError {
+    /** The state key (position in the states tree) that is missing an explicit `id`. */
+    readonly stateKey: string;
+    /** The route template declared on the state (e.g. `"/profile/:username"`). */
+    readonly route: string;
+    constructor(stateKey: string, route: string);
+}
+/**
+ * Thrown by the `PlayerActor` constructor when the `machine` argument is not a
+ * valid XState machine object (null, undefined, or a non-object).
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_MACHINE`
+ */
+export declare class InvalidMachineError extends PlayError {
+    constructor();
+}
+/**
+ * Thrown by `normalizeRoute()` when a state's `meta.route` value is neither a
+ * string nor an object with a `path` property.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`
+ */
+export declare class InvalidRouteMetadataError extends PlayError {
+    /** The serialised form of the invalid route value for debugging. */
+    readonly detail: string;
+    constructor(route: unknown, source?: string);
+}
+/**
+ * Thrown by `composeGuards()` or `composeGuardsOr()` when called with an empty
+ * guards array. A composition of zero guards has no meaningful semantics.
+ *
+ * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
+ */
+export declare class EmptyGuardArrayError extends PlayError {
+    /** The combinator that was called with an empty array (`"and"` or `"or"`). */
+    readonly combinator: "and" | "or";
+    constructor(combinator: "and" | "or");
+}
+/**
+ * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
+ *
+ * `PlayEvent` requires `{ type: string, ...fields }`. Passing `null`, `undefined`,
+ * a string, or any other non-object value is a programmer error.
+ *
+ * The offending value is attached as the `detail` readonly class field for debugging.
+ * TypeScript consumers can access `err.detail` directly without any unsafe cast.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_EVENT`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidEventError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   actor.send(null as any);
+ * } catch (err) {
+ *   if (err instanceof InvalidEventError) {
+ *     // err.detail is typed as `unknown` — no cast needed
+ *     console.error("Invalid event passed to actor.send():", err.detail);
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidEventError extends PlayError {
+    /** The offending value passed to `send()`. */
+    readonly detail: unknown;
+    constructor(detail: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +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"}

package/dist/errors.js

@@ -0,0 +1,202 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
+ * actor's context.
+ *
+ * Use the `param` and `template` fields to identify the missing parameter without
+ * parsing the `.message` string.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
+ *
+ * @example
+ * ```typescript
+ * 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();
+ * } catch (err) {
+ *   if (err instanceof MissingRouteParamError) {
+ *     console.error(
+ *       `Missing "${err.param}" for template "${err.template}"`
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export class MissingRouteParamError extends PlayError {
+    /** The name of the route parameter that was missing (e.g. `"userId"`). */
+    param;
+    /** The route template that required the missing parameter (e.g. `"/profile/:userId"`). */
+    template;
+    constructor(param, template) {
+        super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_MISSING", `Route parameter '${param}' is required by template '${template}' but was not found in context.`);
+        this.name = "MissingRouteParamError";
+        this.param = param;
+        this.template = template;
+    }
+}
+/**
+ * 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.
+ *
+ * **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.
+ *
+ * **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() {
+        super("buildRouteUrl", "PLAY_XSTATE_MISSING_QUERY_CONTEXT", "buildRouteUrl() received a context without a 'query' field. " +
+            "Declare 'query: Record<string, string>' in the machine context type and " +
+            "initialise it to {} so query parameters from play.route events are not silently dropped.");
+        this.name = "MissingQueryContextError";
+    }
+}
+/**
+ * Thrown by `formatPlayRouteTransitions()` when a state node declares `meta.route`
+ * but omits an explicit `id`.
+ *
+ * Without `id`, the function cannot generate a `play.route` guard that targets the
+ * state — the guard compares `event.to` against `#<id>`, so a missing `id` means
+ * the state is silently unreachable via routing. This error surfaces the
+ * misconfiguration at machine-definition time rather than silently skipping the state.
+ *
+ * **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
+ *
+ * @example
+ * ```typescript
+ * // Bad — meta.route without id:
+ * states: {
+ *   profile: {
+ *     meta: { route: "/profile/:username" },
+ *     // ← missing id: "profile"
+ *   }
+ * }
+ *
+ * // Good:
+ * states: {
+ *   profile: {
+ *     id: "profile",
+ *     meta: { route: "/profile/:username" },
+ *   }
+ * }
+ * ```
+ */
+export class MissingStateIdError extends PlayError {
+    /** The state key (position in the states tree) that is missing an explicit `id`. */
+    stateKey;
+    /** The route template declared on the state (e.g. `"/profile/:username"`). */
+    route;
+    constructor(stateKey, route) {
+        super("formatPlayRouteTransitions", "PLAY_XSTATE_MISSING_STATE_ID", `State "${stateKey}" declares meta.route "${route}" but has no explicit id. ` +
+            `Add id: "${stateKey}" to the state config so play.route events can target it.`);
+        this.name = "MissingStateIdError";
+        this.stateKey = stateKey;
+        this.route = route;
+    }
+}
+/**
+ * Thrown by the `PlayerActor` constructor when the `machine` argument is not a
+ * valid XState machine object (null, undefined, or a non-object).
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_MACHINE`
+ */
+export class InvalidMachineError extends PlayError {
+    constructor() {
+        super("PlayerActor", "PLAY_XSTATE_INVALID_MACHINE", "PlayerActor requires a valid XState machine");
+        this.name = "InvalidMachineError";
+    }
+}
+/**
+ * Thrown by `normalizeRoute()` when a state's `meta.route` value is neither a
+ * string nor an object with a `path` property.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`
+ */
+export class InvalidRouteMetadataError extends PlayError {
+    /** The serialised form of the invalid route value for debugging. */
+    detail;
+    constructor(route, source = "deriveRoute") {
+        const detail = JSON.stringify(route);
+        super(source, "PLAY_XSTATE_INVALID_ROUTE_METADATA", `Invalid route metadata: ${detail}. Expected string or { path: string }`);
+        this.name = "InvalidRouteMetadataError";
+        this.detail = detail;
+    }
+}
+/**
+ * Thrown by `composeGuards()` or `composeGuardsOr()` when called with an empty
+ * guards array. A composition of zero guards has no meaningful semantics.
+ *
+ * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
+ */
+export class EmptyGuardArrayError extends PlayError {
+    /** The combinator that was called with an empty array (`"and"` or `"or"`). */
+    combinator;
+    constructor(combinator) {
+        super(combinator === "and" ? "composeGuards" : "composeGuardsOr", "PLAY_XSTATE_EMPTY_GUARD_ARRAY", `${combinator === "and" ? "composeGuards" : "composeGuardsOr"} requires at least one guard`);
+        this.name = "EmptyGuardArrayError";
+        this.combinator = combinator;
+    }
+}
+/**
+ * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
+ *
+ * `PlayEvent` requires `{ type: string, ...fields }`. Passing `null`, `undefined`,
+ * a string, or any other non-object value is a programmer error.
+ *
+ * The offending value is attached as the `detail` readonly class field for debugging.
+ * TypeScript consumers can access `err.detail` directly without any unsafe cast.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_EVENT`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidEventError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   actor.send(null as any);
+ * } catch (err) {
+ *   if (err instanceof InvalidEventError) {
+ *     // err.detail is typed as `unknown` — no cast needed
+ *     console.error("Invalid event passed to actor.send():", err.detail);
+ *   }
+ * }
+ * ```
+ */
+export class InvalidEventError extends PlayError {
+    /** The offending value passed to `send()`. */
+    detail;
+    constructor(detail) {
+        super("PlayerActor", "PLAY_XSTATE_INVALID_EVENT", "PlayerActor.send() received a non-object event.");
+        this.name = "InvalidEventError";
+        this.detail = detail;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/guards/compose.d.ts

@@ -1,4 +1,15 @@
+import type { GuardPredicate } from "xstate";
 import type { Guard, GuardArray } from "./types.js";
+import type { MachineContext, EventObject, ParameterizedObject } from "xstate";
+/**
+ * Narrowest public return type for guard composition helpers.
+ *
+ * `GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
+ * widest-compatible concrete XState guard type that does not use `any`.
+ *
+ * @public
+ */
+export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 /**
  * Compose guards with AND logic using XState's and() helper
  *
@@ -54,7 +65,7 @@ import type { Guard, GuardArray } from "./types.js";
  * @see {@link composeGuardsOr} for OR composition
  * @see {@link negateGuard} for NOT logic
  */
-export declare const composeGuards: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => any;
+export declare const composeGuards: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
  * Compose guards with OR logic using XState's or() helper
  *
@@ -95,7 +106,7 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  * @see {@link composeGuards} for AND composition
  * @see {@link negateGuard} for NOT logic
  */
-export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => any;
+export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
  * Negate a guard using XState's not() helper
  *
@@ -132,5 +143,5 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  * @see {@link composeGuards} for AND composition
  * @see {@link composeGuardsOr} for OR composition
  */
-export declare const negateGuard: <TContext = any, TEvent = any>(guard: Guard<TContext, TEvent> | string) => any;
+export declare const negateGuard: <TContext = any, TEvent = any>(guard: Guard<TContext, TEvent> | string) => ComposedGuard;
 //# sourceMappingURL=compose.d.ts.map