@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -1,309 +1,95 @@
-[Documentation](../../README.md) / @xmachines/play-vue-router
+[API](../../README.md) / @xmachines/play-vue-router
 
 # @xmachines/play-vue-router
 
-**Vue Router 4.x adapter for XMachines Universal Player Architecture**
+Vue Router 4.x adapter for XMachines Universal Player Architecture. Bidirectional sync between Vue Router and XMachines state machines using Vue's reactive primitives.
 
-Bidirectional sync between Vue Router and XMachines state machines with Composition API integration.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-vue-router)
 
-## Overview
-
-`@xmachines/play-vue-router` enables Vue.js applications to use XMachines state machines as the source of truth for routing logic. Your state machine controls navigation through Vue Router's reactive primitives.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
-
-- **Actor Authority (INV-01):** State machine validates navigation, router reflects decisions
-- **Passive Infrastructure (INV-04):** Router observes `actor.currentRoute` signal
-- **Signal-Only Reactivity (INV-05):** Watcher synchronizes URL with actor state
-
-**Key Benefits:**
-
-- **Logic-driven navigation:** Business logic in state machines, not components
-- **Protected routes:** Guards live in state machine, not router config
-- **Bidirectional sync:** Actor ↔ Vue Router with circular update prevention
-- **Type-safe parameters:** Route params flow through state machine context
-- **Composition API:** Integrates with `useRouter`, `useRoute`, `onUnmounted`
-
-**Framework Compatibility:**
-
-- Vue 3.x with Composition API
-- Vue Router 4.x (`^4.0.0`)
-- Named routes pattern (recommended by Vue Router docs)
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install vue-router@^4.0.0 vue@^3.5.0 @xmachines/play-vue-router @xmachines/play-vue
+pnpm add @xmachines/play-vue-router
 ```
 
 **Peer dependencies:**
 
-- `vue-router` ^4.0.0 || ^5.0.0 — Vue Router library
 - `vue` ^3.5.0 — Vue runtime
-- `@xmachines/play-vue` — Vue renderer (`PlayRenderer`)
-- `@xmachines/play-actor` — Actor base
-- `@xmachines/play-router` — Route extraction
-- `@xmachines/play-signals` — TC39 Signals primitives
+- `@vue/reactivity` ^3.5.0 — Vue reactivity primitives
+- `vue-router` ^4.0.0 || ^5.0.0 — Vue Router library
+- `xstate` ^5.31.0 — XState v5 state machine runtime
+
+## Usage
 
-## Quick Start
+### VueRouterBridge — low-level adapter
+
+`VueRouterBridge` wires Vue Router's `currentRoute` ref to an XMachines actor's `currentRoute` signal. Both directions are active: the actor drives the URL, and the URL drives the actor.
 
 ```typescript
-import { createApp } from "vue";
 import { createRouter, createWebHistory } from "vue-router";
-import { VueRouterBridge, createRouteMap } from "@xmachines/play-vue-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
-import Home from "./views/Home.vue";
-import Profile from "./views/Profile.vue";
-
-// 1. Extract routable states from machine (single source of truth)
-const routeTree = extractMachineRoutes(authMachine);
-const routableRoutes = getRoutableRoutes(routeTree);
-const routeComponents = {
-	home: Home,
-	profile: Profile,
-} as const;
-
-// 2. Define Vue Router routes from extracted machine routes
+import { VueRouterBridge, RouteMap } from "@xmachines/play-vue-router";
+
+// 1. Define routes
 const router = createRouter({
 	history: createWebHistory(),
-	routes: routableRoutes.map((route) => ({
-		path: route.fullPath,
-		name: route.stateId.replace(/^#/, ""),
-		component: routeComponents[route.stateId.replace(/^#/, "") as keyof typeof routeComponents],
-	})),
+	routes: [
+		{ path: "/", name: "home", component: HomePage },
+		{ path: "/profile/:userId", name: "profile", component: ProfilePage },
+		{ path: "/settings/:section?", name: "settings", component: SettingsPage },
+	],
 });
 
-// 3. Compute route mapping from machine routes
-const routeMap = createRouteMap(authMachine);
+// 2. Create a bidirectional state ID ↔ path mapping
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
 
-// 4. Create actor with state machine
-const createPlayer = definePlayer({
-	machine: authMachine,
-	catalog: componentCatalog,
-});
-const actor = createPlayer();
-actor.start();
-
-// 5. Create bridge to sync actor and router
+// 3. Start the bridge after the router is ready
+await router.isReady();
 const bridge = new VueRouterBridge(router, actor, routeMap);
-
-// 6. Connect bridge (required)
 bridge.connect();
 
-// 7. Create Vue app
-const app = createApp(App);
-app.use(router);
-app.mount("#app");
-
-// 8. Later, when tearing down your app/integration:
-// bridge.disconnect();
-```
-
-## API Reference
-
-### `VueRouterBridge`
-
-Router adapter implementing the `RouterBridge` protocol for Vue Router 4.x.
-
-**Type Signature:**
-
-```typescript
-class VueRouterBridge {
-	constructor(router: Router, actor: AbstractActor<any>, routeMap: RouteMap);
-	connect(): void;
-	disconnect(): void;
-	dispose(): void;
-}
-```
-
-**Constructor Parameters:**
-
-- `router` - Vue Router instance from `createRouter()`
-- `actor` - XMachines actor instance (from `definePlayer().actor`)
-- `routeMap` - Bidirectional state ID ↔ route name mapping
-
-**Methods:**
-
-- `connect()` - Start bidirectional synchronization.
-- `disconnect()` - Stop synchronization and unhook listeners.
-- `dispose()` - Alias of `disconnect()` for ergonomic teardown.
-
-**Internal Behavior:**
-
-- Watches `actor.currentRoute` signal via `Signal.subtle.Watcher`
-- Updates Vue Router via `router.push({ name, params })` when actor state changes
-- Listens to router navigation via `router.afterEach()` hook
-- Sends `play.route` events to actor when user navigates
-- Prevents circular updates with multi-layer guards
-
-### `RouteMap`
-
-Bidirectional mapping between XMachines state IDs and Vue Router route names.
-
-**Type Signature:**
-
-```typescript
-interface RouteMapping {
-	stateId: string;
-	routeName: string;
-	pattern?: string;
-}
-
-class RouteMap extends VueBaseRouteMap {
-	// Inherits all VueBaseRouteMap methods — no additional API
-}
-```
-
-**Constructor Parameters:**
-
-- `mappings` - Array of mapping objects with:
-    - `stateId` - State machine state ID (e.g., `'#profile'`)
-    - `routeName` - Vue Router route name (e.g., `'profile'`)
-    - `pattern` - Optional path pattern for URL resolution (e.g., `'/profile/:userId'`)
-
-**Methods (inherited from `VueBaseRouteMap`):**
-
-- `getRouteName(stateId)` — Find route name from state ID
-- `getStateId(routeName)` — Find state ID from route name
-- `getPattern(stateId)` — Get URL pattern for state (optional metadata)
-- `getStateIdByPath(path)` — Resolve a URL path to a state ID (from `BaseRouteMap`)
-- `getPathByStateId(stateId)` — Get the URL path pattern for a state ID (from `BaseRouteMap`)
-
-### `VueBaseRouteMap`
-
-Intermediate base class for Vue Router adapters. Extends `BaseRouteMap` (bucket-indexed O(k) pattern matching + QuickLRU cache) and adds Vue-specific named-route lookup.
-
-Exported for consumers who need to extend or test the Vue routing layer directly. Most consumers use `RouteMap` instead.
-
-```typescript
-class VueBaseRouteMap extends BaseRouteMap {
-	constructor(mappings: RouteMapping[]);
-	getRouteName(stateId: string): string | undefined;
-	getStateId(routeName: string): string | undefined;
-	getPattern(stateId: string): string | undefined;
-}
-```
-
-## Examples
-
-### Basic Usage: Simple 2-3 Route Setup
-
-```typescript
-// State machine with 3 states
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const appMachine = setup({
-	types: {
-		events: {} as PlayRouteEvent,
-	},
-}).createMachine({
-	id: "app",
-	initial: "home",
-	states: {
-		home: {
-			meta: { route: "/", view: { component: "Home" } },
-		},
-		about: {
-			meta: { route: "/about", view: { component: "About" } },
-		},
-		contact: {
-			meta: { route: "/contact", view: { component: "Contact" } },
-		},
-	},
-});
-
-const componentCatalog = defineCatalog({
-	Home,
-	About,
-	Contact,
-});
-
-const player = definePlayer({ machine: appMachine, catalog: componentCatalog });
-
-// Vue Router configuration
-const routeTree = extractMachineRoutes(appMachine);
-const routableRoutes = getRoutableRoutes(routeTree);
-const routeComponents = {
-	home: Home,
-	about: About,
-	contact: Contact,
-} as const;
-
-const router = createRouter({
-	history: createWebHistory(),
-	routes: routableRoutes.map((route) => ({
-		path: route.fullPath,
-		name: route.stateId.replace(/^#/, ""),
-		component: routeComponents[route.stateId.replace(/^#/, "") as keyof typeof routeComponents],
-	})),
-});
-
-// Route mapping computed from machine routes
-const routeMap = createRouteMap(appMachine);
+// 4. Dispose when tearing down (e.g. onUnmounted)
+bridge.dispose();
 ```
 
-### Parameter Handling: Dynamic Routes with `:param` Syntax
+### PlayRouterProvider — Vue component wrapper
 
-```typescript
-// State machine with parameter routes
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const machineConfig = {
-	id: "app",
-	context: {},
-	states: {
-		profile: {
-			meta: {
-				route: "/profile/:userId",
-				view: { component: "Profile" },
-			},
-		},
-		settings: {
-			meta: {
-				route: "/settings/:section?",
-				view: { component: "Settings" },
-			},
-		},
-	},
-};
-
-const appMachine = setup({
-	types: {
-		context: {} as { userId?: string; section?: string },
-		events: {} as PlayRouteEvent,
-	},
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const componentCatalog = defineCatalog({
-	Profile,
-	Settings,
-});
+`PlayRouterProvider` is a convenience component that manages the bridge lifecycle automatically — it calls `bridge.connect()` after `router.isReady()` on mount and `bridge.disconnect()` on unmount.
 
-const player = definePlayer({ machine: appMachine, catalog: componentCatalog });
-
-// Router with dynamic routes
-const routeTree = extractMachineRoutes(appMachine);
-const routableRoutes = getRoutableRoutes(routeTree);
-const routeComponents = {
-	profile: Profile,
-	settings: Settings,
-} as const;
+```vue
+<script setup lang="ts">
+import { markRaw } from "vue";
+import { useRouter } from "vue-router";
+import { PlayRouterProvider, RouteMap } from "@xmachines/play-vue-router";
 
-const router = createRouter({
-	routes: routableRoutes.map((route) => ({
-		path: route.fullPath,
-		name: route.stateId.replace(/^#/, ""),
-		component: routeComponents[route.stateId.replace(/^#/, "") as keyof typeof routeComponents],
-	})),
-});
+const router = useRouter();
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+]);
+
+// markRaw prevents Vue from wrapping the actor in a reactive proxy,
+// which would break TC39 Signal receivers.
+const actor = markRaw(createActor());
+</script>
 
-// Route mapping computed from machine routes
-const routeMap = createRouteMap(appMachine);
+<template>
+	<PlayRouterProvider
+		:actor="actor"
+		:router="router"
+		:routeMap="routeMap"
+		:renderer="(actor, router) => h(AppShell, { actor, router })"
+	/>
+</template>
 ```
 
-**Usage in component:**
+### Sending route events from components
 
 ```vue
 <script setup>
@@ -321,279 +107,174 @@ function viewProfile(userId) {
 </template>
 ```
 
-### Query Parameters: Search/Filters via Query Strings
-
-```typescript
-// State machine with query param handling
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const machineConfig = {
-	context: { query: "", filters: {} },
-	states: {
-		search: {
-			meta: {
-				route: "/search",
-				view: { component: "Search" },
-			},
-		},
-	},
-};
-
-const searchMachine = setup({
-	types: {
-		context: {} as { query: string; filters: Record<string, string> },
-		events: {} as PlayRouteEvent,
-	},
-}).createMachine(formatPlayRouteTransitions(machineConfig));
+## API Reference
 
-const componentCatalog = defineCatalog({
-	Search,
-});
+### `VueRouterBridge`
 
-const player = definePlayer({ machine: searchMachine, catalog: componentCatalog });
+Implements the `RouterBridge` protocol by watching Vue Router's `currentRoute` shallowRef and the actor's `currentRoute` TC39 Signal.
 
-// Component sends query params
-function handleSearch(searchTerm, filters) {
-	actor.send({
-		type: "play.route",
-		to: "#search",
-		query: { q: searchTerm, ...filters },
-	});
+```typescript
+class VueRouterBridge {
+	constructor(vueRouter: Router, actor: RoutableActor, routeMap: RouteMap);
+	connect(): void;
+	disconnect(): void;
+	dispose(): void; // alias for disconnect()
 }
 ```
 
-**Vue Router automatically reflects query params in URL:**
+**Constructor parameters:**
 
-- `/search?q=xmachines&tag=typescript`
+| Parameter   | Type            | Description                                  |
+| ----------- | --------------- | -------------------------------------------- |
+| `vueRouter` | `Router`        | Vue Router instance from `createRouter()`    |
+| `actor`     | `RoutableActor` | XMachines actor with a `currentRoute` signal |
+| `routeMap`  | `RouteMap`      | Bidirectional state ID ↔ path mapping        |
 
-### Protected Routes: Authentication Guards
+**Methods:**
 
-```typescript
-// State machine with auth guards
-import { defineCatalog } from "@xmachines/play-catalog";
+- `connect()` — Start bidirectional synchronization. Performs an initial sync from the router's current path to the actor (cold-load / direct-URL support). Uses `watch(router.currentRoute, …)` from `@vue/reactivity` (not `@vue/runtime-core`) so watcher errors propagate directly without being swallowed by Vue's global error handler.
+- `disconnect()` — Stop all watchers and stop the Vue effect scope.
+- `dispose()` — Alias for `disconnect()`, intended for `onUnmounted(() => bridge.dispose())`.
 
-const authMachine = setup({
-	types: {
-		context: {} as { isAuthenticated: boolean },
-		events: {} as PlayRouteEvent | { type: "login" } | { type: "logout" },
-	},
-}).createMachine({
-	context: { isAuthenticated: false },
-	initial: "home",
-	states: {
-		home: {
-			meta: { route: "/", view: { component: "Home" } },
-		},
-		login: {
-			meta: { route: "/login", view: { component: "Login" } },
-			on: {
-				login: {
-					target: "dashboard",
-					actions: assign({ isAuthenticated: true }),
-				},
-			},
-		},
-		dashboard: {
-			meta: { route: "/dashboard", view: { component: "Dashboard" } },
-			always: {
-				guard: ({ context }) => !context.isAuthenticated,
-				target: "login",
-			},
+### `PlayRouterProvider`
+
+Vue component that wraps `VueRouterBridge` in component lifecycle hooks.
+
+```typescript
+import type { PlayActor } from "@xmachines/play-vue-router";
+
+defineComponent({
+	name: "PlayRouterProvider",
+	props: {
+		actor: { type: Object as PropType<PlayActor>, required: true },
+		routeMap: { type: Object as PropType<RouteMap>, required: true },
+		router: { type: Object as PropType<Router>, required: true },
+		renderer: {
+			type: Function as PropType<(actor: PlayActor, router: Router) => VNodeChild>,
+			required: true,
 		},
 	},
 });
-
-const componentCatalog = defineCatalog({
-	Home,
-	Login,
-	Dashboard,
-});
-
-const player = definePlayer({ machine: authMachine, catalog: componentCatalog });
 ```
 
-**Guard behavior:**
-
-- User navigates to `/dashboard`
-- Bridge sends `play.route` event to actor
-- Actor's `always` guard checks `isAuthenticated`
-- If `false`, actor transitions to `login` state
-- Bridge detects state change, redirects router to `/login`
-- Actor Authority principle enforced
-
-### Cleanup: Proper Disposal on Component Unmount
-
-```vue
-<script setup>
-import { onUnmounted } from "vue";
-import { VueRouterBridge } from "@xmachines/play-vue-router";
+The `actor` prop requires `PlayActor` (`AbstractActor & Routable & Viewable`) — the provider renders the current view spec in addition to synchronizing routes. The `renderer` callback receives the same concrete actor type.
 
-const router = useRouter();
-const actor = inject("actor");
-const routeMap = inject("routeMap");
+### `RouteMap` / `VueRouteMap`
 
-const bridge = new VueRouterBridge(router, actor, routeMap);
+`RouteMap` (re-exported from `@xmachines/play-router`) is the bidirectional state ID ↔ path mapping used by the bridge. `VueRouteMap` is an alias for `RouteMap` — both are identical.
 
-// CRITICAL: Cleanup watchers and guards
-onUnmounted(() => {
-	bridge.dispose();
-});
-</script>
+```typescript
+import { RouteMap, createRouteMap } from "@xmachines/play-vue-router";
+
+// Explicit construction
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+// Or derive from an XState machine
+import { createRouteMap } from "@xmachines/play-router";
+const routeMap = createRouteMap(machine);
 ```
 
-**Why cleanup matters:**
-
-- Navigation guards remain active after unmount (memory leak)
-- Watchers continue observing signals (event listeners pile up)
-- Multiple bridge instances send duplicate events
-- Tests fail with "Cannot send to stopped actor" errors
-
-## Architecture
-
-### Bidirectional Sync (Actor ↔ Router)
-
-**Actor → Router (Signal-driven):**
-
-1. Actor transitions to new state with `meta.route`
-2. `actor.currentRoute` signal updates
-3. `Signal.subtle.Watcher` detects change in microtask
-4. Bridge extracts state ID from signal
-5. Bridge looks up route name via `routeMap.getRouteName()`
-6. Bridge calls `router.push({ name, params })`
-7. Vue Router updates URL and renders component
-
-**Router → Actor (Navigation guard):**
+### Exported error classes (`@xmachines/play-vue-router/errors`)
 
-1. User clicks link or browser back button
-2. `router.afterEach()` hook fires with `to` route
-3. Bridge resolves state ID from Vue route `name` via `routeMap.getStateId(...)`
-4. Bridge extracts params from `to.params` (not `route.params` - see Pitfalls)
-5. Bridge sends `play.route` event to actor
-6. Actor validates navigation (guards, transitions)
-7. If accepted: Actor transitions, signal updates, URL stays
-8. If rejected: Actor redirects, bridge corrects URL via `router.replace()`
+All runtime errors extend `PlayError` from `@xmachines/play` and are available from the `./errors` subpath:
 
-### Circular Update Prevention
+```typescript
+import {
+	VueRouterCorrectionError,
+	VueRouterNavigationError,
+	VueRouterSendError,
+} from "@xmachines/play-vue-router/errors";
+```
 
-**Multi-layer guards prevent infinite loops:**
+| Class                      | Error code                          | When thrown                                                            |
+| -------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| `VueRouterCorrectionError` | `PLAY_VUE_ROUTER_CORRECTION_FAILED` | `router.replace()` rejected when syncing actor → router (correction)   |
+| `VueRouterNavigationError` | `PLAY_VUE_ROUTER_NAV_FAILED`        | `router.push()` rejected (navigation guard cancellation, redirect)     |
+| `VueRouterSendError`       | `PLAY_VUE_ROUTER_SEND_FAILED`       | Vue Router watcher callback fails to deliver `play.route` to the actor |
 
-1. **`lastSyncedPath` tracking:** Stores last synchronized path, skips if unchanged
-2. **`isProcessingNavigation` flag:** Set during router-initiated navigation, prevents actor→router sync
-3. **Microtask timing:** Actor validation happens asynchronously, bridge checks result after transition completes
+Each class carries a `cause` property with the original Vue Router error.
 
-**Pattern proven in the TanStack Router adapter:**
+### Exported types
 
 ```typescript
-private syncRouterFromActor(): void {
-  if (this.isProcessingNavigation) return; // Guard 1
-  const currentRoute = this.actor.currentRoute.get();
-  if (currentRoute === this.lastSyncedPath) return; // Guard 2
-  this.lastSyncedPath = currentRoute;
-  this.router.push(currentRoute);
-}
-
-private syncActorFromRouter(to: RouteLocation): void {
-  this.isProcessingNavigation = true; // Guard 3
-  this.actor.send({ type: 'play.route', to: stateId, params });
-  queueMicrotask(() => {
-    this.isProcessingNavigation = false; // Guard 4
-  });
-}
+// Bridge-level (routing only) — from @xmachines/play-router:
+export type {
+	RouteMapping,
+	PlayRouteEvent,
+	RouterBridge,
+	RoutableActor,
+} from "@xmachines/play-router";
+
+// Provider-level (routing + view rendering) — PlayActor re-exported from @xmachines/play-router:
+export type { PlayActor } from "@xmachines/play-vue-router";
+// RoutableActor is also exported as a deprecated alias for PlayActor
 ```
 
-### Relationship to Other Packages
+`PlayActor` is `AbstractActor<AnyActorLogic> & Routable & Viewable` — the shape required by `PlayRouterProvider`, which renders the current view spec in addition to synchronizing routes. Use `RoutableActor` from `@xmachines/play-router` when only routing is needed (e.g. constructing `VueRouterBridge` directly).
 
-**Package Dependencies:**
+## Architecture
 
-- `@xmachines/play` - Protocol interfaces (`PlayRouteEvent`, `RouterBridge`)
-- `@xmachines/play-actor` - Actor base class with signal protocol
-- `@xmachines/play-router` - Route extraction and tree building
-- `@xmachines/play-signals` - TC39 Signals polyfill for reactivity
-- `@xmachines/play-xstate` - XState integration via `definePlayer()`
+### Sync directions
 
-**Architecture Layers:**
+**Router → Actor** (`watch(router.currentRoute, …)`):
 
-```
-┌─────────────────────────────────────┐
-│  Vue Components (View Layer)       │
-│  - Uses inject('actor')             │
-│  - Sends play.route events          │
-└─────────────────────────────────────┘
-              ↕
-┌─────────────────────────────────────┐
-│  VueRouterBridge (Adapter)          │
-│  - Watches actor.currentRoute       │
-│  - Listens to router.afterEach      │
-└─────────────────────────────────────┘
-       ↕                    ↕
-┌─────────────┐    ┌──────────────────┐
-│ Vue Router  │    │ XMachines Actor  │
-│ (Infra)     │    │ (Business Logic) │
-└─────────────┘    └──────────────────┘
-```
+1. User navigates (link click, browser back, programmatic `router.push`).
+2. Vue's `currentRoute` shallowRef is assigned a new object.
+3. `watch` from `@vue/reactivity` fires synchronously (`scheduler: (job) => job()`).
+4. Bridge sanitizes the path, looks up the state ID in `routeMap`.
+5. Bridge sends `{ type: "play.route", to: "#stateId", params, query }` to the actor.
 
-### Vue Router Composition API Integration
+**Actor → Router** (TC39 Signal watcher):
 
-**Recommended patterns:**
+1. Actor transitions; `actor.currentRoute` signal updates to a new state ID or path.
+2. Signal watcher fires in a microtask.
+3. Bridge resolves the navigation path via `resolveNavigationPath`.
+4. Parameterized patterns without concrete params are skipped (returns `null`).
+5. Bridge calls `router.push(resolvedPath)`.
 
-- **`useRouter()`** - Get router instance for programmatic navigation (avoid in components - use actor)
-- **`useRoute()`** - Access current route params (prefer actor context for state-driven components)
-- **`onUnmounted()`** - Cleanup bridge to prevent leaks
+### Echo suppression
 
-**Named routes requirement:**
+`lastSyncedPath` is set before every `router.push()` call. When the Vue watcher subsequently fires with the same path (the router echoing the actor-initiated push), the `sanitizedPath === lastSyncedPath` check short-circuits before any event is sent.
 
-Vue Router adapter uses **named routes** (`router.push({ name: 'profile', params })`) instead of path-based navigation. This provides:
+### Vue effect scope
 
-- Type safety (TypeScript route names)
-- Cleaner param handling (object-based)
-- Better Vue Router integration (recommended by docs)
+The `watch` watcher runs inside a dedicated `effectScope()`. Calling `disconnect()` / `dispose()` calls `scope.stop()`, fully removing the watcher without leaking into the global Vue effect scope.
 
-All routes in your Vue Router config **must have a `name` property** for the bridge to work.
+## Testing
 
-### Pitfall: `to.params` vs `route.params`
+```bash
+# Run all tests for this package
+pnpm --filter @xmachines/play-vue-router test
 
-**⚠️ Common mistake:** Using global `useRoute()` in navigation guards
+# Watch mode
+pnpm --filter @xmachines/play-vue-router run test:watch
 
-```typescript
-// ❌ WRONG: route.params is stale during transition
-router.afterEach((to) => {
-	const route = useRoute(); // Returns "from" route
-	const params = route.params; // STALE
-	// ...
-});
-
-// ✅ CORRECT: to.params is fresh
-router.afterEach((to) => {
-	const params = to.params; // FRESH
-	// ...
-});
+# With coverage (80 % threshold on lines/functions/branches/statements)
+pnpm --filter @xmachines/play-vue-router run test:coverage
 ```
 
-**Why it happens:** Vue Router's global `route` object updates asynchronously during navigation. The `to` parameter in `afterEach` is the destination route with correct params.
-
-## License
-
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+Test files use Vitest with jsdom and `@vue/test-utils`. Integration tests (`test/integration.test.ts`) use real Vue Router instances with SFC fixtures.
 
 ## Classes
 
 - [RouteMap](classes/RouteMap.md)
-- [VueBaseRouteMap](classes/VueBaseRouteMap.md)
 - [VueRouterBridge](classes/VueRouterBridge.md)
 
 ## Interfaces
 
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases
 
-- [RoutableActor](type-aliases/RoutableActor.md)
+- [~~RoutableActor~~](type-aliases/RoutableActor.md)
 
 ## Variables
 
@@ -602,3 +283,9 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 ## Functions
 
 - [createRouteMap](functions/createRouteMap.md)
+
+## References
+
+### VueRouteMap
+
+Renames and re-exports [RouteMap](classes/RouteMap.md)