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

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

@@ -0,0 +1,129 @@
+[Documentation](../../README.md) / @xmachines/play-svelte-spa-router-demo
+
+# Svelte SPA Router Demo
+
+Svelte 5 + `svelte-spa-router` integration demo for the XMachines Play architecture using hash-based URL routing.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via `@xmachines/play-svelte-spa-router`
+- Shell-driven rendering via `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
+npm install
+npm run dev -w @xmachines/play-svelte-spa-router-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
+2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` synchronizes hash URL changes with the actor via `play.route` events and reflects actor-approved routes back to the hash URL.
+4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/lib/router.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 cleanupDemo(): void {
+	disconnectRouter();
+	actor.stop();
+}
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
+	import { actor, registry } from "./lib/router.js";
+</script>
+
+<Shell {actor} {registry} />
+```
+
+```svelte
+<!-- Shell.svelte — sending events (shape) -->
+<PlayRenderer
+	actor={props.actor}
+	registry={props.registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
+/>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/lib/router.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `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 hash URL 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:** `svelte-spa-router` 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: `cleanupDemo()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+
+## Adapter Boundaries
+
+`connectRouter` (from `@xmachines/play-svelte-spa-router`) is passive infrastructure. It translates hash URL changes into `play.route` events and reflects actor-approved route changes back to the URL. Business validity remains actor-owned. The shared `Shell.svelte` from `@xmachines/play-svelte-demo` is reused to avoid duplicating view components across router demos.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                          | Description                      |
+| ---------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-svelte-spa-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-svelte-spa-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-svelte-spa-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-svelte-spa-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-svelte-spa-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 @xmachines/play-svelte-spa-router-demo
+npm run test:browser -w @xmachines/play-svelte-spa-router-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
+
+## Learn More
+
+- [Svelte SPA Router package README](../../README.md)
+- [Svelte package README](../../../play-svelte/README.md)

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

@@ -0,0 +1,130 @@
+[Documentation](../../README.md) / @xmachines/play-sveltekit-router-demo
+
+# 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`
+- Shell-driven rendering via `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
+npm install
+npm run dev -w @xmachines/play-sveltekit-router-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
+2. `src/lib/router.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 `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/lib/router.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 cleanupDemo(): void {
+	disconnectRouter();
+	actor.stop();
+}
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
+	import { actor, registry } from "./lib/router.js";
+</script>
+
+<Shell {actor} {registry} />
+```
+
+```svelte
+<!-- Shell.svelte — sending events (shape) -->
+<PlayRenderer
+	actor={props.actor}
+	registry={props.registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
+/>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/lib/router.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `src/lib/navigation.ts` - SvelteKit navigation helpers for pathname observation
+- `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: `cleanupDemo()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+
+## Adapter Boundaries
+
+`connectRouter` (from `@xmachines/play-sveltekit-router`) 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.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| 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 @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](../../README.md)
+- [Svelte package README](../../../play-svelte/README.md)

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

@@ -125,6 +125,6 @@ Expected result: invariant test suite and the browser shared-demo suite both pas
 
 ## 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

@@ -119,7 +119,7 @@ Expected result: library-pattern invariant tests and the browser shared-demo sui
 
 ## 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/{api → examples}/@xmachines/play-vue-demo/README.md

@@ -141,5 +141,5 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Vue package README](../play-vue/README.md)
-- [Vue Router demo README](../play-vue-router-demo/README.md)
+- [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

@@ -136,5 +136,5 @@ Expected result: reactivity integration tests and the browser shared-demo suite
 
 ## 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,30 @@ 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.
-
-### React Integrations
-
-- **[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`.
-
-### Vue Integration
+### Renderer Demos
 
-- **[Vue Router Demo](../api/@xmachines/play-vue-router-demo/README.md)** — Vue Composition API integration with `PlayRouterProvider` and the shared `authMachine`.
+<!-- typedoc:renderer-demos:start -->
 
-### Svelte Integrations
+- [@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 -->
 
-- **[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.
+### Router Demos
 
-### SolidJS Integrations
+<!-- typedoc:router-demos: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-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 -->
 
 ## Running the Code Examples
 
@@ -62,25 +62,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 +108,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.28",
+  "version": "1.0.0-beta.30",
   "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.28",
+    "@xmachines/shared": "1.0.0-beta.30",
     "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"
   }
 }

package/api/@xmachines/play-actor-shared/README.md

@@ -1,155 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-actor-shared
-
-# play-actor Shared Demo Package
-
-Shared auth machine, catalog, and browser test fixtures consumed by all `@xmachines` renderer and router adapter demos.
-
-## What This Demonstrates
-
-- A single `authMachine` reused across every framework demo without modification
-- Framework-agnostic `authCatalog` defining typed component prop shapes and action param schemas
-- Shared browser test suite (`renderer-demo-browser-suite.ts`) importable by any renderer demo
-- State machine invariants: public routes, protected routes with auth guards, and nested sub-states
-
-## Running the Demo
-
-This is a shared fixture package — it has no standalone dev server. Run its tests from the repository root:
-
-```bash
-npm install
-npm run test -w @xmachines/play-actor-shared
-```
-
-## Step-by-Step Code Flow
-
-Use this order to understand the package structure:
-
-1. `src/auth-machine.ts` defines the `authMachine` using XState `setup()` with `formatPlayRouteTransitions` — all states include `meta.route` and `meta.view` for router and renderer integration.
-2. `src/catalog.ts` defines `authCatalog` using `defineCatalog` from `@json-render/core` — typed component prop schemas (via Zod) and action param schemas for `login`, `logout`, and all `route*` actions.
-3. `src/index.ts` re-exports `authMachine`, `authCatalog`, and all associated TypeScript types (`AuthActor`, `AuthContext`, `AuthEvents`, `AuthSnapshot`, `AuthCatalog`).
-4. `test/shared-package.test.ts` verifies machine invariants: starts at home, unauthenticated; `auth.login` transitions to `dashboard.overview`; `auth.logout` returns to `home`.
-5. `test/renderer-demo-browser-suite.ts` exports `defineNoRouterDemoBrowserSuite` — a portable browser test helper used by renderer demos that mount `<App />` and assert DOM state.
-
-```ts
-// src/auth-machine.ts (shape)
-export const authMachine = authSetup.createMachine(
-	formatPlayRouteTransitions({
-		id: "auth",
-		initial: "home",
-		on: {
-			"auth.login": { target: ".dashboard", guard: ({ context }) => !context.isAuthenticated },
-			"auth.logout": { target: ".home", guard: ({ context }) => context.isAuthenticated },
-		},
-		states: {
-			home: { meta: { route: "/", view: { component: "Home", spec: { ... } } } },
-			login: { meta: { route: "/login", view: { component: "Login", spec: { ... } } } },
-			dashboard: {
-				meta: { route: "/dashboard" },
-				initial: "overview",
-				always: { guard: ({ context }) => !context.isAuthenticated, target: "login" },
-				states: {
-					overview: { meta: { route: "overview", view: { component: "Overview", spec: { ... } } } },
-					stats: { meta: { route: "stats", view: { component: "Stats", spec: { ... } } } },
-				},
-			},
-			profile: { meta: { route: "/profile/:username", view: { component: "Profile", spec: { ... } } } },
-			settings: { meta: { route: "/settings/:section?", view: { component: "Settings", spec: { ... } } } },
-		},
-	}),
-);
-```
-
-```ts
-// src/catalog.ts (shape)
-export const authCatalog = defineCatalog(schema, {
-	components: {
-		Home: { props: z.object({ title: z.string() }) },
-		Login: { props: z.object({ title: z.string() }) },
-		Dashboard: { props: z.object({ welcome: z.boolean(), username: z.string() }) },
-		Profile: { props: z.object({ username: z.string() }) },
-		// ... more components
-	},
-	actions: {
-		login: { params: z.object({ username: z.string() }), description: "Login with username" },
-		logout: { description: "Logout and return to home" },
-		// ... more actions
-	},
-});
-```
-
-## Key Files
-
-- `src/auth-machine.ts` - XState auth machine with route metadata, guards, and nested dashboard states
-- `src/catalog.ts` - `authCatalog` with typed component and action schemas
-- `src/index.ts` - public re-exports: `authMachine`, `authCatalog`, all types
-- `src/index.css` - shared demo stylesheet imported by all renderer demos
-- `test/shared-package.test.ts` - machine invariant tests (start state, login, logout)
-- `test/renderer-demo-browser-suite.ts` - portable browser test helper for renderer demos
-
-## State Machine & Architecture Details
-
-The auth machine embodies XMachines architectural invariants:
-
-1. **Actor Authority:** All navigation uses `play.route` events — the machine evaluates each route transition against its current state and guard conditions. Framework adapters never bypass this.
-2. **Passive Infrastructure:** `meta.route` on each state is metadata for the router adapter to read, not a command. The actor drives the URL, not the other way around.
-3. **Signal-Only Reactivity:** The machine exposes `actor.currentView` and `actor.currentRoute` as TC39 Signals. Framework renderers and router adapters observe these signals — they never poll or subscribe to snapshots directly.
-
-## Watcher Lifecycle and Cleanup Contract
-
-The shared machine itself does not manage watchers — that responsibility belongs to each framework adapter. However, the machine's signal-based architecture requires adapters to follow the canonical lifecycle:
-
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project framework-local state
-5. Re-arm with `watch()`/`watch(...signals)`
-
-The `test/renderer-demo-browser-suite.ts` exports `defineNoRouterDemoBrowserSuite`, which each renderer demo uses to assert startup rendering and debug panel state without coupling to framework internals.
-
-## Adapter Boundaries
-
-This package is pure shared infrastructure: no framework imports, no DOM dependencies. It defines the contract (machine + catalog) that all framework adapters implement against. The `AuthActor` type exported here is the preferred import for components across all framework demos — it decouples component implementations from the concrete machine type.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                                | Description                      |
-| ------------------------------------------------------ | -------------------------------- |
-| `npm run test -w @xmachines/play-actor-shared`         | Run Vitest test suite            |
-| `npm run test:browser -w @xmachines/play-actor-shared` | Run browser-focused Vitest suite |
-| `npm run build -w @xmachines/play-actor-shared`        | Build TypeScript declarations    |
-
-## Verification
-
-Use these checks to validate the shared package invariants:
-
-```bash
-npm run test -w @xmachines/play-actor-shared
-```
-
-Expected result: machine exports, start state, login, and logout invariants all pass.
-
-## Learn More
-
-- [play-actor package README](../play-actor/README.md)
-
-## Interfaces
-
-- [AuthContext](interfaces/AuthContext.md)
-
-## Type Aliases
-
-- [AuthActor](type-aliases/AuthActor.md)
-- [AuthCatalog](type-aliases/AuthCatalog.md)
-- [AuthEvents](type-aliases/AuthEvents.md)
-- [AuthInput](type-aliases/AuthInput.md)
-- [AuthSnapshot](type-aliases/AuthSnapshot.md)
-- [CatalogProps](type-aliases/CatalogProps.md)
-- [InferProps](type-aliases/InferProps.md)
-
-## Variables
-
-- [authCatalog](variables/authCatalog.md)
-- [authMachine](variables/authMachine.md)
-- [authSetup](variables/authSetup.md)

package/api/@xmachines/play-actor-shared/interfaces/AuthContext.md

@@ -1,14 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthContext
-
-# Interface: AuthContext
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L27)
-
-## Properties
-
-| Property                                                | Type                           | Defined in                                                                                                                                                                                 |
-| ------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-isauthenticated"></a> `isAuthenticated` | `boolean`                      | [packages/play-actor/examples/shared/src/auth-machine.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L28) |
-| <a id="property-params"></a> `params`                   | `Record`\<`string`, `string`\> | [packages/play-actor/examples/shared/src/auth-machine.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L30) |
-| <a id="property-query"></a> `query`                     | `Record`\<`string`, `string`\> | [packages/play-actor/examples/shared/src/auth-machine.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L31) |
-| <a id="property-username"></a> `username`               | `string` \| `null`             | [packages/play-actor/examples/shared/src/auth-machine.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L29) |

package/api/@xmachines/play-actor-shared/type-aliases/AuthActor.md

@@ -1,27 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthActor
-
-# Type Alias: AuthActor
-
-```ts
-type AuthActor = PlayerActor<typeof authMachine>;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:293](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/auth-machine.ts#L293)
-
-The actor type for the auth machine.
-
-Import this in components and router adapters instead of `typeof authMachine`.
-Components declare their dependency on the capability contract (AuthContext +
-AuthEvents + routing/view signals) without coupling to the concrete machine
-implementation.
-
-## Example
-
-```ts
-import type { AuthActor } from "@xmachines/play-actor-shared";
-
-function HeaderNav({ actor }: { actor: AuthActor }) {
-	const snap = actor.getSnapshot();
-	snap.context.username; // typed as string | null — no cast needed
-}
-```

package/api/@xmachines/play-actor-shared/type-aliases/AuthCatalog.md

@@ -1,16 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthCatalog
-
-# Type Alias: AuthCatalog
-
-```ts
-type AuthCatalog = typeof authCatalog;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-actor/examples/shared/src/catalog.ts#L69)
-
-The type of the auth catalog — use as the `C` type param in `ComponentFn<AuthCatalog, "X">`,
-`ComponentContext<AuthCatalog, "X">`, and `defineRegistry(authCatalog, ...)`.
-
-Prefer this over `typeof authCatalog` at every call site: it's more readable,
-follows the PascalCase convention for types, and insulates components from
-the catalog's runtime representation.