@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,16 +2,16 @@
 
 # Interface: MachineNodeData
 
-Defined in: [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L9)
+Defined in: [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L9)
 
-Data attached to each node in the machine graph representation.
-Captures the essential state metadata needed for route extraction and queries.
+The data on each node of the graph that represents the machine.
+It holds the state metadata that the route extraction and the queries need.
 
 ## Properties
 
-| Property                                | Type                                                                   | Description                                        | Defined in                                                                                                            |
-| --------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L15) |
-| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L17) |
-| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L11) |
-| <a id="property-type"></a> `type`       | `"history"` \| `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` | State type from XState                             | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L13) |
+| Property                                | Type                                                                   | Description                                                | Defined in                                                                                                    |
+| --------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | The original meta object of the state                      | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L15) |
+| <a id="property-route"></a> `route?`    | `string`                                                               | The route path of meta.route, in its string form           | [types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L17) |
+| <a id="property-stateid"></a> `stateId` | `string`                                                               | The XState state ID, for example "test.dashboard.overview" | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L11) |
+| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | The state type of XState                                   | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L13) |

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

@@ -2,22 +2,24 @@
 
 # Interface: PlayActor
 
-Defined in: [types.ts:316](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L316)
+Defined in: [types.ts:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L312)
 
-Full actor shape used by `PlayRouterProvider` components across all framework
-adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
-adapters built on the shared framework-router bridge bases).
+The complete actor shape of the `PlayRouterProvider` component of each framework
+adapter: `play-solid-router`, `play-vue-router`, `play-react-router`, and each
+adapter on the shared framework router bridge bases.
 
-Extends `RoutableActor` with `currentView` — the provider renders the current
-view spec in addition to synchronizing routes, so it needs both capabilities.
+The shape extends `RoutableActor` with `currentView`, because the provider renders
+the current view spec and also keeps the routes in step. It therefore needs both
+capabilities.
 
-- Use `RoutableActor` when only routing is needed (e.g. `RouterBridgeBase` subclasses,
-  `connectRouter`).
-- Use `PlayActor` when the component also renders the current view spec
-  (e.g. `PlayRouterProvider` renderer callback parameter, `PlayRenderer`).
+- Use `RoutableActor` when you need the routing alone, for example in a
+  `RouterBridgeBase` subclass, or in `connectRouter`.
+- Use `PlayActor` when the component also renders the current view spec, for
+  example for the renderer callback parameter of `PlayRouterProvider`, and in
+  `PlayRenderer`.
 
-All `AbstractActor` subclasses that implement both `Routable` and `Viewable`
-satisfy this interface structurally.
+Every `AbstractActor` subclass that implements both `Routable` and `Viewable`
+satisfies this interface structurally.
 
 ## Example
 
@@ -25,7 +27,7 @@ satisfy this interface structurally.
 import type { PlayActor } from "@xmachines/play-router";
 
 function MyRouterProvider({ actor }: { actor: PlayActor }) {
-	// access actor.currentRoute (routing) and actor.currentView (rendering)
+	// it reads actor.currentRoute for the routing, and actor.currentView for the render
 }
 ```
 
@@ -35,11 +37,11 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                               | 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).                                                                                                                                              | [`RoutableActor`](RoutableActor.md).[`currentRoute`](RoutableActor.md#property-currentroute) | [types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L280) |
-| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                            | [types.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L318) |
-| <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). | [`RoutableActor`](RoutableActor.md).[`initialRoute`](RoutableActor.md#property-initialroute) | [types.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L286) |
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                                              | Inherited from                                                                               | 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.                                                                                                                                                                | [`RoutableActor`](RoutableActor.md).[`currentRoute`](RoutableActor.md#property-currentroute) | [types.ts:274](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L274) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | The TC39 Signal of the current view spec of the actor, or `null` when no view is active.                                                                                                                                                 | -                                                                                            | [types.ts:314](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L314) |
+| <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. | [`RoutableActor`](RoutableActor.md).[`initialRoute`](RoutableActor.md#property-initialroute) | [types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L280) |
 
 ## Methods
 
@@ -49,9 +51,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [types.ts:288](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L288)
+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/PlayRouteEvent.md

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L244)
+Defined in: [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
 
@@ -120,10 +126,10 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                                                                                                              |
-| -------------------------------------- | ---------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L249) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L247) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L248) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L246) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:245](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L245) |
+| Property                               | Modifier   | Type                           | Defined in                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [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`\> | [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`\> | [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`                       | [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"`                 | [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-router/interfaces/ResolvedRoutePath.md

@@ -2,16 +2,16 @@
 
 # Interface: ResolvedRoutePath
 
-Defined in: [validate-routes.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/validate-routes.ts#L9)
+Defined in: [validate-routes.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L9)
 
-A route entry with its RESOLVED full path — the path after relative routes have
-been prefixed with their parent's full path during tree construction.
+A route entry with its RESOLVED complete path, which is the path after the tree
+construction put the path of the parent before each relative route.
 
 `RouteNode` satisfies this shape structurally.
 
 ## Properties
 
-| Property                                  | Type     | Description                                                          | Defined in                                                                                                                                |
-| ----------------------------------------- | -------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-fullpath"></a> `fullPath` | `string` | Resolved absolute route path (e.g. `"/dashboard/settings"`).         | [validate-routes.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/validate-routes.ts#L13) |
-| <a id="property-stateid"></a> `stateId`   | `string` | State identifier owning the route (e.g. `"app.dashboard.settings"`). | [validate-routes.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/validate-routes.ts#L11) |
+| Property                                  | Type     | Description                                                                              | Defined in                                                                                                                        |
+| ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-fullpath"></a> `fullPath` | `string` | The resolved absolute route path, for example `"/dashboard/settings"`.                   | [validate-routes.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L13) |
+| <a id="property-stateid"></a> `stateId`   | `string` | The identifier of the state that owns the route, for example `"app.dashboard.settings"`. | [validate-routes.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L11) |

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

@@ -2,21 +2,22 @@
 
 # Interface: RoutableActor
 
-Defined in: [types.ts:278](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L278)
+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:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L280) |
-| <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:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L286) |
+| 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:288](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L288)
+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:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L75)
+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:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L85) |
-| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L92) |
-| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L83) |
-| <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:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L90) |
-| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L81) |
-| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L77) |
-| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L79) |
+| 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-alpha.1/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-alpha.1/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-alpha.1/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-alpha.1/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-alpha.1/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-alpha.1/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-alpha.1/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-alpha.1/packages/play-router/src/router-sync.ts#L13) |
+| 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.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:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L98)
+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:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L122) |
-| <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:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L111) |
-| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                                                                                                                                                 | [types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L100) |
-| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                                                                                                                                                 | [types.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L126) |
-| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                                                                                                                                                 | [types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L124) |
-| <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:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L105) |
-| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                                                                                                                                               | [types.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L113) |
-| <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:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L120) |
-| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                                                                                                                                           | [types.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L115) |
+| 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) |