@xmachines/docs 1.0.0-beta.27 → 1.0.0-beta.28

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

@@ -0,0 +1,145 @@
+[Documentation](../../README.md) / @xmachines/play-vue-demo
+
+# Vue Demo
+
+Vue 3 renderer demo for `@xmachines/play-vue` — actor + `PlayRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRenderer` rendering actor-projected views with a typed `defineRegistry` catalog
+- Auth machine states drive view switching via `auth.login` / `auth.logout` events only — no URL routing
+- Vue Composition API mapping to TC39 Signals lifecycle
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-vue-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts the Vue app.
+2. The actor is provided to all components via `app.provide("actor", actor)`.
+3. `src/App.vue` injects the actor and builds the component registry with `defineRegistry(authCatalog, { components, actions })`.
+4. `<PlayRenderer :actor="actor" :registry="registry" :actions="..." />` observes actor view signals and renders the active view component.
+5. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
+6. Browser tests in `test/browser/` validate startup and interaction behavior.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const app = createApp(App);
+app.provide("actor", actor);
+app.mount("#app");
+```
+
+```vue
+<!-- src/App.vue (shape) -->
+<script setup lang="ts">
+const actor = inject<AuthActor>("actor")!;
+
+const { registry } = defineRegistry(authCatalog, {
+	components: {
+		Home,
+		About,
+		Contact,
+		Login,
+		Dashboard,
+		Overview,
+		Stats,
+		Profile,
+		Settings,
+		Navigation,
+	},
+	actions: { login: async () => {}, logout: async () => {} },
+});
+</script>
+
+<template>
+	<PlayRenderer
+		:actor="actor"
+		:registry="registry"
+		:actions="{ login: 'auth.login', logout: 'auth.logout' }"
+	/>
+</template>
+```
+
+```vue
+<!-- src/components/Login.vue (shape) -->
+<script setup lang="ts">
+const actor = inject("actor")!;
+const login = () => actor.send({ type: "auth.login", username: "demo" });
+</script>
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation/start and Vue app mount with actor injection
+- `src/App.vue` - registry construction and `PlayRenderer` composition
+- `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** View components dispatch `auth.login` and `auth.logout` events to the actor. The actor evaluates guards and transitions — Vue never decides which view to render.
+2. **Passive Infrastructure:** `PlayRenderer` observes `actor.currentView` signals only. It holds no business state and makes no routing decisions.
+3. **Signal-Only Reactivity:** The bridge leverages Vue's reactivity model internally to react precisely when actor signals update, without polluting the component tree with reactive refs holding business state.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and sync Vue-local render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component unmount.
+
+## Adapter Boundaries
+
+`PlayRenderer` and `defineRegistry` stay passive infrastructure. Business validity remains actor-owned. The registry maps catalog component keys to Vue SFC implementations — the actor owns which key is active. The demo intentionally omits URL routing to isolate the renderer contract.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                            | Description                      |
+| -------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-vue-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-vue-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-vue-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-vue-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-vue-demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w @xmachines/play-vue-demo
+npm run test:browser -w @xmachines/play-vue-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Vue package README](../play-vue/README.md)
+- [Vue Router demo README](../play-vue-router-demo/README.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-vue-router/src/route-map.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/route-map.ts#L10)
+Defined in: [play-vue-router/src/route-map.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/route-map.ts#L10)
 
 Bidirectional route mapper for Vue Router.
 
@@ -20,7 +20,7 @@ Alias for [BaseRouteMap](VueBaseRouteMap.md) from `@xmachines/play-router`.
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -52,7 +52,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -87,7 +87,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -2,7 +2,7 @@
 
 # Class: VueBaseRouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -54,7 +54,7 @@ map.getPathByStateId("missing"); // null
 new VueBaseRouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -82,7 +82,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -113,7 +113,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

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:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L16)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L16)
 
 @xmachines/play-vue-router - Vue Router 4.x adapter for XMachines Play
 
@@ -23,7 +23,7 @@ new VueRouterBridge(
    routeMap): VueRouterBridge;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L21)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L21)
 
 #### Parameters
 
@@ -45,15 +45,15 @@ Defined in: [play-vue-router/src/vue-router-bridge.ts:21](https://gitlab.com/xma
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L99)   |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L87)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L86)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L88)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L100) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L102) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L101) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L90)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -63,7 +63,7 @@ Defined in: [play-vue-router/src/vue-router-bridge.ts:21](https://gitlab.com/xma
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L126)
+Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L126)
 
 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:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L209)
+Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L209)
 
 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:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L135)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L135)
 
 Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`).
 
@@ -133,7 +133,7 @@ Cleanup alias for Vue component lifecycle (`onUnmounted(() => bridge.dispose())`
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L318)
+Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L318)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -171,7 +171,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:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L355)
+Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -199,7 +199,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L115)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L115)
 
 Return the router's current pathname at connect() time.
 
@@ -235,7 +235,7 @@ bridges that have not yet implemented this hook.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L127)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L127)
 
 Return the initial URL search string for query-param forwarding on `connect()`.
 
@@ -260,7 +260,7 @@ 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:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L64)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L64)
 
 Navigate Vue Router to the given path.
 
@@ -290,7 +290,7 @@ are skipped. Navigation errors are thrown as [VueRouterNavigationError](#).
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L340)
+Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L340)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -329,7 +329,7 @@ Concrete URL path, or `null` if navigation should be skipped
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L260)
+Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -359,7 +359,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L240)
+Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -392,7 +392,7 @@ suppressed as circular echoes.
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L110)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L110)
 
 Stop watching for router location changes.
 
@@ -414,7 +414,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-vue-router/src/vue-router-bridge.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-vue-router/src/vue-router-bridge.ts#L78)
+Defined in: [play-vue-router/src/vue-router-bridge.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-vue-router/src/vue-router-bridge.ts#L78)
 
 Subscribe to Vue Router changes using `afterEach`.
 

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

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

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L223)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L228) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L226) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L227) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L225) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L224) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L224) |

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.27/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/setting
 
 | 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.27/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.27/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:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/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.28/packages/play-router/src/base-route-map.ts#L59) |

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

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

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

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

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

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

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

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-vue-router/examples/demo
+npm run dev -w @xmachines/play-vue-router-demo
 ```
 
 Then open `http://localhost:3001`.
@@ -115,21 +115,21 @@ Vue Router integration remains passive infrastructure. `RouterBridgeBase` owns s
 
 These commands are defined in `package.json`:
 
-| Command                                                          | Description                      |
-| ---------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-vue-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-vue-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-vue-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-vue-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-vue-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                   | Description                      |
+| --------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-vue-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-vue-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-vue-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-vue-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-vue-router-demo` | Run browser-focused Vitest suite |
 
 ## Verification
 
 Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test -w packages/play-vue-router/examples/demo
-npm run test:browser -w packages/play-vue-router/examples/demo
+npm run test -w @xmachines/play-vue-router-demo
+npm run test:browser -w @xmachines/play-vue-router-demo
 ```
 
 Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.