@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

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

@@ -1,322 +1,94 @@
 [API](../../README.md) / @xmachines/play-vue-router
 
-# @xmachines/play-vue-router
-
-**Vue Router 4.x adapter for XMachines Universal Player Architecture**
-
-Bidirectional sync between Vue Router and XMachines state machines with Composition API integration.
-
-## 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.
+<!-- generated-by: gsd-doc-writer -->
 
-Per [Play RFC](../../../rfc/play.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`
+# @xmachines/play-vue-router
 
-**Framework Compatibility:**
+Vue Router 4.x adapter for XMachines Universal Player Architecture. Bidirectional sync between Vue Router and XMachines state machines using Vue's reactive primitives.
 
-- Vue 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
+npm install @xmachines/play-vue-router
 ```
 
 **Peer dependencies:**
 
-- `vue-router` ^4.0.0 || ^5.0.0 — Vue Router library
 - `vue` ^3.5.0 — Vue runtime
-  -)
-- — Actor base
-- — Route extraction
-- — TC39 Signals primitives
+- `@vue/reactivity` ^3.5.0 — Vue reactivity primitives
+- `vue-router` ^4.0.0 || ^5.0.0 — Vue Router library
+- `xstate` ^5.30.0 — XState v5 state machine runtime
+
+## Usage
+
+### VueRouterBridge — low-level adapter
 
-## Quick Start
+`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);
-
-// 4. Create actor with state machine
-const createPlayer = definePlayer({
-	machine: authMachine,
-	catalog: componentCatalog,
-});
-const actor = createPlayer();
-actor.start();
+// 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?" },
+]);
 
-// 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. Both pathname and query string from `router.currentRoute.value.fullPath` are forwarded to the actor on first connect, so users landing on `/profile?tab=posts` have `query: { tab: "posts" }` in the initial `play.route` event.
-- `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 using Vue's native `to.params` / `to.query` for accurate extraction (no URLPattern re-parsing)
-- Applies `sanitizePathname()` to all incoming router paths before route-map lookup (defense-in-depth: rejects malformed/oversized paths)
-- 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;
-}
+// 4. Dispose when tearing down (e.g. onUnmounted)
+bridge.dispose();
 ```
 
-## Examples
-
-### Basic Usage: Simple 2-3 Route Setup
-
-```typescript
-// State machine with 3 states
-import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-vue";
-import { z } from "zod";
-
-const appCatalog = defineCatalog(schema, {
-	components: {
-		Home: { props: z.object({}) },
-		About: { props: z.object({}) },
-		Contact: { props: z.object({}) },
-	},
-});
-
-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" } },
-		},
-	},
-});
+### PlayRouterProvider — Vue component wrapper
 
-const registry = defineRegistry(appCatalog, { components: { Home, About, Contact } });
-const player = definePlayer({ machine: appMachine, catalog: appCatalog });
+`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.
 
-// 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);
-```
-
-### Parameter Handling: Dynamic Routes with `:param` Syntax
-
-```typescript
-// State machine with parameter routes
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-vue";
-import { z } from "zod";
-
-const appCatalog = defineCatalog(schema, {
-	components: {
-		Profile: { props: z.object({ userId: z.string() }) },
-		Settings: { props: z.object({ section: z.string().optional() }) },
-	},
-});
-
-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 registry = defineRegistry(appCatalog, { components: { Profile, Settings } });
-const player = definePlayer({ machine: appMachine, catalog: appCatalog });
-
-// 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>
@@ -334,150 +106,82 @@ function viewProfile(userId) {
 </template>
 ```
 
-### Query Parameters: Search/Filters via Query Strings
+## API Reference
 
-```typescript
-// State machine with query param handling
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-vue";
-import { z } from "zod";
-
-const searchCatalog = defineCatalog(schema, {
-	components: {
-		Search: { props: z.object({ query: z.string().optional() }) },
-	},
-});
+### `VueRouterBridge`
 
-const machineConfig = {
-	context: { query: "", filters: {} },
-	states: {
-		search: {
-			meta: {
-				route: "/search",
-				view: { component: "Search" },
-			},
-		},
-	},
-};
+Implements the `RouterBridge` protocol by watching Vue Router's `currentRoute` shallowRef and the actor's `currentRoute` TC39 Signal.
 
-const searchMachine = setup({
-	types: {
-		context: {} as { query: string; filters: Record<string, string> },
-		events: {} as PlayRouteEvent,
-	},
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const registry = defineRegistry(searchCatalog, { components: { Search } });
-const player = definePlayer({ machine: searchMachine, catalog: searchCatalog });
-
-// 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: AbstractActor<AnyActorLogic> & Routable,
+		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`     | `AbstractActor<AnyActorLogic> & Routable` | 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 "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-vue";
-import { z } from "zod";
-
-const authCatalog = defineCatalog(schema, {
-	components: {
-		Home: { props: z.object({}) },
-		Login: { props: z.object({ title: z.string() }) },
-		Dashboard: { props: z.object({ username: z.string() }) },
-	},
-});
+- `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
+defineComponent({
+	name: "PlayRouterProvider",
+	props: {
+		actor: { type: Object as PropType<RoutableActor>, required: true },
+		routeMap: { type: Object as PropType<RouteMap>, required: true },
+		router: { type: Object as PropType<Router>, required: true },
+		renderer: {
+			type: Function as PropType<(actor: RoutableActor, router: Router) => VNodeChild>,
+			required: true,
 		},
 	},
 });
-
-const registry = defineRegistry(authCatalog, { components: { Home, Login, Dashboard } });
-const player = definePlayer({ machine: authMachine, catalog: authCatalog });
 ```
 
-**Guard behavior:**
+The `renderer` prop is a render function that receives the actor and router and returns a `VNodeChild`.
 
-- 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
+### `RouteMap` / `VueRouteMap`
 
-### Cleanup: Proper Disposal on Component Unmount
+`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.
 
-```vue
-<script setup>
-import { onUnmounted } from "vue";
-import { VueRouterBridge } from "@xmachines/play-vue-router";
-
-const router = useRouter();
-const actor = inject("actor");
-const routeMap = inject("routeMap");
-
-const bridge = new VueRouterBridge(router, actor, routeMap);
-
-// 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:**
+### Exported error classes (`@xmachines/play-vue-router/errors`)
 
-- 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
-
-## Error Handling
-
-All runtime errors thrown by this package extend `PlayError` from and
-are exported from the `./errors` subpath:
+All runtime errors extend `PlayError` from `@xmachines/play` and are available from the `./errors` subpath:
 
 ```typescript
 import {
@@ -487,147 +191,63 @@ import {
 } from "@xmachines/play-vue-router/errors";
 ```
 
-| Class                      | Code                                | When thrown                                             |
-| -------------------------- | ----------------------------------- | ------------------------------------------------------- |
-| `VueRouterCorrectionError` | `PLAY_VUE_ROUTER_CORRECTION_FAILED` | `router.replace()` rejected when syncing actor → router |
-| `VueRouterNavigationError` | `PLAY_VUE_ROUTER_NAV_FAILED`        | `router.push()` rejected (guard cancellation, redirect) |
-| `VueRouterSendError`       | `PLAY_VUE_ROUTER_SEND_FAILED`       | `afterEach` hook fails to send `play.route` to actor    |
-
-All three classes carry a `cause` property wrapping the original Vue Router error.
-
-## 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):**
-
-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()`
+| 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 |
 
-### Circular Update Prevention
+Each class carries a `cause` property with the original Vue Router error.
 
-**Multi-layer guards prevent infinite loops:**
-
-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
-
-**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
-  });
-}
+export type { RouteMapping, PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
+export type { RoutableActor } from "./play-router-provider.js";
 ```
 
-### Relationship to Other Packages
-
-**Package Dependencies:**
-
--)
+## Architecture
 
--   - Actor base class with signal protocol
--   - Route extraction and tree building
--   - TC39 Signals polyfill for reactivity
-- **Architecture Layers:**
+### Sync directions
 
-```
-┌─────────────────────────────────────┐
-│  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) │
-└─────────────┘    └──────────────────┘
-```
+**Router → Actor** (`watch(router.currentRoute, …)`):
 
-### Vue Router Composition API Integration
+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.
 
-**Recommended patterns:**
+**Actor → Router** (TC39 Signal watcher):
 
-- **`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
+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)`.
 
-**Named routes requirement:**
+### Echo suppression
 
-Vue Router adapter uses **named routes** (`router.push({ name: 'profile', params })`) instead of path-based navigation. This provides:
+`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.
 
-- Type safety (TypeScript route names)
-- Cleaner param handling (object-based)
-- Better Vue Router integration (recommended by docs)
+### Vue effect scope
 
-All routes in your Vue Router config **must have a `name` property** for the bridge to work.
+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.
 
-### Pitfall: `to.params` vs `route.params`
+## Testing
 
-**⚠️ Common mistake:** Using global `useRoute()` in navigation guards
+```bash
+# Run all tests for this package
+npm test -w packages/play-vue-router
 
-```typescript
-// ❌ WRONG: route.params is stale during transition
-router.afterEach((to) => {
-	const route = useRoute(); // Returns "from" route
-	const params = route.params; // STALE
-	// ...
-});
+# Watch mode
+npm run test:watch -w packages/play-vue-router
 
-// ✅ CORRECT: to.params is fresh
-router.afterEach((to) => {
-	const params = to.params; // FRESH
-	// ...
-});
+# With coverage (80 % threshold on lines/functions/branches/statements)
+npm run test:coverage -w packages/play-vue-router
 ```
 
-**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.
-
-## Learn More
-
-- [Demo](../../../examples/@xmachines/play-vue-router-demo/README.md)
-- [Vue renderer](../play-vue/README.md)
-
-## 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