@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,14 +2,14 @@
 
 # Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
 
-Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L45)
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L46)
 
-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-tanstack-react-router` binds `TRouter` to the TanStack Router
-instance 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-tanstack-react-router` binds `TRouter` to the type of the TanStack
+Router instance.
 
 ## Extended by
 
@@ -24,9 +24,9 @@ instance 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-tanstack-react-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L51) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-tanstack-react-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L68) |
-| <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-tanstack-react-router/src/create-play-router-provider.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L66) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [play-tanstack-react-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L53) |
+| 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-tanstack-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L52) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [play-tanstack-react-router/src/create-play-router-provider.tsx:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L69) |
+| <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-tanstack-react-router/src/create-play-router-provider.tsx:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L67) |
+| <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-tanstack-react-router/src/create-play-router-provider.tsx:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L54) |

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

@@ -2,13 +2,13 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/play-router-provider.tsx#L43)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L45)
 
-Props for the TanStack React Router `PlayRouterProvider`.
+The props of the `PlayRouterProvider` of TanStack React Router.
 
-`router` is the TanStack Router instance returned by `createRouter`.
-See `PlayRouterProviderBaseProps` for the stable-reference requirements on
-`actor`, `router`, and `routeMap`.
+`router` is the TanStack Router instance that `createRouter` 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-tanstack-react-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L51) |
-| <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-tanstack-react-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L68) |
-| <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-tanstack-react-router/src/create-play-router-provider.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L66) |
-| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-tanstack-react-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L53) |
+| 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-tanstack-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L52) |
+| <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-tanstack-react-router/src/create-play-router-provider.tsx:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L69) |
+| <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-tanstack-react-router/src/create-play-router-provider.tsx:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L67) |
+| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | 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-tanstack-react-router/src/create-play-router-provider.tsx:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L54) |

package/api/@xmachines/play-tanstack-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-tanstack-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) |

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

@@ -1,16 +1,17 @@
 [API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteNavigateEvent
 
-# Interface: RouteNavigateEvent
+# ~~Interface: RouteNavigateEvent~~
 
-Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/types.ts#L21)
+Defined in: [play-tanstack-react-router/src/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/types.ts#L24)
 
-Event sent to actor when browser navigates.
+The event that the bridge sends to the actor when the browser navigates.
 
-Browser navigation (user clicks link, back/forward button, direct URL entry)
-sends this event to the actor. The actor's guards determine if navigation
-is allowed based on business logic.
+A browser navigation sends this event to the actor. A click on a link, the BACK
+or FORWARD button, and a URL that the user types each cause a navigation. The
+guards of the actor then decide if the business logic permits the navigation.
 
-Invariant: Passive Infrastructure - Router suggests, actor decides validity.
+Invariant: Passive Infrastructure. The router makes a request, and the actor
+decides the validity.
 
 ## Example
 
@@ -18,9 +19,13 @@ Invariant: Passive Infrastructure - Router suggests, actor decides validity.
 actor.send({ type: "route.navigate", path: "/dashboard" });
 ```
 
+## Deprecated
+
+Superseded by `PlayRouteEvent` from `@xmachines/play-router`. Will be removed in the next major.
+
 ## Properties
 
-| Property                          | Modifier   | Type               | Description                                                  | Defined in                                                                                                                                                          |
-| --------------------------------- | ---------- | ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `readonly` | `string`           | Target route path (may include parameters, e.g., /posts/123) | [play-tanstack-react-router/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/types.ts#L25) |
-| <a id="property-type"></a> `type` | `readonly` | `"route.navigate"` | Event type discriminant (extends XState event pattern)       | [play-tanstack-react-router/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/types.ts#L23) |
+| Property                              | Modifier   | Type               | Description                                                            | Defined in                                                                                                                                                  |
+| ------------------------------------- | ---------- | ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> ~~`path`~~ | `readonly` | `string`           | The target route path. It can hold a parameter, for example /posts/123 | [play-tanstack-react-router/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/types.ts#L28) |
+| <a id="property-type"></a> ~~`type`~~ | `readonly` | `"route.navigate"` | The event type discriminant. It follows the XState event pattern       | [play-tanstack-react-router/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/types.ts#L26) |

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

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

package/api/@xmachines/play-tanstack-react-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -6,9 +6,9 @@
 type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
 ```
 
-Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L31)
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L32)
 
-Constructor shape a bridge class must satisfy to be used with
+The constructor shape that a bridge class must satisfy for
 `createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
 
 ## Type Parameters

package/api/@xmachines/play-tanstack-react-router/type-aliases/TanStackRouterInstance.md

@@ -6,4 +6,4 @@
 type TanStackRouterInstance = ConstructorParameters<typeof TanStackReactRouterBridge>[0];
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/play-router-provider.tsx#L34)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L36)

package/api/@xmachines/play-tanstack-react-router/type-aliases/TanStackRouterLike.md

@@ -6,11 +6,11 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
 
-Structural (type-only) interface for the TanStack Router surface used by
-`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
-`@tanstack/solid-router` instances satisfy it.
+The type-only interface of the TanStack Router surface that
+`TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
+instance of `@tanstack/solid-router` both satisfy it.
 
 ## Properties
 
@@ -20,7 +20,7 @@ Structural (type-only) interface for the TanStack Router surface used by
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L46)
 
 #### location
 
@@ -28,9 +28,10 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https:/
 location: object;
 ```
 
-Current location — populated from `window.location` when `createRouter()` runs,
-before `router.load()`. Always available in the browser.
-`router.state.location` is only populated after `router.load()` and may be stale.
+The current location. `createRouter()` fills it from `window.location`, before
+`router.load()`. It is always available in the browser.
+`router.state.location` has a value only after `router.load()`, and that value
+can be old.
 
 ##### location.pathname
 
@@ -68,11 +69,12 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L45)
 
-Re-runs TanStack route matching and loaders for the current location.
-Optional: the bridge calls it (fire-and-forget) after every navigation so
-matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+Runs the TanStack route matching and the loaders again for the current location.
+This method is optional. The bridge calls it after every navigation, and it does
+not wait for the result. The matching and the loaders therefore stay correct,
+also when no `<RouterProvider>` is mounted.
 
 #### Returns
 
@@ -86,7 +88,7 @@ matching/loaders stay in sync even without a mounted `<RouterProvider>`.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L38)
 
 #### Parameters
 

package/api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md

@@ -6,16 +6,17 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-tanstack-react-router/src/play-router-provider.tsx#L57)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L60)
 
-Connects a `PlayerActor` to TanStack React Router, keeping actor state and
-browser URL in sync bidirectionally.
+Connects a `PlayerActor` to TanStack React 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 bridge supports.
+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 bridge supports this.
 
 ## Type Parameters
 

package/api/@xmachines/play-tanstack-router/README.md

@@ -4,14 +4,16 @@
 
 Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
 
-TanStack Router exposes the identical `navigate` / `load` / `history` surface in
-both its React and Solid flavours, so the entire bridge implementation lives here
-as `TanStackRouterBridgeBase` (extending `RouterBridgeBase` from
-[`@xmachines/play-router`](../play-router/README.md)). The framework adapter
-packages only subclass it to bind their concrete router type.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
 
-This package has **no TanStack runtime dependency** — `TanStackRouterLike` is a
-structural, type-only interface covering the small router surface the bridge uses.
+TanStack Router gives React and Solid the same `navigate`, `load`, and `history`
+surface. Therefore the complete bridge implementation lives here, in
+`TanStackRouterBridgeBase`. That class extends `RouterBridgeBase` from
+[`@xmachines/play-router`](../play-router/README.md). Each framework adapter
+package makes a subclass of it, and binds its own router type.
+
+This package has **no TanStack runtime dependency**. `TanStackRouterLike` is a
+type-only interface. It describes the small router surface that the bridge uses.
 
 ## Who consumes it
 
@@ -21,21 +23,41 @@ structural, type-only interface covering the small router surface the bridge use
 ## Usage
 
 ```typescript
+import { createMachine } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { createRouteMap } from "@xmachines/play-router";
 import { TanStackRouterBridgeBase } from "@xmachines/play-tanstack-router";
 
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
+const actor = definePlayer({ machine })();
+actor.start();
+
+const routeMap = createRouteMap(machine);
+
 export class MyTanStackBridge extends TanStackRouterBridgeBase {}
 
+// router: your TanStack Router instance (from the React or Solid createRouter)
 const bridge = new MyTanStackBridge(router, actor, routeMap);
 bridge.connect();
-// Cleanup on unmount
-return () => bridge.disconnect();
+// Disconnect the bridge at teardown
+bridge.disconnect();
 ```
 
 ## Exports
 
-- `TanStackRouterBridgeBase` — abstract bridge base class
-- `TanStackRouterLike` — structural (type-only) TanStack router surface
-- `TanStackRouteMapLike` — narrow route-map surface the bridge requires
+- `TanStackRouterBridgeBase` — the concrete bridge base class. Use it directly, or make a subclass of it
+- `TanStackRouterLike` — the TanStack router surface, as a type-only interface
+- `TanStackRouteMapLike` — the narrow route-map surface that the bridge requires
 
 ## License
 
@@ -43,10 +65,10 @@ MIT
 
 @xmachines/play-tanstack-router
 
-Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
-Consumed by `@xmachines/play-tanstack-react-router` and
-`@xmachines/play-tanstack-solid-router`, which subclass
-`TanStackRouterBridgeBase` to bind their concrete router type.
+The shared, framework-agnostic TanStack Router bridge base for XMachines Play.
+`@xmachines/play-tanstack-react-router` and
+`@xmachines/play-tanstack-solid-router` use it. Each of them makes a subclass of
+`TanStackRouterBridgeBase`, and the subclass binds its own router type.
 
 ## Classes