@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.26

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

@@ -2,7 +2,7 @@
 
 # Class: VueRouterBridge
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L47)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L16)
 
 @xmachines/play-vue-router - Vue Router 4.x adapter for XMachines Play
 
@@ -20,33 +20,23 @@ Provides bidirectional integration between Vue Router and XMachines state machin
 new VueRouterBridge(
    vueRouter,
    actor,
-   vueRouteMap): VueRouterBridge;
+   routeMap): VueRouterBridge;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L137)
-
-Create a Vue Router bridge
+Defined in: [play-vue-router/src/vue-router-bridge.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L21)
 
 #### Parameters
 
-| Parameter     | Type                                                                                                                                                                                                                                                             | Description                                 |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `vueRouter`   | `Router`                                                                                                                                                                                                                                                         | Vue Router instance                         |
-| `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | XMachines actor instance                    |
-| `vueRouteMap` | [`RouteMap`](RouteMap.md)                                                                                                                                                                                                                                        | Bidirectional state ID ↔ route name mapping |
+| Parameter   | Type                                                                                                                                                                                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vueRouter` | `Router`                                                                                                                                                                                                                                                         |
+| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) |
+| `routeMap`  | [`RouteMap`](RouteMap.md)                                                                                                                                                                                                                                        |
 
 #### Returns
 
 `VueRouterBridge`
 
-#### Example
-
-```typescript
-const bridge = new VueRouterBridge(router, actor, routeMap);
-bridge.connect(); // Explicit connect — NOT automatic
-onUnmounted(() => bridge.disconnect());
-```
-
 #### Overrides
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
@@ -55,15 +45,15 @@ onUnmounted(() => bridge.disconnect());
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L90)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L92)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L91)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L103) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L105) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L93)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -73,7 +63,7 @@ onUnmounted(() => bridge.disconnect());
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L129)
+Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L126)
 
 Connect the router bridge to the Actor.
 
@@ -105,7 +95,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L197)
+Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L209)
 
 Disconnect the router bridge from the Actor.
 
@@ -127,20 +117,14 @@ Stops signal watching and unregisters framework-specific router listener.
 dispose(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L280)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L135)
 
-Cleanup alias for component lifecycle integration.
+Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`).
 
 #### Returns
 
 `void`
 
-#### Example
-
-```typescript
-onUnmounted(() => bridge.dispose());
-```
-
 ---
 
 ### extractParams()
@@ -149,14 +133,14 @@ onUnmounted(() => bridge.dispose());
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L300)
+Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L318)
 
 Extract path parameters from URL using the URLPattern API.
 
 Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
-polyfill), this method returns `{}` silently (graceful degradation — routing still
-works, params will be empty).
+library. If `URLPattern` is unavailable and the matched route has parameterized
+segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
+for environments without native URLPattern support (Node.js < 24, older browsers).
 
 #### Parameters
 
@@ -169,7 +153,11 @@ works, params will be empty).
 
 `Record`\<`string`, `string`\>
 
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
+Extracted path parameters, or empty object if no match
+
+#### Throws
+
+When URLPattern is absent and the route is parameterized
 
 #### Inherited from
 
@@ -183,7 +171,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L321)
+Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -211,14 +199,25 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:268](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L268)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L115)
+
+Return the router's current pathname at connect() time.
 
-Return the current Vue Router URL for initial sync.
+Called once during connect() to perform the initial URL → actor sync.
+router.subscribe() only fires on _future_ navigation events; it does not
+replay the already-loaded location. Subclasses that can read the router's
+current location synchronously (e.g. `router.state.location.pathname`)
+should override this method so that deep-link / direct-URL loads drive the
+actor to the correct state instead of leaving it at its machine default.
 
-The base class `connect()` uses this together with `actor.initialRoute` to
-distinguish a deep-link (non-initial URL → router wins, guards evaluate) from
-a restore (initial URL + actor at a different restored route → actor wins,
-bridge pushes actor's route to the router).
+Return semantics:
+
+- `string` → router has a current path; base connect() will sync actor from router
+- `null` → router is active but has no current path yet; base connect() will sync router from actor
+- `undefined` → adapter handles initial sync itself and base connect() should stay out of the way
+
+The default returns `undefined`, preserving the previous behaviour for
+bridges that have not yet implemented this hook.
 
 #### Returns
 
@@ -230,19 +229,44 @@ bridge pushes actor's route to the router).
 
 ---
 
+### getInitialRouterSearch()
+
+```ts
+protected getInitialRouterSearch(): string | undefined;
+```
+
+Defined in: [play-vue-router/src/vue-router-bridge.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L127)
+
+Return the initial URL search string for query-param forwarding on `connect()`.
+
+Vue Router does not expose a raw `search` string on the normalized route — only
+`fullPath` (e.g. `"/profile/123?tab=posts"`). The search is extracted by slicing
+from the first `"?"`. Returns `undefined` when no query string is present so
+`syncActorFromRouter` produces `query: {}` rather than parsing an empty string.
+
+#### Returns
+
+`string` \| `undefined`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`getInitialRouterSearch`](../../play-router/classes/RouterBridgeBase.md#getinitialroutersearch)
+
+---
+
 ### navigateRouter()
 
 ```ts
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L155)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L64)
 
-Navigate Vue Router to the given path/stateId.
+Navigate Vue Router to the given path.
 
-For state IDs (starting with #), resolves to named route.
-For paths (starting with /), navigates directly.
-Navigation errors are thrown as [VueRouterNavigationError](#).
+Receives a raw actor route value (stateId or concrete path).
+`resolveNavigationPath` normalizes to a concrete path; parameterized patterns
+are skipped. Navigation errors are thrown as [VueRouterNavigationError](#).
 
 #### Parameters
 
@@ -260,13 +284,52 @@ Navigation errors are thrown as [VueRouterNavigationError](#).
 
 ---
 
+### resolveNavigationPath()
+
+```ts
+protected resolveNavigationPath(route): string | null;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L340)
+
+Resolve an actor route value to a concrete URL path for navigation.
+
+Bridges that receive raw `actor.currentRoute` values in `navigateRouter`
+can call this to normalize stateIds (with or without `#` prefix) to paths.
+Returns `null` when navigation is not possible:
+
+- unknown stateId with no route map entry
+- parameterized pattern (e.g. `/profile/:id`) — no concrete values available
+- non-path string that isn't a known stateId
+
+Route maps may store stateIds with or without the `#` prefix; both forms
+are tried automatically.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                    |
+| --------- | -------- | -------------------------------------------------------------- |
+| `route`   | `string` | Raw actor route value (stateId, `#`-stateId, or concrete path) |
+
+#### Returns
+
+`string` \| `null`
+
+Concrete URL path, or `null` if navigation should be skipped
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`resolveNavigationPath`](../../play-router/classes/RouterBridgeBase.md#resolvenavigationpath)
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -296,7 +359,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L228)
+Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -329,9 +392,11 @@ suppressed as circular echoes.
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L255)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L110)
+
+Stop watching for router location changes.
 
-Unsubscribe from Vue Router afterEach guard.
+Called by disconnect(). Should clean up the framework-specific subscription.
 
 #### Returns
 
@@ -349,12 +414,12 @@ Unsubscribe from Vue Router afterEach guard.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:186](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-router-bridge.ts#L186)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/vue-router-bridge.ts#L78)
 
-Start watching for router location changes.
+Subscribe to Vue Router changes using `afterEach`.
 
-Called by connect(). Should set up the framework-specific subscription
-for location changes and call syncActorFromRouter() on each change.
+Uses Vue's native `to.params` / `to.query` for accurate extraction
+instead of URLPattern-based re-parsing.
 
 #### Returns
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-vue-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/create-route-map.ts#L9)
+Defined in: [play-vue-router/src/create-route-map.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/create-route-map.ts#L5)
 
 ## Parameters
 

package/api/@xmachines/play-vue-router/interfaces/PlayRouteEvent.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L216)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L224) |

package/api/@xmachines/play-vue-router/interfaces/RouteMapping.md

@@ -2,14 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-vue-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/types.ts#L10)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L57)
 
-Mapping configuration between XMachines state IDs and Vue Router route names
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`BaseRouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                    | Modifier   | Type     | Description                                    | Defined in                                                                                                                                    |
-| ------------------------------------------- | ---------- | -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pattern"></a> `pattern?`    | `readonly` | `string` | Optional URL pattern for debugging             | [play-vue-router/src/types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/types.ts#L16) |
-| <a id="property-routename"></a> `routeName` | `readonly` | `string` | Vue Router route name                          | [play-vue-router/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/types.ts#L14) |
-| <a id="property-stateid"></a> `stateId`     | `readonly` | `string` | XMachines state ID (e.g., '#home', '#profile') | [play-vue-router/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/types.ts#L12) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L264)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L280)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L296)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-vue-router/type-aliases/RoutableActor.md

@@ -6,6 +6,6 @@
 type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/play-router-provider.ts#L10)
+Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/play-router-provider.ts#L10)
 
 Minimum actor shape accepted by PlayRouterProvider.

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

@@ -64,7 +64,7 @@ const PlayRouterProvider: DefineComponent<
 >;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/play-router-provider.ts#L19)
+Defined in: [play-vue-router/src/play-router-provider.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/play-router-provider.ts#L19)
 
 PlayRouterProvider — Vue convenience wrapper for VueRouterBridge.
 

package/api/@xmachines/play-xstate/README.md

@@ -40,8 +40,8 @@ const machine = setup({
 	types: {
 		context: {} as {
 			isAuthenticated: boolean;
-			routeParams: Record<string, string>;
-			queryParams: Record<string, string>;
+			params: Record<string, string>;
+			query: Record<string, string>;
 		},
 		events: {} as
 			| { type: "play.route"; to: string; params?: Record<string, string> }
@@ -52,7 +52,7 @@ const machine = setup({
 	formatPlayRouteTransitions({
 		id: "app",
 		initial: "login",
-		context: { isAuthenticated: false, routeParams: {}, queryParams: {} },
+		context: { isAuthenticated: false, params: {}, query: {} },
 		states: {
 			login: {
 				id: "login",
@@ -180,8 +180,8 @@ Concrete actor implementing Play signal protocol:
 **Signal Properties:**
 
 - `state: Signal.State<AnyMachineSnapshot>` — Reactive snapshot of current state
-- `currentRoute: Signal.Computed<string | null>` — Derived URL from the current state's `meta.route` and `context.routeParams`. Returns `null` when no route metadata is present or a required route parameter is missing from context.
-- `currentView: Signal.State<ViewMetadata | null>` — Current view spec (updated on every state transition). The spec is automatically enriched with `context.routeParams` (URL params) and any `contextProps`-allowlisted context fields before being emitted (see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context)).
+- `currentRoute: Signal.Computed<string | null>` — Derived URL from the current state's `meta.route` and `context.params`. Returns `null` when no route metadata is present or a required route parameter is missing from context.
+- `currentView: Signal.State<ViewMetadata | null>` — Current view spec (updated on every state transition). The spec is automatically enriched with `context.params` (URL params) and any `contextProps`-allowlisted context fields before being emitted (see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context)).
 
 **Lifecycle ordering:**
 
@@ -207,7 +207,7 @@ Concrete actor implementing Play signal protocol:
 **View derivation and route-param enrichment:**
 
 - `currentView` emits a fresh `ViewMetadata` object on every transition so TC39 Signal equality checks always detect changes (including re-entries to the same state with different params).
-- `context.routeParams` and `contextProps`-allowlisted context fields are merged into spec element props — see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context).
+- `context.params` and `contextProps`-allowlisted context fields are merged into spec element props — see [Prop Enrichment from Routing and Context](#prop-enrichment-from-routing-and-context).
 
 **Example:**
 
@@ -316,8 +316,8 @@ const machine = setup({
 	types: {
 		context: {} as {
 			isAuthenticated: boolean;
-			routeParams: Record<string, string>;
-			queryParams: Record<string, string>;
+			params: Record<string, string>;
+			query: Record<string, string>;
 		},
 		events: {} as
 			| { type: "play.route"; to: string; params?: Record<string, string> }
@@ -474,7 +474,7 @@ spec: {
 }
 // After play.route to /settings/profile:
 // Component receives: { section: "profile", username: "alice", theme: "dark" }
-//   section  → from routeParams (URL)
+//   section  → from context.params (URL)
 //   username → from contextProps (context)
 //   theme    → from spec (explicit value, untouched)
 ```
@@ -526,11 +526,11 @@ it to be filled in automatically.
 
 ### Merge priority (highest → lowest)
 
-| Source                                  | When it applies                  | Wins over                 |
-| --------------------------------------- | -------------------------------- | ------------------------- |
-| Explicit non-`undefined` spec prop      | Always                           | Everything                |
-| URL route param (`context.routeParams`) | State has a `:param` URL segment | `contextProps` values     |
-| `contextProps` field                    | Listed in `spec.contextProps`    | Nothing (lowest priority) |
+| Source                             | When it applies                  | Wins over                 |
+| ---------------------------------- | -------------------------------- | ------------------------- |
+| Explicit non-`undefined` spec prop | Always                           | Everything                |
+| URL route param (`context.params`) | State has a `:param` URL segment | `contextProps` values     |
+| `contextProps` field               | Listed in `spec.contextProps`    | Nothing (lowest priority) |
 
 ### URL route parameters
 
@@ -580,7 +580,7 @@ If both a route param and a `contextProps` field share the same key, the route p
 
 ```typescript
 // context.username = "alice" (logged-in user)
-// play.route to /profile/demo → routeParams.username = "demo"
+// play.route to /profile/demo → context.params.username = "demo"
 // contextProps: ["username"], props: { username: undefined }
 // Component receives: { username: "demo" }  ← route param wins
 ```