@xmachines/docs 2.0.0 → 2.1.1

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

@@ -4,22 +4,20 @@
 
 **TanStack Solid Router adapter for XMachines Universal Player Architecture**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-solid-router)
+[![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.1-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-solid-router)
 
-Signals-native integration with TanStack Solid Router enabling logic-driven navigation through Solid.js reactivity.
-
-Part of the [xmachines-js](../../README.md) monorepo.
+This package integrates TanStack Solid Router with the TC39 Signals. The logic then drives the navigation through the Solid.js reactivity.
 
 ## Overview
 
 [`@xmachines/play-tanstack-solid-router`](README.md) connects a Play actor to TanStack Solid Router through `TanStackSolidRouterBridge`.
 
-The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md), keeping adapter behavior consistent across frameworks:
+The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md). Each adapter therefore behaves in the same way in every framework:
 
-- Actor route signal (`actor.currentRoute`) drives router navigation.
-- Router history events send `play.route` intents back to the actor.
-- Guarded state transitions remain actor-owned (Actor Authority).
-- Circular update prevention built into `RouterBridgeBase`.
+- The actor route signal (`actor.currentRoute`) drives the router navigation.
+- Each router history event sends a `play.route` intent to the actor.
+- The actor keeps the ownership of each guarded state transition (Actor Authority).
+- `RouterBridgeBase` stops a circular update.
 
 ## Installation
 
@@ -36,31 +34,53 @@ pnpm add @xmachines/play-tanstack-solid-router @xmachines/play-router
 
 ## Current Exports
 
-- `TanStackSolidRouterBridge` — primary adapter class
-- `PlayRouterProvider` — Solid component wrapper for bridge lifecycle
+- `TanStackSolidRouterBridge` — the primary adapter class
+- `PlayRouterProvider` — the Solid component that manages the bridge lifecycle
 - `PlayRouterProviderProps`, `TanStackRouterInstance` (types)
-- `PlayActor` — canonical actor shape (`AbstractActor & Routable & Viewable`) from `@xmachines/play-router`; use when constructing a typed renderer callback for `PlayRouterProvider`
-- `RoutableActor` — deprecated alias for `PlayActor`; use `PlayActor` from `@xmachines/play-router` instead
+- `PlayActor` — the canonical actor shape (`AbstractActor & Routable & Viewable`) from `@xmachines/play-router`. Use it for the type of a renderer callback of `PlayRouterProvider`
+- `RoutableActor` — the deprecated alias of `PlayActor`. Use `PlayActor` from `@xmachines/play-router`
 - `RouteMap`, `createRouteMap`, `RouteMapping`, `RouteMapOptions` (re-exported from `@xmachines/play-router`)
 - `TanStackRouterLike` (type)
 - `RouterBridge`, `PlayRouteEvent` (types)
 
 ## URLPattern Support
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via [`@xmachines/play-router`](../play-router/README.md).
+This package matches each route pattern with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern), through [`@xmachines/play-router`](../play-router/README.md).
 
-URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router`](../play-router/README.md) for details.
+URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+). In an older environment, load a polyfill **before** you import this package. See [`@xmachines/play-router`](../play-router/README.md) for the details.
 
 ## Quick Start
 
 ```tsx
-import { createRouter } from "@tanstack/solid-router";
-import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { createRouter, createRootRoute, createRoute } from "@tanstack/solid-router";
+import { createMachine } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
 import { TanStackSolidRouterBridge, createRouteMap } from "@xmachines/play-tanstack-solid-router";
 
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
 const routeMap = createRouteMap(machine);
-const router = createRouter({ routeTree: tanstackRouteTree });
+
+// Mirror the machine's routable states as TanStack routes
+const rootRoute = createRootRoute();
+const tanstackRoutes = getRoutableRoutes(extractMachineRoutes(machine)).map((route) =>
+	createRoute({
+		getParentRoute: () => rootRoute,
+		path: route.fullPath.replace(/:(\w+)/g, "$$$1"),
+		component: () => null,
+	}),
+);
+const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
 
 const actor = definePlayer({ machine })();
 actor.start();
@@ -74,12 +94,13 @@ bridge.disconnect();
 
 ### Solid convenience wrapper
 
-Use `PlayRouterProvider` when you want bridge lifecycle wiring managed by a component:
+Use `PlayRouterProvider` when you want a component to manage the bridge lifecycle:
 
 ```tsx
 import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
 import { RouterProvider } from "@tanstack/solid-router";
 
+// actor, router, and routeMap from the Quick Start above
 <PlayRouterProvider
 	actor={actor}
 	router={router}
@@ -94,7 +115,7 @@ import { RouterProvider } from "@tanstack/solid-router";
 
 ### `TanStackSolidRouterBridge`
 
-Primary adapter class extending `RouterBridgeBase`.
+The primary adapter class. It extends `RouterBridgeBase`.
 
 ```ts
 class TanStackSolidRouterBridge {
@@ -107,14 +128,15 @@ class TanStackSolidRouterBridge {
 
 **Behavior:**
 
-- `connect()` — subscribes to `router.history`, performs initial deep-link sync from `router.history.location`, and starts watching `actor.currentRoute` for state-driven navigation.
-- `disconnect()` — unsubscribes from history and stops all sync.
-- Navigates via `router.navigate({ to: path })`.
-- Subscribes via `router.history.subscribe` — covers PUSH, POP, BACK, FORWARD, REPLACE, and GO, and works without `<RouterProvider>` mounted.
+- `connect()` — subscribes to `router.history`, sets the actor state from `router.history.location` for a deep link, and then watches `actor.currentRoute` for a state-driven navigation.
+- `disconnect()` — cancels the subscription to the history and stops all the synchronization.
+- It navigates with `router.navigate({ to: path })`.
+- It subscribes with `router.history.subscribe`. This covers PUSH, POP, BACK, FORWARD, REPLACE, and GO, and it works when no `<RouterProvider>` is mounted.
+- It waits for the `router.load()` of a history event before it synchronizes the actor. A mounted `<RouterProvider>` defers the refresh of `router.latestLocation`, and without the wait TanStack drops the corrective navigation for a refused URL. See the [`@xmachines/play-tanstack-router` README](../play-tanstack-router/README.md) for the details.
 
 ### `PlayRouterProvider`
 
-Solid component that instantiates, connects, and cleans up a `TanStackSolidRouterBridge` automatically.
+This Solid component creates a `TanStackSolidRouterBridge`, connects it, and cleans it up for you.
 
 ```ts
 interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
@@ -129,11 +151,11 @@ interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
 }
 ```
 
-The bridge is created synchronously at component evaluation time (Solid's execution model) and torn down via `onCleanup` when the component is disposed.
+The component creates the bridge synchronously, during its own evaluation, because this is the execution model of Solid. It disconnects the bridge in `onCleanup`, when Solid disposes of the component.
 
 ### `RouteMap` and `createRouteMap`
 
-Map state IDs to URL paths and resolve URLs back to state IDs.
+These two exports map each state ID to a URL path, and each URL back to a state ID.
 
 ```ts
 const routeMap = new RouteMap([
@@ -145,13 +167,17 @@ const routeMap = new RouteMap([
 routeMap.getStateIdByPath("/profile/123"); // "profile"
 routeMap.getPathByStateId("home"); // "/"
 routeMap.getStateIdByPath("/unknown"); // null
+```
 
-// Or build from a machine directly:
+Or build from a machine directly:
+
+```ts
 import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
-const routeMap = createRouteMap(machine);
+
+const routeMap = createRouteMap(machine); // machine: your routable machine (states carry meta.route)
 ```
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+`getStateIdByPath` returns `null`, not `undefined`, for a path that it cannot match.
 
 ## Usage Patterns
 
@@ -169,7 +195,7 @@ const routeMap = new RouteMap([
 
 ### Protected Routes and Guards
 
-Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
+The auth guards are inside the state machine only. Unauthorized content therefore never appears, not even for a moment:
 
 ```ts
 const machineConfig = {
@@ -185,13 +211,13 @@ const machineConfig = {
 };
 ```
 
-When a user navigates to `/dashboard` while unauthenticated:
+A user navigates to `/dashboard`, and the user is not authenticated:
 
-1. TanStack Router updates location.
-2. Bridge intercepts and sends `play.route` to the actor.
-3. Actor evaluates the guard — denies transition, moves to `login` instead.
-4. Bridge observes new actor route (`/login`).
-5. Bridge calls `router.navigate({ to: "/login" })`.
+1. TanStack Router updates the location.
+2. The bridge receives the change and sends `play.route` to the actor.
+3. The actor evaluates the guard. The guard refuses the transition, and the actor moves to `login`.
+4. The bridge reads the new actor route (`/login`).
+5. The bridge calls `router.navigate({ to: "/login" })`.
 
 ### Full App Example
 
@@ -201,6 +227,7 @@ import { onCleanup } from "solid-js";
 import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
 import { definePlayer } from "@xmachines/play-xstate";
 import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+import { authMachine } from "./auth-machine.js"; // your routable machine (states carry meta.route)
 
 const createPlayer = definePlayer({ machine: authMachine });
 const actor = createPlayer();
@@ -246,12 +273,12 @@ export default function App() {
 
 Bridge-first data flow:
 
-1. `RouterBridgeBase.connect()` performs initial actor/router synchronization — both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
-2. Actor route updates (`actor.currentRoute` signal) call TanStack navigation (`router.navigate({ to })`).
-3. TanStack history updates are subscribed and translated to `play.route` events sent to the actor.
-4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+1. `RouterBridgeBase.connect()` does the first synchronization between the actor and the router. It sends both the pathname and the query string of `router.history.location` to the actor.
+2. Each actor route update, through the `actor.currentRoute` signal, calls the TanStack navigation (`router.navigate({ to })`).
+3. The bridge subscribes to the TanStack history updates. It converts each update into a `play.route` event, then sends the event to the actor.
+4. The guards of the actor accept or refuse each transition. The infrastructure reflects the state that results.
 
-This keeps routing infrastructure passive while preserving business-logic control in the state machine.
+The routing infrastructure therefore stays passive, and the state machine keeps the control of the business logic.
 
 ## Testing
 
@@ -267,7 +294,7 @@ Or from the package directory:
 pnpm test
 ```
 
-**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce: BACK/FORWARD navigation via `router.history.subscribe`, echo suppression under real microtask timing, `navigate({ to })` call verification, and subscriber teardown on `disconnect()` and `dispose()`.
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run in real Chromium through Playwright. They cover the asynchronous sequences that jsdom cannot reproduce: BACK and FORWARD navigation through `router.history.subscribe`, echo suppression under real microtask timing, the check of each `navigate({ to })` call, and subscriber teardown on `disconnect()` and on `dispose()`.
 
 ```bash
 # Run browser tests only
@@ -279,7 +306,7 @@ Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
 ## Related Packages
 
 - [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
-- [@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md) — TanStack Router (React) equivalent
+- [@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md) — the same adapter for TanStack Router (React)
 - [@xmachines/play-solid](../play-solid/README.md) — SolidJS renderer
 - [@xmachines/play-solid-router](../play-solid-router/README.md) — native `@solidjs/router` adapter
 - [@xmachines/play-xstate](../play-xstate/README.md) — XState v5 player factory

package/api/@xmachines/play-tanstack-solid-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.1/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.1/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.1/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.1/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-solid-router/classes/TanStackSolidRouterBridge.md

@@ -2,18 +2,19 @@
 
 # Class: TanStackSolidRouterBridge
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L42)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L43)
 
-TanStack Solid Router adapter implementing RouterBridge protocol via TanStackRouterBridgeBase
+TanStack Solid Router adapter that implements the RouterBridge protocol through TanStackRouterBridgeBase
 
 ## Remarks
 
-All behavior lives in the shared `TanStackRouterBridgeBase` (see its docs for the
-history-subscription rationale and initial-sync semantics). This subclass binds the
-adapter to the Solid flavour of TanStack Router and keeps the `dispose()` alias.
+All the behavior is in the shared `TanStackRouterBridgeBase`. Its own
+documentation gives the reason for the history subscription and the rules of the
+first synchronization. This subclass binds the adapter to the Solid version of
+TanStack Router, and it keeps the `dispose()` alias.
 
-Consumers should call `onCleanup(() => bridge.disconnect())` in their Solid
-component to ensure the bridge disconnects on unmount.
+Call `onCleanup(() => bridge.disconnect())` in your Solid component. The bridge
+then disconnects on unmount.
 
 ## Extends
 
@@ -30,17 +31,17 @@ new TanStackSolidRouterBridge(
    routeMap): TanStackSolidRouterBridge;
 ```
 
-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:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L150)
 
-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
 
@@ -58,21 +59,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.1/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
 
@@ -90,11 +93,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.1/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
 
@@ -106,16 +110,20 @@ Stops signal watching and unregisters framework-specific router listener.
 
 ---
 
-### dispose()
+### ~~dispose()~~
 
 ```ts
 dispose(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L46)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L49)
 
-Dispose the bridge (alias for disconnect).
+Disposes of the bridge. This method is the alias of disconnect.
 
 #### Returns
 
 `void`
+
+#### Deprecated
+
+Use [disconnect](#disconnect). Will be removed in the next major.

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

@@ -6,17 +6,18 @@
 function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(props) => any;
 ```
 
-Defined in: [play-tanstack-solid-router/src/create-play-router-provider.tsx:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L76)
+Defined in: [play-tanstack-solid-router/src/create-play-router-provider.tsx:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L78)
 
-Create a Solid `PlayRouterProvider` component bound to a specific bridge class.
+Creates a Solid `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 synchronously at component evaluation time (Solid's
-execution model) and torn down via `onCleanup` when the component is disposed.
-Unlike React, prop stability is not a concern — Solid's `props` accessor is
-already reactive and the bridge is created once per component instance.
+The component creates the bridge synchronously, during its own evaluation, because
+this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+when Solid disposes of the component. React is different: the stability of a prop
+is no concern here, because the `props` accessor of Solid is reactive already, and
+the component creates the bridge one time for each of its instances.
 
 ## Type Parameters
 
@@ -26,14 +27,15 @@ already reactive and the bridge is created once per component instance.
 
 ## 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`\>(`props`) => `any`