@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

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

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

@@ -2,22 +2,24 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/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: [play-router/src/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`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/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.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/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`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/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`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [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-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.                                                                                                                                                 | -                                                                                                                                                              | [play-router/src/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`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [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
 
@@ -49,9 +51,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [play-router/src/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: [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-react-router/interfaces/PlayRouteEvent.md

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/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: [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
 
@@ -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`                      | [play-router/src/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`\> | [play-router/src/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`\> | [play-router/src/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`                       | [play-router/src/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"`                 | [play-router/src/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`                      | [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-react-router/interfaces/PlayRouterProviderBaseProps.md

@@ -2,14 +2,14 @@
 
 # Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L34)
+Defined in: [play-react-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L34)
 
-Props shared by every factory-created React `PlayRouterProvider`.
+The props that every React `PlayRouterProvider` of the factory shares.
 
-Adapter packages re-export a concrete alias with `TRouter` bound to their
-router instance type (e.g. `PlayRouterProviderProps<TActor>` in
-`@xmachines/play-react-router` binds `TRouter` to the `createBrowserRouter`
-return type).
+An adapter package re-exports a concrete alias, with `TRouter` bound to the type of
+its router instance. For example, `PlayRouterProviderProps<TActor>` in
+`@xmachines/play-react-router` binds `TRouter` to the return type of
+`createBrowserRouter`.
 
 ## Extended by
 
@@ -24,9 +24,9 @@ return type).
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                                                      |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L42) |
+| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Defined in                                                                                                                                                                              |
+| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
+| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

package/api/@xmachines/play-react-router/interfaces/PlayRouterProviderProps.md

@@ -2,13 +2,13 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/play-router-provider.tsx#L26)
+Defined in: [play-react-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/play-router-provider.tsx#L27)
 
-Props for the React Router `PlayRouterProvider`.
+The props of the `PlayRouterProvider` of React Router.
 
-`router` is the React Router instance returned by `createBrowserRouter`.
-See `PlayRouterProviderBaseProps` for the stable-reference requirements on
-`actor`, `router`, and `routeMap`.
+`router` is the React Router instance that `createBrowserRouter` returns.
+`PlayRouterProviderBaseProps` holds the requirement of a stable reference for
+`actor`, for `router`, and for `routeMap`.
 
 ## Extends
 
@@ -22,9 +22,9 @@ See `PlayRouterProviderBaseProps` for the stable-reference requirements on
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from                                                                                                                 | Defined in                                                                                                                                                                                      |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `Router`                             | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L42) |
+| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Inherited from                                                                                                                 | Defined in                                                                                                                                                                              |
+| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
+| <a id="property-router"></a> `router`     | `Router`                             | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

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

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/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: [play-router/src/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`. | [play-router/src/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`. | [play-router/src/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-react-router/interfaces/RouteMapping.md

@@ -2,14 +2,15 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/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: [play-router/src/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?"`) | [play-router/src/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"`)                         | [play-router/src/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?"` | [play-router/src/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"`                          | [play-router/src/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) |