@xmachines/docs 3.0.0 → 5.0.0

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

@@ -2,7 +2,7 @@
 
 # Class: TanStackRouterBridgeBase
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L133)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L133)
 
 The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase
 
@@ -24,12 +24,12 @@ does internally: `router.history.subscribe(router.load)`.
 
 Architectural invariants:
 
-- INV-02 (Passive Infrastructure): the router reflects the actor state. It never decides
+- INV-04 (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. 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.
+the adapter.
 
 ## Example
 
@@ -41,11 +41,7 @@ return () => bridge.disconnect();
 
 ## Extends
 
-- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
-
-## Extended by
-
-- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+- [`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md)
 
 ## Constructors
 
@@ -56,21 +52,22 @@ new TanStackRouterBridgeBase(
    router,
    actor,
    routeMap,
-   options?): TanStackRouterBridgeBase;
+   options?
+): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L151)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L151)
 
 Creates a TanStack Router bridge
 
 #### Parameters
 
-| 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 |
-| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) | -                                                         |
+| 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 |
+| `options?` | [`RouterBridgeOptions`](../../play-router/index/interfaces/RouterBridgeOptions.md) | -                                                         |
 
 #### Returns
 
@@ -78,7 +75,7 @@ Creates a TanStack Router bridge
 
 #### Overrides
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`constructor`](../../play-router/index/classes/RouterBridgeBase.md#constructor)
 
 ## Accessors
 
@@ -90,7 +87,7 @@ Creates a TanStack Router bridge
 get basePath(): string;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L255)
+Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L282)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -103,7 +100,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePath`](../../play-router/classes/RouterBridgeBase.md#basepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePath`](../../play-router/index/classes/RouterBridgeBase.md#basepath)
 
 ---
 
@@ -115,7 +112,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 get basePathParams(): Readonly<Record<string, string>>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L311)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -156,7 +153,7 @@ mount while the machine stays on the same route, and no event goes out.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/classes/RouterBridgeBase.md#basepathparams)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/index/classes/RouterBridgeBase.md#basepathparams)
 
 ## Methods
 
@@ -166,11 +163,11 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
+Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
-The method installs the TC39 Signal watcher of the direction from the actor to the
+The method installs the atom 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.
 
@@ -190,7 +187,7 @@ An adapter that needs a different behavior of the first synchronization override
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`connect`](../../play-router/index/classes/RouterBridgeBase.md#connect)
 
 ---
 
@@ -200,11 +197,11 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
+Defined in: [play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L791)
 
 Disconnects the router bridge from the Actor.
 
-The method stops the watch of the signal, and it removes the router listener of the
+The method stops the watch of the atom, and it removes the router listener of the
 framework.
 
 #### Returns
@@ -213,7 +210,7 @@ framework.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/index/classes/RouterBridgeBase.md#disconnect)
 
 ---
 
@@ -223,7 +220,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 
@@ -275,4 +272,4 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/classes/RouterBridgeBase.md#setbasepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/index/classes/RouterBridgeBase.md#setbasepath)

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

@@ -6,7 +6,7 @@
 type TanStackRouteMapLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L95)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L95)
 
 The narrow route-map surface that `TanStackRouterBridgeBase` requires.
 `RouteMap` from `@xmachines/play-router` satisfies it. The bridge converts a
@@ -24,7 +24,7 @@ that holds one form only still resolves the path.
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L97)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L97)
 
 #### Parameters
 
@@ -44,7 +44,7 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:97](https:/
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L96)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L96)
 
 #### Parameters
 

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

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
 
 The type-only interface of the TanStack Router surface that
 `TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
@@ -20,7 +20,7 @@ instance of `@tanstack/solid-router` both satisfy it.
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
 
 #### location
 
@@ -69,7 +69,7 @@ subscribe(handler): () => void;
 optional options?: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
 
 The options of the router. The bridge reads `parseSearch` only.
 
@@ -103,7 +103,7 @@ optional parseSearch(search): Record<string, unknown>;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 Runs the TanStack route matching and the loaders again for the current location.
 This method is optional. The bridge calls it after every navigation. The matching
@@ -128,7 +128,7 @@ bridge then synchronizes synchronously.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
 
 Navigates to a location. `search` carries the query of the target.
 

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

@@ -4,9 +4,9 @@
 
 **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-3.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-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-solid-router)
 
-This package integrates TanStack Solid Router with the TC39 Signals. The logic then drives the navigation through the Solid.js reactivity.
+This package integrates TanStack Solid Router with the atoms. The logic then drives the navigation through the Solid.js reactivity.
 
 ## Overview
 
@@ -14,7 +14,7 @@ This package integrates TanStack Solid Router with the TC39 Signals. The logic t
 
 The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md). Each adapter therefore behaves in the same way in every framework:
 
-- The actor route signal (`actor.currentRoute`) drives the router navigation.
+- The actor route atom (`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.
@@ -30,34 +30,28 @@ pnpm add @xmachines/play-tanstack-solid-router @xmachines/play-router
 
 - `@tanstack/solid-router` `^1.168.7`
 - `solid-js` `^1.8.0`
-- `xstate` `^5.31.0`
 
 ## Current Exports
 
 - `TanStackSolidRouterBridge` — the primary adapter class
 - `PlayRouterProvider` — the Solid component that manages the bridge lifecycle
 - `PlayRouterProviderProps`, `TanStackRouterInstance` (types)
-- `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`)
+- `RoutableActor` — `currentRoute`, `initialRoute` and `send`, from [`@xmachines/play-router`](../play-router/README.md). It names no view: routing implies no rendering. A renderer callback that reads `currentView` declares its own actor type, and the constraint keeps it whole
+- `RouteMap`, `RouteMapping`, `RouteMapOptions` (re-exported from [`@xmachines/play-router`](../play-router/README.md))
+- `createRouteMap` (re-exported from [`@xmachines/play-router/xstate`](../play-router/README.md))
 - `TanStackRouterLike` (type)
 - `RouterBridge`, `PlayRouteEvent` (types)
 
-## URLPattern Support
-
-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 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, 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";
-
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { TanStackSolidRouterBridge } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 const machine = createMachine(
 	formatPlayRouteTransitions({
 		id: "app",
@@ -82,7 +76,8 @@ const tanstackRoutes = getRoutableRoutes(extractMachineRoutes(machine)).map((rou
 );
 const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
 
-const actor = definePlayer({ machine })();
+// The bridge needs the routing capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withRouting) })();
 actor.start();
 
 const bridge = new TanStackSolidRouterBridge(router, actor, routeMap);
@@ -122,7 +117,6 @@ class TanStackSolidRouterBridge {
 	constructor(router: TanStackRouterLike, actor: RoutableActor, routeMap: RouteMap);
 	connect(): void;
 	disconnect(): void;
-	dispose(): void; // alias for disconnect()
 }
 ```
 
@@ -139,7 +133,7 @@ class TanStackSolidRouterBridge {
 This Solid component creates a `TanStackSolidRouterBridge`, connects it, and cleans it up for you.
 
 ```ts
-interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
+interface PlayRouterProviderProps<TActor extends RoutableActor = RoutableActor> {
 	/** The actor to sync with TanStack Solid Router. */
 	actor: TActor;
 	/** The TanStack Router instance returned by `createRouter`. */
@@ -153,9 +147,9 @@ interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
 
 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`
+### `RouteMap`, and `createRouteMap` of `@xmachines/play-router/xstate`
 
-These two exports map each state ID to a URL path, and each URL back to a state ID.
+They map each state ID to a URL path, and each URL back to a state ID. This package exports `RouteMap`, and it re-exports `createRouteMap` never: the barrel names no state machine.
 
 ```ts
 const routeMap = new RouteMap([
@@ -172,8 +166,7 @@ routeMap.getStateIdByPath("/unknown"); // null
 Or build from a machine directly:
 
 ```ts
-import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
-
+import { createRouteMap } from "@xmachines/play-router/xstate";
 const routeMap = createRouteMap(machine); // machine: your routable machine (states carry meta.route)
 ```
 
@@ -224,12 +217,17 @@ A user navigates to `/dashboard`, and the user is not authenticated:
 ```tsx
 import { createRouter, RouterProvider, createRootRoute, createRoute } from "@tanstack/solid-router";
 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 { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
 import { authMachine } from "./auth-machine.js"; // your routable machine (states carry meta.route)
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -274,35 +272,12 @@ export default function App() {
 Bridge-first data flow:
 
 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 })`).
+2. Each actor route update, through the `actor.currentRoute` atom, 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.
 
 The routing infrastructure therefore stays passive, and the state machine keeps the control of the business logic.
 
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-pnpm --filter @xmachines/play-tanstack-solid-router test
-```
-
-Or from the package directory:
-
-```bash
-pnpm test
-```
-
-**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
-pnpm exec vitest --config vitest.browser.config.ts --project play-tanstack-solid-router-browser
-```
-
-Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
-
 ## Related Packages
 
 - [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
@@ -315,6 +290,7 @@ Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
 
 - [Demo](../../../examples/@xmachines/play-tanstack-solid-router-demo/README.md)
 - [SolidJS renderer](../play-solid/README.md)
+- [Routing guide](../../../guides/routing.md) — the URLPattern language that a `meta.route` path declares
 
 ## License
 
@@ -327,9 +303,9 @@ MIT — see [LICENSE](LICENSE).
 
 ## Interfaces
 
-- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RoutableActor](interfaces/RoutableActor.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
@@ -338,7 +314,6 @@ MIT — see [LICENSE](LICENSE).
 
 - [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
 - [PlayRouterProviderBaseProps](type-aliases/PlayRouterProviderBaseProps.md)
-- [~~RoutableActor~~](type-aliases/RoutableActor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 
@@ -349,4 +324,3 @@ MIT — see [LICENSE](LICENSE).
 ## Functions
 
 - [createPlayRouterProvider](functions/createPlayRouterProvider.md)
-- [createRouteMap](functions/createRouteMap.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [play-router/src/base-route-map.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L177)
 
 The shared base class of the route map for both directions.
 
@@ -14,15 +14,22 @@ of its own, and it inherits the complete public API from here.
 - 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
+- The class keeps each result of a first match in an LRU cache. The default cache
+  holds between 500 and 1000 entries, and the `pathCache` constructor option
+  replaces it
 
-**The syntax of a pattern** (`:param`, `:param?`, and `*`):
+**The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+often are:
 
 - `: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
 
+A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+too. The [routing guide](../../../../guides/routing.md) states every form, the prefix
+rule, and the one divergence from the standard: a param name of this library can hold a
+hyphen.
+
 **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
@@ -58,7 +65,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [play-router/src/base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L210)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -69,11 +76,10 @@ candidates is therefore efficient.
 
 #### Parameters
 
-| 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`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| 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`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | See [RouteMapOptions](../interfaces/RouteMapOptions.md). A map holds TWO caches, so no option is named `cache`: each one names the cache that it carries. |
 
 #### Returns
 
@@ -87,7 +93,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [play-router/src/base-route-map.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L324)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [play-router/src/base-route-map.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L279)
 
 Resolves a URL path to its state ID.