@xmachines/docs 2.0.0-alpha.1 → 2.0.0

package/api/@xmachines/play-xstate/functions/composeGuardsOr.md

@@ -1,36 +1,37 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
 
-# Function: composeGuardsOr()
+# ~~Function: composeGuardsOr()~~
 
 ```ts
 function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L189)
+Defined in: [packages/play-xstate/src/guards/compose.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L156)
 
-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.
 
 ## Type Parameters
 
-| Type Parameter | Default type |
-| -------------- | ------------ |
-| `TContext`     | `any`        |
-| `TEvent`       | `any`        |
+| Type Parameter | Default type | Description                |
+| -------------- | ------------ | -------------------------- |
+| `TContext`     | `any`        | State machine context type |
+| `TEvent`       | `any`        | Event type                 |
 
 ## Parameters
 
-| Parameter | Type                                                                  | Description                                                                                                          |
-| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references resolved against `args.guards` from `setup({ guards })`) |
+| Parameter | Type                                                                  | Description                              |
+| --------- | --------------------------------------------------------------------- | ---------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-Predicate returning `true` when any guard passes
+XState or() guard composition
 
 ## Throws
 
@@ -44,8 +45,6 @@ OR composition with named 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",
@@ -53,9 +52,10 @@ const machine = setup({
 	},
 }).createMachine({
 	on: {
-		deleteResource: (args, enq) => {
-			if (!canDelete(args)) return;
-			enq(() => deleteIt());
+		deleteResource: {
+			// Either guard can pass
+			guard: composeGuardsOr(["isOwner", "isAdmin"]),
+			actions: "delete",
 		},
 	},
 });
@@ -65,3 +65,8 @@ const machine = setup({
 
 - [composeGuards](composeGuards.md) for AND composition
 - [negateGuard](negateGuard.md) 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.

package/api/@xmachines/play-xstate/functions/contextFieldMatches.md

@@ -1,12 +1,12 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / contextFieldMatches
 
-# Function: contextFieldMatches()
+# ~~Function: contextFieldMatches()~~
 
 ```ts
 function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L71)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/helpers.ts#L75)
 
 Check if a context field matches an expected value.
 
@@ -36,3 +36,8 @@ For XState state-node matching, use the built-in `in:` guard syntax instead.
 [`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
 
 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.

package/api/@xmachines/play-xstate/functions/definePlayer.md

@@ -6,11 +6,11 @@
 function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/define-player.ts#L61)
+Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/define-player.ts#L61)
 
 Create a player factory from an XState machine
 
-Factory pattern that accepts an XState v6 machine,
+Factory pattern that accepts an XState v5 machine,
 returning a function that creates [PlayerActor](../classes/PlayerActor.md) instances. This enables
 creating multiple actor instances from a single configuration, useful for
 testing, multi-instance scenarios, or server-side rendering.
@@ -19,7 +19,7 @@ testing, multi-instance scenarios, or server-side rendering.
 
 | Type Parameter                                                                                 | Description                  |
 | ---------------------------------------------------------------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v6 state machine type |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine type |
 
 ## Parameters
 

package/api/@xmachines/play-xstate/functions/deriveRoute.md

@@ -6,7 +6,7 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/derive-route.ts#L91)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/derive-route.ts#L91)
 
 Derive route from XState state metadata
 

package/api/@xmachines/play-xstate/functions/eventMatches.md

@@ -1,12 +1,12 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
 
-# Function: eventMatches()
+# ~~Function: eventMatches()~~
 
 ```ts
 function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L50)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/helpers.ts#L52)
 
 Check if event type matches expected type
 
@@ -38,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+Part of the guard utilities slated for removal in the next major —
+write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md

@@ -6,20 +6,14 @@
 function formatPlayRouteTransitions<T>(machineConfig): T;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L146)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L106)
 
-Formats play.route routing from declarative route configs.
+Formats play.route transitions from declarative route configs
 
-Crawls machine states looking for states with `meta.route` and wires them to
-XState v6's **native routing machinery**:
+Crawls machine states looking for states with meta.route and generates
+transitions that handle `play.route` events by matching event.to to state IDs.
 
-- every routed state gets a native `route: {}` config (unless it already
-  declares its own `route`), making it targetable via the built-in
-  `{ type: "xstate.route", to: "#id" }` event (Stately tooling interop and
-  statically-known graph edges), and
-- one root-level `play.route` forwarder performs the navigation for those
-  targets as ONE atomic transition: target + re-entry + a shallow
-  `params`/`query` context patch.
+Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
 
 ## Type Parameters
 
@@ -37,7 +31,7 @@ XState v6's **native routing machinery**:
 
 `T`
 
-The machine config with native `route` configs and the `play.route` forwarder merged in, preserving the original type `T`.
+The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
 
 ## Example
 
@@ -53,36 +47,8 @@ const machineConfig = {
 const machine = createMachine(formatPlayRouteTransitions(machineConfig));
 ```
 
-Because the injected `route` configs are static (object form), the machine's
-route transitions keep **statically-known targets** — `toDirectedGraph()` /
-`machineToGraph()` edges point at the actual routed states, so graph
-reachability queries work. (Function-form transition candidates would have
-dynamic targets, opaque to static analysis.)
-
-The `play.route` public API and its v5 semantics are preserved:
-
-- `send({ type: "play.route", to: "#home", params, query })` navigates and
-  patches `context.params`/`context.query` in the SAME transition — exit
-  actions of the departing state observe the OLD params, entry actions of
-  the target observe the NEW ones, `always` transitions never see a
-  half-navigated intermediate state, and entry/exit actions receive the
-  original `play.route` event;
-- user-defined `play.route` transitions (e.g. a hand-written 404 fallback)
-  are preserved AFTER the forwarder: for unknown targets the forwarder
-  returns `undefined`, so evaluation falls through to them;
-- `params`/`query` are only patched when the forwarder navigates — unknown
-  and blocked targets leave context untouched.
-
-When a state declares its OWN `route` config (which wins over the injected
-default), the forwarder re-raises the event as `xstate.route` instead of
-navigating, so the user's resolver decides — including blocking. The
-forwarder does NOT patch `params`/`query` for such targets (a blocking
-resolver would otherwise leave context describing a route that was never
-entered); the user's function-form resolver owns any context patch, and
-that navigation microstep runs under the `xstate.route` event.
-
-Native `xstate.route` events also work directly (Stately ecosystem tooling),
-but bypass the forwarder — no `params`/`query` context patch is applied, so
-stale values from earlier `play.route` events linger in context (and a
-router bridge deriving the URL from context would interpolate those stale
-params).
+This automatically generates play.route handlers at the root level that:
+
+- Match event.to against state IDs (e.g., event.to === "#home")
+- Target the appropriate state
+- Assign params and query from the event to context

package/api/@xmachines/play-xstate/functions/hasContext.md

@@ -1,17 +1,15 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
 
-# Function: hasContext()
+# ~~Function: hasContext()~~
 
 ```ts
 function hasContext<TContext>(path): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L24)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/helpers.ts#L24)
 
 Check if context has a truthy value at path
 
-Per CONTEXT.md: Convenience helper for common guard pattern
-
 ## Type Parameters
 
 | Type Parameter | Default type                    |
@@ -40,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+Part of the guard utilities slated for removal in the next major —
+write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/isAbsoluteRoute.md

@@ -6,7 +6,7 @@
 function isAbsoluteRoute(path): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/derive-route.ts#L160)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/derive-route.ts#L160)
 
 Check if route path is absolute
 

package/api/@xmachines/play-xstate/functions/negateGuard.md

@@ -1,35 +1,36 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
 
-# Function: negateGuard()
+# ~~Function: negateGuard()~~
 
 ```ts
 function negateGuard<TContext, TEvent>(guard): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L248)
+Defined in: [packages/play-xstate/src/guards/compose.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L211)
 
-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.
 
 ## Type Parameters
 
-| Type Parameter | Default type | Description                                                                                     |
-| -------------- | ------------ | ----------------------------------------------------------------------------------------------- |
-| `TContext`     | `any`        | State machine context type (defaults to `any` so inline predicates compile without annotations) |
-| `TEvent`       | `any`        | Event type                                                                                      |
+| Type Parameter | Default type | Description                |
+| -------------- | ------------ | -------------------------- |
+| `TContext`     | `any`        | State machine context type |
+| `TEvent`       | `any`        | Event type                 |
 
 ## Parameters
 
-| Parameter | Type                                                                    | Description                                                                                       |
-| --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `guard`   | `string` \| [`Guard`](../type-aliases/Guard.md)\<`TContext`, `TEvent`\> | Guard predicate or guard name (resolved against `args.guards` from `setup({ guards })`) to negate |
+| Parameter | Type                                                                    | Description                             |
+| --------- | ----------------------------------------------------------------------- | --------------------------------------- |
+| `guard`   | `string` \| [`Guard`](../type-aliases/Guard.md)\<`TContext`, `TEvent`\> | Guard predicate or guard name to negate |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-Predicate returning the inverted guard result
+XState not() guard negation
 
 ## Example
 
@@ -39,17 +40,16 @@ NOT composition with named guard
 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",
 		},
 	},
 });
@@ -59,3 +59,8 @@ const machine = setup({
 
 - [composeGuards](composeGuards.md) for AND composition
 - [composeGuardsOr](composeGuardsOr.md) 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.

package/api/@xmachines/play-xstate/interfaces/PlayerConfig.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayerConfig\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L7)
+Defined in: [packages/play-xstate/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L7)
 
 Configuration for definePlayer()
 
@@ -14,7 +14,7 @@ Configuration for definePlayer()
 
 ## Properties
 
-| Property                                 | Type                                              | Description                       | Defined in                                                                                                                                     |
-| ---------------------------------------- | ------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-machine"></a> `machine`  | `TMachine`                                        | XState v6 state machine           | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L9)   |
-| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | Lifecycle hooks and configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L12) |
+| Property                                 | Type                                              | Description                       | Defined in                                                                                                                             |
+| ---------------------------------------- | ------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-machine"></a> `machine`  | `TMachine`                                        | XState v5 state machine           | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L9)   |
+| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | Lifecycle hooks and configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L12) |

package/api/@xmachines/play-xstate/interfaces/PlayerFactoryResumeOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayerFactoryResumeOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L47)
+Defined in: [packages/play-xstate/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L111)
 
 Optional restore arguments for the player factory.
 
@@ -17,6 +17,6 @@ Mirrors XState's createActor options bag while preserving the existing
 
 ## Properties
 
-| Property                                   | Type                                                                              | Description                                            | Defined in                                                                                                                                     |
-| ------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-snapshot"></a> `snapshot?` | [`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\> | Persisted XState snapshot used to restore actor state. | [packages/play-xstate/src/types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L49) |
+| Property                                   | Type                                                                     | Description                                                                                                                                                                                                                              | Defined in                                                                                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-snapshot"></a> `snapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\> | Persisted XState snapshot used to restore actor state. Typed as XState's own `ActorOptions["snapshot"]` — the exact type `createActor` accepts and `getPersistedSnapshot()` returns — so restoring a stored snapshot never needs a cast. | [packages/play-xstate/src/types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L119) |

package/api/@xmachines/play-xstate/interfaces/PlayerOptions.md

@@ -2,11 +2,9 @@
 
 # Interface: PlayerOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L20)
+Defined in: [packages/play-xstate/src/types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L18)
 
-Player lifecycle hooks
-
-Per CONTEXT.md: Rich set of hooks for observability
+Player lifecycle hooks — the observability surface around the actor.
 
 ## Type Parameters
 
@@ -16,10 +14,11 @@ Per CONTEXT.md: Rich set of hooks for observability
 
 ## Properties
 
-| Property                                             | Type                                          | Description                      | Defined in                                                                                                                                     |
-| ---------------------------------------------------- | --------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                  | Called on actor errors           | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L38) |
-| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                           | Called when actor starts         | [packages/play-xstate/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L22) |
-| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                  | Called when state signal changes | [packages/play-xstate/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L35) |
-| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                           | Called when actor stops          | [packages/play-xstate/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L25) |
-| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition | [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L28) |
+| Property                                             | Type                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                               |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-inspect"></a> `inspect?`             | \| [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<`InspectionEvent`\> \| ((`inspectionEvent`) => `void`) | Inspection observer forwarded verbatim to XState's `createActor`. This is the creation-time attachment route, and the only one that observes the actor's construction events. Attaching later via `actor.system.inspect(fn)` also works, but only sees events from that point on. A `PlayerActor` is itself the XState actor, so its own events carry `actorRef === playerActor` and can be recognised by identity. Each `PlayerActor` is also its own root system, so `event.rootId === actor.sessionId` demultiplexes the whole tree — including events from invoked and spawned children, whose `actorRef` is the child. One caveat comes with that identity: the `@xstate.actor` event fires from inside the actor's constructor, so its `actorRef` is the instance mid-construction. `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet — reading them there throws. Capture the reference and read the signals from a later event, or from outside the observer. **Example** `import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } });` For an inspector created after the factory (e.g. behind a dev-tools toggle), pass a forwarding function: `inspect: (event) => currentInspector?.(event)`. | [packages/play-xstate/src/types.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L102) |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                                                                                           | Called on actor errors: a snapshot restore that fails at `start()`, a throwing action or guard, and view-derivation failures. Read when an error is delivered, not at construction: the options bag is shared by reference, so a handler attached to it later still receives actor errors, and removing the handler restores the loud default below. With a handler in place, the error is routed there and counts as handled. XState decides its global rethrow per observer, beyond this option's reach: a subscription of your own without an `error` listener still forces it, `onError` or not. Without `onError`, actor errors stay loud (an unhandled rethrow via `setTimeout`) so they are never silently swallowed — and your own `error` subscribers do not suppress that default; only `onError` does. An actor failure that is already an `Error` arrives unchanged, keeping the identity the machine gave it. A machine that throws a non-`Error` value arrives as `ActorThrewNonErrorError` with the thrown value on `cause`.                                                                                                                                                                                                                                                                                                             | [packages/play-xstate/src/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L68)   |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                                                                                                    | Called on each real start: every transition from not-running to running, including a start after a stop. A repeated `start()` while the actor is already running does not re-fire it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [packages/play-xstate/src/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L24)   |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                                                                                           | Called when state signal changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L45)   |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                                                                                                    | Called on each real stop: only when a running actor was actually torn down. Repeated `stop()`/`dispose()` calls, and stopping an actor that never started, do not fire it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L31)   |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void`                                                                          | Called after every event `send()` processes — including events the machine ignores, where `prevState` and `nextState` are the same snapshot. Compare the two when only real transitions matter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L38)   |

package/api/@xmachines/play-xstate/interfaces/RouteContext.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteContext
 
-Defined in: [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L19)
+Defined in: [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L19)
 
 Route build context from machine context.
 
@@ -16,9 +16,9 @@ must populate `params` explicitly.
 
 ## Properties
 
-| Property                                   | Type                            | Description                                                                        | Defined in                                                                                                                                                     |
-| ------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?` | `string`                        | Base path for relative routes                                                      | [packages/play-xstate/src/routing/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L21) |
-| <a id="property-hash"></a> `hash?`         | `string`                        | Hash fragment                                                                      | [packages/play-xstate/src/routing/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L27) |
-| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) | [packages/play-xstate/src/routing/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L23) |
-| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | Query parameters                                                                   | [packages/play-xstate/src/routing/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L25) |
+| Property                                   | Type                            | Description                                                                        | Defined in                                                                                                                                             |
+| ------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-basepath"></a> `basePath?` | `string`                        | Base path for relative routes                                                      | [packages/play-xstate/src/routing/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L21) |
+| <a id="property-hash"></a> `hash?`         | `string`                        | Hash fragment                                                                      | [packages/play-xstate/src/routing/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L27) |
+| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) | [packages/play-xstate/src/routing/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L23) |
+| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | Query parameters                                                                   | [packages/play-xstate/src/routing/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L25) |

package/api/@xmachines/play-xstate/interfaces/RouteObject.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteObject
 
-Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L1)
+Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L1)
 
 ## Indexable
 
@@ -12,6 +12,6 @@ Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xma
 
 ## Properties
 
-| Property                          | Type     | Defined in                                                                                                                                                   |
-| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-path"></a> `path` | `string` | [packages/play-xstate/src/routing/types.ts:2](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L2) |
+| Property                          | Type     | Defined in                                                                                                                                           |
+| --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `string` | [packages/play-xstate/src/routing/types.ts:2](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L2) |

package/api/@xmachines/play-xstate/type-aliases/ComposedGuard.md

@@ -1,35 +1,19 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
 
-# Type Alias: ComposedGuard
+# ~~Type Alias: ComposedGuard~~
 
 ```ts
-type ComposedGuard = (args) => boolean;
+type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L28)
+Defined in: [packages/play-xstate/src/guards/compose.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L32)
 
-Composed guard: a plain predicate over transition arguments.
+Narrowest public return type for guard composition helpers.
 
-XState v6 removed guard objects and the `and()`/`or()`/`not()` creators —
-guards are now plain functions evaluated inside transition functions. A
-composed guard is therefore just another predicate with the same shape as
-[Guard](Guard.md), callable anywhere transition args are available.
+`GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
+widest-compatible concrete XState guard type that does not use `any`.
 
-String guard names are resolved against `args.guards` (the named guards
-declared in `setup({ guards })`, which XState v6 passes to every transition
-function). Resolving a name outside a transition function — or a name that
-was never declared — throws `UnresolvableGuardNameError` immediately.
+## Deprecated
 
-String names work in `on` transitions, `always`, entry/exit actions (since
-xstate 6.0.0-alpha.20 populates `guards` there), and function-form route
-resolvers.
-
-## Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `args`    | `unknown` |
-
-## Returns
-
-`boolean`
+The guard utilities will be removed in the next major — use
+XState's own combinator types directly.

package/api/@xmachines/play-xstate/type-aliases/Guard.md

@@ -1,16 +1,14 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
 
-# Type Alias: Guard\<TContext, TEvent\>
+# ~~Type Alias: Guard\<TContext, TEvent\>~~
 
 ```ts
 type Guard<TContext, TEvent> = (args) => boolean;
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/types.ts#L13)
+Defined in: [packages/play-xstate/src/guards/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/types.ts#L12)
 
-Standard XState guard function signature
-
-Per CONTEXT.md: Guards receive { context, event } per XState standard
+Standard XState guard function signature — guards receive `{ context, event }`.
 
 ## Type Parameters
 
@@ -32,3 +30,7 @@ Per CONTEXT.md: Guards receive { context, event } per XState standard
 `boolean`
 
 boolean indicating if guard passes
+
+## Deprecated
+
+The guard utilities will be removed in the next major.