@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,11 +2,9 @@
 
 # @xmachines/play-vue-router
 
-Vue Router 4.x adapter for XMachines Universal Player Architecture. Bidirectional sync between Vue Router and XMachines state machines using Vue's reactive primitives.
+Vue Router 4.x adapter for the XMachines Universal Player Architecture. It keeps Vue Router and an XMachines state machine in step, in both directions, with the reactive primitives of Vue.
 
-[![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-vue-router)
-
-Part of the [xmachines-js monorepo](../../README.md).
+[![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-vue-router)
 
 ## Installation
 
@@ -25,20 +23,22 @@ pnpm add @xmachines/play-vue-router
 
 ### VueRouterBridge — low-level adapter
 
-`VueRouterBridge` wires Vue Router's `currentRoute` ref to an XMachines actor's `currentRoute` signal. Both directions are active: the actor drives the URL, and the URL drives the actor.
+`VueRouterBridge` connects the `currentRoute` ref of Vue Router to the `currentRoute` signal of an XMachines actor. Both directions are active: the actor drives the URL, and the URL drives the actor.
 
 ```typescript
 import { createRouter, createWebHistory } from "vue-router";
+import { h } from "vue";
 import { VueRouterBridge, RouteMap } from "@xmachines/play-vue-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { machine } from "./machine.js"; // your routable machine (states carry meta.route)
+
+// 1. Define routes — a single catch-all with a stub host component;
+//    PlayRenderer picks the actual view from actor state
+const RouteHost = { render: () => h("div") };
 
-// 1. Define routes
 const router = createRouter({
 	history: createWebHistory(),
-	routes: [
-		{ path: "/", name: "home", component: HomePage },
-		{ path: "/profile/:userId", name: "profile", component: ProfilePage },
-		{ path: "/settings/:section?", name: "settings", component: SettingsPage },
-	],
+	routes: [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }],
 });
 
 // 2. Create a bidirectional state ID ↔ path mapping
@@ -48,7 +48,10 @@ const routeMap = new RouteMap([
 	{ stateId: "settings", path: "/settings/:section?" },
 ]);
 
-// 3. Start the bridge after the router is ready
+// 3. Start the actor, then the bridge after the router is ready
+const actor = definePlayer({ machine })();
+actor.start();
+
 await router.isReady();
 const bridge = new VueRouterBridge(router, actor, routeMap);
 bridge.connect();
@@ -59,13 +62,18 @@ bridge.dispose();
 
 ### PlayRouterProvider — Vue component wrapper
 
-`PlayRouterProvider` is a convenience component that manages the bridge lifecycle automatically — it calls `bridge.connect()` after `router.isReady()` on mount and `bridge.disconnect()` on unmount.
+`PlayRouterProvider` manages the bridge lifecycle for you. It calls `bridge.connect()` on mount, after `router.isReady()`. It calls `bridge.disconnect()` on unmount.
 
 ```vue
 <script setup lang="ts">
-import { markRaw } from "vue";
+import { h, markRaw } from "vue";
 import { useRouter } from "vue-router";
 import { PlayRouterProvider, RouteMap } from "@xmachines/play-vue-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { machine } from "./machine.js"; // your routable machine (states carry meta.route)
+// AppShell: your root component — a real app renders PlayUIProvider + PlayRenderer
+// from @xmachines/play-vue (see the workspace-only @xmachines/play-vue-demo Shell)
+import AppShell from "./AppShell.vue";
 
 const router = useRouter();
 const routeMap = new RouteMap([
@@ -75,7 +83,8 @@ const routeMap = new RouteMap([
 
 // markRaw prevents Vue from wrapping the actor in a reactive proxy,
 // which would break TC39 Signal receivers.
-const actor = markRaw(createActor());
+const actor = markRaw(definePlayer({ machine })());
+actor.start();
 </script>
 
 <template>
@@ -94,6 +103,7 @@ const actor = markRaw(createActor());
 <script setup>
 import { inject } from "vue";
 
+// Provided at app setup with the matching call: app.provide("actor", actor)
 const actor = inject("actor");
 
 function viewProfile(userId) {
@@ -110,7 +120,7 @@ function viewProfile(userId) {
 
 ### `VueRouterBridge`
 
-Implements the `RouterBridge` protocol by watching Vue Router's `currentRoute` shallowRef and the actor's `currentRoute` TC39 Signal.
+This class implements the `RouterBridge` protocol. It watches the `currentRoute` shallowRef of Vue Router and the `currentRoute` TC39 Signal of the actor.
 
 ```typescript
 class VueRouterBridge {
@@ -123,21 +133,21 @@ class VueRouterBridge {
 
 **Constructor parameters:**
 
-| Parameter   | Type            | Description                                  |
-| ----------- | --------------- | -------------------------------------------- |
-| `vueRouter` | `Router`        | Vue Router instance from `createRouter()`    |
-| `actor`     | `RoutableActor` | XMachines actor with a `currentRoute` signal |
-| `routeMap`  | `RouteMap`      | Bidirectional state ID ↔ path mapping        |
+| Parameter   | Type            | Description                                               |
+| ----------- | --------------- | --------------------------------------------------------- |
+| `vueRouter` | `Router`        | The Vue Router instance from `createRouter()`             |
+| `actor`     | `RoutableActor` | The XMachines actor with a `currentRoute` signal          |
+| `routeMap`  | `RouteMap`      | The bidirectional map between the state IDs and the paths |
 
 **Methods:**
 
-- `connect()` — Start bidirectional synchronization. Performs an initial sync from the router's current path to the actor (cold-load / direct-URL support). Uses `watch(router.currentRoute, …)` from `@vue/reactivity` (not `@vue/runtime-core`) so watcher errors propagate directly without being swallowed by Vue's global error handler.
-- `disconnect()` — Stop all watchers and stop the Vue effect scope.
-- `dispose()` — Alias for `disconnect()`, intended for `onUnmounted(() => bridge.dispose())`.
+- `connect()` — starts the work in both directions. It first sets the actor state from the current path of the router, which supports a cold load and a direct URL. It uses `watch(router.currentRoute, …)` from `@vue/reactivity`, not from `@vue/runtime-core`. Therefore a watcher error goes to the caller, and the global error handler of Vue does not hide it.
+- `disconnect()` — stops every watcher and stops the Vue effect scope.
+- `dispose()` — the alias of `disconnect()`. Use it in `onUnmounted(() => bridge.dispose())`.
 
 ### `PlayRouterProvider`
 
-Vue component that wraps `VueRouterBridge` in component lifecycle hooks.
+This Vue component wraps `VueRouterBridge` in the component lifecycle hooks.
 
 ```typescript
 import type { PlayActor } from "@xmachines/play-vue-router";
@@ -156,14 +166,14 @@ defineComponent({
 });
 ```
 
-The `actor` prop requires `PlayActor` (`AbstractActor & Routable & Viewable`) — the provider renders the current view spec in addition to synchronizing routes. The `renderer` callback receives the same concrete actor type.
+The `actor` prop requires a `PlayActor` (`AbstractActor & Routable & Viewable`), because the provider renders the current view spec and also keeps the routes in step. The `renderer` callback receives the same concrete actor type.
 
 ### `RouteMap` / `VueRouteMap`
 
-`RouteMap` (re-exported from `@xmachines/play-router`) is the bidirectional state ID ↔ path mapping used by the bridge. `VueRouteMap` is an alias for `RouteMap` — both are identical.
+`RouteMap` comes from `@xmachines/play-router`. It is the bidirectional map between the state IDs and the paths, and the bridge uses it. `VueRouteMap` is a deprecated alias of `RouteMap`. The two names are identical, and the next major version removes the alias.
 
 ```typescript
-import { RouteMap, createRouteMap } from "@xmachines/play-vue-router";
+import { RouteMap } from "@xmachines/play-vue-router";
 
 // Explicit construction
 const routeMap = new RouteMap([
@@ -171,15 +181,18 @@ const routeMap = new RouteMap([
 	{ stateId: "profile", path: "/profile/:userId" },
 	{ stateId: "settings", path: "/settings/:section?" },
 ]);
+```
+
+```typescript
+import { createRouteMap } from "@xmachines/play-vue-router";
 
 // Or derive from an XState machine
-import { createRouteMap } from "@xmachines/play-router";
-const routeMap = createRouteMap(machine);
+const routeMap = createRouteMap(machine); // machine: your routable machine (states carry meta.route)
 ```
 
 ### Exported error classes (`@xmachines/play-vue-router/errors`)
 
-All runtime errors extend `PlayError` from `@xmachines/play` and are available from the `./errors` subpath:
+Every runtime error extends `PlayError` from `@xmachines/play`. The `./errors` subpath exports them:
 
 ```typescript
 import {
@@ -189,13 +202,13 @@ import {
 } from "@xmachines/play-vue-router/errors";
 ```
 
-| Class                      | Error code                          | When thrown                                                            |
-| -------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
-| `VueRouterCorrectionError` | `PLAY_VUE_ROUTER_CORRECTION_FAILED` | `router.replace()` rejected when syncing actor → router (correction)   |
-| `VueRouterNavigationError` | `PLAY_VUE_ROUTER_NAV_FAILED`        | `router.push()` rejected (navigation guard cancellation, redirect)     |
-| `VueRouterSendError`       | `PLAY_VUE_ROUTER_SEND_FAILED`       | Vue Router watcher callback fails to deliver `play.route` to the actor |
+| Class                      | Error code                          | When thrown                                                                                      |
+| -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `VueRouterCorrectionError` | `PLAY_VUE_ROUTER_CORRECTION_FAILED` | Deprecated. No code throws it. A correction reports `VueRouterNavigationError`                   |
+| `VueRouterNavigationError` | `PLAY_VUE_ROUTER_NAV_FAILED`        | `router.push()` refused the navigation: a navigation guard stopped it, or a redirect replaced it |
+| `VueRouterSendError`       | `PLAY_VUE_ROUTER_SEND_FAILED`       | The Vue Router watcher callback cannot send `play.route` to the actor                            |
 
-Each class carries a `cause` property with the original Vue Router error.
+Each class holds the original Vue Router error in its `cause` property.
 
 ### Exported types
 
@@ -213,7 +226,7 @@ export type { PlayActor } from "@xmachines/play-vue-router";
 // RoutableActor is also exported as a deprecated alias for PlayActor
 ```
 
-`PlayActor` is `AbstractActor<AnyActorLogic> & Routable & Viewable` — the shape required by `PlayRouterProvider`, which renders the current view spec in addition to synchronizing routes. Use `RoutableActor` from `@xmachines/play-router` when only routing is needed (e.g. constructing `VueRouterBridge` directly).
+`PlayActor` is `AbstractActor<AnyActorLogic> & Routable & Viewable`. `PlayRouterProvider` requires this shape, because it renders the current view spec and also keeps the routes in step. Use `RoutableActor` from `@xmachines/play-router` when you need the routing alone, for example when you create a `VueRouterBridge` yourself.
 
 ## Architecture
 
@@ -221,27 +234,27 @@ export type { PlayActor } from "@xmachines/play-vue-router";
 
 **Router → Actor** (`watch(router.currentRoute, …)`):
 
-1. User navigates (link click, browser back, programmatic `router.push`).
-2. Vue's `currentRoute` shallowRef is assigned a new object.
+1. The user navigates: a link click, the browser BACK button, or a `router.push` call in the code.
+2. Vue puts a new object in the `currentRoute` shallowRef.
 3. `watch` from `@vue/reactivity` fires synchronously (`scheduler: (job) => job()`).
-4. Bridge sanitizes the path, looks up the state ID in `routeMap`.
-5. Bridge sends `{ type: "play.route", to: "#stateId", params, query }` to the actor.
+4. The bridge cleans the path, then finds the state ID in `routeMap`.
+5. The bridge sends `{ type: "play.route", to: "#stateId", params, query }` to the actor.
 
 **Actor → Router** (TC39 Signal watcher):
 
-1. Actor transitions; `actor.currentRoute` signal updates to a new state ID or path.
-2. Signal watcher fires in a microtask.
-3. Bridge resolves the navigation path via `resolveNavigationPath`.
-4. Parameterized patterns without concrete params are skipped (returns `null`).
-5. Bridge calls `router.push(resolvedPath)`.
+1. The actor makes a transition, and the `actor.currentRoute` signal gets a new state ID or a new path.
+2. The signal watcher fires in a microtask.
+3. The bridge resolves the navigation path with `resolveNavigationPath`.
+4. The bridge skips a parameterized pattern that has no concrete params, and `resolveNavigationPath` returns `null`.
+5. The bridge calls `router.push(resolvedPath)`.
 
 ### Echo suppression
 
-`lastSyncedPath` is set before every `router.push()` call. When the Vue watcher subsequently fires with the same path (the router echoing the actor-initiated push), the `sanitizedPath === lastSyncedPath` check short-circuits before any event is sent.
+The bridge sets `lastSyncedPath` before every `router.push()` call. The Vue watcher then fires with the same path, because the router repeats the push of the actor. The `sanitizedPath === lastSyncedPath` check stops the bridge before it sends an event.
 
 ### Vue effect scope
 
-The `watch` watcher runs inside a dedicated `effectScope()`. Calling `disconnect()` / `dispose()` calls `scope.stop()`, fully removing the watcher without leaking into the global Vue effect scope.
+The `watch` watcher runs inside its own `effectScope()`. `disconnect()` and `dispose()` call `scope.stop()`. This removes the watcher completely, and nothing stays in the global Vue effect scope.
 
 ## Testing
 
@@ -256,7 +269,7 @@ pnpm --filter @xmachines/play-vue-router run test:watch
 pnpm --filter @xmachines/play-vue-router run test:coverage
 ```
 
-Test files use Vitest with jsdom and `@vue/test-utils`. Integration tests (`test/integration.test.ts`) use real Vue Router instances with SFC fixtures.
+The test files use Vitest with jsdom and `@vue/test-utils`. The integration tests (`test/integration.test.ts`) use a real Vue Router instance with an SFC fixture.
 
 ## Classes
 
@@ -274,17 +287,13 @@ Test files use Vitest with jsdom and `@vue/test-utils`. Integration tests (`test
 ## Type Aliases
 
 - [~~RoutableActor~~](type-aliases/RoutableActor.md)
+- [~~VueRouteMap~~](type-aliases/VueRouteMap.md)
 
 ## Variables
 
 - [PlayRouterProvider](variables/PlayRouterProvider.md)
+- [~~VueRouteMap~~](variables/VueRouteMap.md)
 
 ## Functions
 
 - [createRouteMap](functions/createRouteMap.md)
-
-## References
-
-### VueRouteMap
-
-Renames and re-exports [RouteMap](classes/RouteMap.md)

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

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

package/api/@xmachines/play-vue-router/classes/VueRouterBridge.md

@@ -2,11 +2,11 @@
 
 # Class: VueRouterBridge
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue-router/src/vue-router-bridge.ts#L32)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue-router/src/vue-router-bridge.ts#L35)
 
 @xmachines/play-vue-router - Vue Router 4.x adapter for XMachines Play
 
-Provides bidirectional integration between Vue Router and XMachines state machines.
+It integrates Vue Router with an XMachines state machine, in both directions.
 
 ## Extends
 
@@ -23,7 +23,7 @@ new VueRouterBridge(
    routeMap): VueRouterBridge;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue-router/src/vue-router-bridge.ts#L41)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue-router/src/vue-router-bridge.ts#L44)
 
 #### Parameters
 
@@ -49,21 +49,23 @@ Defined in: [play-vue-router/src/vue-router-bridge.ts:41](https://gitlab.com/xma
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L151)
+Defined in: [play-router/src/router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L158)
 
-Connect the router bridge to the Actor.
+Connects the router bridge to the Actor.
 
-Sets up the TC39 Signal watcher for actor → router direction and
-starts watching router changes (framework-specific).
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
 
-Ordering here is part of the bridge contract:
+The order of these steps is part of the contract of the bridge:
 
-- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-- the actor watcher is installed before adapter router subscriptions
-- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The method installs the actor watcher before the router subscriptions of the adapter
+- The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
-Adapters that need custom initial-sync behavior should override
-`getInitialRouterPath()` rather than reordering `connect()` steps.
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
 
 #### Returns
 
@@ -81,11 +83,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L256)
+Defined in: [play-router/src/router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L270)
 
-Disconnect the router bridge from the Actor.
+Disconnects the router bridge from the Actor.
 
-Stops signal watching and unregisters framework-specific router listener.
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
 
 #### Returns
 
@@ -97,16 +100,20 @@ Stops signal watching and unregisters framework-specific router listener.
 
 ---
 
-### dispose()
+### ~~dispose()~~
 
 ```ts
 dispose(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue-router/src/vue-router-bridge.ts#L203)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:215](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue-router/src/vue-router-bridge.ts#L215)
 
-Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`).
+The cleanup alias for the Vue component lifecycle (`onUnmounted(() => bridge.dispose())`).
 
 #### Returns
 
 `void`
+
+#### Deprecated
+
+Use [disconnect](#disconnect). Will be removed in the next major.

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

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