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

package/{api → examples}/@xmachines/play-sveltekit-router-demo/README.md

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-sveltekit-router/examples/demo
+npm run dev -w @xmachines/play-sveltekit-router-demo
 ```
 
 Then open `http://localhost:5173`.
@@ -105,27 +105,26 @@ Watcher notifications are one-shot. Cleanup is explicit: `cleanupDemo()` calls `
 
 These commands are defined in `package.json`:
 
-| Command                                                                | Description                      |
-| ---------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-sveltekit-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-sveltekit-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-sveltekit-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-sveltekit-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-sveltekit-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                         | Description                      |
+| --------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-sveltekit-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-sveltekit-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-sveltekit-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-sveltekit-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-sveltekit-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-sveltekit-router/examples/demo
-npm run test:browser -w packages/play-sveltekit-router/examples/demo
+npm run test -w @xmachines/play-sveltekit-router-demo
+npm run test:browser -w @xmachines/play-sveltekit-router-demo
 ```
 
 Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
 
 ## Learn More
 
-- [SvelteKit Router package README](../play-sveltekit-router/README.md)
-- [Svelte package README](../play-svelte/README.md)
-- [Svelte SPA Router demo README](../play-svelte-spa-router-demo/README.md)
+- [SvelteKit Router package README](../../README.md)
+- [Svelte package README](../../../play-svelte/README.md)

package/{api → examples}/@xmachines/play-tanstack-react-router-demo/README.md

@@ -17,7 +17,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-tanstack-react-router/examples/demo
+npm run dev -w @xmachines/play-tanstack-react-router-demo
 ```
 
 Then open `http://localhost:3000`.
@@ -104,27 +104,27 @@ The TanStack React adapter wraps TanStack's `router.navigate({ to })` and `route
 
 These commands are defined in `package.json`:
 
-| Command                                                                     | Description                      |
-| --------------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-tanstack-react-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-tanstack-react-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-tanstack-react-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-tanstack-react-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-tanstack-react-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                              | Description                      |
+| -------------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-tanstack-react-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-tanstack-react-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-tanstack-react-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-tanstack-react-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-tanstack-react-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-tanstack-react-router/examples/demo
-npm run test:browser -w packages/play-tanstack-react-router/examples/demo
+npm run test -w @xmachines/play-tanstack-react-router-demo
+npm run test:browser -w @xmachines/play-tanstack-react-router-demo
 ```
 
 Expected result: invariant test suite and the browser shared-demo suite both pass, confirming actor authority, route sync, and guard-driven redirection.
 
 ## Learn More
 
-- [TanStack React Router package README](../play-tanstack-react-router/README.md)
-- [React package README](../play-react/README.md)
-- [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)
+- [TanStack React Router package README](../../README.md)
+- [React package README](../../../play-react/README.md)
+- [TanStack Solid Router demo README](../../../play-tanstack-solid-router/examples/demo/README.md)

package/{api → examples}/@xmachines/play-tanstack-solid-router-demo/README.md

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-tanstack-solid-router/examples/demo
+npm run dev -w @xmachines/play-tanstack-solid-router-demo
 ```
 
 Then open `http://localhost:3005`.
@@ -98,28 +98,28 @@ The TanStack Solid adapter wraps TanStack's `router.navigate({ to })` and `route
 
 These commands are defined in `package.json`:
 
-| Command                                                                     | Description                      |
-| --------------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-tanstack-solid-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-tanstack-solid-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-tanstack-solid-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-tanstack-solid-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-tanstack-solid-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                              | Description                      |
+| -------------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-tanstack-solid-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-tanstack-solid-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-tanstack-solid-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-tanstack-solid-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-tanstack-solid-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-tanstack-solid-router/examples/demo
-npm run test:browser -w packages/play-tanstack-solid-router/examples/demo
+npm run test -w @xmachines/play-tanstack-solid-router-demo
+npm run test:browser -w @xmachines/play-tanstack-solid-router-demo
 ```
 
 Expected result: library-pattern invariant tests and the browser shared-demo suite both pass, confirming actor-driven route and view updates including protected route redirection.
 
 ## Learn More
 
-- [TanStack Solid Router package README](../play-tanstack-solid-router/README.md)
-- [SolidJS package README](../play-solid/README.md)
-- [Solid Router demo README](../play-solid-router-demo/README.md)
-- [TanStack React Router demo README](../play-tanstack-react-router-demo/README.md)
+- [TanStack Solid Router package README](../../README.md)
+- [SolidJS package README](../../../play-solid/README.md)
+- [Solid Router demo README](../../../play-solid-router/examples/demo/README.md)
+- [TanStack React Router demo README](../../../play-tanstack-react-router/examples/demo/README.md)

package/examples/@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](../../README.md)
+- [Vue Router demo README](../../../play-vue-router/examples/demo/README.md)

package/{api → examples}/@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,26 +115,26 @@ 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.
 
 ## Learn More
 
-- [Vue Router package README](../play-vue-router/README.md)
-- [Vue package README](../play-vue/README.md)
+- [Vue Router package README](../../README.md)
+- [Vue package README](../../../play-vue/README.md)

package/examples/README.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # XMachines Examples
 
 Practical code examples demonstrating current XMachines Play patterns and use cases.
@@ -27,28 +25,38 @@ Complete working implementations of actor-authoritative routing with all archite
 
 ## Complete Demo Applications
 
-### Framework-Agnostic Baseline
-
-- **[Vanilla JavaScript Router Demo](../api/@xmachines/play-dom-router-demo/README.md)** — Pure browser integration: `connectRouter` + `connectRenderer` + DOM components. The lowest-level reference implementation.
+### Renderer Demos
 
-### React Integrations
+<!-- typedoc:renderer-demos:start -->
 
-- **[TanStack React Router Demo](../api/@xmachines/play-tanstack-react-router-demo/README.md)** — Canonical reference implementation with all 5 invariants, comprehensive routing, authentication guards, and browser tests.
-- **[React Router Demo](../api/@xmachines/play-react-router-demo/README.md)** — React Router v7 data-router integration using a catch-all route and `ReactRouterBridge`.
+- [@xmachines/play-dom-demo](@xmachines/play-dom-demo/README.md)
+- [@xmachines/play-react-demo](@xmachines/play-react-demo/README.md)
+- [@xmachines/play-solid-demo](@xmachines/play-solid-demo/README.md)
+- [@xmachines/play-svelte-demo](@xmachines/play-svelte-demo/README.md)
+- [@xmachines/play-vue-demo](@xmachines/play-vue-demo/README.md)
+  <!-- typedoc:renderer-demos:end -->
 
-### Vue Integration
+### Router Demos
 
-- **[Vue Router Demo](../api/@xmachines/play-vue-router-demo/README.md)** — Vue Composition API integration with `PlayRouterProvider` and the shared `authMachine`.
+<!-- typedoc:router-demos:start -->
 
-### Svelte Integrations
+- [@xmachines/play-dom-router-demo](@xmachines/play-dom-router-demo/README.md)
+- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
+- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-svelte-spa-router-demo](@xmachines/play-svelte-spa-router-demo/README.md)
+- [@xmachines/play-sveltekit-router-demo](@xmachines/play-sveltekit-router-demo/README.md)
+- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
+- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
+  <!-- typedoc:router-demos:end -->
 
-- **[SvelteKit Router Demo](../api/@xmachines/play-sveltekit-router-demo/README.md)** — SvelteKit-style routing with `connectRouter` + `afterNavigate`/`goto` and Svelte 5 runes.
-- **[Svelte SPA Router Demo](../api/@xmachines/play-svelte-spa-router-demo/README.md)** — Hash-based SPA routing using `svelte-spa-router` with the same actor-authoritative flow.
+### Shared Fixtures
 
-### SolidJS Integrations
+<!-- typedoc:shared-fixtures:start -->
 
-- **[Solid Router Demo](../api/@xmachines/play-solid-router-demo/README.md)** — `@solidjs/router` integration with `PlayRouterProvider` and SolidJS fine-grained reactivity.
-- **[TanStack Solid Router Demo](../api/@xmachines/play-tanstack-solid-router-demo/README.md)** — TanStack Router for Solid with dynamic route creation from the machine's route tree.
+- [@xmachines/play-actor-shared](@xmachines/play-actor-shared/README.md)
+- [@xmachines/play-router-shared](@xmachines/play-router-shared/README.md)
+  <!-- typedoc:shared-fixtures:end -->
 
 ## Running the Code Examples
 
@@ -62,25 +70,45 @@ npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
 npx tsx my-example.ts
 ```
 
-To run a complete demo application, `cd` into the relevant package and start its dev server:
+To run a complete demo application, use the workspace package name:
 
 ```bash
-# Example: vanilla DOM router demo
-cd packages/play-dom-router/examples/demo
-npm install
-npm run dev
+npm run dev -w @xmachines/play-dom-router-demo
 ```
 
 ## Key Packages
 
+### Core
+
 | Package                   | Role                                                        |
 | ------------------------- | ----------------------------------------------------------- |
 | `@xmachines/play-xstate`  | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
 | `@xmachines/play-actor`   | `AbstractActor`, `typedSpec`                                |
 | `@xmachines/play-signals` | TC39 Signals polyfill, `watchSignal`                        |
 | `@xmachines/play-router`  | `extractMachineRoutes`, `getRoutableRoutes`                 |
-| `@xmachines/play-dom`     | `connectRenderer`, `defineRegistry` (vanilla)               |
-| `@xmachines/play-react`   | `PlayRenderer`, `defineRegistry` (React)                    |
+
+### Renderers
+
+| Package                  | Role                                |
+| ------------------------ | ----------------------------------- |
+| `@xmachines/play-dom`    | `connectRenderer`, `defineRegistry` |
+| `@xmachines/play-react`  | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-solid`  | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-svelte` | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-vue`    | `PlayRenderer`, `defineRegistry`    |
+
+### Router Adapters
+
+| Package                                 | Router                  |
+| --------------------------------------- | ----------------------- |
+| `@xmachines/play-dom-router`            | Vanilla browser history |
+| `@xmachines/play-react-router`          | React Router v7         |
+| `@xmachines/play-tanstack-react-router` | TanStack Router (React) |
+| `@xmachines/play-solid-router`          | SolidJS Router          |
+| `@xmachines/play-tanstack-solid-router` | TanStack Router (Solid) |
+| `@xmachines/play-vue-router`            | Vue Router              |
+| `@xmachines/play-svelte-spa-router`     | svelte-spa-router       |
+| `@xmachines/play-sveltekit-router`      | SvelteKit               |
 
 ## Related Documentation
 
@@ -88,7 +116,3 @@ npm run dev
 - **[Installation Guide](../guides/installation.md)** — Package installation and TypeScript setup
 - **[API Reference](../api/README.md)** — Generated API docs for all public packages
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification
-
----
-
-**Contributing Examples:** Have a useful example to share? See the repository contribution guidelines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.27",
+  "version": "1.0.0-beta.29",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -45,14 +45,16 @@
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "typedoc": "typedoc"
+    "typedoc": "typedoc",
+    "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.27",
+    "@xmachines/shared": "1.0.0-beta.29",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.57.0",
     "typedoc": "^0.28.18",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.11.0"
+    "typedoc-plugin-markdown": "^4.11.0",
+    "vitest": "^4.1.2"
   }
 }