@xmachines/docs 1.0.0-beta.52 → 1.0.0-beta.54

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:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L30)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L32)
 
 @xmachines/play-vue-router - Vue Router 4.x adapter for XMachines Play
 
@@ -23,13 +23,13 @@ new VueRouterBridge(
    routeMap): VueRouterBridge;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L39)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L41)
 
 #### Parameters
 
 | Parameter   | Type                                                                 |
 | ----------- | -------------------------------------------------------------------- |
-| `vueRouter` | `Router`                                                             |
+| `vueRouter` | `RouterClassic`                                                      |
 | `actor`     | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) |
 | `routeMap`  | [`RouteMap`](RouteMap.md)                                            |
 
@@ -45,15 +45,15 @@ Defined in: [play-vue-router/src/vue-router-bridge.ts:39](https://gitlab.com/xma
 
 | Property                                                              | Modifier    | Type                                                                                    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                    | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L125) |
-| <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:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L103) |
-| <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:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                               | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L115) |
-| <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:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L104) |
-| <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(machine)` or an equivalent.                                                                                                                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L126) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L128) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L127) |
-| <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:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L116) |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                    | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L124) |
+| <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:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <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:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L98)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                               | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L111) |
+| <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:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L100) |
+| <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(machine)` or an equivalent. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one.                                                                          | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L125) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L127) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L126) |
+| <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:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L112) |
 
 ## Methods
 
@@ -63,7 +63,7 @@ Defined in: [play-vue-router/src/vue-router-bridge.ts:39](https://gitlab.com/xma
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L152)
+Defined in: [play-router/src/router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
@@ -95,7 +95,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -117,7 +117,7 @@ Stops signal watching and unregisters framework-specific router listener.
 dispose(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:186](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L186)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L203)
 
 Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`).
 
@@ -130,36 +130,31 @@ Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`
 ### extractParams()
 
 ```ts
-protected extractParams(pathname, stateId): Record<string, string>;
+protected extractParams(_pathname, _stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L402)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L121)
 
-Extract path parameters from URL using the URLPattern API.
+Extract path parameters using vue-router's pre-parsed `route.params`.
 
-Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-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).
+Vue Router has already extracted all named parameters (decoded) for the
+matched route, so URLPattern-based re-parsing is unnecessary — parameterized
+routes work without a URLPattern polyfill. Read from `currentRoute.value` at
+call time: both the watcher and connect()'s initial sync run when the ref
+already reflects the route being synced.
 
 #### Parameters
 
-| Parameter  | Type     | Description                                           |
-| ---------- | -------- | ----------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')           |
-| `stateId`  | `string` | The matched state ID for looking up the route pattern |
+| Parameter   | Type     | Description                                     |
+| ----------- | -------- | ----------------------------------------------- |
+| `_pathname` | `string` | Unused — params already extracted by Vue Router |
+| `_stateId`  | `string` | Unused — params already extracted by Vue Router |
 
 #### Returns
 
 `Record`\<`string`, `string`\>
 
-Extracted path parameters, or empty object if no match
-
-#### Throws
-
-When URLPattern is absent and the route is parameterized
-
-#### Inherited from
+#### Overrides
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`extractParams`](../../play-router/classes/RouterBridgeBase.md#extractparams)
 
@@ -171,7 +166,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L439)
+Defined in: [play-router/src/router-bridge-base.ts:480](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L480)
 
 Extract query parameters from URL search string.
 
@@ -199,7 +194,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:166](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L166)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:183](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L183)
 
 Return the router's current pathname at connect() time.
 
@@ -235,14 +230,15 @@ bridges that have not yet implemented this hook.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L178)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:196](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L196)
 
 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.
+Serialized from vue-router's pre-parsed `route.query` via the same
+`searchFromQuery` used by the watcher — NOT sliced from `fullPath`, whose
+hash fragment would otherwise leak into query values. Returns `undefined`
+when no query params are present so `syncActorFromRouter` produces
+`query: {}` rather than parsing an empty string.
 
 #### Returns
 
@@ -260,19 +256,19 @@ from the first `"?"`. Returns `undefined` when no query string is present so
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L84)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L103)
 
 Navigate Vue Router to the given path.
 
-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](#).
+Receives a RESOLVED concrete URL path — the base class resolves stateIds
+and skips unresolvable routes before calling this method, so the value is
+pushed as-is. Navigation errors are thrown as [VueRouterNavigationError](#).
 
 Echo suppression — preventing the watcher from re-driving the actor with the
 router's response to this push — is handled by `lastSyncedPath` in the base
-class. `syncRouterFromActor` sets `lastSyncedPath = resolved` before this call,
-so when the watcher fires with the same path it short-circuits at the
-`sanitizedPath === lastSyncedPath` check and sends no event.
+class. `syncRouterFromActor` sets `lastSyncedPath` to the resolved path before
+this call, so when the watcher fires with the same path it short-circuits at
+the `sanitized === lastSyncedPath` check and sends no event.
 
 #### Parameters
 
@@ -296,7 +292,7 @@ so when the watcher fires with the same path it short-circuits at the
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:424](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L424)
+Defined in: [play-router/src/router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L447)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -305,11 +301,13 @@ 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
+- parameterized or wildcard pattern (e.g. `/profile/:id`, `/docs/*`) — no
+  concrete values available to build a real URL
 - non-path string that isn't a known stateId
 
-Route maps may store stateIds with or without the `#` prefix; both forms
-are tried automatically.
+StateId lookups try both the `"#stateId"` and bare `"stateId"` forms
+automatically (via `lookupPathByStateId`), so custom route maps keyed on
+only one form still resolve.
 
 #### Parameters
 
@@ -335,7 +333,7 @@ Concrete URL path, or `null` if navigation should be skipped
 protected sanitizePath(pathname): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:466](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L466)
+Defined in: [play-router/src/router-bridge-base.ts:513](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L513)
 
 Sanitize and validate a raw URL pathname received from the router.
 
@@ -373,7 +371,7 @@ Sanitized pathname, or `null` if the path is invalid / too long.
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [play-router/src/router-bridge-base.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L347)
 
 Sync actor state when router location changes.
 
@@ -413,17 +411,22 @@ sends no spurious event.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:289](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L289)
+Defined in: [play-router/src/router-bridge-base.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L302)
 
 Sync router location when actor route signal changes.
 
-Calls navigateRouter() for framework-specific navigation.
+Resolves the actor route to a concrete URL path and calls navigateRouter()
+for framework-specific navigation. When the route cannot be resolved
+(unknown stateId, parameterized pattern with no concrete values) the push
+is skipped entirely — `navigateRouter` is never called with a raw stateId
+or pattern.
 
 Echo suppression — preventing the router's own callback from re-driving the
-actor — is handled entirely by `lastSyncedPath`: it is set to `route` before
-`navigateRouter()` is called, so any `syncActorFromRouter` invocation for the
-same path short-circuits at the `sanitized === lastSyncedPath` check and sends
-no event regardless of whether the callback fires synchronously or asynchronously.
+actor — is handled entirely by `lastSyncedPath`: it is set to the resolved
+path before `navigateRouter()` is called, so any `syncActorFromRouter`
+invocation for the same path short-circuits at the
+`sanitized === lastSyncedPath` check and sends no event regardless of
+whether the callback fires synchronously or asynchronously.
 
 `isProcessingNavigation` is NOT set here — it is only used inside
 `syncActorFromRouter` to guard against re-entrant guard-redirect loops.
@@ -450,7 +453,7 @@ no event regardless of whether the callback fires synchronously or asynchronousl
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L161)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L178)
 
 Stop watching for router location changes.
 
@@ -472,7 +475,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-vue-router/src/vue-router-bridge.ts#L111)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-vue-router/src/vue-router-bridge.ts#L152)
 
 Subscribe to Vue Router changes using `watch` from `@vue/reactivity`.
 
@@ -481,8 +484,16 @@ updated once per navigation, only when the route actually changes. This fires wi
 exactly-once semantics — unlike `afterEach`, it does not fire for actor→router
 programmatic pushes that land on the same URL, eliminating the GAP-12 double-fire.
 
-Uses Vue's native `to.params` / `to.query` for accurate param extraction
-instead of URLPattern-based re-parsing.
+The callback delegates to the base class's `syncActorFromRouter`, which
+provides path sanitization, echo suppression, re-entrancy guarding, AND the
+unmatched-path contract: navigating to a path with no matching route pushes
+the actor's current route back to the router so URL and actor state never
+desync. Vue-native pre-parsed params/query are still used — params via the
+`extractParams` override, query via `searchFromQuery(to.query)`.
+
+`RouterSyncError` from the base sync is re-thrown as [VueRouterSendError](#)
+to preserve this package's error surface; other errors (e.g.
+`URLPatternUnavailableError`) propagate unchanged.
 
 `watch` is imported from `@vue/reactivity` (not `vue`/`@vue/runtime-core`) so
 that errors thrown from the callback propagate through the reactivity scheduler's

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

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

@@ -2,11 +2,11 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L297)
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L297)
 
 Full actor shape used by `PlayRouterProvider` components across all framework
-adapters (`play-solid-router`, `play-tanstack-solid-router`, `play-vue-router`,
-`play-tanstack-react-router`, `play-react-router`).
+adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
+adapters built on the shared framework-router bridge bases).
 
 Extends `RoutableActor` with `currentView` — the provider renders the current
 view spec in addition to synchronizing routes, so it needs both capabilities.
@@ -37,9 +37,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 
 | Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                                                                                                 | Defined in                                                                                                                              |
 | ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L261) |
-| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L299) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L267) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L261) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L299) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L267) |
 
 ## Methods
 
@@ -49,7 +49,7 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L269)
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L269)
 
 Send a route navigation event to the actor.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L225)
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L225)
 
 Enhanced routing event with parameter and query support
 
@@ -22,22 +22,32 @@ via `play.route` events, Actor decides via state machine transitions.
 
 ## Param
 
+**type**
+
 Event discriminator (always "play.route")
 
 ## Param
 
+**to**
+
 Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
+**params**
+
 Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
+**query**
+
 Query parameters only (isolated from path params)
 
 ## Param
 
+**match**
+
 Full URLPattern match result for debugging/observability (optional)
 
 ## Examples
@@ -112,8 +122,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:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L230) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L228) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L229) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L227) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L226) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ Options for `createRouteMap` and `createRouteMapFromTree`.
 
 | Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
 | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L20) |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L51)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | 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.52/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.52/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L53) |

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

@@ -2,11 +2,11 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L341)
 
 RouterBridge interface for runtime infrastructure adapters
 
-Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
 the Actor. Infrastructure "bridges" to the Actor by observing its signals and
 managing its own lifecycle accordingly.
 
@@ -16,13 +16,13 @@ a unidirectional observation pattern. Infrastructure connects to observe Actor s
 
 ## Example
 
-TanStack Router bridge implementation
+Framework router bridge implementation
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
 
-class TanStackRouterBridge implements RouterBridge {
+class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L357)
 
 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:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

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

@@ -6,7 +6,7 @@
 type RoutableActor = PlayActor;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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.54/packages/play-vue-router/src/play-router-provider.ts#L10)
 
 ## Deprecated
 

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

@@ -19,7 +19,7 @@ const PlayRouterProvider: DefineComponent<
 		};
 		router: {
 			required: true;
-			type: PropType<Router>;
+			type: PropType<RouterClassic>;
 		};
 	}>,
 	() => VNodeChild,
@@ -47,7 +47,7 @@ const PlayRouterProvider: DefineComponent<
 			};
 			router: {
 				required: true;
-				type: PropType<Router>;
+				type: PropType<RouterClassic>;
 			};
 		}>,
 		{}
@@ -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.52/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.54/packages/play-vue-router/src/play-router-provider.ts#L19)
 
 PlayRouterProvider — Vue convenience wrapper for VueRouterBridge.