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

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/examples/@xmachines/play-solid-demo/README.md

@@ -0,0 +1,159 @@
+[Documentation](../../README.md) / @xmachines/play-solid-demo
+
+# SolidJS Demo
+
+Solid renderer demo for `@xmachines/play-solid` — actor + `PlayRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRenderer` rendering actor-projected views with a typed `defineRegistry` catalog
+- Auth machine states drive view switching via `auth.login` / `auth.logout` events only — no URL routing
+- Canonical TC39 Signals lifecycle integrated with Solid's fine-grained reactivity
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-solid-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` mounts `<App />` to the DOM root via Solid's `render`.
+2. `src/App.tsx` calls `definePlayer({ machine: authMachine })` and starts the actor at module scope.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed component registry.
+4. `<PlayRenderer actor={actor} registry={registry} actions={...} />` observes actor view signals and renders the current component.
+5. `onCleanup` calls `actor.stop()` when the `App` component is disposed.
+6. Browser tests in `test/browser/` validate startup and interaction behavior.
+
+```tsx
+// src/main.tsx (shape)
+render(() => <App />, document.getElementById("app")!);
+```
+
+```tsx
+// src/App.tsx (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer() as AuthActor;
+actor.start();
+
+const { registry } = defineRegistry(authCatalog, {
+	components: {
+		Home,
+		About,
+		Contact,
+		Login,
+		Dashboard,
+		Overview,
+		Stats,
+		Profile,
+		Settings,
+		Navigation,
+	},
+	actions: { login: async () => {}, logout: async () => {} },
+});
+
+export function App() {
+	onCleanup(() => {
+		actor.stop();
+	});
+
+	return (
+		<main class="demo-content" data-demo-content>
+			<PlayRenderer
+				actor={actor}
+				registry={registry}
+				actions={{ login: "auth.login", logout: "auth.logout" }}
+			/>
+		</main>
+	);
+}
+```
+
+## Key Files
+
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/App.tsx` - actor lifecycle, registry construction, and `PlayRenderer` composition
+- `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/renderer-demo.browser.test.tsx` - browser-mode renderer coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** View components dispatch `auth.login` and `auth.logout` events to the actor. The actor evaluates guards and transitions — Solid 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:** Instead of React-like re-renders, Solid uses fine-grained `createEffect` internally within the renderer to react precisely when actor signals update.
+
+## 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 Solid-local render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: Solid teardown uses `onCleanup`, and `PlayRenderer` handles internal watcher teardown natively on disposal.
+
+## Adapter Boundaries
+
+`PlayRenderer` and `defineRegistry` stay passive infrastructure. Business validity remains actor-owned. The registry maps catalog component keys to Solid component implementations — the actor owns which key is active. The demo intentionally omits URL routing to isolate the renderer contract.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                              | Description                      |
+| ---------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-solid-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-solid-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-solid-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-solid-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-solid-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-solid-demo
+npm run test:browser -w @xmachines/play-solid-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [SolidJS package README](../../README.md)
+- [Solid Router demo README](../../../play-solid-router/examples/demo/README.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [App](functions/App.md)
+- [DebugPanel](functions/DebugPanel.md)
+- [HeaderNav](functions/HeaderNav.md)
+- [Shell](functions/Shell.md)

package/examples/@xmachines/play-solid-demo/functions/App.md

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / App
+
+# Function: App()
+
+```ts
+function App(): Element;
+```
+
+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
+
+`Element`

package/examples/@xmachines/play-solid-demo/functions/DebugPanel.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / DebugPanel
+
+# Function: DebugPanel()
+
+```ts
+function DebugPanel(props): Element;
+```
+
+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
+
+| Parameter     | Type                                                                             |
+| ------------- | -------------------------------------------------------------------------------- |
+| `props`       | \{ `actor`: [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md); \} |
+| `props.actor` | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md)                 |
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-solid-demo/functions/HeaderNav.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / HeaderNav
+
+# Function: HeaderNav()
+
+```ts
+function HeaderNav(props): Element;
+```
+
+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
+
+| Parameter     | Type                                                                             |
+| ------------- | -------------------------------------------------------------------------------- |
+| `props`       | \{ `actor`: [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md); \} |
+| `props.actor` | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md)                 |
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-solid-demo/functions/Shell.md

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Shell
+
+# Function: Shell()
+
+```ts
+function Shell(props): Element;
+```
+
+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
+
+| Parameter        | Type                                                                                                                                    | Description                                                                      |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `props`          | \{ `actor`: [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md); `registry`: `ComponentRegistry`; `router?`: `unknown`; \} | -                                                                                |
+| `props.actor`    | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md)                                                                        | -                                                                                |
+| `props.registry` | `ComponentRegistry`                                                                                                                     | -                                                                                |
+| `props.router?`  | `unknown`                                                                                                                               | Bridged router instance — accepted for prop parity with router demos but unused. |
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-solid-demo/variables/About.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Contact.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Dashboard.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Home.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Login.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Navigation.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Overview.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Profile.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Settings.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+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/examples/@xmachines/play-solid-demo/variables/Stats.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+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

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-solid-router/examples/demo
+npm run dev -w @xmachines/play-solid-router-demo
 ```
 
 Then open `http://localhost:3002`.
@@ -98,27 +98,27 @@ Solid Router integration remains passive infrastructure. `RouterBridgeBase` stay
 
 These commands are defined in `package.json`:
 
-| Command                                                            | Description                      |
-| ------------------------------------------------------------------ | -------------------------------- |
-| `npm run dev -w packages/play-solid-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-solid-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-solid-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-solid-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-solid-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                     | Description                      |
+| ----------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-solid-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-solid-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-solid-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-solid-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-solid-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 packages/play-solid-router/examples/demo
-npm run test:browser -w packages/play-solid-router/examples/demo
+npm run test -w @xmachines/play-solid-router-demo
+npm run test:browser -w @xmachines/play-solid-router-demo
 ```
 
 Expected result: library-pattern invariant tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
 
 ## 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/examples/@xmachines/play-svelte-demo/README.md

@@ -0,0 +1,127 @@
+[Documentation](../../README.md) / @xmachines/play-svelte-demo
+
+# Svelte Demo
+
+Svelte 5 renderer demo for `@xmachines/play-svelte` — actor + `PlayRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRenderer` rendering actor-projected views with a typed `defineRegistry` catalog
+- Auth machine states drive view switching via `auth.login` / `auth.logout` events only — no URL routing
+- Svelte 5 runes and `mount` API mapped to TC39 Signals lifecycle
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-svelte-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts `App.svelte` via Svelte's `mount`.
+2. The actor is passed to `App` as a prop.
+3. `src/App.svelte` calls `defineRegistry(authCatalog, { components, actions })` to build the typed component registry.
+4. `App.svelte` delegates to `Shell.svelte`, which renders `<PlayRenderer>` with the actor and registry.
+5. `Shell.svelte` also renders `<HeaderNav>` and `<DebugPanel>` — both observe actor signals directly.
+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 actor = createPlayer();
+actor.start();
+
+mount(App, { target: document.getElementById("app")!, props: { actor } });
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	let { actor } = $props();
+	const { registry } = defineRegistry(authCatalog, {
+		components: { Home, About, Contact, Login, Dashboard, Overview, Stats, Profile, Settings, Navigation },
+		actions: { login: async () => {}, logout: async () => {} },
+	});
+</script>
+
+<Shell {actor} {registry} />
+```
+
+```svelte
+<!-- src/components/Shell.svelte (shape) -->
+<PlayRenderer
+	actor={props.actor}
+	registry={props.registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
+/>
+```
+
+## 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 `PlayRenderer`, `HeaderNav`, and `DebugPanel`
+- `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
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** View components dispatch `auth.login` and `auth.logout` events to the actor. The actor evaluates guards and transitions — 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.
+
+## 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: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component destruction.
+
+## Adapter Boundaries
+
+`PlayRenderer` and `defineRegistry` stay passive infrastructure. Business validity remains actor-owned. The registry maps catalog component keys to Svelte 5 component implementations — the actor owns which key is active. The `Shell.svelte` component is shared with all Svelte router demos, accepting an optional `router` prop for prop-shape parity.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                               | Description                      |
+| ----------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-svelte-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-svelte-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-svelte-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-svelte-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-svelte-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-demo
+npm run test:browser -w @xmachines/play-svelte-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Svelte package README](../../README.md)

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

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-svelte-spa-router/examples/demo
+npm run dev -w @xmachines/play-svelte-spa-router-demo
 ```
 
 Then open `http://localhost:5173`.
@@ -104,27 +104,26 @@ Watcher notifications are one-shot. Cleanup is explicit: `cleanupDemo()` calls `
 
 These commands are defined in `package.json`:
 
-| Command                                                                 | Description                      |
-| ----------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-svelte-spa-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-svelte-spa-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-svelte-spa-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-svelte-spa-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-svelte-spa-router/examples/demo` | Run browser-focused Vitest suite |
+| 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 packages/play-svelte-spa-router/examples/demo
-npm run test:browser -w packages/play-svelte-spa-router/examples/demo
+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](../play-svelte-spa-router/README.md)
-- [Svelte package README](../play-svelte/README.md)
-- [SvelteKit Router demo README](../play-sveltekit-router-demo/README.md)
+- [Svelte SPA Router package README](../../README.md)
+- [Svelte package README](../../../play-svelte/README.md)