@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -6,20 +6,16 @@
 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:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L112)
 
-Formats play.route routing from declarative route configs.
+Makes the play.route transitions from the declarative route configs
 
-Crawls machine states looking for states with `meta.route` and wires them to
-XState v6's **native routing machinery**:
+The function walks the machine states. It looks for each state with a `meta.route`
+field, and it generates the transitions that handle a `play.route` event: each
+transition matches event.to against a state ID.
 
-- 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.
+The internal formatRouteTransitions function of XState was the model for this
+function (stateUtils.ts, line 391).
 
 ## Type Parameters
 
@@ -29,15 +25,15 @@ XState v6's **native routing machinery**:
 
 ## Parameters
 
-| Parameter       | Type | Description                                                                     |
-| --------------- | ---- | ------------------------------------------------------------------------------- |
-| `machineConfig` | `T`  | XState machine config (before createMachine). Must extend `RouteMachineConfig`. |
+| Parameter       | Type | Description                                                                             |
+| --------------- | ---- | --------------------------------------------------------------------------------------- |
+| `machineConfig` | `T`  | The XState machine config, before `createMachine`. It must extend `RouteMachineConfig`. |
 
 ## Returns
 
 `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 the generated `play.route` handlers in it. The original type `T` stays.
 
 ## Example
 
@@ -53,36 +49,9 @@ 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).
+The function generates the `play.route` handlers at the root level. Those
+handlers:
+
+- match event.to against a state ID, for example event.to === "#home"
+- target the correct state
+- assign the params and the query of the event to the context

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

@@ -1,16 +1,14 @@
 [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.1.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
+Tells you if the context holds a value at the path, and that the value is truthy
 
 ## Type Parameters
 
@@ -20,15 +18,15 @@ Per CONTEXT.md: Convenience helper for common guard pattern
 
 ## Parameters
 
-| Parameter | Type     | Description                            |
-| --------- | -------- | -------------------------------------- |
-| `path`    | `string` | Dot-separated path to context property |
+| Parameter | Type     | Description                                                       |
+| --------- | -------- | ----------------------------------------------------------------- |
+| `path`    | `string` | The path to the context property, with a dot between two segments |
 
 ## Returns
 
 [`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
 
-Guard predicate checking if property is truthy
+The guard predicate. It tests the property for a truthy value
 
 ## Example
 
@@ -40,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+This function is part of the guard utilities, and the next major version removes
+them. Write a plain typed predicate instead.

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

@@ -6,25 +6,25 @@
 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:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/derive-route.ts#L163)
 
-Check if route path is absolute
+Tells you if the route path is absolute
 
-Determines whether a route path is absolute (starts with `/`) or relative.
-Absolute paths don't inherit from parent routes, while relative paths can be
-composed with parent paths for nested routing.
+The function decides if a route path is absolute, which means that it starts with
+`/`, or relative. An absolute path inherits nothing from a parent route. A
+relative path joins a parent path, for a nested routing.
 
 ## Parameters
 
-| Parameter | Type     | Description         |
-| --------- | -------- | ------------------- |
-| `path`    | `string` | Route path to check |
+| Parameter | Type     | Description            |
+| --------- | -------- | ---------------------- |
+| `path`    | `string` | The route path to test |
 
 ## Returns
 
 `boolean`
 
-true if path starts with '/', false otherwise
+true when the path starts with '/'. In every other case, false
 
 ## Example
 
@@ -38,4 +38,4 @@ console.log(isAbsoluteRoute("./about")); // false
 
 ## See
 
-[deriveRoute](deriveRoute.md) for route extraction
+[deriveRoute](deriveRoute.md) for the read of a route

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

@@ -1,55 +1,56 @@
 [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:215](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L215)
 
-Negate a guard.
+Negates a guard, through the not() helper of XState
 
-Inverts a guard's result—if the guard passes, NOT fails; if guard fails, NOT passes.
+The function inverts the result of a guard: the guard passes, and NOT then fails;
+the guard fails, and NOT then passes. It uses the built-in `not()` helper of
+XState, and the serialization is therefore correct.
 
 ## 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`        | The context type of the state machine |
+| `TEvent`       | `any`        | The 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`\> | The guard predicate to negate, or its name |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-Predicate returning the inverted guard result
+The not() guard negation of XState
 
 ## Example
 
-NOT composition with named guard
+A NOT composition with a named guard
 
 ```typescript
 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: {
+			// Permit the transition when the user is NOT a guest, which means an authenticated user
+			guard: negateGuard("isGuest"),
+			target: "dashboard",
 		},
 	},
 });
@@ -57,5 +58,10 @@ const machine = setup({
 
 ## See
 
-- [composeGuards](composeGuards.md) for AND composition
-- [composeGuardsOr](composeGuardsOr.md) for OR composition
+- [composeGuards](composeGuards.md) for the AND composition
+- [composeGuardsOr](composeGuardsOr.md) for the OR composition
+
+## Deprecated
+
+Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+does not compose with a guard slot that `setup()` types, and the next major version removes it.

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

@@ -2,9 +2,9 @@
 
 # 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.1.0/packages/play-xstate/src/types.ts#L7)
 
-Configuration for definePlayer()
+The configuration of definePlayer()
 
 ## Type Parameters
 
@@ -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`                                        | The XState v5 state machine               | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L9)   |
+| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | The lifecycle hooks and the configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L12) |

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

@@ -2,12 +2,12 @@
 
 # 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:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L115)
 
-Optional restore arguments for the player factory.
+The optional restore arguments of the player factory.
 
-Mirrors XState's createActor options bag while preserving the existing
-`createPlayer(input?)` calling convention for fresh actors.
+The shape follows the options object of `createActor` in XState. It also keeps the
+`createPlayer(input?)` calling convention of a new actor.
 
 ## Type Parameters
 
@@ -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`\> | The persisted XState snapshot. The factory restores the actor state from it. Its type is the `ActorOptions["snapshot"]` type of XState, which is the exact type that `createActor` accepts and that `getPersistedSnapshot()` returns. The restore of a stored snapshot therefore needs no cast. | [packages/play-xstate/src/types.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L123) |

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.1.0/packages/play-xstate/src/types.ts#L18)
 
-Player lifecycle hooks
-
-Per CONTEXT.md: Rich set of hooks for observability
+The lifecycle hooks of the player — 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`) | The inspection observer. The factory gives it to `createActor` of XState without a change. This is the attachment at the moment of the creation, and it is the only route that observes the construction events of the actor. An attachment later, with `actor.system.inspect(fn)`, also works, but it sees only the events after that moment. A `PlayerActor` is the XState actor itself. Therefore its own events carry `actorRef === playerActor`, and you can recognize it by its identity. Each `PlayerActor` is also its own root system. Therefore `event.rootId === actor.sessionId` separates the complete tree, and this includes the events of an invoked child and of a spawned child, whose `actorRef` is the child. That identity brings one point to note: the `@xstate.actor` event fires from inside the constructor of the actor. Its `actorRef` value is therefore the instance during the construction, and `state`, `currentRoute`, `currentView`, and `initialRoute` do not exist yet. A read of one of them there throws. Keep the reference, and read the signals from a later event, or outside the observer. **Example** `import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } });` For an inspector that you create after the factory, for example behind a dev-tools switch, give the factory a function that forwards each event: `inspect: (event) => currentInspector?.(event)`. | [packages/play-xstate/src/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L106) |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                                                                                           | The actor calls it on an actor error: a snapshot restore that fails at `start()`, an action or a guard that throws, and a failure of the view derivation. The actor reads this field at the moment of the delivery of an error, and not at its construction. The options object is shared by its reference. Therefore a handler on that object still receives each actor error, also after a later attachment, and the removal of the handler restores the loud default below. With a handler in place, the actor sends the error there, and the error counts as handled. XState decides its own global rethrow for each observer, and this option does not reach that decision: a subscription of your own without an `error` listener still forces the rethrow, with an `onError` handler and without one. Without `onError`, each actor error stays loud, with an unhandled rethrow through `setTimeout`. No error therefore disappears in silence. Your own `error` subscribers stop that default not: `onError` alone stops it. A failure of the actor that is an `Error` already arrives without a change, and it keeps the identity of the machine. A machine that throws a value that is not an `Error` arrives as an `ActorThrewNonErrorError`, with the value from the throw on its `cause` field.                                                                                                                                                                                                                            | [packages/play-xstate/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L71)   |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                                                                                                    | The actor calls it on each real start, which is every transition from "not running" to "running". A start after a stop is such a transition. A second `start()` call while the actor runs fires the hook not again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-xstate/src/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L24)   |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                                                                                           | The actor calls it when the state signal changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [packages/play-xstate/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L46)   |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                                                                                                    | The actor calls it on each real stop, which means only after it tore a running actor down. A second `stop()` call, a second `dispose()` call, and a stop of an actor that never started fire the hook not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L31)   |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void`                                                                          | The actor calls it after every event that `send()` processes. This includes an event that the machine ignores, and `prevState` and `nextState` are then the same snapshot. Compare the two values when only a real transition is important to you.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [packages/play-xstate/src/types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L39)   |

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

@@ -2,23 +2,24 @@
 
 # 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:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L20)
 
-Route build context from machine context.
+The context of the route construction, from the machine context.
 
-All URL parameter substitution must go through `params` — flat context fields are not
-inspected. This is intentional: the index signature was removed to enable compile-time
-validation of context shapes and IDE autocomplete on context fields.
+Every substitution of a URL parameter reads `params`, because the type reads no
+flat context field. This is deliberate: the type has no index signature now, and
+the compiler therefore checks the shape of a context, and the IDE completes each
+context field.
 
-Machines using `formatPlayRouteTransitions` have `params` and `query` assigned
-automatically from each `play.route` event. Machines that call `buildRouteUrl` directly
-must populate `params` explicitly.
+A machine with `formatPlayRouteTransitions` receives its `params` field and its
+`query` field from each `play.route` event, and the transitions assign them. A
+machine that calls `buildRouteUrl` itself must fill `params` itself.
 
 ## 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`                        | The base path of a relative route                                                     | [packages/play-xstate/src/routing/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L22) |
+| <a id="property-hash"></a> `hash?`         | `string`                        | The hash fragment                                                                     | [packages/play-xstate/src/routing/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L28) |
+| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | The parameters of the path to substitute, for example `:userId` of `/profile/:userId` | [packages/play-xstate/src/routing/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L24) |
+| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | The query parameters                                                                  | [packages/play-xstate/src/routing/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L26) |

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.1.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.1.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:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L33)
 
-Composed guard: a plain predicate over transition arguments.
+The narrowest public return type of the 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
+concrete XState guard type with the widest compatibility that uses no `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 next major version removes the guard utilities. Use the
+combinator types of XState 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.1.0/packages/play-xstate/src/guards/types.ts#L12)
 
-Standard XState guard function signature
-
-Per CONTEXT.md: Guards receive { context, event } per XState standard
+The standard signature of an XState guard function. A guard receives `{ context, event }`.
 
 ## Type Parameters
 
@@ -21,14 +19,18 @@ Per CONTEXT.md: Guards receive { context, event } per XState standard
 
 ## Parameters
 
-| Parameter      | Type                                            | Description                               |
-| -------------- | ----------------------------------------------- | ----------------------------------------- |
-| `args`         | \{ `context`: `TContext`; `event`: `TEvent`; \} | Guard arguments with context and event    |
-| `args.context` | `TContext`                                      | Current machine context                   |
-| `args.event`   | `TEvent`                                        | Event that triggered the guard evaluation |
+| Parameter      | Type                                            | Description                                           |
+| -------------- | ----------------------------------------------- | ----------------------------------------------------- |
+| `args`         | \{ `context`: `TContext`; `event`: `TEvent`; \} | The arguments of the guard: the context and the event |
+| `args.context` | `TContext`                                      | The current machine context                           |
+| `args.event`   | `TEvent`                                        | The event that started the evaluation of the guard    |
 
 ## Returns
 
 `boolean`
 
-boolean indicating if guard passes
+The boolean value. It tells you if the guard passes
+
+## Deprecated
+
+The next major version removes the guard utilities.

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

@@ -1,16 +1,15 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
 
-# Type Alias: GuardArray\<TContext, TEvent\>
+# ~~Type Alias: GuardArray\<TContext, TEvent\>~~
 
 ```ts
 type GuardArray<TContext, TEvent> = (Guard<TContext, TEvent> | string)[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/types.ts#L23)
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/types.ts#L23)
 
-Array of guard predicates or guard names
-
-Per CONTEXT.md: Array means AND - all guards must pass
+The array of the guard predicates, or of the guard names. An array means AND:
+every guard must pass.
 
 ## Type Parameters
 
@@ -18,3 +17,7 @@ Per CONTEXT.md: Array means AND - all guards must pass
 | -------------- | --------------------------------------------------- |
 | `TContext`     | `Record`\<`string`, `unknown`\>                     |
 | `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
+
+## Deprecated
+
+The next major version removes the guard utilities.