@xmachines/docs 2.0.0 → 2.1.0

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

@@ -6,35 +6,38 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/build-url.ts#L35)
+Defined in: [packages/play-xstate/src/routing/build-url.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/build-url.ts#L38)
 
-Build a full URL from a route template and the actor's context.
+Builds a complete URL from a route template and the context of the actor.
 
-Substitutes `:param` and `:param?` placeholders from `context.params`,
-then appends query params and hash fragments.
+The function replaces each `:param` placeholder and each `:param?` placeholder
+with a value of `context.params`. It then appends the query params and the hash
+fragment.
 
-All parameter values must be in `context.params`. Flat context fields are not
-inspected — this is intentional so misspelled placeholders produce a compile-time
-error rather than silently resolving to `undefined`.
+Every parameter value must be in `context.params`. The function reads no flat
+context field, and this is deliberate: a placeholder with a spelling error
+therefore gives a compile-time error, and it does not resolve to `undefined` in
+silence.
 
 ## Parameters
 
-| Parameter       | Type                                            | Description                                                                                                                                                                           |
-| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `routeTemplate` | `string`                                        | Route path template, e.g. `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                            |
-| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Actor context object. Route parameters must be in `context.params`; flat context fields are not inspected. A missing `query` field builds a query-less URL, exactly like `query: {}`. |
+| Parameter       | Type                                            | Description                                                                                                                                                                                                          |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routeTemplate` | `string`                                        | The template of the route path, for example `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                                         |
+| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | The context object of the actor. Each route parameter must be in `context.params`, because the function reads no flat context field. An absent `query` field builds a URL without a query, exactly like `query: {}`. |
 
 ## Returns
 
 `string`
 
-The fully resolved URL string.
+The complete URL string.
 
 ## Throws
 
-When a **required** `:param` placeholder has no
-matching value in context. Optional parameters (`:param?`) are silently omitted
-when missing. Import the class from `@xmachines/play-xstate/errors`.
+When a **necessary** `:param` placeholder has no
+value in the context. The function omits an optional parameter (`:param?`) in
+silence when its value is absent. Import the class from
+`@xmachines/play-xstate/errors`.
 
 ## Example
 
@@ -43,5 +46,5 @@ buildRouteUrl("/user/:id", { params: { id: "123" }, query: { tab: "profile" }, h
 // → "/user/123?tab=profile#top"
 
 buildRouteUrl("/settings/:section?", { params: {}, query: {} });
-// → "/settings"  (optional param omitted, no query string)
+// → "/settings"  (the optional param is absent, and there is no query string)
 ```

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

@@ -6,44 +6,46 @@
 function composeGuards<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L97)
+Defined in: [packages/play-xstate/src/guards/compose.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L100)
 
-Compose guards with AND logic using XState's and() helper
+Composes the guards with the AND logic, through the and() helper of XState
 
-Combines multiple guard predicates using AND semantics—all guards must pass for
-the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
-type inference and machine serialization.
+The function joins more than one guard predicate with the AND semantics: every
+guard must pass, and the composition then succeeds. It uses the built-in `and()`
+helper of XState. The type inference and the serialization of the machine are
+therefore correct.
 
-**Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
-declarative guard composition in state machine transitions. Guards enforce business
-logic rules that determine whether navigation or actions are valid.
+**Architectural context:** the function supports **Actor Authority (INV-01)**,
+because it composes the guards of a state machine transition declaratively. A
+guard enforces a rule of the business logic, and that rule decides if a
+navigation or an action is valid.
 
 ## 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                                                  |
-| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references) |
+| Parameter | Type                                                                  | Description                                                         |
+| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | The array of the guard predicates, or of the guard names as strings |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-XState and() guard composition
+The and() guard composition of XState
 
 ## Throws
 
-If guards array is empty
+When the array of the guards is empty
 
 ## Examples
 
-AND composition with named guards
+An AND composition with named guards
 
 ```typescript
 import { setup } from "xstate";
@@ -65,7 +67,7 @@ const machine = setup({
 });
 ```
 
-AND composition with inline predicates
+An AND composition with inline predicates
 
 ```typescript
 import { composeGuards } from "@xmachines/play-xstate";
@@ -75,10 +77,10 @@ guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => conte
 
 ## See
 
-- [composeGuardsOr](composeGuardsOr.md) for OR composition
-- [negateGuard](negateGuard.md) for NOT logic
+- [composeGuardsOr](composeGuardsOr.md) for the OR composition
+- [negateGuard](negateGuard.md) for the NOT logic
 
 ## Deprecated
 
-Use XState's own `and()`/`or()`/`not()` directly — this helper does not
-compose with `setup()`-typed guard slots and will be removed in the next major.
+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/functions/composeGuardsOr.md

@@ -6,40 +6,40 @@
 function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/compose.ts#L156)
+Defined in: [packages/play-xstate/src/guards/compose.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L159)
 
-Compose guards with OR logic using XState's or() helper
+Composes the guards with the OR logic, through the or() helper of XState
 
-Combines multiple guard predicates using OR semantics—at least one guard must pass
-for the composition to succeed. Uses XState's built-in `or()` helper for proper
-type inference.
+The function joins more than one guard predicate with the OR semantics: one guard
+must pass at least, and the composition then succeeds. It uses the built-in `or()`
+helper of XState, and the type inference 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                              |
-| --------- | --------------------------------------------------------------------- | ---------------------------------------- |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names |
+| Parameter | Type                                                                  | Description                                              |
+| --------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | The array of the guard predicates, or of the guard names |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-XState or() guard composition
+The or() guard composition of XState
 
 ## Throws
 
-If guards array is empty
+When the array of the guards is empty
 
 ## Example
 
-OR composition with named guards
+An OR composition with named guards
 
 ```typescript
 import { setup } from "xstate";
@@ -53,7 +53,7 @@ const machine = setup({
 }).createMachine({
 	on: {
 		deleteResource: {
-			// Either guard can pass
+			// One guard is sufficient
 			guard: composeGuardsOr(["isOwner", "isAdmin"]),
 			actions: "delete",
 		},
@@ -63,10 +63,10 @@ const machine = setup({
 
 ## See
 
-- [composeGuards](composeGuards.md) for AND composition
-- [negateGuard](negateGuard.md) for NOT logic
+- [composeGuards](composeGuards.md) for the AND composition
+- [negateGuard](negateGuard.md) for the NOT logic
 
 ## Deprecated
 
-Use XState's own `and()`/`or()`/`not()` directly — this helper does not
-compose with `setup()`-typed guard slots and will be removed in the next major.
+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/functions/contextFieldMatches.md

@@ -6,17 +6,17 @@
 function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/helpers.ts#L75)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/helpers.ts#L75)
 
-Check if a context field matches an expected value.
+Tells you if a context field holds the expected value.
 
-- Accepts an explicit dot-separated field path (e.g. `"user.role"`)
-- Uses strict equality for primitives, deep structural equality for objects
-- Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
-- Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
-- Does NOT use substring matching — `"a"` will not match `"active"`
+- The function accepts an explicit field path, with a dot between two segments, for example `"user.role"`
+- It compares a primitive with a strict equality, and an object with a deep structural equality
+- The order of the keys has no effect on the comparison of an object: `{a:1,b:2}` equals `{b:2,a:1}`
+- It supports a Date, a RegExp, an instance of a class, a nested object, and an array, through `dequal/lite`
+- It does NOT match a substring: `"a"` does not match `"active"`
 
-For XState state-node matching, use the built-in `in:` guard syntax instead.
+For a match of an XState state node, use the built-in `in:` guard syntax instead.
 
 ## Type Parameters
 
@@ -26,18 +26,18 @@ For XState state-node matching, use the built-in `in:` guard syntax instead.
 
 ## Parameters
 
-| Parameter       | Type      | Description                                                          |
-| --------------- | --------- | -------------------------------------------------------------------- |
-| `fieldPath`     | `string`  | Dot-separated path to context property (e.g., "status", "user.role") |
-| `expectedValue` | `unknown` | Value to compare against (string, object, Date, etc.)                |
+| Parameter       | Type      | Description                                                                                            |
+| --------------- | --------- | ------------------------------------------------------------------------------------------------------ |
+| `fieldPath`     | `string`  | The path to the context property, with a dot between two segments, for example "status" or "user.role" |
+| `expectedValue` | `unknown` | The value for the comparison: a string, an object, a Date, and so on                                   |
 
 ## Returns
 
 [`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
 
-Guard predicate checking if context field matches
+The guard predicate. It tests the context field for the value
 
 ## Deprecated
 
-Part of the guard utilities slated for removal in the next major —
-write a plain typed predicate instead.
+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/definePlayer.md

@@ -6,36 +6,36 @@
 function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/define-player.ts#L61)
+Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/define-player.ts#L61)
 
-Create a player factory from an XState machine
+Creates a player factory from an XState machine
 
-Factory pattern that accepts an XState v5 machine,
-returning a function that creates [PlayerActor](../classes/PlayerActor.md) instances. This enables
-creating multiple actor instances from a single configuration, useful for
-testing, multi-instance scenarios, or server-side rendering.
+This factory function accepts an XState v5 machine. It returns a function that
+makes [PlayerActor](../classes/PlayerActor.md) instances. One configuration can therefore make more
+than one actor instance, and this helps with a test, with an application of
+several instances, and with a render on the server.
 
 ## Type Parameters
 
-| Type Parameter                                                                                 | Description                  |
-| ---------------------------------------------------------------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine type |
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
 
 ## Parameters
 
-| Parameter | Type                                                          | Description                 |
-| --------- | ------------------------------------------------------------- | --------------------------- |
-| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | Player configuration object |
+| Parameter | Type                                                          | Description                            |
+| --------- | ------------------------------------------------------------- | -------------------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | The configuration object of the player |
 
 ## Returns
 
 [`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`\>
 
-Factory function that creates actor instances with optional input context
+The factory function. It makes an actor instance, with an optional input context
 
 ## Examples
 
-Basic player factory
+A basic player factory
 
 ```typescript
 import { setup } from "xstate";
@@ -54,19 +54,19 @@ const actor = createPlayer();
 actor.start();
 ```
 
-Multiple actor instances from single factory
+More than one actor instance from one factory
 
 ```typescript
 const createPlayer = definePlayer({ machine });
 
-// Create actors for different users
+// Create an actor for each user
 const alice = createPlayer({ userId: "alice" });
 const bob = createPlayer({ userId: "bob" });
 
 alice.start();
 bob.start();
 
-// Independent state machines
+// The two state machines are independent
 console.log(alice.state.get() !== bob.state.get());
 ```
 
@@ -74,5 +74,5 @@ console.log(alice.state.get() !== bob.state.get());
 
 - [Play RFC](../../../../rfc/play.md)
 - [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
-- [PlayerConfig](../interfaces/PlayerConfig.md) for configuration options
-- [PlayerFactory](../type-aliases/PlayerFactory.md) for factory function signature
+- [PlayerConfig](../interfaces/PlayerConfig.md) for the configuration options
+- [PlayerFactory](../type-aliases/PlayerFactory.md) for the signature of the factory function

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

@@ -6,34 +6,35 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/derive-route.ts#L91)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/derive-route.ts#L92)
 
-Derive route from XState state metadata
+Derives the route from the metadata of an XState state
 
-Extracts route URL template from `meta.route` in the active state's metadata.
-Supports both string routes (`"/about"`) and object routes with path property
-(`{ path: "/about" }`). Returns null for states without route metadata (not
-all states need to be routable).
+The function reads the URL template of the route from the `meta.route` field in
+the metadata of the active state. It supports a string route (`"/about"`) and also
+an object route with a path property (`{ path: "/about" }`). It returns null for a
+state without route metadata, because not every state needs a route.
 
-**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
-routing information from state machine definitions rather than external configuration.
-The route is determined by the Actor's current state, not by infrastructure decisions.
+**Architectural context:** the function implements **Actor Authority (INV-01)**,
+because it reads the routing information from the state machine definition, and
+not from an external configuration. The current state of the Actor decides the
+route, and no decision of the infrastructure decides it.
 
 ## Parameters
 
-| Parameter   | Type                            | Description                            |
-| ----------- | ------------------------------- | -------------------------------------- |
-| `stateMeta` | `Record`\<`string`, `unknown`\> | State metadata from snapshot.getMeta() |
+| Parameter   | Type                            | Description                                |
+| ----------- | ------------------------------- | ------------------------------------------ |
+| `stateMeta` | `Record`\<`string`, `unknown`\> | The state metadata from snapshot.getMeta() |
 
 ## Returns
 
 `string` \| `null`
 
-Route path template (may include :params) or null if no route found
+The template of the route path, which can hold a :param, or null when the function finds no route
 
 ## Examples
 
-Basic route extraction
+The basic read of a route
 
 ```typescript
 import { deriveRoute } from "@xmachines/play-xstate";
@@ -56,7 +57,7 @@ const route = deriveRoute(meta);
 console.log(route); // "/about"
 ```
 
-Route with parameters
+A route with a parameter
 
 ```typescript
 const machine = setup({}).createMachine({
@@ -71,10 +72,10 @@ const machine = setup({}).createMachine({
 });
 
 const route = deriveRoute(snapshot.getMeta());
-console.log(route); // "/profile/:userId" (template, before substitution)
+console.log(route); // "/profile/:userId" — the template, before the substitution
 ```
 
-Route object format
+The object form of a route
 
 ```typescript
 const machine = setup({}).createMachine({
@@ -95,15 +96,15 @@ console.log(route); // "/dashboard"
 ## See
 
 - [Play RFC](../../../../rfc/play.md)
-- [buildRouteUrl](buildRouteUrl.md) for URL construction with parameter substitution
-- [isAbsoluteRoute](isAbsoluteRoute.md) for checking path absoluteness
+- [buildRouteUrl](buildRouteUrl.md) for the construction of a URL, with the substitution of each parameter
+- [isAbsoluteRoute](isAbsoluteRoute.md) for the test of an absolute path
 
 ## Remarks
 
-This function checks `meta.route` for route definitions. States with `route: {}` config
-are routable. Parameter substitution happens via [buildRouteUrl](buildRouteUrl.md), not in this
-function (deriveRoute returns templates).
+This function reads the route definition from `meta.route`. A state with a
+`route: {}` config has a route. [buildRouteUrl](buildRouteUrl.md) substitutes each parameter,
+and this function does not: deriveRoute returns a template.
 
-**Non-routable States:** States without `meta.route` return `null`. This is intentional—
-not all states need routes. For example, intermediate loading states or substates may
-not correspond to distinct URLs.
+**A state without a route:** a state without a `meta.route` field gives `null`.
+This is deliberate, because not every state needs a route. An intermediate loading
+state and a substate, for example, often have no URL of their own.

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

@@ -6,9 +6,9 @@
 function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/helpers.ts#L52)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/helpers.ts#L52)
 
-Check if event type matches expected type
+Tells you if the type of the event is the expected type
 
 ## Type Parameters
 
@@ -18,15 +18,15 @@ Check if event type matches expected type
 
 ## Parameters
 
-| Parameter   | Type     | Description         |
-| ----------- | -------- | ------------------- |
-| `eventType` | `string` | Expected event type |
+| Parameter   | Type     | Description             |
+| ----------- | -------- | ----------------------- |
+| `eventType` | `string` | The expected event type |
 
 ## Returns
 
 [`Guard`](../type-aliases/Guard.md)\<`unknown`, `TEvent`\>
 
-Guard predicate checking event type
+The guard predicate. It tests the event type
 
 ## Example
 
@@ -41,5 +41,5 @@ const machine = setup({
 
 ## Deprecated
 
-Part of the guard utilities slated for removal in the next major —
-write a plain typed predicate instead.
+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/formatPlayRouteTransitions.md

@@ -6,14 +6,16 @@
 function formatPlayRouteTransitions<T>(machineConfig): T;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L106)
+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 transitions from declarative route configs
+Makes the play.route transitions from the declarative route configs
 
-Crawls machine states looking for states with meta.route and generates
-transitions that handle `play.route` events by matching event.to to state IDs.
+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.
 
-Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
+The internal formatRouteTransitions function of XState was the model for this
+function (stateUtils.ts, line 391).
 
 ## Type Parameters
 
@@ -23,15 +25,15 @@ Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
 
 ## 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 same machine config with auto-generated `play.route` handlers 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
 
@@ -47,8 +49,9 @@ const machineConfig = {
 const machine = createMachine(formatPlayRouteTransitions(machineConfig));
 ```
 
-This automatically generates play.route handlers at the root level that:
+The function generates the `play.route` handlers at the root level. Those
+handlers:
 
-- Match event.to against state IDs (e.g., event.to === "#home")
-- Target the appropriate state
-- Assign params and query from the event to context
+- 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

@@ -6,9 +6,9 @@
 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/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
+Tells you if the context holds a value at the path, and that the value is truthy
 
 ## Type Parameters
 
@@ -18,15 +18,15 @@ Check if context has a truthy value at path
 
 ## 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
 
@@ -41,5 +41,5 @@ const machine = setup({
 
 ## Deprecated
 
-Part of the guard utilities slated for removal in the next major —
-write a plain typed predicate instead.
+This function is part of the guard utilities, and the next major version removes
+them. Write a plain typed predicate instead.