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

package/examples/@xmachines/play-router-shared/README.md

@@ -0,0 +1,111 @@
+[Documentation](../../README.md) / @xmachines/play-router-shared
+
+# play-router Shared Demo Package
+
+Shared routing test fixtures for `@xmachines` router adapter demos — route extraction, route map resolution, and portable browser test helpers.
+
+## What This Demonstrates
+
+- `extractMachineRoutes` correctly extracts public, protected, and nested routes from `authMachine`
+- `createRouteMap` resolves concrete URLs to actor state IDs and URL params
+- `play.route` events drive the actor to the correct routed states
+- Portable `defineSharedDemoBrowserSuite` browser test helper consumed by all router demos
+
+## 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-router-shared
+```
+
+## Step-by-Step Code Flow
+
+Use this order to understand the package structure:
+
+1. `test/auth-machine-routing.test.ts` imports `authMachine` from `@xmachines/play-actor-shared` and verifies route extraction, route map resolution, param preservation, and `play.route`-driven actor transitions.
+2. `test/demo-browser-suite.ts` exports `defineSharedDemoBrowserSuite` — a comprehensive browser test helper that covers the full auth flow: home → about → contact → login → dashboard → settings → profile → logout.
+3. Router adapter demos import `defineSharedDemoBrowserSuite` (aliased as `defineRouterDemoBrowserSuite`) to mount their app and run the canonical flow against the shared test assertions.
+
+```ts
+// test/auth-machine-routing.test.ts (shape)
+const tree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMap(extractMachineRoutes(authMachine));
+
+// URL → state ID
+expect(routeMap.resolve("/").to).toBe("#home");
+expect(routeMap.resolve("/dashboard/overview").to).toBe("#dashboard-overview");
+
+// URL → params
+expect(routeMap.resolve("/profile/alice")?.params).toEqual({ username: "alice" });
+
+// play.route events drive actor state
+actor.send({ type: "play.route", to: "#about" });
+expect(snapshot.matches("about")).toBe(true);
+```
+
+```ts
+// test/demo-browser-suite.ts (shape)
+export function defineSharedDemoBrowserSuite({ mountApp }) {
+	test("shared demo flow covers public, auth, protected, and logout routes", async () => {
+		const cleanup = await mountApp();
+		// Navigates: home → about → contact → login → dashboard → settings → profile → logout
+		// Validates: URL sync, view rendering, params, back/forward, and guard redirection
+		await cleanup?.();
+	});
+}
+
+export const defineRouterDemoBrowserSuite = defineSharedDemoBrowserSuite;
+```
+
+## Key Files
+
+- `test/auth-machine-routing.test.ts` - route extraction, route map resolution, param inheritance, and `play.route`-driven actor transitions
+- `test/demo-browser-suite.ts` - `defineSharedDemoBrowserSuite` / `defineRouterDemoBrowserSuite` portable browser test helper covering the full auth flow
+- `test/env.d.ts` - Vitest browser environment type declarations
+
+## State Machine & Architecture Details
+
+The routing tests verify XMachines architectural invariants at the routing layer:
+
+1. **Actor Authority:** `play.route` events are the only mechanism for URL-driven state transitions. The test suite verifies that actors respond correctly to these events and apply guards (e.g. protected routes redirect to login when unauthenticated).
+2. **Passive Infrastructure:** `createRouteMap` is a pure lookup structure — it maps URLs to state IDs and params but executes no business logic. The actor decides whether a resolved route is reachable from its current state.
+3. **Signal-Only Reactivity:** Route resolution is synchronous and deterministic. The browser test suite validates that URL changes produce the correct `[data-page]` DOM state, confirming that the signal-driven render loop completed.
+
+## Watcher Lifecycle and Cleanup Contract
+
+The shared test fixtures exercise teardown contracts by calling `cleanup()` at the end of each test. Each router adapter demo's `mountApp` implementation must return a cleanup function that calls `disconnectRouter()` and `actor.stop()` to satisfy this contract.
+
+## Adapter Boundaries
+
+This package has no framework imports — it only depends on `@xmachines/play-actor-shared`, `@xmachines/play-router`, and `xstate`. It defines the routing contract that all concrete router adapters must satisfy. The `defineRouterDemoBrowserSuite` export is the single source of truth for browser-level routing assertions across all adapter demos.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                         | Description           |
+| ----------------------------------------------- | --------------------- |
+| `npm run test -w @xmachines/play-router-shared` | Run Vitest test suite |
+
+## Verification
+
+Use these checks to validate the shared routing invariants:
+
+```bash
+npm run test -w @xmachines/play-router-shared
+```
+
+Expected result: route extraction, URL-to-state resolution, param inheritance, and `play.route`-driven actor transition tests all pass.
+
+## Learn More
+
+- [play-router package README](../../README.md)
+- [play-actor shared README](../../../play-actor/examples/shared/README.md)
+
+## Modules
+
+- [test/auth-machine-routing.test.ts](test/auth-machine-routing.test.ts/README.md)
+- [test/demo-browser-suite.ts](test/demo-browser-suite.ts/README.md)
+- [test/env.d.ts](test/env.d.ts/README.md)

package/examples/@xmachines/play-router-shared/test/auth-machine-routing.test.ts/README.md

@@ -0,0 +1,3 @@
+[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/auth-machine-routing.test.ts
+
+# test/auth-machine-routing.test.ts

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/README.md

@@ -0,0 +1,11 @@
+[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/demo-browser-suite.ts
+
+# test/demo-browser-suite.ts
+
+## Variables
+
+- [defineRouterDemoBrowserSuite](variables/defineRouterDemoBrowserSuite.md)
+
+## Functions
+
+- [defineSharedDemoBrowserSuite](functions/defineSharedDemoBrowserSuite.md)

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/functions/defineSharedDemoBrowserSuite.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/demo-browser-suite.ts](../README.md) / defineSharedDemoBrowserSuite
+
+# Function: defineSharedDemoBrowserSuite()
+
+```ts
+function defineSharedDemoBrowserSuite(__namedParameters): void;
+```
+
+Defined in: [packages/play-router/examples/shared/test/demo-browser-suite.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/demo-browser-suite.ts#L75)
+
+## Parameters
+
+| Parameter           | Type                      |
+| ------------------- | ------------------------- |
+| `__namedParameters` | `DemoBrowserSuiteOptions` |
+
+## Returns
+
+`void`

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/variables/defineRouterDemoBrowserSuite.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/demo-browser-suite.ts](../README.md) / defineRouterDemoBrowserSuite
+
+# Variable: defineRouterDemoBrowserSuite
+
+```ts
+const defineRouterDemoBrowserSuite: (__namedParameters) => void = defineSharedDemoBrowserSuite;
+```
+
+Defined in: [packages/play-router/examples/shared/test/demo-browser-suite.ts:234](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/demo-browser-suite.ts#L234)
+
+## Parameters
+
+| Parameter           | Type                      |
+| ------------------- | ------------------------- |
+| `__namedParameters` | `DemoBrowserSuiteOptions` |
+
+## Returns
+
+`void`

package/examples/@xmachines/play-router-shared/test/env.d.ts/README.md

@@ -0,0 +1,8 @@
+[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/env.d.ts
+
+# test/env.d.ts
+
+## Interfaces
+
+- [ImportMeta](interfaces/ImportMeta.md)
+- [ImportMetaEnv](interfaces/ImportMetaEnv.md)

package/examples/@xmachines/play-router-shared/test/env.d.ts/interfaces/ImportMeta.md

@@ -0,0 +1,63 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/env.d.ts](../README.md) / ImportMeta
+
+# Interface: ImportMeta
+
+Defined in: `typescript`
+
+The type of `import.meta`.
+
+If you need to declare that a given property exists on `import.meta`,
+this type may be augmented via interface merging.
+
+## Properties
+
+| Property                                  | Modifier   | Type                                | Defined in |
+| ----------------------------------------- | ---------- | ----------------------------------- | ---------- |
+| <a id="property-dirname"></a> `dirname`   | `public`   | `string`                            | -          |
+| <a id="property-env"></a> `env`           | `readonly` | [`ImportMetaEnv`](ImportMetaEnv.md) | -          |
+| <a id="property-filename"></a> `filename` | `public`   | `string`                            | -          |
+| <a id="property-glob"></a> `glob`         | `public`   | `ImportGlobFunction`                | -          |
+| <a id="property-hot"></a> `hot?`          | `readonly` | `ViteHotContext`                    | -          |
+| <a id="property-main"></a> `main`         | `public`   | `boolean`                           | -          |
+| <a id="property-url"></a> `url`           | `public`   | `string`                            | -          |
+
+## Methods
+
+### resolve()
+
+#### Call Signature
+
+```ts
+resolve(specifier): string;
+```
+
+Defined in: `typescript`
+
+##### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `specifier` | `string` |
+
+##### Returns
+
+`string`
+
+#### Call Signature
+
+```ts
+resolve(specifier, parent?): string;
+```
+
+Defined in: `@types/node`
+
+##### Parameters
+
+| Parameter   | Type              |
+| ----------- | ----------------- |
+| `specifier` | `string`          |
+| `parent?`   | `string` \| `URL` |
+
+##### Returns
+
+`string`

package/examples/@xmachines/play-router-shared/test/env.d.ts/interfaces/ImportMetaEnv.md

@@ -0,0 +1,32 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/env.d.ts](../README.md) / ImportMetaEnv
+
+# Interface: ImportMetaEnv
+
+Defined in: `vite`
+
+Custom environment variables for the shared demo browser suite.
+
+## See
+
+packages/play-router/examples/shared/test/demo-browser-suite.ts
+
+## Extends
+
+- `Record`\<`ImportMetaEnvFallbackKey`, `any`\>
+
+## Indexable
+
+```ts
+[key: string]: any
+```
+
+## Properties
+
+| Property                                                                 | Modifier   | Type      | Description                                                                 | Defined in                                                                                                                                                                       |
+| ------------------------------------------------------------------------ | ---------- | --------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-base_url"></a> `BASE_URL`                                | `public`   | `string`  | -                                                                           | -                                                                                                                                                                                |
+| <a id="property-dev"></a> `DEV`                                          | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
+| <a id="property-mode"></a> `MODE`                                        | `public`   | `string`  | -                                                                           | -                                                                                                                                                                                |
+| <a id="property-prod"></a> `PROD`                                        | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
+| <a id="property-ssr"></a> `SSR`                                          | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
+| <a id="property-vite_enable_screenshots"></a> `VITE_ENABLE_SCREENSHOTS?` | `readonly` | `string`  | Set to any truthy string to enable screenshot capture during browser tests. | [packages/play-router/examples/shared/test/env.d.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/env.d.ts#L10) |

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

@@ -2,7 +2,7 @@
 
 # SolidJS Demo
 
-SolidJS renderer demo for `@xmachines/play-solid` — actor + `PlayRenderer` without a router.
+Solid renderer demo for `@xmachines/play-solid` — actor + `PlayRenderer` without a router.
 
 ## What This Demonstrates
 
@@ -135,8 +135,8 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [SolidJS package README](../play-solid/README.md)
-- [Solid Router demo README](../play-solid-router-demo/README.md)
+- [SolidJS package README](../../README.md)
+- [Solid Router demo README](../../../play-solid-router/examples/demo/README.md)
 
 ## Variables
 

package/{api → examples}/@xmachines/play-solid-demo/functions/App.md

@@ -6,7 +6,7 @@
 function App(): Element;
 ```
 
-Defined in: [App.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/App.tsx#L55)
+Defined in: [App.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/App.tsx#L55)
 
 ## Returns
 

package/{api → examples}/@xmachines/play-solid-demo/functions/DebugPanel.md

@@ -6,7 +6,7 @@
 function DebugPanel(props): Element;
 ```
 
-Defined in: [components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)
+Defined in: [components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)
 
 ## Parameters
 

package/{api → examples}/@xmachines/play-solid-demo/functions/HeaderNav.md

@@ -6,7 +6,7 @@
 function HeaderNav(props): Element;
 ```
 
-Defined in: [components/HeaderNav.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/HeaderNav.tsx#L5)
+Defined in: [components/HeaderNav.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/HeaderNav.tsx#L5)
 
 ## Parameters
 

package/{api → examples}/@xmachines/play-solid-demo/functions/Shell.md

@@ -6,7 +6,7 @@
 function Shell(props): Element;
 ```
 
-Defined in: [components/Shell.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Shell.tsx#L7)
+Defined in: [components/Shell.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Shell.tsx#L7)
 
 ## Parameters
 

package/{api → examples}/@xmachines/play-solid-demo/variables/About.md

@@ -6,4 +6,4 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [components/About.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/About.tsx#L4)
+Defined in: [components/About.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/About.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Contact.md

@@ -6,4 +6,4 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [components/Contact.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Contact.tsx#L4)
+Defined in: [components/Contact.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Contact.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Dashboard.md

@@ -6,4 +6,4 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [components/Dashboard.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L4)
+Defined in: [components/Dashboard.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Home.md

@@ -6,4 +6,4 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [components/Home.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Home.tsx#L4)
+Defined in: [components/Home.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Home.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Login.md

@@ -6,4 +6,4 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [components/Login.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Login.tsx#L7)
+Defined in: [components/Login.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Login.tsx#L7)

package/{api → examples}/@xmachines/play-solid-demo/variables/Navigation.md

@@ -6,4 +6,4 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [components/Navigation.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Navigation.tsx#L4)
+Defined in: [components/Navigation.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Navigation.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Overview.md

@@ -6,4 +6,4 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [components/Overview.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Overview.tsx#L4)
+Defined in: [components/Overview.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Overview.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Profile.md

@@ -6,4 +6,4 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [components/Profile.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Profile.tsx#L4)
+Defined in: [components/Profile.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Profile.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Settings.md

@@ -6,4 +6,4 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [components/Settings.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Settings.tsx#L4)
+Defined in: [components/Settings.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Settings.tsx#L4)

package/{api → examples}/@xmachines/play-solid-demo/variables/Stats.md

@@ -6,4 +6,4 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [components/Stats.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-solid/examples/demo/src/components/Stats.tsx#L4)
+Defined in: [components/Stats.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-solid/examples/demo/src/components/Stats.tsx#L4)

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

@@ -119,6 +119,6 @@ Expected result: library-pattern invariant tests and the browser shared-demo sui
 
 ## Learn More
 
-- [Solid Router package README](../play-solid-router/README.md)
-- [SolidJS package README](../play-solid/README.md)
-- [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)
+- [Solid Router package README](../../README.md)
+- [SolidJS package README](../../../play-solid/README.md)
+- [TanStack Solid Router demo README](../../../play-tanstack-solid-router/examples/demo/README.md)

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

@@ -124,4 +124,4 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Svelte package README](../play-svelte/README.md)
+- [Svelte package README](../../README.md)

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)