@xmachines/docs 7.0.0 → 7.2.0

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

@@ -8,8 +8,8 @@ Svelte 5 + `svelte-spa-router` integration demo for the XMachines Play architect
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
-- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md)
+- Shared auth machine (the login wall: `/`, `/login`, and the protected `/dashboard`) reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md) — a hash deep link to `#/dashboard` is bounced to `#/login` by the machine's `always` guard
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - Canonical atoms lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
@@ -33,8 +33,8 @@ 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 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`, `registryResult`, and `inspector` 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 with the **Show Inspector** button).
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the Svelte gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (header plus the debug panel with the **Show Inspector** button). There is no nav bar: the machine's own specs carry the navigation buttons.
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts fragment
@@ -60,7 +60,7 @@ export function cleanup(): void {
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	import { Shell } from "@xmachines/play-svelte-demo";
+	import { Shell } from "@xmachines/play-svelte-gallery-demo";
 	import { actor, inspector, registryResult } from "./runtime.js";
 </script>
 
@@ -69,7 +69,7 @@ export function cleanup(): void {
 
 ```svelte
 <!-- Shell.svelte — rendering (shape) -->
-<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+<PlayUIProvider {actor} {registryResult}>
 	<PlayRenderer />
 </PlayUIProvider>
 ```
@@ -78,7 +78,7 @@ export function cleanup(): void {
 
 - `src/main.ts` - Svelte app mount and HMR cleanup registration
 - `src/runtime.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
-- `src/App.svelte` - minimal root component delegating to shared `Shell.svelte`
+- `src/App.svelte` - minimal root component delegating to the gallery's `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
 
@@ -102,7 +102,7 @@ One subscription lives for the whole watch, and no caller arms a watcher again.
 
 ## Adapter Boundaries
 
-`connectRouter` (from [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md)) 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`](../play-svelte-demo/README.md) is reused to avoid duplicating view components across router demos.
+`connectRouter` (from [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md)) 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 `Shell.svelte`, the built `authCatalog`, and the five-component kit all come from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md), so no view component is duplicated across the Svelte demos.
 
 ## Available Scripts
 

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

@@ -0,0 +1,77 @@
+[Examples](../../README.md) / @xmachines/play-svelte-spa-router-donut-demo
+
+# @xmachines/play-svelte-spa-router-donut-demo
+
+Svelte 5 + `svelte-spa-router` integration demo of the shared **Donut** machine for the XMachines Play architecture, using hash-based URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared Donut machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md) — the wizard steps map to `#/`, `#/bake/mix`, `#/bake/fry`, `#/bake/decorate`, and `#/done`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a hash deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Snapshot persistence: `options.onTransition` stores `getPersistedSnapshot()` in `localStorage` and the actor resumes it on load, with a **Reset saved donut** control in the Shell header
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run dev
+```
+
+Then open `http://localhost:3074`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor through `createResumedPlayer()` (restoring a stored snapshot when one exists), builds the registry from `donutCatalog` + `demoComponents` (both imported from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md)), calls `createRouteMap(donutMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates fragment changes into `play.route` events and reflects actor-approved routes back into `window.location.hash`.
+4. `src/App.svelte` imports the singletons from `src/runtime.ts` and delegates to the gallery's shared `Shell.svelte`, passing the **Reset saved donut** button as the Shell's `nav` snippet.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the debug panel with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared Donut router browser suite.
+
+Everything in `src/runtime.ts` is a module singleton on purpose: `svelte-spa-router` holds its location in one module-level store and navigates by assigning `window.location.hash`, so exactly one bridge may own the fragment.
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor, registry, route map, and `connectRouter` wiring, plus the snapshot resume/save/reset helpers
+- `src/App.svelte` - minimal root component delegating to the gallery's `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary assertions over the source text
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Donut router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A fragment change becomes a `play.route` event. The actor evaluates its guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** `svelte-spa-router` runs no business logic. It transports the URL; the machine owns the truth.
+3. **State-Driven Reset:** An external fragment change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                       | Description                                    |
+| ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3074/) |
+| `pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run test
+pnpm --filter @xmachines/play-svelte-spa-router-donut-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared Donut router browser suite completes.
+
+## Learn More
+
+- [Svelte SPA Router adapter](../../../api/@xmachines/play-svelte-spa-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-svelte-spa-router-flight-demo
+
+# @xmachines/play-svelte-spa-router-flight-demo
+
+Svelte 5 + `svelte-spa-router` integration demo of the shared **Flight** machine for the XMachines Play architecture, using hash-based URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared Flight machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md) — the wizard steps map to `#/`, `#/dates`, `#/review`, `#/submitting`, and `#/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a hash deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run dev
+```
+
+Then open `http://localhost:3075`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `flightCatalog` + `demoComponents` (both imported from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md)), calls `createRouteMap(flightMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates fragment changes into `play.route` events and reflects actor-approved routes back into `window.location.hash`.
+4. `src/App.svelte` imports the singletons from `src/runtime.ts` and delegates to the gallery's shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the debug panel with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared Flight router browser suite.
+
+Everything in `src/runtime.ts` is a module singleton on purpose: `svelte-spa-router` holds its location in one module-level store and navigates by assigning `window.location.hash`, so exactly one bridge may own the fragment.
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor, registry, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to the gallery's `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary assertions over the source text
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A fragment change becomes a `play.route` event. The actor evaluates its guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** `svelte-spa-router` runs no business logic. It transports the URL; the machine owns the truth.
+3. **State-Driven Reset:** An external fragment change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                        | Description                                    |
+| ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3075/) |
+| `pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run test
+pnpm --filter @xmachines/play-svelte-spa-router-flight-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared Flight router browser suite completes.
+
+## Learn More
+
+- [Svelte SPA Router adapter](../../../api/@xmachines/play-svelte-spa-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-svelte-spa-router-todomvc-demo
+
+# @xmachines/play-svelte-spa-router-todomvc-demo
+
+Svelte 5 + `svelte-spa-router` integration demo of the shared **TodoMVC** machine for the XMachines Play architecture, using hash-based URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared TodoMVC machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md) — the filter states map to `#/`, `#/active`, and `#/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a hash deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3072`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `todoMvcCatalog` + `demoComponents` (both imported from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md)), calls `createRouteMap(todoMvcMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates fragment changes into `play.route` events and reflects actor-approved routes back into `window.location.hash`.
+4. `src/App.svelte` imports the singletons from `src/runtime.ts` and delegates to the gallery's shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the debug panel with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared TodoMVC router browser suite.
+
+Everything in `src/runtime.ts` is a module singleton on purpose: `svelte-spa-router` holds its location in one module-level store and navigates by assigning `window.location.hash`, so exactly one bridge may own the fragment.
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor, registry, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to the gallery's `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary assertions over the source text
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared TodoMVC router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A fragment change becomes a `play.route` event. The actor evaluates its guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** `svelte-spa-router` runs no business logic. It transports the URL; the machine owns the truth.
+3. **State-Driven Reset:** An external fragment change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                         | Description                                    |
+| ------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3072/) |
+| `pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run test
+pnpm --filter @xmachines/play-svelte-spa-router-todomvc-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared TodoMVC router browser suite completes.
+
+## Learn More
+
+- [Svelte SPA Router adapter](../../../api/@xmachines/play-svelte-spa-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-svelte-spa-router-trivia-demo
+
+# @xmachines/play-svelte-spa-router-trivia-demo
+
+Svelte 5 + `svelte-spa-router` integration demo of the shared **Trivia** machine for the XMachines Play architecture, using hash-based URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared Trivia machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md) — the game states map to `#/`, `#/trivia`, `#/win`, and `#/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a hash deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3073`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `triviaCatalog` + `demoComponents` (both imported from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md)), calls `createRouteMap(triviaMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates fragment changes into `play.route` events and reflects actor-approved routes back into `window.location.hash`.
+4. `src/App.svelte` imports the singletons from `src/runtime.ts` and delegates to the gallery's shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the debug panel with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared Trivia router browser suite.
+
+Everything in `src/runtime.ts` is a module singleton on purpose: `svelte-spa-router` holds its location in one module-level store and navigates by assigning `window.location.hash`, so exactly one bridge may own the fragment.
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor, registry, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to the gallery's `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary assertions over the source text
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A fragment change becomes a `play.route` event. The actor evaluates its guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** `svelte-spa-router` runs no business logic. It transports the URL; the machine owns the truth.
+3. **State-Driven Reset:** An external fragment change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                        | Description                                    |
+| ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3073/) |
+| `pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run test
+pnpm --filter @xmachines/play-svelte-spa-router-trivia-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared Trivia router browser suite completes.
+
+## Learn More
+
+- [Svelte SPA Router adapter](../../../api/@xmachines/play-svelte-spa-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -8,8 +8,8 @@ Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play arch
 
 ## 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)
+- Shared auth machine (the login wall: `/`, `/login`, and the protected `/dashboard`) reused without framework-specific business logic
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md) — a deep link to `/dashboard` is bounced to `/login` by the machine's `always` guard
 - Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
 - Canonical atoms lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
@@ -33,8 +33,8 @@ 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`, `registryResult`, and `inspector` 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 with the **Show Inspector** button).
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the Svelte gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (header plus the debug panel with the **Show Inspector** button). There is no nav bar: the machine's own specs carry the navigation buttons.
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts fragment
@@ -60,7 +60,7 @@ export function cleanup(): void {
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	import { Shell } from "@xmachines/play-svelte-demo";
+	import { Shell } from "@xmachines/play-svelte-gallery-demo";
 	import { actor, inspector, registryResult } from "./runtime.js";
 </script>
 
@@ -69,7 +69,7 @@ export function cleanup(): void {
 
 ```svelte
 <!-- Shell.svelte — rendering (shape) -->
-<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+<PlayUIProvider {actor} {registryResult}>
 	<PlayRenderer />
 </PlayUIProvider>
 ```
@@ -80,7 +80,7 @@ export function cleanup(): void {
 - `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`
+- `src/App.svelte` - minimal root component delegating to the gallery's `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
 
@@ -104,7 +104,7 @@ One subscription lives for the whole watch, and no caller arms a watcher again.
 
 ## 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`](../play-svelte-demo/README.md) is reused to avoid duplicating view components across router demos.
+`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 `Shell.svelte`, the built `authCatalog`, and the five-component kit all come from [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md), so no view component is duplicated across the Svelte 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).
 

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

@@ -0,0 +1,103 @@
+[Examples](../../README.md) / @xmachines/play-sveltekit-router-donut-demo
+
+# @xmachines/play-sveltekit-router-donut-demo
+
+Svelte 5 + SvelteKit router integration demo of the shared **donut** machine for the XMachines Play architecture, using browser pathname URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared donut machine reused without framework-specific business logic
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md) — the wizard steps map to `/`, `/bake/mix`, `/bake/fry`, `/bake/decorate`, and `/done`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link to a step whose prerequisites are unmet cascades back through the guard chain and the URL is overwritten (State-Driven Reset)
+- Snapshot persistence: the actor snapshot is stored on every transition and resumed on reload, with a **Reset saved donut** header button to drop it
+- Atom lifecycle integrated with Svelte 5 runes
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-sveltekit-router-donut-demo run dev
+```
+
+Then open `http://localhost:3078`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` loads any stored snapshot, creates the actor through `createResumedPlayer()`, builds the registry from `donutCatalog` + `demoComponents`, calls `createRouteMap(donutMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates SvelteKit `afterNavigate` notifications into `play.route` events and reflects actor-approved routes back through `goto`.
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the `DebugPanel` with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared donut router browser suite.
+
+## Snapshot Persistence
+
+The gallery creates a fresh actor per selection, so persistence belongs to this demo, which owns exactly one donut actor:
+
+- `definePlayer({ machine: donutMachine, options: { inspect, onTransition } })` — `onTransition` calls `saveDonutSnapshot(actor)`, writing `actor.getPersistedSnapshot()` to `localStorage` after every processed event.
+- `createResumedPlayer()` reads `loadDonutSnapshot()` and passes it through the player factory's resume options — `createDemoPlayer(undefined, { snapshot })`. An absent snapshot (`null`) becomes `undefined`, which starts the machine from its initial state.
+- `resetSavedDonut()` calls `clearDonutSnapshot()` and reloads, wired to the `data-demo-id="reset-snapshot"` button that this demo passes into the Shell's `nav` snippet.
+
+All three helpers come from `@xmachines/play-actor-shared` and degrade to no-ops outside a browser.
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<Shell {actor} {registryResult} {inspector}>
+	{#snippet nav()}
+		<button type="button" class="button" data-demo-id="reset-snapshot" onclick={resetSavedDonut}>
+			Reset saved donut
+		</button>
+	{/snippet}
+</Shell>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor with persistence hooks, registry, route map, and `connectRouter` wiring
+- `src/App.svelte` - hands the actor to the gallery `Shell` and fills its `nav` snippet with the reset-snapshot button
+- `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
+- `test/library-pattern.test.ts` - architecture boundary and route-map invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared donut router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A URL change becomes a `play.route` event. The actor evaluates it against its own guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** The SvelteKit router adapter executes no business logic — it only translates and reflects.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state; the URL always reflects the machine.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)) is passive infrastructure. 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
+
+| Command                                                                      | Description                                    |
+| ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-sveltekit-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3078/) |
+| `pnpm --filter @xmachines/play-sveltekit-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-sveltekit-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-sveltekit-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-sveltekit-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-sveltekit-router-donut-demo run test
+pnpm --filter @xmachines/play-sveltekit-router-donut-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared donut router browser suite completes.
+
+## Learn More
+
+- [SvelteKit Router adapter](../../../api/@xmachines/play-sveltekit-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,86 @@
+[Examples](../../README.md) / @xmachines/play-sveltekit-router-flight-demo
+
+# @xmachines/play-sveltekit-router-flight-demo
+
+Svelte 5 + SvelteKit router integration demo of the shared **flight-booking** machine for the XMachines Play architecture, using browser pathname URL routing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared flight-booking machine reused without framework-specific business logic
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md) — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link to `/booked` without a confirmation is bounced back to `/` (State-Driven Reset)
+- Atom lifecycle integrated with Svelte 5 runes
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-sveltekit-router-flight-demo run dev
+```
+
+Then open `http://localhost:3079`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `flightCatalog` + `demoComponents`, calls `createRouteMap(flightMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates SvelteKit `afterNavigate` notifications into `play.route` events and reflects actor-approved routes back through `goto`.
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the `DebugPanel` with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared flight router browser suite.
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<Shell {actor} {registryResult} {inspector} />
+```
+
+## 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/App.svelte` - minimal root component delegating to the shared gallery `Shell.svelte`
+- `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
+- `test/library-pattern.test.ts` - architecture boundary and route-map invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A URL change becomes a `play.route` event. The actor evaluates it against its own guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** The SvelteKit router adapter executes no business logic — it only translates and reflects.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state; the URL always reflects the machine.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)) is passive infrastructure. 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
+
+| Command                                                                       | Description                                    |
+| ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-sveltekit-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3079/) |
+| `pnpm --filter @xmachines/play-sveltekit-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-sveltekit-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-sveltekit-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-sveltekit-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-sveltekit-router-flight-demo run test
+pnpm --filter @xmachines/play-sveltekit-router-flight-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared flight router browser suite completes.
+
+## Learn More
+
+- [SvelteKit Router adapter](../../../api/@xmachines/play-sveltekit-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)