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

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

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

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

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

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

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

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

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

@@ -2,12 +2,12 @@
 
 # Vue Router Demo
 
-Vue Router integration demonstrating Play Architecture with Vue Composition API.
+Vue Router integration demo for the XMachines Play architecture using Vue Composition API.
 
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
-- `PlayVueRouterProvider` renderer-based integration with Vue Router
+- `PlayRouterProvider` renderer-based integration with Vue Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - Vue Composition API mapping to TC39 Signals lifecycle
 - Non-browser invariant tests plus browser E2E coverage
@@ -21,22 +21,22 @@ npm install
 npm run dev -w packages/play-vue-router/examples/demo
 ```
 
-Visit `http://localhost:5173`.
+Then open `http://localhost:3001`.
 
 ## Step-by-Step Code Flow
 
 Use this order to understand how the demo is wired:
 
-1. `src/main.ts` creates the actor via `definePlayer({ machine: authMachine, catalog })`.
-2. `src/router.ts` installs one catch-all route; `PlayRenderer` selects the actual view from actor state.
-3. `src/App.vue` uses `PlayVueRouterProvider` + `createRouteMap(authMachine)` with a renderer function to connect router navigation and actor routing events.
-4. Provider waits for `router.isReady()` so direct URL loads are handled correctly.
-5. `src/Shell.vue` renders actor-projected state (`PlayRenderer`) and sends events back to the actor.
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, creates the Vue app, provides the actor, installs Vue Router, and mounts.
+2. `src/router.ts` installs a single catch-all route; `PlayRenderer` selects the actual view from actor state.
+3. `src/App.vue` calls `createRouteMap(authMachine)` and renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` renderer function.
+4. The renderer function creates the shared `Shell` component with actor, router, and registry as props.
+5. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
+const createPlayer = definePlayer({ machine: authMachine });
 const actor = createPlayer();
 actor.start();
 
@@ -51,13 +51,24 @@ app.mount("#app");
 export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }];
 ```
 
-```ts
-// src/App.vue (renderer shape)
+```vue
+<!-- src/App.vue (shape) -->
+<script setup lang="ts">
+const actor = inject<AuthActor>("actor")!;
+const routeMap = createRouteMap(authMachine);
+
 const renderShell = (currentActor, currentRouter) =>
-	h(Shell, {
-		actor: currentActor,
-		router: currentRouter,
-	});
+	h(SharedShell, { actor: currentActor, router: currentRouter, registry });
+</script>
+
+<template>
+	<PlayRouterProvider
+		:actor="actor"
+		:route-map="routeMap"
+		:router="router"
+		:renderer="renderShell"
+	/>
+</template>
 ```
 
 ```vue
@@ -70,26 +81,23 @@ const login = () => actor.send({ type: "auth.login", username: "demo" });
 
 ## Key Files
 
-- `src/main.ts` - actor creation/start and app mount
+- `src/main.ts` - actor creation/start and Vue app mount with actor injection
 - `src/router.ts` - single catch-all route record
-- `src/App.vue` - provider wiring and renderer composition
-- `src/Shell.vue` - actor-driven demo shell with nav, renderer, and debug panel
-- `src/components/` - route and page view components
-- `test/browser/startup.browser.test.ts` - startup check for home + login link rendering
-- `test/browser/auth-flow.browser.test.ts` - login -> dashboard -> profile -> logout browser flow
+- `src/App.vue` - `createRouteMap`, `PlayRouterProvider` wiring, and renderer composition
 - `test/reactivity.test.ts` - reactive integration assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
 
 ## State Machine & Architecture Details
 
 The demo utilizes XMachines architectural invariants:
 
-1. **Actor Authority:** When a user navigates to a protected route via a link, Vue Router updates the location. The `PlayVueRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions.
+1. **Actor Authority:** When a user navigates to a protected route via a link, Vue Router updates the location. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions.
 2. **Passive Infrastructure:** The router does not execute Vue route guards for business logic. The actor dictates whether navigation is permitted. The Vue application only renders the state.
 3. **Signal-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when signals update, without polluting the Vue component tree with reactive refs that hold business state.
 
 ## Watcher Lifecycle and Cleanup Contract
 
-This demo uses the canonical watcher lifecycle:
+This demo follows the canonical watcher lifecycle:
 
 1. `notify`
 2. `queueMicrotask`
@@ -97,7 +105,7 @@ This demo uses the canonical watcher lifecycle:
 4. Read actor signals and sync Vue-local render state
 5. Re-arm with `watch()`/`watch(...signals)`
 
-Notifications are one-shot, so re-arm is required. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayVueRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
+Notifications are one-shot, so re-arm is required. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
 
 ## Adapter Boundaries
 
@@ -105,29 +113,28 @@ Vue Router integration remains passive infrastructure. `RouterBridgeBase` owns s
 
 ## Available Scripts
 
-```bash
-npm run dev           # Start Vite dev server (default: http://localhost:5173)
-npm run build         # Build production assets
-npm run preview       # Preview production build locally
-npm run test          # Run unit/integration tests via Vitest
-npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
-```
+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 |
 
 ## Verification
 
-Use these checks from this directory:
+Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test
-npm run test:browser
+npm run test -w packages/play-vue-router/examples/demo
+npm run test:browser -w packages/play-vue-router/examples/demo
 ```
 
-Manual sanity check:
-
-1. Start with `npm run dev`.
-2. Open `http://localhost:5173`.
-3. Confirm login/logout transitions update both view and URL, and that accessing protected routes while logged out redirects properly.
+Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
 
 ## Learn More
 
-- **[Vue Router Adapter README](../play-vue-router/README.md)** - Package-level API and bridge docs
+- [Vue Router package README](../play-vue-router/README.md)
+- [Vue package README](../play-vue/README.md)

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

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