@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play-dom-router/interfaces/BrowserHistory.md

@@ -2,17 +2,17 @@
 
 # Interface: BrowserHistory
 
-Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L1)
+Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L1)
 
 ## Properties
 
-| Property                                  | Modifier   | Type      | Description                | Defined in                                                                                                                                                            |
-| ----------------------------------------- | ---------- | --------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [play-dom-router/src/create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L5) |
-| `location.hash`                           | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L8) |
-| `location.pathname`                       | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L6) |
-| `location.search`                         | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L7) |
-| `location.state`                          | `public`   | `unknown` | -                          | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L9) |
+| Property                                  | Modifier   | Type      | Description                               | Defined in                                                                                                                                                            |
+| ----------------------------------------- | ---------- | --------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-location"></a> `location` | `readonly` | `object`  | Returns the state of the current location | [play-dom-router/src/create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L5) |
+| `location.hash`                           | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L8) |
+| `location.pathname`                       | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L6) |
+| `location.search`                         | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L7) |
+| `location.state`                          | `public`   | `unknown` | -                                         | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L9) |
 
 ## Methods
 
@@ -22,7 +22,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com
 back(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L26)
+Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L26)
 
 #### Returns
 
@@ -36,9 +36,9 @@ Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.co
 createHref(path): string;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L38)
+Defined in: [play-dom-router/src/create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L38)
 
-Create href from path
+Creates an href from a path
 
 #### Parameters
 
@@ -58,13 +58,12 @@ Create href from path
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L47)
+Defined in: [play-dom-router/src/create-browser-history.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L46)
 
-Cleanup.
+Cleans up.
 
-Safe to call more than once. When multiple wrappers share the same
-`window.history`, the original methods are restored only after the last
-wrapper is destroyed.
+A second call is safe. When more than one wrapper shares the same
+`window.history`, the last wrapper restores the original methods.
 
 #### Returns
 
@@ -78,7 +77,7 @@ wrapper is destroyed.
 forward(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L27)
+Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L27)
 
 #### Returns
 
@@ -92,9 +91,9 @@ Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.co
 go(delta): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L25)
+Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L25)
 
-Go back/forward
+Moves back or forward in the history
 
 #### Parameters
 
@@ -114,9 +113,9 @@ Go back/forward
 push(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L15)
+Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L15)
 
-Push new URL to history
+Pushes a new URL to the history
 
 #### Parameters
 
@@ -137,9 +136,9 @@ Push new URL to history
 replace(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L20)
+Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L20)
 
-Replace current URL in history
+Replaces the current URL in the history
 
 #### Parameters
 
@@ -160,10 +159,10 @@ Replace current URL in history
 subscribe(listener): () => void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L33)
+Defined in: [play-dom-router/src/create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L33)
 
-Subscribe to history changes
-Returns unsubscribe function
+Subscribes to the history changes.
+It returns a function that cancels the subscription
 
 #### Parameters
 

package/api/@xmachines/play-dom-router/interfaces/BrowserWindow.md

@@ -2,29 +2,30 @@
 
 # Interface: BrowserWindow
 
-Defined in: [play-dom-router/src/create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L59)
+Defined in: [play-dom-router/src/create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L59)
 
-Minimal window interface for createBrowserHistory
+The minimal window interface of createBrowserHistory
 
-Structural interface covering only the properties actually used.
-Accepts Window, JSDOM window, or any compatible test double.
-Avoids coupling to `Window & typeof globalThis` which varies across environments.
+This structural interface holds only the properties that the package uses.
+It accepts Window, a JSDOM window, and every compatible test double.
+The package therefore does not depend on `Window & typeof globalThis`, which is
+different in each environment.
 
 ## Properties
 
 | Property                                  | Modifier   | Type      | Defined in                                                                                                                                                              |
 | ----------------------------------------- | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`   | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L60) |
-| `history.state`                           | `readonly` | `unknown` | [play-dom-router/src/create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L61) |
-| `history.back`                            | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L65) |
-| `history.forward`                         | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L66) |
-| `history.go`                              | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L64) |
-| `history.pushState`                       | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L62) |
-| `history.replaceState`                    | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L63) |
-| <a id="property-location"></a> `location` | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L68) |
-| `location.hash`                           | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L71) |
-| `location.pathname`                       | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L69) |
-| `location.search`                         | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L70) |
+| <a id="property-history"></a> `history`   | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L60) |
+| `history.state`                           | `readonly` | `unknown` | [play-dom-router/src/create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L61) |
+| `history.back`                            | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L65) |
+| `history.forward`                         | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L66) |
+| `history.go`                              | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L64) |
+| `history.pushState`                       | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L62) |
+| `history.replaceState`                    | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L63) |
+| <a id="property-location"></a> `location` | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L68) |
+| `location.hash`                           | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L71) |
+| `location.pathname`                       | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L69) |
+| `location.search`                         | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L70) |
 
 ## Methods
 
@@ -34,7 +35,7 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 addEventListener(type, listener): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L73)
+Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L73)
 
 #### Parameters
 
@@ -55,7 +56,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.co
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L74)
+Defined in: [play-dom-router/src/create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L74)
 
 #### Parameters
 

package/api/@xmachines/play-dom-router/interfaces/ConnectRouterOptions.md

@@ -2,14 +2,14 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-dom-router/src/connect-router.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L23)
+Defined in: [play-dom-router/src/connect-router.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L23)
 
-Options for [connectRouter](../functions/connectRouter.md).
+The options of [connectRouter](../functions/connectRouter.md).
 
 ## Properties
 
-| Property                                  | Modifier   | Type                                            | Description                                                                 | Defined in                                                                                                                                              |
-| ----------------------------------------- | ---------- | ----------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `readonly` | [`RoutableActor`](RoutableActor.md)             | The actor to synchronize with the browser URL. Must implement `Routable`.   | [play-dom-router/src/connect-router.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L25) |
-| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteLookupContract`](RouteLookupContract.md) | Route lookup used to match URL pathnames to machine state IDs.              | [play-dom-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L29) |
-| <a id="property-router"></a> `router`     | `readonly` | [`VanillaRouter`](VanillaRouter.md)             | The vanilla router created by [createRouter](../functions/createRouter.md). | [play-dom-router/src/connect-router.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L27) |
+| Property                                  | Modifier   | Type                                            | Description                                                                   | Defined in                                                                                                                                              |
+| ----------------------------------------- | ---------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `readonly` | [`RoutableActor`](RoutableActor.md)             | The actor to keep in step with the browser URL. It must implement `Routable`. | [play-dom-router/src/connect-router.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L25) |
+| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteLookupContract`](RouteLookupContract.md) | The route lookup that matches a URL pathname to a machine state ID.           | [play-dom-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L29) |
+| <a id="property-router"></a> `router`     | `readonly` | [`VanillaRouter`](VanillaRouter.md)             | The vanilla router from [createRouter](../functions/createRouter.md).         | [play-dom-router/src/connect-router.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L27) |

package/api/@xmachines/play-dom-router/interfaces/PlayRouteEvent.md

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L225)
+Defined in: [play-router/src/types.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L237)
 
-Enhanced routing event with parameter and query support
+The routing event, with its parameters and its query
 
-Unified routing event used throughout the Play architecture. Supports parameter-aware
-navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+This is the one routing event of the complete Play architecture. It supports a
+navigation that knows the parameters, for example `/profile/:userId`, for a dynamic
+route segment.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
-user navigation intent that the Actor evaluates through guards. Infrastructure proposes
-via `play.route` events, Actor decides via state machine transitions.
+**Architectural context:** the event implements **Passive Infrastructure
+(INV-04)**, because it holds the navigation intent of the user, and the Actor then
+evaluates that intent with its guards. The infrastructure makes a request with a
+`play.route` event, and the Actor decides with a transition of its state machine.
 
-**Browser Navigation Flow:**
+**The flow of a browser navigation:**
 
-1. Browser fires `popstate`
-2. Router adapter resolves URL to route target
-3. Adapter sends `PlayRouteEvent` to Actor
-4. Actor validates transition via state machine guards
+1. The browser fires `popstate`
+2. The router adapter resolves the URL to a route target
+3. The adapter sends a `PlayRouteEvent` to the Actor
+4. The Actor checks the transition with the guards of its state machine
 
 ## Param
 
 **type**
 
-Event discriminator (always "play.route")
+The discriminator of the event. It is always "play.route"
 
 ## Param
 
 **to**
 
-Target state ID with # prefix (e.g., '#home', '#profile')
+The target state ID, with a # prefix, for example '#home' or '#profile'
 
 ## Param
 
 **params**
 
-Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+The route parameters of the path only, from the URL path, for
+example `{ userId: '123' }` of `/profile/123`. The `query` field holds the query
+parameters separately.
 
 ## Param
 
 **query**
 
-Query parameters only (isolated from path params)
+The query parameters only. They stay separate from the params of the path
 
 ## Param
 
 **match**
 
-Full URLPattern match result for debugging/observability (optional)
+The complete match result of URLPattern, for the debug work and for
+the observability. It is optional
 
 ## Examples
 
-Combining base and routing events
+The base event and the routing event together
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
@@ -61,7 +66,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 type AppEvent = PlayEvent | PlayRouteEvent;
 ```
 
-Basic navigation to a route
+A basic navigation to a route
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -73,7 +78,7 @@ const event: PlayRouteEvent = {
 actor.send(event);
 ```
 
-Navigation with route parameters
+A navigation with route parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -84,10 +89,10 @@ const event: PlayRouteEvent = {
 	params: { userId: "123" },
 };
 actor.send(event);
-// Resolves to route: /profile/123
+// It resolves to the route /profile/123
 ```
 
-Navigation with query parameters
+A navigation with query parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -95,11 +100,11 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Path-only route parameter
-	query: { tab: "security" }, // Query-only
+	params: { section: "profile" }, // a route parameter of the path only
+	query: { tab: "security" }, // the query only
 };
 actor.send(event);
-// Resolves to route: /settings/profile?tab=security
+// It resolves to the route /settings/profile?tab=security
 ```
 
 ## See
@@ -108,9 +113,10 @@ actor.send(event);
 
 ## Remarks
 
-Use `play.route` when you need parameter-aware navigation with the `route: {}`
-config pattern on your state machine nodes. The `match` field exposes the full
-URLPatternResult for advanced use cases (debugging, pattern analysis).
+Use `play.route` when you need a navigation that knows the parameters, with the
+`route: {}` config pattern on the nodes of your state machine. The `match` field
+gives you the complete URLPatternResult, for an advanced use such as a debug or an
+analysis of the pattern.
 
 ## Indexable
 
@@ -122,8 +128,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
 | -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L230) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L228) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L229) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L227) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L242) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L240) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L241) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L239) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L238) |

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

@@ -2,21 +2,22 @@
 
 # Interface: RoutableActor
 
-Defined in: [play-router/src/types.ts:259](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L259)
+Defined in: [play-router/src/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
 
@@ -40,10 +41,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).                                                                                                                                              | [play-router/src/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). | [play-router/src/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.                                                                                                                                                                | [play-router/src/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. | [play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L280) |
 
 ## Methods
 
@@ -53,9 +54,9 @@ class MyBridge extends RouterBridgeBase {
 send(event): void;
 ```
 
-Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L269)
+Defined in: [play-router/src/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-dom-router/interfaces/RouteLookupContract.md

@@ -2,16 +2,16 @@
 
 # Interface: RouteLookupContract
 
-Defined in: [play-dom-router/src/connect-router.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L15)
+Defined in: [play-dom-router/src/connect-router.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L15)
 
-Structural route lookup interface accepted by [connectRouter](../functions/connectRouter.md).
+The structural route lookup interface that [connectRouter](../functions/connectRouter.md) accepts.
 
-Any object with these two methods satisfies the constraint — including
-`RouteMap` instances, subclasses, and plain test objects.
+Every object with these two methods satisfies the constraint. A `RouteMap`
+instance, a subclass, and a plain test object all work.
 
-`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
-`"stateId"` form — the bridge tries both forms automatically, so
-implementations keyed on a single form still resolve.
+`getPathByStateId` can receive the stateId in the form `"#stateId"` or in the
+bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
+that holds one form only still resolves the path.
 
 ## Methods
 
@@ -21,7 +21,7 @@ implementations keyed on a single form still resolve.
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L17)
+Defined in: [play-dom-router/src/connect-router.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L17)
 
 #### Parameters
 
@@ -41,7 +41,7 @@ Defined in: [play-dom-router/src/connect-router.ts:17](https://gitlab.com/xmachi
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L16)
+Defined in: [play-dom-router/src/connect-router.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L16)
 
 #### Parameters