@xmachines/docs 5.0.0 → 5.0.1

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

@@ -1,18 +1,24 @@
 [Examples](../../README.md) / @xmachines/play-svelte-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-svelte-demo
 
 Svelte 5 renderer demo for [`@xmachines/play-svelte`](../../../api/@xmachines/play-svelte/README.md) — actor + `PlayRenderer` without a router.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `PlayRenderer` rendering actor-projected views with a typed `defineRegistry` catalog
 - Auth machine states drive view switching via `auth.login` / `auth.logout` events only — no URL routing
-- Svelte 5 runes and `mount` API mapped to TC39 Signals lifecycle
+- Svelte 5 runes and `mount` API mapped to atoms lifecycle
 - Non-browser invariant tests plus browser renderer coverage
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+- json-render 0.20 showcase pages driven purely by spec:
+    - **Overview** — two data planes side by side: `/context/tasks` (machine context via the read-only `/context` projection; `repeat` + `key`, `$item`-filtered lists, per-row actions sending inspectable machine events) next to ephemeral store state (`pushState`/`removeState`/`setState` built-ins driving filter chips and toggles that survive context updates)
+    - **Stats** — nested repeats (`repeat.statePath: { $item: "members" }`) over `/context/teams`
+    - **Settings** — declarative field validation, the `validateForm` built-in, a confirm-gated `resetForm` host action, and `onSuccess`/`onError` chains
+    - **Contact** — a chained named action: submit validates, then routes home on success or writes `"$error.message"` to state on failure
 
 ## Running the Demo
 
@@ -29,54 +35,49 @@ Then open `http://localhost:3003`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` calls `definePlayer({ machine: authMachine })` to create a factory, invokes it to get an actor, starts it, and mounts `App.svelte` via Svelte's `mount`.
+1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect } })` to create a factory, invokes it to get an actor, starts it, and mounts `App.svelte` via Svelte's `mount` with both `actor` and `inspector` as props.
 2. The actor is passed to `App` as a prop.
 3. `src/App.svelte` calls `defineRegistry(authCatalog, { components, actions })` to build the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
-4. `App.svelte` delegates to `Shell.svelte`, passing both `actor` and `registryResult`.
-5. `Shell.svelte` renders `<PlayUIProvider><PlayRenderer /></PlayUIProvider>`, `<NavBar>`, and `<DebugPanel>` — the latter two observe actor signals directly via `watchSignal` inside `$effect`.
+4. `App.svelte` delegates to `Shell.svelte`, passing `actor`, `registryResult`, and `inspector`.
+5. `Shell.svelte` renders `<PlayUIProvider><PlayRenderer /></PlayUIProvider>`, `<NavBar>`, and `<DebugPanel>` — the latter two observe actor atoms directly via `watchAtom` inside `$effect`, and the debug panel's **Show Inspector** button calls `inspector.show()`.
 6. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
 7. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
+const inspector = createDemoInspector();
+const createPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
-mount(App, { target: document.getElementById("app")!, props: { actor } });
+mount(App, { target: document.getElementById("app")!, props: { actor, inspector } });
 ```
 
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	let { actor }: { actor: AuthActor } = $props();
+	import Shell from "./components/Shell.svelte";
+
+	let { actor, inspector }: { actor: AuthActor; inspector: DemoInspector } = $props();
 
 	const registryResult = defineRegistry(authCatalog, {
-		components: {
-			Home, About, Contact, Login, Dashboard,
-			Overview, Stats, Profile, Settings, Navigation,
-			NavBar: NavBarView,
-		},
-		actions: {
-			login: async (args) =>
-				actor.send({ type: "auth.login", username: assertNonNullable(args, "args").username }),
-			logout: async () => actor.send({ type: "auth.logout" }),
-			route: async (args) => {
-				const { to, params } = assertNonNullable(args, "args");
-				actor.send({ type: "play.route", to, ...(params != null && { params }) });
-			},
-		},
+		components: demoComponents, // one shared map — Home…NavBar plus the 0.20 Panel/Field/Button leaves
+		actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
 	});
 </script>
 
-<Shell {actor} {registryResult} />
+<Shell {actor} {registryResult} {inspector} />
 ```
 
 ## Key Files
 
 - `src/main.ts` - actor creation/start and Svelte app mount with actor as prop
 - `src/App.svelte` - registry construction, delegates rendering to `Shell.svelte`
-- `src/components/Shell.svelte` - shared shell with `PlayUIProvider` + `PlayRenderer`, `NavBar`, and `DebugPanel`
+- `src/components/Shell.svelte` - shared shell with `PlayUIProvider` + `PlayRenderer`, `NavBar`, and `DebugPanel` (which owns the **Show Inspector** button)
 - `src/components/` - demo view Svelte components bound to catalog component keys
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
@@ -86,20 +87,18 @@ mount(App, { target: document.getElementById("app")!, props: { actor } });
 The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** View components dispatch `auth.login` and `auth.logout` events to the actor. The actor evaluates guards and transitions — Svelte never decides which view to render.
-2. **Passive Infrastructure:** `PlayRenderer` observes `actor.currentView` signals only. It holds no business state and makes no routing decisions.
-3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
+2. **Passive Infrastructure:** `PlayRenderer` observes `actor.currentView` atoms only. It holds no business state and makes no routing decisions.
+3. **Atom-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor atoms 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)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and projects Svelte-local render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component destruction.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component destruction.
 
 ## Adapter Boundaries
 
@@ -117,20 +116,10 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-svelte-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-svelte-demo run test:browser` | Run browser-focused Vitest suite               |
 
-## Verification
-
-Use these checks to validate README claims against the current demo implementation:
-
-```bash
-pnpm --filter @xmachines/play-svelte-demo run test
-pnpm --filter @xmachines/play-svelte-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
-
 ## Learn More
 
 - [`@xmachines/play-svelte`](../../../api/@xmachines/play-svelte/README.md) — the Svelte 5 renderer package this demo exercises
+- [Inspecting a Running Actor](../../../guides/inspector.md)
 
 ## Type Aliases
 
@@ -141,3 +130,8 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 - [App](variables/App.md)
 - [authCatalog](variables/authCatalog.md)
+- [demoComponents](variables/demoComponents.md)
+
+## Functions
+
+- [createAuthActionHandlers](functions/createAuthActionHandlers.md)

package/examples/@xmachines/play-svelte-demo/functions/createAuthActionHandlers.md

@@ -0,0 +1,35 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / createAuthActionHandlers
+
+# Function: createAuthActionHandlers()
+
+```ts
+function createAuthActionHandlers(actor): object;
+```
+
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L48)
+
+Build the demo action handler map for one actor.
+
+Returned functions use the `(params, setState) => Promise<void>` shape every
+framework's `defineRegistry` accepts; spread the result into its `actions`.
+
+## Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `actor`   | `AuthActor` |
+
+## Returns
+
+`object`
+
+| Name             | Type                                                    | Defined in                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L92) |

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

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-svelte/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-svelte/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-svelte/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-svelte-demo/variables/authCatalog.md

@@ -36,8 +36,17 @@ const authCatalog: Catalog<
 						{
 							children: SchemaType<"array", SchemaType<"string", unknown>>;
 							props: SchemaType<"propsOf", string>;
+							repeat: {
+								inner?: unknown;
+								kind: "any";
+								optional: true;
+							};
 							type: SchemaType<"ref", string>;
-							visible: SchemaType<"any", unknown>;
+							visible: {
+								inner?: unknown;
+								kind: "any";
+								optional: true;
+							};
 						}
 					>
 				>;
@@ -47,6 +56,24 @@ const authCatalog: Catalog<
 	},
 	{
 		actions: {
+			addTask: {
+				description: "Add a task (sends task.add to the machine)";
+				params: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			completeTask: {
+				description: "Mark a task done (sends task.complete to the machine)";
+				params: ZodObject<
+					{
+						id: ZodString;
+					},
+					$strip
+				>;
+			};
 			login: {
 				description: "Login with username";
 				params: ZodObject<
@@ -59,6 +86,24 @@ const authCatalog: Catalog<
 			logout: {
 				description: "Logout and return to home";
 			};
+			removeTask: {
+				description: "Remove a task (sends task.remove to the machine)";
+				params: ZodObject<
+					{
+						id: ZodString;
+					},
+					$strip
+				>;
+			};
+			resetForm: {
+				description: "Reset a demo form to its defaults (confirm-gated in the spec)";
+				params: ZodObject<
+					{
+						form: ZodString;
+					},
+					$strip
+				>;
+			};
 			route: {
 				description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
 				params: ZodObject<
@@ -69,6 +114,16 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			submitForm: {
+				description: "Submit a demo form; rejects when the form did not pass validation";
+				params: ZodObject<
+					{
+						form: ZodString;
+						valid: ZodOptional<ZodNullable<ZodBoolean>>;
+					},
+					$strip
+				>;
+			};
 		};
 		components: {
 			About: {
@@ -79,6 +134,23 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Button: {
+				props: ZodObject<
+					{
+						disabled: ZodOptional<ZodBoolean>;
+						label: ZodString;
+						testId: ZodOptional<ZodString>;
+						variant: ZodOptional<
+							ZodEnum<{
+								danger: "danger";
+								primary: "primary";
+								secondary: "secondary";
+							}>
+						>;
+					},
+					$strip
+				>;
+			};
 			Contact: {
 				props: ZodObject<
 					{
@@ -96,6 +168,26 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Field: {
+				props: ZodObject<
+					{
+						checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+						formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+						inputType: ZodOptional<
+							ZodEnum<{
+								email: "email";
+								text: "text";
+								textarea: "textarea";
+							}>
+						>;
+						label: ZodString;
+						placeholder: ZodOptional<ZodString>;
+						testId: ZodOptional<ZodString>;
+						value: ZodOptional<ZodString>;
+					},
+					$strip
+				>;
+			};
 			Home: {
 				props: ZodObject<
 					{
@@ -139,6 +231,26 @@ const authCatalog: Catalog<
 					$strip
 				>;
 			};
+			Panel: {
+				props: ZodObject<
+					{
+						note: ZodOptional<
+							ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>
+						>;
+						testId: ZodOptional<ZodString>;
+						title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
+						tone: ZodOptional<
+							ZodEnum<{
+								danger: "danger";
+								default: "default";
+								muted: "muted";
+								success: "success";
+							}>
+						>;
+					},
+					$strip
+				>;
+			};
 			Profile: {
 				props: ZodObject<
 					{
@@ -169,4 +281,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-svelte/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-svelte/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-svelte/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-svelte-demo/variables/demoComponents.md

@@ -0,0 +1,30 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / demoComponents
+
+# Variable: demoComponents
+
+```ts
+const demoComponents: object;
+```
+
+Defined in: [packages/play-svelte/examples/demo/src/components/demo-components.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L20)
+
+demoComponents — the full catalog component map, shared with the router demos.
+
+## Type Declaration
+
+| Name                                          | Type                  | Default value | Defined in                                                                                                                                                                                                   |
+| --------------------------------------------- | --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-about"></a> `About`           | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L22) |
+| <a id="property-button"></a> `Button`         | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L34) |
+| <a id="property-contact"></a> `Contact`       | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L23) |
+| <a id="property-dashboard"></a> `Dashboard`   | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L25) |
+| <a id="property-field"></a> `Field`           | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L33) |
+| <a id="property-home"></a> `Home`             | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L21) |
+| <a id="property-login"></a> `Login`           | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L24) |
+| <a id="property-navbar"></a> `NavBar`         | `LegacyComponentType` | `NavBarView`  | [packages/play-svelte/examples/demo/src/components/demo-components.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L31) |
+| <a id="property-navigation"></a> `Navigation` | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L30) |
+| <a id="property-overview"></a> `Overview`     | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L26) |
+| <a id="property-panel"></a> `Panel`           | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L32) |
+| <a id="property-profile"></a> `Profile`       | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L28) |
+| <a id="property-settings"></a> `Settings`     | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L29) |
+| <a id="property-stats"></a> `Stats`           | `LegacyComponentType` | -             | [packages/play-svelte/examples/demo/src/components/demo-components.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-svelte/examples/demo/src/components/demo-components.ts#L27) |

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

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-svelte-spa-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-svelte-spa-router-demo
 
 Svelte 5 + `svelte-spa-router` integration demo 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 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)
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
+- Canonical atoms lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
+- 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
 
@@ -32,13 +33,18 @@ 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` and `registryResult` from `src/runtime.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
+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).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
 // src/runtime.ts (shape)
-const createDemoPlayer = definePlayer({ machine: authMachine });
+export const inspector = createDemoInspector();
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+});
 export const actor = createDemoPlayer();
 actor.start();
 
@@ -55,10 +61,10 @@ export function cleanup(): void {
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
 	import { Shell } from "@xmachines/play-svelte-demo";
-	import { actor, registryResult } from "./runtime.js";
+	import { actor, inspector, registryResult } from "./runtime.js";
 </script>
 
-<Shell {actor} {registryResult} />
+<Shell {actor} {registryResult} {inspector} />
 ```
 
 ```svelte
@@ -82,19 +88,17 @@ 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.
+3. **Atom-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor atoms 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)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and projects Svelte-local render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
 
 ## Adapter Boundaries
 
@@ -112,18 +116,8 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-svelte-spa-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-svelte-spa-router-demo run test:browser` | Run browser-focused Vitest suite               |
 
-## Verification
-
-Use these checks to validate README claims against the current demo implementation:
-
-```bash
-pnpm --filter @xmachines/play-svelte-spa-router-demo run test
-pnpm --filter @xmachines/play-svelte-spa-router-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
-
 ## Learn More
 
 - [Svelte SPA Router](../../../api/@xmachines/play-svelte-spa-router/README.md)
 - [Svelte](../../../api/@xmachines/play-svelte/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-sveltekit-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-sveltekit-router-demo
 
 Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play architecture using browser pathname URL routing.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)
 - Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
+- Canonical atoms lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
+- 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
 
@@ -32,13 +33,18 @@ Use this order to understand the implementation:
 1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
 2. `src/runtime.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
-4. `src/App.svelte` imports the singleton `actor` and `registryResult` from `src/runtime.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
+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).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
 // src/runtime.ts (shape)
-const createDemoPlayer = definePlayer({ machine: authMachine });
+export const inspector = createDemoInspector();
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+});
 export const actor = createDemoPlayer();
 actor.start();
 
@@ -55,10 +61,10 @@ export function cleanup(): void {
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
 	import { Shell } from "@xmachines/play-svelte-demo";
-	import { actor, registryResult } from "./runtime.js";
+	import { actor, inspector, registryResult } from "./runtime.js";
 </script>
 
-<Shell {actor} {registryResult} />
+<Shell {actor} {registryResult} {inspector} />
 ```
 
 ```svelte
@@ -84,19 +90,17 @@ 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.
+3. **Atom-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor atoms 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)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and projects Svelte-local render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
 
 ## Adapter Boundaries
 
@@ -116,18 +120,8 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-sveltekit-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-sveltekit-router-demo run test:browser` | Run browser-focused Vitest suite               |
 
-## Verification
-
-Use these checks to validate README claims against the current demo implementation:
-
-```bash
-pnpm --filter @xmachines/play-sveltekit-router-demo run test
-pnpm --filter @xmachines/play-sveltekit-router-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
-
 ## Learn More
 
 - [SvelteKit Router](../../../api/@xmachines/play-sveltekit-router/README.md)
 - [Svelte](../../../api/@xmachines/play-svelte/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)