@xmachines/docs 2.0.0 → 2.1.0

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/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

@@ -6,35 +6,36 @@
 function negateGuard<TContext, TEvent>(guard): ComposedGuard;
 ```
 
-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)
+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 using XState's not() helper
+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.
-Uses XState's built-in `not()` helper for proper serialization.
+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 |
-| `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 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)
 
-XState not() guard negation
+The not() guard negation of XState
 
 ## Example
 
-NOT composition with named guard
+A NOT composition with a named guard
 
 ```typescript
 import { setup } from "xstate";
@@ -47,7 +48,7 @@ const machine = setup({
 }).createMachine({
 	on: {
 		accessDashboard: {
-			// Allow if NOT a guest (i.e., authenticated)
+			// Permit the transition when the user is NOT a guest, which means an authenticated user
 			guard: negateGuard("isGuest"),
 			target: "dashboard",
 		},
@@ -57,10 +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 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.
+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/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 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) |
+| 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:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L111)
+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?` | [`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) |
+| 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,9 +2,9 @@
 
 # Interface: PlayerOptions\<TMachine\>
 
-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)
+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 — the observability surface around the actor.
+The lifecycle hooks of the player — the observability surface around the actor.
 
 ## Type Parameters
 
@@ -14,11 +14,11 @@ Player lifecycle hooks — the observability surface around the actor.
 
 ## Properties
 
-| 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)   |
+| 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/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/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) |
+| 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/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
 
@@ -14,4 +14,4 @@ Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xma
 
 | 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) |
+| <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

@@ -6,14 +6,14 @@
 type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 ```
 
-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)
+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)
 
-Narrowest public return type for guard composition helpers.
+The narrowest public return type of the guard composition helpers.
 
 `GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
-widest-compatible concrete XState guard type that does not use `any`.
+concrete XState guard type with the widest compatibility that uses no `any`.
 
 ## Deprecated
 
-The guard utilities will be removed in the next major — use
-XState's own combinator types directly.
+The next major version removes the guard utilities. Use the
+combinator types of XState directly.

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

@@ -6,9 +6,9 @@
 type Guard<TContext, TEvent> = (args) => boolean;
 ```
 
-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)
+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 — guards receive `{ context, event }`.
+The standard signature of an XState guard function. A guard receives `{ context, event }`.
 
 ## Type Parameters
 
@@ -19,18 +19,18 @@ Standard XState guard function signature — guards receive `{ context, event }`
 
 ## 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 guard utilities will be removed in the next major.
+The next major version removes the guard utilities.

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

@@ -6,9 +6,10 @@
 type GuardArray<TContext, TEvent> = (Guard<TContext, TEvent> | string)[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/types.ts#L22)
+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 — an array means AND: all must pass.
+The array of the guard predicates, or of the guard names. An array means AND:
+every guard must pass.
 
 ## Type Parameters
 
@@ -19,4 +20,4 @@ Array of guard predicates or guard names — an array means AND: all must pass.
 
 ## Deprecated
 
-The guard utilities will be removed in the next major.
+The next major version removes the guard utilities.

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

@@ -9,15 +9,15 @@ type PlayerFactory<TMachine> =
 		: (input, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L131)
+Defined in: [packages/play-xstate/src/types.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L135)
 
-Factory function returned by definePlayer() — each call creates an
-independent actor instance from the same configuration.
+The factory function that definePlayer() returns. Each call makes an independent
+actor instance from the same configuration.
 
-Input requiredness mirrors XState's `createActor`: a machine whose input
-cannot be `undefined` makes the factory's first argument required, so
-forgetting it is a compile error instead of an actor that starts in an
-error status with a `null` initial route.
+The `input` argument follows the rule of `createActor` in XState. If the input of
+a machine cannot be `undefined`, the first argument of the factory is necessary.
+An absent input is then a compile error, and not an actor that starts in an error
+status with a `null` initial route.
 
 ## Type Parameters
 

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

@@ -6,17 +6,17 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L70)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
 
-Minimal structural constraint for machine configs accepted by
-`formatPlayRouteTransitions`.
+The minimal structural constraint of a machine config that
+`formatPlayRouteTransitions` accepts.
 
-This is intentionally loose so the function accepts both the bare `createMachine`
-config object and the stricter `setup().createMachine` config without requiring
-any type casts at the call site. The generic `T extends RouteMachineConfig`
-parameter on `formatPlayRouteTransitions` preserves the original concrete type
-through the transform, so the return value remains directly usable by
-`setup().createMachine()`.
+The constraint is loose on purpose. The function therefore accepts the bare config
+object of `createMachine` and also the stricter config of
+`setup().createMachine`, and the call site needs no type cast. The generic
+parameter `T extends RouteMachineConfig` of `formatPlayRouteTransitions` keeps the
+original concrete type through the transform. Therefore
+`setup().createMachine()` accepts the return value directly.
 
 ## Indexable
 
@@ -32,7 +32,7 @@ through the transform, so the return value remains directly usable by
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L71)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L74)
 
 ---
 
@@ -42,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
 
 ---
 
@@ -52,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L72)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L75)

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

@@ -6,4 +6,4 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L6)
+Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/types.ts#L6)

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

@@ -6,14 +6,14 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
 
-Minimal structural shape of a single XState state node as read by
-`formatPlayRouteTransitions` when crawling the machine config.
+The minimal structural shape of one XState state node, as
+`formatPlayRouteTransitions` reads it during its walk over the machine config.
 
-Only the fields the function actually inspects are typed here; all other
-state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
-the index signature.
+This type holds only the fields that the function reads. Every other field of a
+state node, such as `on`, `entry`, and `after`, passes through the index
+signature without a change.
 
 ## Indexable
 
@@ -29,9 +29,9 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
-Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
+The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
 ---
 
@@ -41,9 +41,9 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
 
-State metadata — `meta.route` marks the state as routable.
+The state metadata. A `meta.route` field gives the state a route.
 
 #### route?
 
@@ -51,8 +51,9 @@ State metadata — `meta.route` marks the state as routable.
 optional route?: RouteMetadata;
 ```
 
-URL path template — string form (e.g. `"/profile/:username"`) or object
-form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
+The template of the URL path: the string form, for example
+`"/profile/:username"`, or the object form (`{ path, title }`). Both match
+[RouteMetadata](RouteMetadata.md).
 
 ---
 
@@ -62,6 +63,6 @@ form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L44)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
 
-Nested child states, recursively crawled for additional route declarations.
+The nested child states. The function walks them for each further route declaration.