@xmachines/docs 2.0.0 → 2.1.0

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/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,16 +4,16 @@
 
 Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
 
-[![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-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.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
 
-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.
+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
-structural, type-only interface covering the small router surface the bridge uses.
+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
 
@@ -23,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
 
@@ -45,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
 

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

@@ -2,32 +2,34 @@
 
 # Class: TanStackRouterBridgeBase
 
-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
 
@@ -56,17 +58,17 @@ new TanStackRouterBridgeBase(
    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`](../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`](../type-aliases/TanStackRouteMapLike.md)    | The bidirectional map between the state IDs and the paths |
 
 #### Returns
 
@@ -84,21 +86,23 @@ Create a TanStack Router bridge
 connect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:120
+Defined in: play-router/dist/router-bridge-base.d.ts:124
 
-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
 
@@ -116,11 +120,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:126
+Defined in: play-router/dist/router-bridge-base.d.ts:131
 
-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-router/type-aliases/TanStackRouteMapLike.md

@@ -6,15 +6,15 @@
 type TanStackRouteMapLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L66)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L69)
 
-Narrow route-map surface required by `TanStackRouterBridgeBase`.
-`RouteMap` from `@xmachines/play-router` satisfies it (null returns are
-adapted to undefined internally).
+The narrow route-map surface that `TanStackRouterBridgeBase` requires.
+`RouteMap` from `@xmachines/play-router` satisfies it. The bridge converts a
+`null` result into `undefined` internally.
 
-`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
-`"stateId"` form — the bridge tries both forms automatically, so custom
-implementations keyed on a single form still resolve.
+`getPathByStateId` can receive the stateId in the form `"#stateId"` or in the
+bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
+that holds one form only still resolves the path.
 
 ## Methods
 
@@ -24,7 +24,7 @@ implementations keyed on a single form still resolve.
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L68)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 #### Parameters
 
@@ -44,7 +44,7 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https:/
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L67)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L70)
 
 #### Parameters
 

package/api/@xmachines/play-tanstack-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/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/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/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/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-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.0-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,14 @@ 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.
 
 ### `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 +150,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 +166,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 +194,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 +210,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 +226,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 +272,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 +293,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 +305,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