@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/api/@xmachines/play-router/classes/RouteMap.md

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L105)
 
-Shared bidirectional route map base class.
+The shared base class of the route map for both directions.
 
-All framework adapters use this class as their route map — they add no logic of their
-own and inherit the full public API from here.
+Every framework adapter uses this class as its route map. An adapter adds no logic
+of its own, and it inherits the complete public API from here.
 
-**Lookup strategy:**
+**The strategy of a lookup:**
 
-- Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
-  of routes sharing the same first path segment
-- Results are cached after the first match in an LRU cache (default 500 entries,
-  configurable via the `cacheSize` constructor option)
+- A static path, without a `:param` → a `Map` lookup in O(1)
+- A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
+  `k` is the number of the routes with the same first path segment
+- The class keeps each result of a first match in an LRU cache. The default size
+  is 500 entries, and the `cacheSize` constructor option changes it
 
-**Pattern syntax** (`:param` / `:param?` / `*`):
+**The syntax of a pattern** (`:param`, `:param?`, and `*`):
 
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-- `*` — wildcard, matches any number of segments (URLPattern semantics)
+- `:param` — a necessary segment. It matches exactly one segment without a `/`
+- `:param?` — an optional segment. It matches zero segments or one segment without a `/`
+- `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
-**StateId forms:** stateIds may be registered and looked up in either
-`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
-`getStateIdByPath` returns the stateId exactly as registered;
-`getPathByStateId` accepts both forms. Registering the same stateId in both
-forms refers to one entry (the later registration wins for reverse lookup).
+**The forms of a stateId:** you can register a stateId, and you can look one up,
+in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
+canonical form itself. `getStateIdByPath` returns the stateId exactly as you
+registered it, and `getPathByStateId` accepts both forms. A registration of the
+same stateId in both forms gives one entry, and the later registration wins for
+the lookup in the other direction.
 
 ## Example
 
@@ -57,21 +58,22 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L133)
 
-Build a route map from an array of state ID ↔ path mappings.
+Builds a route map from an array of the mappings between a state ID and a path.
 
-Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `URLPattern` and grouped into first-segment
-buckets for efficient candidate selection.
+The constructor puts each static path, which holds no `:param`, into a `Map` for a
+lookup in O(1). It compiles each parameterized path to a `URLPattern`, and it
+groups the patterns into the buckets of the first segment. The selection of the
+candidates is therefore efficient.
 
 #### Parameters
 
-| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
-| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
-| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
-| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                                                                                                                                                                                                                                                                                                                                                     |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | The optional configuration. `options.cacheSize`: the maximum number of the resolved parameterized path lookups in the cache. The default is `500`. Raise it for an application with many different values in a parameterized URL, for example a page of a user profile with thousands of different IDs. After an eviction, the path goes to the bucket pattern scan in O(k) again, which is correct but slower. The smallest effective value is `1`, because QuickLRU requires it. |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 #### Returns
 
@@ -85,31 +87,31 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [base-route-map.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L225)
 
-Look up the path pattern registered for a state ID.
+Returns the path pattern of a state ID.
 
-Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
-which form was used at registration — lookups are canonicalized internally,
-so consumers never need to try both forms.
+The method accepts the stateId in the form `"#stateId"` and in the form
+`"stateId"`, and the form of the registration has no effect. The method makes the
+canonical form itself. Therefore a consumer tries never both forms.
 
 #### Parameters
 
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+| Parameter | Type     | Description                                                                 |
+| --------- | -------- | --------------------------------------------------------------------------- |
+| `stateId` | `string` | The state ID of the state machine, for example `"profile"` or `"#settings"` |
 
 #### Returns
 
 `string` \| `null`
 
-The registered path pattern, or `null` if the state ID is unknown
+The registered path pattern, or `null` when the state ID is unknown
 
 #### Example
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("#profile"); // "/profile/:userId" — the same entry
 map.getPathByStateId("missing"); // null
 ```
 
@@ -121,25 +123,25 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [base-route-map.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L185)
 
-Resolve a URL path to its mapped state ID.
+Resolves a URL path to its state ID.
 
-Strips query strings and hash fragments before matching. Tries an O(1) exact
-lookup first, then falls back to bucket-indexed pattern matching. Results are
-cached after the first pattern match.
+The method removes the query string and the hash fragment before the match. It
+tries an exact lookup in O(1) first, then it uses the pattern match on the bucket
+index. It keeps each result of a first pattern match in the cache.
 
 #### Parameters
 
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+| Parameter | Type     | Description                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------- |
+| `path`    | `string` | The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"` |
 
 #### Returns
 
 `string` \| `null`
 
-The mapped state ID, or `null` if no route matches
+The state ID of the path, or `null` when no route matches
 
 #### Example
 

package/api/@xmachines/play-router/classes/RouterBridgeBase.md

@@ -2,19 +2,22 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L96)
+Defined in: [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L99)
 
-Abstract base class for all `@xmachines` router adapter bridges.
+The abstract base class of every router adapter bridge of `@xmachines`.
 
-Implements RouterBridge protocol and contains all common bridge logic.
-Subclasses only need to implement the 3 abstract methods that differ
-between frameworks.
+The class implements the RouterBridge protocol, and it holds every part of the
+bridge logic that the adapters share. A subclass implements the 3 abstract methods
+that are different in each framework, and it implements nothing more.
 
 ## Extended by
 
+- [`DomRouterBridge`](../../play-dom-router/classes/DomRouterBridge.md)
 - [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
 - [`TanStackRouterBridgeBase`](../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
 - [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
+- [`SvelteKitRouterBridge`](../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
+- [`SvelteSpaRouterBridge`](../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
 - [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
 - [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
 
@@ -30,14 +33,14 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L123)
+Defined in: [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L127)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                        |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one. |
+| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only. |
 | `routeMap.getPathByStateId` | -                                                                                                                   |
 | `routeMap.getStateIdByPath` | -                                                                                                                   |
 
@@ -53,21 +56,23 @@ Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L151)
+Defined in: [router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L158)
 
-Connect the router bridge to the Actor.
+Connects the router bridge to the Actor.
 
-Sets up the TC39 Signal watcher for actor → router direction and
-starts watching router changes (framework-specific).
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
 
-Ordering here is part of the bridge contract:
+The order of these steps is part of the contract of the bridge:
 
-- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-- the actor watcher is installed before adapter router subscriptions
-- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The method installs the actor watcher before the router subscriptions of the adapter
+- The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
-Adapters that need custom initial-sync behavior should override
-`getInitialRouterPath()` rather than reordering `connect()` steps.
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
 
 #### Returns
 
@@ -85,11 +90,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L256)
+Defined in: [router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L270)
 
-Disconnect the router bridge from the Actor.
+Disconnects the router bridge from the Actor.
 
-Stops signal watching and unregisters framework-specific router listener.
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
 
 #### Returns
 

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-alpha.1/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-alpha.1/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-alpha.1/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 v6 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-alpha.1/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-alpha.1/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-alpha.1/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 v6 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-alpha.1/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