@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/examples/@xmachines/play-sveltekit-router-demo/README.md

@@ -0,0 +1,133 @@
+[Examples](../../README.md) / @xmachines/play-sveltekit-router-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-sveltekit-router-demo
+
+Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play architecture using browser pathname URL routing.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)
+- Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-sveltekit-router-demo run dev
+```
+
+Then open `http://localhost:3009`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
+4. `src/App.svelte` imports the singleton `actor` and `registryResult` from `src/runtime.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/runtime.ts (shape)
+const createDemoPlayer = definePlayer({ machine: authMachine });
+export const actor = createDemoPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+export const disconnectRouter = connectRouter({ actor, routeMap });
+
+export function cleanup(): void {
+	disconnectRouter();
+	actor.stop();
+}
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	import { Shell } from "@xmachines/play-svelte-demo";
+	import { actor, registryResult } from "./runtime.js";
+</script>
+
+<Shell {actor} {registryResult} />
+```
+
+```svelte
+<!-- Shell.svelte — rendering (shape) -->
+<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `src/lib/navigation.ts` - History API shim implementing SvelteKit's `$app/navigation` contract for Vite dev and production builds
+- `src/app-navigation.d.ts` - TypeScript ambient declaration for the `$app/navigation` module
+- `src/App.svelte` - minimal root component delegating to shared `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and auth route flow coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user clicks a nav link, the browser pathname changes. `connectRouter` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions to the appropriate state.
+2. **Passive Infrastructure:** The SvelteKit router adapter does not execute business logic. The actor dictates whether navigation is permitted. The Svelte application only renders the state.
+3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
+
+## 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 project Svelte-local render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)) is passive infrastructure. It translates pathname URL changes into `play.route` events and reflects actor-approved route changes back to the browser pathname. Business validity remains actor-owned. The shared `Shell.svelte` from `@xmachines/play-svelte-demo` is reused to avoid duplicating view components across router demos.
+
+The `$app/navigation` module is shimmed by `src/lib/navigation.ts` using the History API, so the demo runs outside a full SvelteKit project (plain Vite dev server and production build).
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                                | Description                                    |
+| ---------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-sveltekit-router-demo run dev`          | Start Vite dev server (http://localhost:3009/) |
+| `pnpm --filter @xmachines/play-sveltekit-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-sveltekit-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-sveltekit-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-sveltekit-router-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-sveltekit-router-demo run test
+pnpm --filter @xmachines/play-sveltekit-router-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
+
+## Learn More
+
+- [SvelteKit Router](../../../api/@xmachines/play-sveltekit-router/README.md)
+- [Svelte](../../../api/@xmachines/play-svelte/README.md)

package/examples/@xmachines/play-tanstack-react-router-demo/README.md

@@ -0,0 +1,156 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-react-router-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-tanstack-react-router-demo
+
+React + TanStack Router integration demo for the XMachines Play architecture with actor-authoritative routing.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with TanStack Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-tanstack-react-router-demo run dev
+```
+
+Then open `http://localhost:3011`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor from the shared machine and start it once per mounted app.
+3. `src/runtime.ts` exports `createPlayer` (via `definePlayer`), `routeMap` (via `createRouteMap(authMachine)`), and `createRegistryResult` which binds UI components and actor event actions.
+4. `createAppRuntime()` constructs a TanStack `createRootRoute`/`createRouter` instance, then `PlayRouterProvider` bridges it to the actor and renders `Shell` via `renderer(actor, router)`.
+5. `Shell` renders `PlayRenderer`, header/nav, and debug panel from actor state.
+6. Tests in `test/` and `test/browser/` validate invariant and runtime behavior.
+
+```tsx
+// src/App.tsx (shape)
+function createAppRuntime() {
+	const actor = createPlayer();
+	actor.start();
+
+	const registryResult = createRegistryResult(actor);
+
+	const rootRoute = createRootRoute();
+	const router = createRouter({ routeTree: rootRoute, defaultPreload: "intent" });
+
+	return { actor, router, registryResult };
+}
+
+const { actor, router, registryResult } = useMemo(createAppRuntime, []);
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(currentActor, currentRouter) => (
+			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
+		)}
+	/>
+);
+```
+
+```tsx
+// src/runtime.ts (shape)
+export const createPlayer = definePlayer({ machine: authMachine });
+export const routeMap = createRouteMap(authMachine);
+
+export function createRegistryResult(actor) {
+	return defineRegistry(authCatalog, {
+		actions: {
+			login: async (args) => actor.send({ type: "auth.login", username: args.username }),
+			logout: async () => actor.send({ type: "auth.logout" }),
+			route: async (args) => actor.send({ type: "play.route", to: args.to, ...args.params }),
+		},
+	});
+}
+```
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - actor lifecycle, provider wiring, and `Shell` rendering
+- `src/runtime.ts` - actor factory, route map creation, and registry/action binding
+- `test/actor-authority.test.ts` - actor authority and guarded navigation behavior
+- `test/passive-infra.test.ts` - passive infrastructure separation contracts
+- `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
+- `test/signal-only.test.ts` - signal-only reactivity invariant
+- `test/route-parameters.test.ts` - route parameter handling
+- `test/invalid-route-redirect.test.ts` - invalid route redirect behavior
+- `test/xstate-route-events.test.ts` - XState route event contracts
+- `test/browser/shared-demo.browser.test.tsx` - canonical browser auth flow
+- `test/browser/auth-flow.browser.test.tsx` - extended browser auth flow checks
+- `test/browser/back-forward-sync.browser.test.tsx` - URL sync and history behavior
+- `test/browser/dashboard-logout.browser.test.tsx` - logout and redirection flow
+- `test/browser/guard-rejection.browser.test.tsx` - guard-driven rejection in browser
+- `test/browser/login-flow.browser.test.tsx` - login flow browser coverage
+- `test/browser/navigation.browser.test.tsx` - navigation behavior in browser
+- `test/browser/settings-parameter.browser.test.tsx` - parameterized route in browser
+- `test/browser/invalid-route-redirect.browser.test.tsx` - invalid route redirect in browser
+- `test/browser/tanstack-integration.browser.test.tsx` - TanStack Router integration checks
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user navigates to a protected route, TanStack Router updates the URL. 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 executes state transitions.
+2. **Passive Infrastructure:** The router does not execute route loaders or guards for business logic. The actor dictates whether navigation is permitted.
+3. **Signal-Only Reactivity:** The bridge leverages React's internal mechanisms combined with TanStack's `router.subscribe` to react precisely when signals update, without relying on `useEffect` synchronization inside the application codebase.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and trigger React state updates
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: the provider automatically triggers `bridge.disconnect()` when the component tree unmounts to prevent memory leaks and zombie subscriptions.
+
+## Adapter Boundaries
+
+The TanStack React adapter wraps TanStack's `router.navigate({ to })` and `router.subscribe` methods while delegating core synchronization policy to `RouterBridgeBase`.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                                     | Description                                    |
+| --------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-tanstack-react-router-demo run dev`          | Start Vite dev server (http://localhost:3011/) |
+| `pnpm --filter @xmachines/play-tanstack-react-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-react-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-react-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-react-router-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-demo run test:browser
+```
+
+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](../../../api/@xmachines/play-tanstack-react-router/README.md)
+- [React](../../../api/@xmachines/play-react/README.md)
+- [TanStack Solid Router](../play-tanstack-solid-router-demo/README.md)

package/examples/@xmachines/play-tanstack-solid-router-demo/README.md

@@ -0,0 +1,139 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-solid-router-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-tanstack-solid-router-demo
+
+Solid + `@tanstack/solid-router` integration demo for the XMachines Play architecture with actor-authoritative routing.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with TanStack Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Object-based routing and deep location observation using TanStack's Solid primitives
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-tanstack-solid-router-demo run dev
+```
+
+Then open `http://localhost:3012`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` bootstraps the demo app and mounts `<App />` onto `#app`.
+2. `src/runtime.ts` initializes the actor, builds the registry, and creates the route map using `createRouteMap(authMachine)`.
+3. `src/App.tsx` constructs the TanStack Router route tree from machine routes and wires `PlayRouterProvider` with the actor, router, and route map from `runtime.ts`.
+4. Router infrastructure stays passive: it forwards navigation intent to the actor via the `PlayRouterProvider` and reflects actor-approved route changes back to TanStack.
+5. `Shell` (from `@xmachines/play-solid-demo`) renders actor-projected state (`PlayRenderer`) and emits actor events via the `registryResult` actions.
+6. `test/library-pattern.test.ts` plus `test/browser/` verify invariants and browser routing behavior.
+
+```tsx
+// src/main.tsx (shape)
+render(() => <App />, document.getElementById("app")!);
+```
+
+```ts
+// src/runtime.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+export const actor = createPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+const routeTree = extractMachineRoutes(authMachine);
+export const routes = getRoutableRoutes(routeTree);
+```
+
+```tsx
+// src/App.tsx (shape)
+import { actor, registryResult, routeMap, routes } from "./runtime.js";
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(currentActor, currentRouter) => (
+			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
+		)}
+	/>
+);
+```
+
+```ts
+// src/runtime.ts — actor events wired via registryResult actions
+login: async (args) => actor.send({ type: "auth.login", username: args.username }),
+logout: async () => actor.send({ type: "auth.logout" }),
+route: async (args) => actor.send({ type: "play.route", to: args.to, ...params }),
+```
+
+## Key Files
+
+- `src/runtime.ts` - actor lifecycle, registry, route map, and routable routes setup
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` wiring
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+- `test/browser/xstate-route-events.browser.test.ts` - actor route event behavior in the browser
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user clicks a link, TanStack Router updates the location object. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards and applies state transitions.
+2. **Passive Infrastructure:** The router does not execute route loaders or guards for business logic. The actor dictates whether navigation is permitted.
+3. **Signal-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to observe location changes and signal updates without polling.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and trigger state updates
+5. Re-arm with `watch()`/`watch(...signals)`
+
+In Solid, this is largely abstracted by `createEffect` within the bridge adapter. Cleanup remains explicit: the provider executes `bridge.disconnect()` on unmount (`onCleanup`) to prevent ghost subscriptions, ensuring safe component teardown and hot module replacement.
+
+## Adapter Boundaries
+
+The TanStack Solid adapter wraps TanStack's `router.navigate({ to })` and `router.subscribe` methods while delegating core synchronization policy to `RouterBridgeBase`. This keeps complex double-dispatch logic normalized across all frameworks.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                                     | Description                                    |
+| --------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-demo run dev`          | Start Vite dev server (http://localhost:3012/) |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router-demo run test
+pnpm --filter @xmachines/play-tanstack-solid-router-demo run test:browser
+```
+
+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](../../../api/@xmachines/play-tanstack-solid-router/README.md)
+- [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [Solid Router](../play-solid-router-demo/README.md)
+- [TanStack React Router](../play-tanstack-react-router-demo/README.md)

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

@@ -0,0 +1,183 @@
+[Examples](../../README.md) / @xmachines/play-vue-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-vue-demo
+
+Vue 3 renderer demo for [`@xmachines/play-vue`](../../../api/@xmachines/play-vue/README.md) — 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
+pnpm install
+pnpm --filter @xmachines/play-vue-demo run dev
+```
+
+Then open `http://localhost:3004`.
+
+## 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, declares a typed `ComponentsMap<typeof authCatalog>` for `demoViews`, and builds the `registryResult` with `defineRegistry(authCatalog, { components: demoViews, actions })` inside `computed` — action handlers use `satisfies ActionFn` for catalog-typed safety and dispatch to `actor.send()`.
+4. `<PlayUIProvider :actor="typedActor" :registryResult="registryResult"><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` SFC observes `actor` signals directly for nav visibility.
+6. `<DebugPanel :actor="typedActor" />` shows live state, auth status, and current route.
+7. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
+8. Browser tests in `test/browser/` validate startup and interaction behavior.
+
+```ts
+// src/main.ts
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer() as AuthActor;
+actor.start();
+
+const app = createApp(App);
+app.provide("actor", actor);
+app.mount("#app");
+```
+
+```vue
+<!-- src/App.vue -->
+<script setup lang="ts">
+import type { ComponentsMap } from "@xmachines/play-vue";
+import type { ActionFn } from "@xmachines/json-render-vue";
+
+const typedActor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+
+const demoViews: ComponentsMap<typeof authCatalog> = {
+	Home: HomeSFC,
+	About: AboutSFC,
+	Contact: ContactSFC,
+	Login: LoginSFC,
+	Dashboard: DashboardSFC,
+	Overview: OverviewSFC,
+	Stats: StatsSFC,
+	Profile: ProfileSFC,
+	Settings: SettingsSFC,
+	Navigation: NavigationSFC,
+	NavBar: NavBarViewSFC,
+};
+
+const registryResult = computed(() =>
+	defineRegistry(authCatalog, {
+		components: demoViews,
+		actions: {
+			login: (async (args) => {
+				typedActor.send({
+					type: "auth.login",
+					username: assertNonNullable(args, "args").username,
+				});
+			}) satisfies ActionFn<typeof authCatalog, "login">,
+			logout: async () => typedActor.send({ type: "auth.logout" }),
+			route: (async (args) => {
+				const { to, params } = assertNonNullable(args, "args");
+				typedActor.send({
+					type: "play.route",
+					to,
+					...(params != null && { params }),
+				});
+			}) satisfies ActionFn<typeof authCatalog, "route">,
+		},
+	}),
+);
+</script>
+
+<template>
+	<div class="demo-app" data-demo-shell>
+		<header class="demo-header">
+			<h1 class="demo-title">XMachines Play Vue Demo</h1>
+			<NavBar :actor="typedActor" />
+		</header>
+		<main class="demo-content" data-demo-content>
+			<PlayUIProvider :actor="typedActor" :registryResult="registryResult">
+				<PlayRenderer />
+			</PlayUIProvider>
+		</main>
+		<DebugPanel :actor="typedActor" />
+	</div>
+</template>
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation/start and Vue app mount with actor injection
+- `src/App.vue` - typed `ComponentsMap` declaration, registry construction, and `PlayUIProvider` + `PlayRenderer` composition
+- `src/catalog.ts` - `authCatalog` built via `defineCatalog` with the `@xmachines/json-render-vue` schema
+- `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
+- `src/index.ts` - re-exports all components and catalog for library-pattern testing
+- `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                                    |
+| --------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-demo run dev`          | Start Vite dev server (http://localhost:3004/) |
+| `pnpm --filter @xmachines/play-vue-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-vue-demo run test
+pnpm --filter @xmachines/play-vue-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Vue](../../../api/@xmachines/play-vue/README.md)
+- [Vue Router](../play-vue-router-demo/README.md)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+
+## Variables
+
+- [App](variables/App.md)
+- [authCatalog](variables/authCatalog.md)

package/examples/@xmachines/play-vue-demo/type-aliases/AuthCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+type AuthCatalog = typeof authCatalog;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-vue/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-vue-demo/variables/App.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / App
+
+# Variable: App
+
+```ts
+const App: DefineComponent<{}, {}, unknown>;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-vue/examples/demo/src/env.d.ts#L5)