@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play-router/functions/buildPlayRouteEvent.md

@@ -9,13 +9,14 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L168)
+Defined in: [router-sync.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L175)
 
-Build a normalized `play.route` event from raw router/browser input.
+Builds a normalized `play.route` event from the raw input of a router or of a
+browser.
 
-Both `connectRouter()` (from `@xmachines/play-dom-router`) and `RouterBridgeBase`
-use this helper so low-level and framework adapters share the same pathname
-sanitization, route matching, and query extraction behavior.
+`connectRouter()` of `@xmachines/play-dom-router` and `RouterBridgeBase` both use
+this helper. Therefore a low-level adapter and a framework adapter clean each
+pathname, match each route, and read each query in the same way.
 
 ## Parameters
 

package/api/@xmachines/play-router/functions/buildRouteTree.md

@@ -6,32 +6,33 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/build-tree.ts#L21)
+Defined in: [build-tree.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/build-tree.ts#L22)
 
-Build hierarchical route tree from flat route list
+Builds the hierarchical route tree from the flat list of the routes
 
-Constructs nested tree respecting parent-child state relationships.
-Absolute routes become top-level, relative routes nest under parents.
-Creates bidirectional maps for state ID ↔ path lookup.
+The function makes a nested tree, and it keeps the parent-child relation of the
+states. An absolute route becomes a route of the top level, and a relative route
+goes below its parent. The function also makes the maps of both directions, for
+the lookup between a state ID and a path.
 
-Duplicate detection runs here — after relative routes are resolved against
-their parent's full path — so two relative routes with the same raw string
-under different parents are valid, while distinct raw strings that resolve to
-the same full path (which would silently overwrite each other in `byPath`)
-are rejected.
+The detection of a duplicate runs here, after the function resolved each relative
+route against the complete path of its parent. Therefore two relative routes with
+the same raw string below two different parents are valid, and two different raw
+strings that resolve to the same complete path are not: those two overwrite each
+other in `byPath` in silence.
 
 ## Parameters
 
-| Parameter | Type                                        | Description                            |
-| --------- | ------------------------------------------- | -------------------------------------- |
-| `routes`  | [`RouteInfo`](../interfaces/RouteInfo.md)[] | Flat list of RouteInfo from extraction |
+| Parameter | Type                                        | Description                                                 |
+| --------- | ------------------------------------------- | ----------------------------------------------------------- |
+| `routes`  | [`RouteInfo`](../interfaces/RouteInfo.md)[] | The flat list of the RouteInfo objects, from the extraction |
 
 ## Returns
 
 [`RouteTree`](../interfaces/RouteTree.md)
 
-RouteTree with root, byStateId map, and byPath map
+The RouteTree, with its root, its byStateId map, and its byPath map
 
 ## Throws
 
-If two states resolve to the same full path
+When two states resolve to the same complete path

package/api/@xmachines/play-router/functions/createRouteMap.md

@@ -6,27 +6,28 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L47)
 
-Create a `RouteMap` from an XState state machine.
+Creates a `RouteMap` from an XState state machine.
 
-Extracts all routable states (those with `meta.route`) and builds a bidirectional
-path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
-subclasses to translate browser URL changes into `play.route` actor events and
-vice-versa.
+The function reads every state with a route, which means each state with a
+`meta.route` field. It then builds the lookup structure between a path and a
+stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+converts each change of the browser URL into a `play.route` actor event, and each
+actor route into a URL.
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
-| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+| Parameter  | Type                                                                      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine, with a `meta.route` annotation on each state with a route.                                         |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | The optional configuration. Give `{ cacheSize }` to change the default size of the LRU cache of the parameterized path lookups. |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
 
-A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ## Example
 

package/api/@xmachines/play-router/functions/createRouteMapFromTree.md

@@ -6,41 +6,41 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
-Create a `RouteMap` from a `RouteTree` node structure.
+Creates a `RouteMap` from the node structure of a `RouteTree`.
 
-Used by framework-router adapters that pass a
-`RouteTree` produced by `extractMachineRoutes()` rather than calling
-`createRouteMap()` directly.
+A framework router adapter uses this function when it gives a `RouteTree` from
+`extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
 
-Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
-`node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
-which is what `RouteMap` needs for browser URL matching. This matches the
-behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
+The function walks every node, and it collects the pairs
+`{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
+absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` needs
+that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
+same way, because it also uses `node.fullPath`.
 
 ## Parameters
 
-| Parameter   | Type                                                  | Description                                                                   |
-| ----------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md)             | A `RouteTree` as returned by `extractMachineRoutes()`.                        |
-| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size). |
+| Parameter   | Type                                                  | Description                                                                                  |
+| ----------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md)             | A `RouteTree`, as `extractMachineRoutes()` returns it.                                       |
+| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache. |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
 
-A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ## Example
 
 ```typescript
-// Preferred — single call for XState machines:
+// The preferred form — one call for an XState machine:
 import { createRouteMap } from "@xmachines/play-router";
-const routeMap = createRouteMap(machine); // takes AnyStateMachine
+const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
 
-// Two-step form used by framework adapters that work with route trees:
+// The two-step form, for a framework adapter that works with a route tree:
 import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
 const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
 ```

package/api/@xmachines/play-router/functions/detectDuplicateRoutes.md

@@ -6,29 +6,30 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L69)
+Defined in: [validate-routes.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L70)
 
-Detect duplicate route paths
+Finds each duplicate route path
 
-THROWS ERROR when multiple states share the same RESOLVED full path.
+The function THROWS AN ERROR when more than one state holds the same RESOLVED
+complete path.
 
-Detection operates on resolved full paths (after relative routes have been
-prefixed with their parent's path in `buildRouteTree`), not on raw route
-strings: two relative `"settings"` routes under different parents resolve to
-distinct full paths and are valid, while a relative route and an absolute
-route resolving to the same URL genuinely collide and must be rejected.
-Called from `buildRouteTree` once full paths are known.
+The detection works on the resolved complete paths, after `buildRouteTree` put the
+path of each parent before its relative routes. It does not work on the raw route
+strings: two relative `"settings"` routes below two different parents resolve to
+two different complete paths, and they are valid; a relative route and an absolute
+route that resolve to the same URL are a real collision, and the function refuses
+them. `buildRouteTree` calls this function when the complete paths are known.
 
-Rationale: URL-based routing requires one-to-one mapping between URLs and states.
-Multiple states at the same path creates ambiguity for browser navigation (back button,
-direct URL access). Use different paths for different states, or single state with
-conditional rendering.
+The reason: a routing on the URL requires one state for each URL. Two states at
+the same path make the browser navigation ambiguous, for the BACK button and for a
+direct URL. Use a different path for each state, or use one state with a
+conditional render.
 
 ## Parameters
 
-| Parameter | Type                                                        | Description                                                         |
-| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
-| `routes`  | [`ResolvedRoutePath`](../interfaces/ResolvedRoutePath.md)[] | Array of route entries with resolved full paths (e.g. `RouteNode`s) |
+| Parameter | Type                                                        | Description                                                                                            |
+| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `routes`  | [`ResolvedRoutePath`](../interfaces/ResolvedRoutePath.md)[] | The array of the route entries with their resolved complete paths, for example the `RouteNode` objects |
 
 ## Returns
 
@@ -36,4 +37,4 @@ conditional rendering.
 
 ## Throws
 
-If duplicate resolved route paths are detected
+When the function finds two resolved route paths that are equal

package/api/@xmachines/play-router/functions/extractMachineRoutes.md

@@ -6,23 +6,24 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/extract-routes.ts#L89)
+Defined in: [extract-routes.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/extract-routes.ts#L92)
 
-Extract complete route tree from state machine graph
+Reads the complete route tree from the graph of a state machine
 
-Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
-then walks graph nodes to extract route metadata, validate route references,
-and build a hierarchical RouteTree. The graph is attached to the returned
-RouteTree for downstream transition-aware queries.
+The function converts the XState machine into a Graph of @statelyai/graph, with
+machineToGraph(). It then walks the graph nodes: it reads the route metadata of
+each node, it checks each route reference, and it builds a hierarchical RouteTree.
+The RouteTree of the return value also holds the graph, for a later query that
+needs the transitions.
 
 ## Parameters
 
-| Parameter | Type                                                                      | Description             |
-| --------- | ------------------------------------------------------------------------- | ----------------------- |
-| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine |
+| Parameter | Type                                                                      | Description                 |
+| --------- | ------------------------------------------------------------------------- | --------------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine |
 
 ## Returns
 
 [`RouteTree`](../interfaces/RouteTree.md)
 
-Route tree with root, byStateId map, byPath map, and graph
+The route tree, with its root, its byStateId map, its byPath map, and its graph

package/api/@xmachines/play-router/functions/extractQuery.md

@@ -6,10 +6,10 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L149)
+Defined in: [router-sync.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L155)
 
-Parse a URL search string into the plain object shape expected by
-`play.route` events.
+Parses a URL search string into the plain object that a `play.route` event
+needs.
 
 ## Parameters
 

package/api/@xmachines/play-router/functions/extractRouteParams.md

@@ -6,40 +6,43 @@
 function extractRouteParams(pathname, pattern): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L112)
+Defined in: [router-sync.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L117)
 
-Extract named path parameters from a URL using the URLPattern API.
+Reads the named path parameters of a URL, with the URLPattern API.
 
-Takes the pattern string directly — use this when the pattern is already known.
-For extraction via a state ID lookup, see `RouterBridgeBase.extractParams`.
+The function takes the string of the pattern directly. Use it when you know the
+pattern already. For a read through the lookup of a state ID, see
+`RouterBridgeBase.extractParams`.
 
-Undefined values (unmatched optional segments, e.g. `/settings` against
-`/settings/:section?`) are omitted from the returned object.
+The object of the return holds no undefined value. Such a value comes from an
+optional segment without a match, for example `/settings` against
+`/settings/:section?`.
 
-The pattern is normalized with the same rules `RouteMap` uses for matching
-(hyphenated names like `:cat-id` become `:cat_id` for URLPattern), and the
-extracted group names are mapped back to the original param names, so
-`/docs/123` against `/docs/:cat-id` yields `{ "cat-id": "123" }`.
+The function normalizes the pattern with the rules of the match in `RouteMap`: a
+name with a hyphen, such as `:cat-id`, becomes `:cat_id` for URLPattern. It then
+maps each group name back to the original param name. Therefore `/docs/123`
+against `/docs/:cat-id` gives `{ "cat-id": "123" }`.
 
-Values are percent-decoded (`john%20doe` → `john doe`), matching framework
-router semantics (e.g. vue-router). Malformed sequences are kept raw.
+The function decodes each percent sequence of a value (`john%20doe` → `john doe`),
+as a framework router does, for example vue-router. It keeps a malformed sequence
+raw.
 
 ## Parameters
 
-| Parameter  | Type     | Description                                          |
-| ---------- | -------- | ---------------------------------------------------- |
-| `pathname` | `string` | The concrete URL pathname (e.g. `/profile/alice`)    |
-| `pattern`  | `string` | The URL pattern template (e.g. `/profile/:username`) |
+| Parameter  | Type     | Description                                                       |
+| ---------- | -------- | ----------------------------------------------------------------- |
+| `pathname` | `string` | The concrete URL pathname, for example `/profile/alice`           |
+| `pattern`  | `string` | The template of the URL pattern, for example `/profile/:username` |
 
 ## Returns
 
 `Record`\<`string`, `string`\>
 
-A record of extracted parameter values, or `{}` for static patterns.
+The record of the parameter values of the read, or `{}` for a static pattern.
 
 ## Throws
 
-When `URLPattern` is absent and the pattern is parameterized.
+When `URLPattern` is absent and the pattern holds a parameter.
 
 ## Example
 
@@ -50,5 +53,5 @@ extractRouteParams("/profile/alice", "/profile/:username");
 // → { username: "alice" }
 
 extractRouteParams("/settings", "/settings/:section?");
-// → {}  (optional param absent — not included)
+// → {}  — the optional param is absent, and the object holds it not
 ```

package/api/@xmachines/play-router/functions/findRouteById.md

@@ -6,25 +6,26 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/find-route.ts#L57)
+Defined in: [find-route.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/find-route.ts#L59)
 
-Find route node by state ID
+Finds a route node by its state ID
 
-Looks up route node using the state's ID property. Used to get URL path
-from state ID for browser URL sync after play.route transitions.
+The function looks the route node up by the ID property of the state. It gives you
+the URL path of a state ID, for the update of the browser URL after a `play.route`
+transition.
 
 ## Parameters
 
-| Parameter | Type                                      | Description                                      |
-| --------- | ----------------------------------------- | ------------------------------------------------ |
-| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | Route tree from extractMachineRoutes             |
-| `id`      | `string`                                  | State ID (e.g., 'dashboard', 'settings.profile') |
+| Parameter | Type                                      | Description                                                 |
+| --------- | ----------------------------------------- | ----------------------------------------------------------- |
+| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | The route tree, from extractMachineRoutes                   |
+| `id`      | `string`                                  | The state ID, for example 'dashboard' or 'settings.profile' |
 
 ## Returns
 
 [`RouteNode`](../interfaces/RouteNode.md) \| `undefined`
 
-Route node if found, undefined otherwise
+The route node, or undefined when the function finds none
 
 ## Example
 

package/api/@xmachines/play-router/functions/findRouteByPath.md

@@ -6,30 +6,32 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/find-route.ts#L82)
+Defined in: [find-route.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/find-route.ts#L86)
 
-Find route node by URL path
+Finds a route node by its URL path
 
-Looks up route node using the URL path. Used to get state ID from browser
-URL for sending play.route events on navigation.
+The function looks the route node up by the URL path. It gives you the state ID of
+a browser URL, for the `play.route` event of a navigation.
 
-When multiple states share the same path (e.g., root and a state both at "/"),
-prefers routable nodes (with meta.route) over non-routable nodes.
+When more than one state holds the same path, for example the root and a second
+state both at "/", the function prefers a node with a route, which means a node
+with a `meta.route` field, over a node without one.
 
-Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
+The function also matches a pattern of a dynamic route, for example
+'/settings/:section?'.
 
 ## Parameters
 
-| Parameter | Type                                      | Description                                        |
-| --------- | ----------------------------------------- | -------------------------------------------------- |
-| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | Route tree from extractMachineRoutes               |
-| `path`    | `string`                                  | URL path (e.g., '/dashboard', '/settings/profile') |
+| Parameter | Type                                      | Description                                                   |
+| --------- | ----------------------------------------- | ------------------------------------------------------------- |
+| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | The route tree, from extractMachineRoutes                     |
+| `path`    | `string`                                  | The URL path, for example '/dashboard' or '/settings/profile' |
 
 ## Returns
 
 [`RouteNode`](../interfaces/RouteNode.md) \| `undefined`
 
-Route node if found, undefined otherwise
+The route node, or undefined when the function finds none
 
 ## Example
 

package/api/@xmachines/play-router/functions/getNavigableRoutes.md

@@ -6,25 +6,25 @@
 function getNavigableRoutes(tree, stateId): RouteNode[];
 ```
 
-Defined in: [query.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/query.ts#L41)
+Defined in: [query.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/query.ts#L41)
 
-Get all routes navigable from given state
+Returns every route of a navigation from the given state
 
-Returns child routes of the specified state. Future enhancement will
-include sibling routes reachable via transitions.
+The function returns the child routes of the state. A later version also returns
+the sibling routes of a transition.
 
 ## Parameters
 
-| Parameter | Type                                      | Description                            |
-| --------- | ----------------------------------------- | -------------------------------------- |
-| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
-| `stateId` | `string`                                  | Current state ID                       |
+| Parameter | Type                                      | Description                                 |
+| --------- | ----------------------------------------- | ------------------------------------------- |
+| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | The route tree, from extractMachineRoutes() |
+| `stateId` | `string`                                  | The ID of the current state                 |
 
 ## Returns
 
 [`RouteNode`](../interfaces/RouteNode.md)[]
 
-Array of route nodes reachable from state
+The array of the route nodes that the state can reach
 
 ## Example
 

package/api/@xmachines/play-router/functions/getRoutableRoutes.md

@@ -6,25 +6,25 @@
 function getRoutableRoutes(tree): RouteNode[];
 ```
 
-Defined in: [query.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/query.ts#L103)
+Defined in: [query.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/query.ts#L106)
 
-Get all routable routes from tree as flat array
+Returns every route of the tree that has a route, in one flat array
 
-Returns all routes that have meta.route defined, excluding non-routable
-states and the synthetic root node. Useful for dynamically generating
-router configurations in framework adapters.
+The function returns each route with a `meta.route` field. It returns no state
+without a route, and no synthetic root node. Use it to generate a router
+configuration in a framework adapter dynamically.
 
 ## Parameters
 
-| Parameter | Type                                      | Description                            |
-| --------- | ----------------------------------------- | -------------------------------------- |
-| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
+| Parameter | Type                                      | Description                                 |
+| --------- | ----------------------------------------- | ------------------------------------------- |
+| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | The route tree, from extractMachineRoutes() |
 
 ## Returns
 
 [`RouteNode`](../interfaces/RouteNode.md)[]
 
-Array of routable route nodes with path and stateId
+The array of the route nodes with a route, with their path and their stateId
 
 ## Example
 

package/api/@xmachines/play-router/functions/getTransitionReachableRoutes.md

@@ -6,31 +6,32 @@
 function getTransitionReachableRoutes(graph, stateId): string[];
 ```
 
-Defined in: [query.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/query.ts#L154)
+Defined in: [query.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/query.ts#L158)
 
-Get routes reachable via transitions from current state
+Returns the routes that a transition from the current state can reach
 
-Uses the @statelyai/graph successor algorithm to find all states
-directly reachable via transition edges from the given state,
-then filters to those with defined routes.
+The function uses the successor algorithm of @statelyai/graph. It finds every
+state of a direct transition edge from the given state, then it keeps the states
+with a route.
 
-Returned values are the RAW `meta.route` strings from the machine — relative
-routes (e.g. `"detail"`) are NOT resolved to full paths and cannot be used as
-`tree.byPath` keys. For resolved `RouteNode`s use `getNavigableRoutes`, which
-resolves reachable states through `tree.byStateId`.
+The values of the return are the RAW `meta.route` strings of the machine. The
+function does NOT resolve a relative route, for example `"detail"`, to a complete
+path, and such a value is therefore no key of `tree.byPath`. For a resolved
+`RouteNode`, use `getNavigableRoutes`: that function resolves each state that the
+transition reaches through `tree.byStateId`.
 
 ## Parameters
 
-| Parameter | Type                                                                                                                    | Description                          |
-| --------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `graph`   | `Graph`\<[`MachineNodeData`](../interfaces/MachineNodeData.md), [`MachineEdgeData`](../interfaces/MachineEdgeData.md)\> | Machine graph from RouteTree.graph   |
-| `stateId` | `string`                                                                                                                | Current state ID (e.g., "test.home") |
+| Parameter | Type                                                                                                                    | Description                                          |
+| --------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `graph`   | `Graph`\<[`MachineNodeData`](../interfaces/MachineNodeData.md), [`MachineEdgeData`](../interfaces/MachineEdgeData.md)\> | The machine graph, from RouteTree.graph              |
+| `stateId` | `string`                                                                                                                | The ID of the current state, for example "test.home" |
 
 ## Returns
 
 `string`[]
 
-Array of raw route strings reachable via transitions
+The array of the raw route strings that a transition can reach
 
 ## Example
 
@@ -38,6 +39,6 @@ Array of raw route strings reachable via transitions
 const tree = extractMachineRoutes(machine);
 if (tree.graph) {
 	const reachable = getTransitionReachableRoutes(tree.graph, "auth.loggedIn");
-	// ['/dashboard', '/settings'] — routes reachable via transitions
+	// ['/dashboard', '/settings'] — the routes that a transition can reach
 }
 ```