@xmachines/docs 2.0.0 → 2.1.0

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

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

package/api/@xmachines/play-tanstack-react-router/classes/TanStackReactRouterBridge.md

@@ -2,32 +2,34 @@
 
 # Class: TanStackReactRouterBridge
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L107)
 
-Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
+The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase
 
 ## Remarks
 
-Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
-the TanStack-specific navigation and subscription methods shared by the React
-and Solid adapters.
-
-Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
-back/forward browser navigation (popstate events) are also captured. The
-router.subscribe("onBeforeLoad") approach only works when TanStack's
-Transitioner component is mounted (i.e. inside a full <RouterProvider>).
-Since this bridge is used without <RouterProvider>, we must subscribe to
-the underlying history object directly — which is exactly what Transitioner
+The class extends RouterBridgeBase, and the base class does all the common
+lifecycle work and synchronization work. This class adds the TanStack navigation
+methods and subscription methods that the React adapter and the Solid adapter
+share.
+
+The bridge subscribes to router.history, not to
+router.subscribe("onBeforeLoad"). Therefore it also receives a browser BACK or
+FORWARD navigation, which is a popstate event. The
+router.subscribe("onBeforeLoad") method works only when the Transitioner
+component of TanStack is mounted, which means inside a complete
+<RouterProvider>. This bridge works without <RouterProvider>. Therefore it
+subscribes to the history object directly, and this is exactly what Transitioner
 does internally: `router.history.subscribe(router.load)`.
 
-Architectural Invariants:
+Architectural invariants:
 
-- INV-02 (Passive Infrastructure): Router reflects actor state, never decides
-- Actor validates all navigation via guards before URL changes
+- INV-02 (Passive Infrastructure): the router reflects the actor state. It never decides
+- The actor checks every navigation with its guards before the URL changes
 
-The class is concrete — it can be instantiated directly. The framework
-packages re-export or subclass it purely to bind the public adapter name
-(and, for Solid, to add the `dispose()` alias).
+The class is concrete. You can create an instance of it directly. Each framework
+package re-exports it, or makes a subclass of it, only to bind the public name of
+the adapter. The Solid package also adds the `dispose()` alias.
 
 ## Example
 
@@ -52,17 +54,17 @@ new TanStackReactRouterBridge(
    routeMap): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L117)
 
-Create a TanStack Router bridge
+Creates a TanStack Router bridge
 
 #### Parameters
 
-| Parameter  | Type                                                                                      | Description                                       |
-| ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                             | TanStack Router instance (from `createRouter`)    |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                      | XMachines actor instance                          |
-| `routeMap` | [`TanStackRouteMapLike`](../../play-tanstack-router/type-aliases/TanStackRouteMapLike.md) | Bidirectional mapping between state IDs and paths |
+| Parameter  | Type                                                                                      | Description                                               |
+| ---------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                             | The TanStack Router instance from `createRouter`          |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                      | The XMachines actor instance                              |
+| `routeMap` | [`TanStackRouteMapLike`](../../play-tanstack-router/type-aliases/TanStackRouteMapLike.md) | The bidirectional map between the state IDs and the paths |
 
 #### Returns
 
@@ -80,21 +82,23 @@ Create a TanStack Router bridge
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L151)
+Defined in: [play-router/src/router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L158)
 
-Connect the router bridge to the Actor.
+Connects the router bridge to the Actor.
 
-Sets up the TC39 Signal watcher for actor → router direction and
-starts watching router changes (framework-specific).
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
 
-Ordering here is part of the bridge contract:
+The order of these steps is part of the contract of the bridge:
 
-- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-- the actor watcher is installed before adapter router subscriptions
-- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The method installs the actor watcher before the router subscriptions of the adapter
+- The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
-Adapters that need custom initial-sync behavior should override
-`getInitialRouterPath()` rather than reordering `connect()` steps.
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
 
 #### Returns
 
@@ -112,11 +116,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L256)
+Defined in: [play-router/src/router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L270)
 
-Disconnect the router bridge from the Actor.
+Disconnects the router bridge from the Actor.
 
-Stops signal watching and unregisters framework-specific router listener.
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
 
 #### Returns
 

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

@@ -6,18 +6,19 @@
 function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L92)
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L95)
 
-Create a React `PlayRouterProvider` component bound to a specific bridge class.
+Creates a React `PlayRouterProvider` component of one bridge class.
 
-The returned component connects a `PlayerActor` to the framework router,
-keeping actor state and browser URL in sync bidirectionally.
+The component of the return value connects a `PlayerActor` to the framework
+router. It keeps the actor state and the browser URL in step, in both directions.
 
-The bridge is created once on mount and torn down on unmount. It is also
-rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
-props must be **stable references** (created outside JSX or memoized).
-Under React `<StrictMode>` the effect runs twice on mount
-(connect → disconnect → connect), which the bridges support.
+The component creates the bridge one time, on mount, and it disconnects the bridge
+on unmount. It also builds the bridge again on a change of the identity of `actor`,
+of `router`, or of `routeMap`. Therefore all three props must be **stable
+references**: create them outside the JSX, or hold them with `useMemo`. Under the
+React `<StrictMode>`, the effect runs two times on mount (connect, disconnect,
+connect), and the bridges support this.
 
 ## Type Parameters
 
@@ -27,14 +28,15 @@ Under React `<StrictMode>` the effect runs twice on mount
 
 ## Parameters
 
-| Parameter    | Type                                                                                         | Description                                                            |
-| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | Bridge class constructed as `new BridgeCtor(router, actor, routeMap)`. |
+| Parameter    | Type                                                                                         | Description                                                                            |
+| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`. |
 
 ## Returns
 
-A `PlayRouterProvider` component, generic over the actor type so the
-`renderer` callback receives the same concrete actor type that was passed in.
+A `PlayRouterProvider` component. It is generic over the actor type.
+Therefore the `renderer` callback receives the same concrete actor type as the
+prop.
 
 \<`TActor`\>(`__namedParameters`) => `Element`
 

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

@@ -6,27 +6,28 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L47)
 
-Create a `RouteMap` from an XState state machine.
+Creates a `RouteMap` from an XState state machine.
 
-Extracts all routable states (those with `meta.route`) and builds a bidirectional
-path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
-subclasses to translate browser URL changes into `play.route` actor events and
-vice-versa.
+The function reads every state with a route, which means each state with a
+`meta.route` field. It then builds the lookup structure between a path and a
+stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+converts each change of the browser URL into a `play.route` actor event, and each
+actor route into a URL.
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
-| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+| Parameter  | Type                                                                      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine, with a `meta.route` annotation on each state with a route.                                         |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | The optional configuration. Give `{ cacheSize }` to change the default size of the LRU cache of the parameterized path lookups. |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
 
-A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ## Example
 

package/api/@xmachines/play-tanstack-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/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-tanstack-react-router/functions/extractMachineRoutes.md

@@ -6,23 +6,24 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [play-router/src/extract-routes.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/extract-routes.ts#L89)
+Defined in: [play-router/src/extract-routes.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/extract-routes.ts#L92)
 
-Extract complete route tree from state machine graph
+Reads the complete route tree from the graph of a state machine
 
-Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
-then walks graph nodes to extract route metadata, validate route references,
-and build a hierarchical RouteTree. The graph is attached to the returned
-RouteTree for downstream transition-aware queries.
+The function converts the XState machine into a Graph of @statelyai/graph, with
+machineToGraph(). It then walks the graph nodes: it reads the route metadata of
+each node, it checks each route reference, and it builds a hierarchical RouteTree.
+The RouteTree of the return value also holds the graph, for a later query that
+needs the transitions.
 
 ## Parameters
 
-| Parameter | Type                                                                      | Description             |
-| --------- | ------------------------------------------------------------------------- | ----------------------- |
-| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine |
+| Parameter | Type                                                                      | Description                 |
+| --------- | ------------------------------------------------------------------------- | --------------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine |
 
 ## Returns
 
 [`RouteTree`](../../play-router/interfaces/RouteTree.md)
 
-Route tree with root, byStateId map, byPath map, and graph
+The route tree, with its root, its byStateId map, its byPath map, and its graph

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

@@ -2,22 +2,24 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L297)
+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:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L261) |
-| <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:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L299) |
-| <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:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L267) |
+| 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:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L269)
+Defined in: [play-router/src/types.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L282)
 
-Send a route navigation event to the actor.
+Sends a route navigation event to the actor.
 
 #### Parameters