@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play-router/interfaces/RoutableActor.md

@@ -2,21 +2,22 @@
 
 # Interface: RoutableActor
 
-Defined in: [types.ts:259](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L259)
+Defined in: [types.ts:272](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L272)
 
-Minimal actor interface required by `RouterBridgeBase` and all framework router
-adapters.
+The minimal actor interface that `RouterBridgeBase` and every framework router
+adapter require.
 
-Using this interface instead of `AbstractActor<AnyActorLogic> & Routable` lets
-`RouterBridgeBase.actor.send` be typed to accept `PlayRouteEvent` directly —
-eliminating the unsafe `(actor.send as (e: PlayRouteEvent) => void)` cast that
-existed when the actor was typed with the weaker `EventObject` constraint.
+This interface, and not `AbstractActor<AnyActorLogic> & Routable`, gives
+`RouterBridgeBase.actor.send` the type that accepts a `PlayRouteEvent` directly.
+It therefore removes the unsafe cast `(actor.send as (e: PlayRouteEvent) => void)`,
+which the weaker `EventObject` constraint of the actor type needed before.
 
-All `AbstractActor` subclasses satisfy this interface structurally because:
+Every `AbstractActor` subclass satisfies this interface structurally, for two
+reasons:
 
-- `AbstractActor` implements `send(event: TEvent): void` where `TEvent` accepts
-  any `EventObject`, so `PlayRouteEvent` (a subtype) is always accepted.
-- `Routable` provides `currentRoute` and `initialRoute`.
+- `AbstractActor` implements `send(event: TEvent): void`, and `TEvent` accepts each
+  `EventObject`. Therefore it always accepts a `PlayRouteEvent`, which is a subtype.
+- `Routable` gives `currentRoute` and `initialRoute`.
 
 ## Example
 
@@ -36,10 +37,10 @@ class MyBridge extends RouterBridgeBase {
 
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                         | Description                                                                                                                                                                                                   | Defined in                                                                                                      |
-| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L261) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L267) |
+| Property                                          | Modifier   | Type                                                                                         | Description                                                                                                                                                                                                                              | Defined in                                                                                                      |
+| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | The TC39 Signal of the current URL path of the actor, or of its state ID.                                                                                                                                                                | [types.ts:274](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L274) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | The route of the initial state of the machine. The constructor fixes it. A router bridge compares it with the browser URL. It therefore separates a deep link, where the router wins, from a restore of a session, where the actor wins. | [types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L280) |
 
 ## Methods
 
@@ -49,9 +50,9 @@ class MyBridge extends RouterBridgeBase {
 send(event): void;
 ```
 
-Defined in: [types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L269)
+Defined in: [types.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L282)
 
-Send a route navigation event to the actor.
+Sends a route navigation event to the actor.
 
 #### Parameters
 

package/api/@xmachines/play-router/interfaces/RouteInfo.md

@@ -2,18 +2,18 @@
 
 # Interface: RouteInfo
 
-Defined in: [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L56)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L60)
 
-Extracted route information from a state node
+The route information of a state node
 
 ## Properties
 
-| Property                                      | Type                                                | Description                                                                                          | Defined in                                                                                                    |
-| --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L66) |
-| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L73) |
-| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L64) |
-| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L71) |
-| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L62) |
-| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L58) |
-| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L60) |
+| Property                                      | Type                                                | Description                                                                                                                                                 | Defined in                                                                                                    |
+| --------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | It tells you if the route path is absolute, which means that it starts with /                                                                               | [types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L70) |
+| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | The original route metadata                                                                                                                                 | [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L77) |
+| <a id="property-pattern"></a> `pattern?`      | `string`                                            | The route pattern with its parameters, for example /profile/:userId, when routePath holds a parameter                                                       | [types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L68) |
+| <a id="property-routable"></a> `routable`     | `boolean`                                           | It tells you if this state has a route, which means that it has a meta.route field. true = it has a meta.route field, and it can receive a play.route event | [types.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L75) |
+| <a id="property-routepath"></a> `routePath`   | `string`                                            | The route path of meta.route                                                                                                                                | [types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L66) |
+| <a id="property-stateid"></a> `stateId`       | `string`                                            | The identifier of the state: node.id, or path.join('.')                                                                                                     | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L62) |
+| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | The segments of the state path, from the root                                                                                                               | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L64) |

package/api/@xmachines/play-router/interfaces/RouteMapOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L9)
 
-Options for `createRouteMap` and `createRouteMapFromTree`.
+The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                          |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L20) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L21) |

package/api/@xmachines/play-router/interfaces/RouteMapping.md

@@ -2,14 +2,15 @@
 
 # Interface: RouteMapping
 
-Defined in: [base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L54)
 
-A single state ID ↔ path mapping entry.
+One entry of the map between a state ID and a path.
 
-Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
-Adapter packages re-export a structurally compatible `RouteMapping` type under
-their own name. This type is published from `@xmachines/play-router` as
-`RouteMapping` to avoid name collisions with those adapter-local types.
+Both fields are `readonly`, because a mapping is immutable after the caller gives
+it to `RouteMap`. An adapter package re-exports a structurally compatible
+`RouteMapping` type under its own name. `@xmachines/play-router` publishes this
+type as `RouteMapping`, and its name therefore does not collide with such a local
+type of an adapter.
 
 ## Example
 
@@ -21,7 +22,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                      |
-| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L53) |
+| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L56) |

package/api/@xmachines/play-router/interfaces/RouteMatch.md

@@ -2,11 +2,11 @@
 
 # Interface: RouteMatch
 
-Defined in: [router-sync.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L12)
+Defined in: [router-sync.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L12)
 
 ## Properties
 
 | Property                               | Type                              | Defined in                                                                                                                |
 | -------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L14) |
-| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L13) |
+| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L14) |
+| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L13) |

package/api/@xmachines/play-router/interfaces/RouteNode.md

@@ -2,20 +2,20 @@
 
 # Interface: RouteNode
 
-Defined in: [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L79)
+Defined in: [types.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L83)
 
-Node in the route tree representing a single route
+A node of the route tree. It represents one route
 
 ## Properties
 
-| Property                                  | Type                                                | Description                                                                                                                                                                                                                  | Defined in                                                                                                      |
-| ----------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children` | `RouteNode`[]                                       | Child routes                                                                                                                                                                                                                 | [types.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L103) |
-| <a id="property-fullpath"></a> `fullPath` | `string`                                            | The fully resolved absolute path from the root (e.g. `"/dashboard/overview"`). Always use `fullPath` for browser URL matching and route map construction. `createRouteMapFromTree` and `createRouteMap` both use this field. | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L92)   |
-| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                                                                                                                                                 | [types.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L81)   |
-| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                                                                                                                                                 | [types.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L107) |
-| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                                                                                                                                                 | [types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L105) |
-| <a id="property-path"></a> `path`         | `string`                                            | The raw route path segment as declared in `meta.route` — may be relative (e.g. `"overview"`) or absolute (e.g. `"/dashboard"`). Do not use this for URL matching; use `fullPath` instead.                                    | [types.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L86)   |
-| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                                                                                                                                               | [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L94)   |
-| <a id="property-routable"></a> `routable` | `boolean`                                           | Whether this state is routable (has meta.route) States with meta.route can receive play.route events                                                                                                                         | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L101) |
-| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                                                                                                                                           | [types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L96)   |
+| Property                                  | Type                                                | Description                                                                                                                                                                                                                                   | Defined in                                                                                                      |
+| ----------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-children"></a> `children` | `RouteNode`[]                                       | The child routes                                                                                                                                                                                                                              | [types.ts:108](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L108) |
+| <a id="property-fullpath"></a> `fullPath` | `string`                                            | The complete absolute path from the root, for example `"/dashboard/overview"`. Always use `fullPath` for a match of a browser URL and for the construction of a route map. `createRouteMapFromTree` and `createRouteMap` both use this field. | [types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L97)   |
+| <a id="property-id"></a> `id`             | `string`                                            | The unique identifier, which is the state ID                                                                                                                                                                                                  | [types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L85)   |
+| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | The original meta.route metadata                                                                                                                                                                                                              | [types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L112) |
+| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | The parent route. It is null for the root                                                                                                                                                                                                     | [types.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L110) |
+| <a id="property-path"></a> `path`         | `string`                                            | The raw segment of the route path, as `meta.route` declares it. It is relative, for example `"overview"`, or absolute, for example `"/dashboard"`. Never use it for a match of a URL: use `fullPath` for that.                                | [types.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L91)   |
+| <a id="property-pattern"></a> `pattern?`  | `string`                                            | The route pattern with its parameters, for example /profile/:userId, when path holds a parameter                                                                                                                                              | [types.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L99)   |
+| <a id="property-routable"></a> `routable` | `boolean`                                           | It tells you if this state has a route, which means that it has a meta.route field. A state with a meta.route field can receive a play.route event                                                                                            | [types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L106) |
+| <a id="property-stateid"></a> `stateId`   | `string`                                            | The XState state ID of this route                                                                                                                                                                                                             | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L101) |

package/api/@xmachines/play-router/interfaces/RouteObject.md

@@ -2,9 +2,9 @@
 
 # Interface: RouteObject
 
-Defined in: [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L41)
+Defined in: [types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L45)
 
-Route object with additional metadata.
+A route object, with more metadata.
 
 ## Indexable
 
@@ -12,10 +12,10 @@ Route object with additional metadata.
 [key: string]: unknown
 ```
 
-Additional route metadata (title, breadcrumb, etc.)
+The additional metadata of the route: a title, a breadcrumb, and so on
 
 ## Properties
 
-| Property                          | Type     | Description                             | Defined in                                                                                                    |
-| --------------------------------- | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L43) |
+| Property                          | Type     | Description                                             | Defined in                                                                                                    |
+| --------------------------------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `string` | The template of the route path, for example '/user/:id' | [types.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L47) |

package/api/@xmachines/play-router/interfaces/RouteTree.md

@@ -2,20 +2,20 @@
 
 # Interface: RouteTree
 
-Defined in: [types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L117)
+Defined in: [types.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L122)
 
-Complete route tree with lookup maps
+The complete route tree, with its lookup maps
 
-Provides bidirectional mapping between state IDs and URL paths:
+It gives you the map between a state ID and a URL path, in both directions:
 
-- byStateId: Maps state IDs to route nodes (for play.route event targeting)
-- byPath: Maps URL paths to route nodes (for browser navigation)
+- byStateId: it maps each state ID to its route node, for the target of a play.route event
+- byPath: it maps each URL path to its route node, for the browser navigation
 
 ## Properties
 
-| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                      | Defined in                                                                                                      |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | Map full path -> route node Used to look up state ID from URL path for play.route event targeting                                                                                                                                                                                                                                                                | [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L129) |
-| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | Map state ID -> route node Used to look up URL path from state ID for browser URL sync                                                                                                                                                                                                                                                                           | [types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L124) |
-| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | Graph representation of the state machine for advanced queries. Populated by extractMachineRoutes() — use for hierarchy queries, reachability checks, and transition-aware navigation via @statelyai/graph algorithms. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L141) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | Root route node                                                                                                                                                                                                                                                                                                                                                  | [types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L119) |
+| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                      |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a complete path to its route node. It gives you the state ID of a URL path, for the target of a play.route event                                                                                                                                                                                                                                                                       | [types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L134) |
+| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a state ID to its route node. It gives you the URL path of a state ID, for the update of the browser URL                                                                                                                                                                                                                                                                               | [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L129) |
+| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | The graph of the state machine, for an advanced query. extractMachineRoutes() fills it. Use it for a query of the hierarchy, for a test of the reachability, and for a navigation that knows the transitions, through the algorithms of @statelyai/graph. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L147) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | The root node of the routes                                                                                                                                                                                                                                                                                                                                                                         | [types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L124) |

package/api/@xmachines/play-router/interfaces/RouteWatcherHandle.md

@@ -2,19 +2,19 @@
 
 # Interface: RouteWatcherHandle
 
-Defined in: [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L71)
+Defined in: [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L72)
 
-Narrow interface for the TC39 Signal watcher used by `RouterBridgeBase` to
-monitor `actor.currentRoute` changes.
+The narrow interface of the TC39 Signal watcher. `RouterBridgeBase` uses it to
+observe each change of `actor.currentRoute`.
 
-This interface hides the full `Signal.subtle.Watcher` surface and exposes only
-the two operations that `RouterBridgeBase` actually needs:
+The interface hides the complete `Signal.subtle.Watcher` surface. It exposes the
+two operations that `RouterBridgeBase` needs:
 
-- `watch(signal)` — arm the watcher on a specific signal
-- `unwatch()` — stop watching and release resources
+- `watch(signal)` — it arms the watcher on one signal
+- `unwatch()` — it stops the watch and frees the resources
 
-Framework adapter subclasses never interact with this handle directly; it is
-created and managed internally by `RouterBridgeBase`.
+A framework adapter subclass touches this handle never. `RouterBridgeBase` makes
+it and manages it internally.
 
 ## Methods
 
@@ -24,9 +24,9 @@ created and managed internally by `RouterBridgeBase`.
 unwatch(): void;
 ```
 
-Defined in: [router-bridge-base.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L75)
+Defined in: [router-bridge-base.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L76)
 
-Stop observing and release the watcher.
+Stops the observation and frees the watcher.
 
 #### Returns
 
@@ -40,9 +40,9 @@ Stop observing and release the watcher.
 watch(signal): void;
 ```
 
-Defined in: [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L73)
+Defined in: [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L74)
 
-Arm the watcher to observe the given signal.
+Arms the watcher on the given signal.
 
 #### Parameters
 

package/api/@xmachines/play-router/interfaces/RouterBridge.md

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L341)
+Defined in: [types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L358)
 
-RouterBridge interface for runtime infrastructure adapters
+The RouterBridge interface of a runtime infrastructure adapter
 
-Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
-the Actor. Infrastructure "bridges" to the Actor by observing its signals and
-managing its own lifecycle accordingly.
+The interface defines the connection of the lifecycle between the infrastructure,
+for example a framework router, and the Actor. The infrastructure builds a "bridge"
+to the Actor: it observes the signals of the Actor, and it manages its own
+lifecycle accordingly.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
-a unidirectional observation pattern. Infrastructure connects to observe Actor signals
-(currentRoute, currentView, state) and reflects changes without making state decisions.
+**Architectural context:** the interface implements **Passive Infrastructure
+(INV-04)**, because it gives an observation in one direction. The infrastructure
+connects to observe the signals of the Actor (currentRoute, currentView, and
+state), and it reflects each change. It makes no decision about the state.
 
 ## Example
 
-Framework router bridge implementation
+The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
@@ -26,7 +28,7 @@ class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
-		// Start observing actor.currentRoute signal
+		// Start the observation of the actor.currentRoute signal
 		this.watcher = new Signal.subtle.Watcher(() => {
 			const route = actor.currentRoute.get();
 			if (route) router.navigate(route);
@@ -35,7 +37,7 @@ class MyRouterBridge implements RouterBridge {
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop observing, cleanup watchers
+		// Stop the observation, and clean the watchers up
 		this.watcher?.unwatch(actor.currentRoute);
 		this.watcher = null;
 	}
@@ -44,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -54,25 +56,26 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L357)
+Defined in: [types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L375)
 
-Connect the router bridge to the Actor
+Connects the router bridge to the Actor
 
-Called when Infrastructure should begin observing Actor signals and
-synchronizing its state (e.g., browser URL) with Actor state.
+The infrastructure calls it when it must start the observation of the Actor
+signals, and when it must bring its own state, for example the browser URL, in line
+with the Actor state.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when connection is established, or void for synchronous connection
+The promise that resolves after the connection, or void for a synchronous connection
 
 #### Example
 
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// Bridge now observing actor.currentRoute signal
+// The bridge observes the actor.currentRoute signal now
 ```
 
 ---
@@ -83,22 +86,22 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L373)
+Defined in: [types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L391)
 
-Disconnect the router bridge from the Actor
+Disconnects the router bridge from the Actor
 
-Called when Infrastructure should stop observing and clean up resources
-(e.g., signal watchers, event listeners).
+The infrastructure calls it when it must stop the observation and free its
+resources, for example a signal watcher and an event listener.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when disconnection is complete, or void for synchronous disconnection
+The promise that resolves after the disconnection, or void for a synchronous disconnection
 
 #### Example
 
 ```typescript
 await bridge.disconnect();
-// Bridge stopped observing, resources cleaned up
+// The bridge stopped its observation, and it freed its resources
 ```

package/api/@xmachines/play-router/interfaces/WindowLike.md

@@ -2,22 +2,22 @@
 
 # Interface: WindowLike
 
-Defined in: [types.ts:394](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L394)
+Defined in: [types.ts:412](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L412)
 
-Minimal window interface required by adapters that subscribe to DOM events
-(e.g. `hashchange`). Injectable for SSR and testing — pass a mock instead of
-the global `window` when the DOM is unavailable.
+The minimal window interface of an adapter that subscribes to a DOM event, for
+example to `hashchange`. You can inject it for SSR and for a test: give a mock in
+place of the global `window` when no DOM is available.
 
-Defined structurally (no `Window` reference) so this package compiles without
-the DOM lib.
+The definition is structural, and it holds no reference to `Window`. This package
+therefore compiles without the DOM lib.
 
 ## Example
 
 ```typescript
-// Normal usage — global window (default)
+// The normal use — the global window, which is the default
 connectRouter({ actor, routeMap });
 
-// SSR / test — injected mock
+// SSR or a test — an injected mock
 const mockWin: WindowLike = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
 connectRouter({ actor, routeMap, window: mockWin });
 ```
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L395)
+Defined in: [types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L413)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [types.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:396](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L396)
+Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L414)
 
 #### Parameters
 

package/api/@xmachines/play-router/type-aliases/BaseRouteMapping.md

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMapping
+
+# ~~Type Alias: BaseRouteMapping~~
+
+```ts
+type BaseRouteMapping = RouteMapping;
+```
+
+Defined in: [index.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/index.ts#L61)
+
+## Deprecated
+
+Use [RouteMapping](../interfaces/RouteMapping.md). Will be removed in the next major.

package/api/@xmachines/play-router/type-aliases/MachineGraph.md

@@ -6,10 +6,11 @@
 type MachineGraph = Graph<MachineNodeData, MachineEdgeData>;
 ```
 
-Defined in: [machine-to-graph.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/machine-to-graph.ts#L18)
+Defined in: [machine-to-graph.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/machine-to-graph.ts#L19)
 
-Typed @statelyai/graph Graph representing a state machine.
-Provides hierarchy queries, traversal algorithms, and reachability checks.
+The typed Graph of @statelyai/graph that represents a state machine.
+It gives you the queries of the hierarchy, the algorithms of a walk, and the tests
+of the reachability.
 
 ## Example
 

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

@@ -6,6 +6,6 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [types.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L51)
+Defined in: [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L55)
 
-Route metadata from state machine `meta.route` field.
+The route metadata of the `meta.route` field of a state machine.