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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.27",
+  "version": "1.0.0-beta.28",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -48,7 +48,7 @@
     "typedoc": "typedoc"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.27",
+    "@xmachines/shared": "1.0.0-beta.28",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.57.0",
     "typedoc": "^0.28.18",

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

@@ -1,130 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-svelte-spa-router-demo
-
-# Svelte SPA Router Demo
-
-Svelte 5 + `svelte-spa-router` integration demo for the XMachines Play architecture using hash-based URL routing.
-
-## What This Demonstrates
-
-- Shared auth machine reused without framework-specific business logic
-- `connectRouter` hash-URL ↔ actor sync via `@xmachines/play-svelte-spa-router`
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
-- Non-browser invariant tests plus browser E2E coverage
-
-## Running the Demo
-
-From the repository root:
-
-```bash
-npm install
-npm run dev -w packages/play-svelte-spa-router/examples/demo
-```
-
-Then open `http://localhost:5173`.
-
-## Step-by-Step Code Flow
-
-Use this order to understand the implementation:
-
-1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
-2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
-3. `connectRouter` synchronizes hash URL changes with the actor via `play.route` events and reflects actor-approved routes back to the hash URL.
-4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
-6. Browser tests in `test/browser/` validate startup and auth route transitions.
-
-```ts
-// src/lib/router.ts (shape)
-const createDemoPlayer = definePlayer({ machine: authMachine });
-export const actor = createDemoPlayer();
-actor.start();
-
-export const routeMap = createRouteMap(authMachine);
-export const disconnectRouter = connectRouter({ actor, routeMap });
-
-export function cleanupDemo(): void {
-	disconnectRouter();
-	actor.stop();
-}
-```
-
-```svelte
-<!-- src/App.svelte (shape) -->
-<script lang="ts">
-	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
-</script>
-
-<Shell {actor} {registry} />
-```
-
-```svelte
-<!-- Shell.svelte — sending events (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
-```
-
-## Key Files
-
-- `src/main.ts` - Svelte app mount and HMR cleanup registration
-- `src/lib/router.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
-- `src/App.svelte` - minimal root component delegating to shared `Shell.svelte`
-- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
-- `test/browser/shared-demo.browser.test.ts` - browser startup and auth route flow coverage
-
-## State Machine & Architecture Details
-
-The demo utilizes XMachines architectural invariants:
-
-1. **Actor Authority:** When a user clicks a nav link, the hash URL changes. `connectRouter` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions to the appropriate state.
-2. **Passive Infrastructure:** `svelte-spa-router` does not execute business logic. The actor dictates whether navigation is permitted. The Svelte application only renders the state.
-3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
-
-## Watcher Lifecycle and Cleanup Contract
-
-This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
-
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project Svelte-local render state
-5. Re-arm with `watch()`/`watch(...signals)`
-
-Watcher notifications are one-shot. Cleanup is explicit: `cleanupDemo()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
-
-## Adapter Boundaries
-
-`connectRouter` (from `@xmachines/play-svelte-spa-router`) is passive infrastructure. It translates hash URL changes into `play.route` events and reflects actor-approved route changes back to the URL. Business validity remains actor-owned. The shared `Shell.svelte` from `@xmachines/play-svelte-demo` is reused to avoid duplicating view components across router demos.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                                                 | Description                      |
-| ----------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w 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 |
-
-## 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
-```
-
-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)

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

@@ -1,131 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-sveltekit-router-demo
-
-# SvelteKit Router Demo
-
-Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play architecture using browser pathname URL routing.
-
-## What This Demonstrates
-
-- Shared auth machine reused without framework-specific business logic
-- `connectRouter` pathname URL ↔ actor sync via `@xmachines/play-sveltekit-router`
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
-- Non-browser invariant tests plus browser E2E coverage
-
-## Running the Demo
-
-From the repository root:
-
-```bash
-npm install
-npm run dev -w packages/play-sveltekit-router/examples/demo
-```
-
-Then open `http://localhost:5173`.
-
-## Step-by-Step Code Flow
-
-Use this order to understand the implementation:
-
-1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
-2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
-3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
-4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
-6. Browser tests in `test/browser/` validate startup and auth route transitions.
-
-```ts
-// src/lib/router.ts (shape)
-const createDemoPlayer = definePlayer({ machine: authMachine });
-export const actor = createDemoPlayer();
-actor.start();
-
-export const routeMap = createRouteMap(authMachine);
-export const disconnectRouter = connectRouter({ actor, routeMap });
-
-export function cleanupDemo(): void {
-	disconnectRouter();
-	actor.stop();
-}
-```
-
-```svelte
-<!-- src/App.svelte (shape) -->
-<script lang="ts">
-	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
-</script>
-
-<Shell {actor} {registry} />
-```
-
-```svelte
-<!-- Shell.svelte — sending events (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
-```
-
-## Key Files
-
-- `src/main.ts` - Svelte app mount and HMR cleanup registration
-- `src/lib/router.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
-- `src/lib/navigation.ts` - SvelteKit navigation helpers for pathname observation
-- `src/App.svelte` - minimal root component delegating to shared `Shell.svelte`
-- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
-- `test/browser/shared-demo.browser.test.ts` - browser startup and auth route flow coverage
-
-## State Machine & Architecture Details
-
-The demo utilizes XMachines architectural invariants:
-
-1. **Actor Authority:** When a user clicks a nav link, the browser pathname changes. `connectRouter` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions to the appropriate state.
-2. **Passive Infrastructure:** The SvelteKit router adapter does not execute business logic. The actor dictates whether navigation is permitted. The Svelte application only renders the state.
-3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
-
-## Watcher Lifecycle and Cleanup Contract
-
-This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
-
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project Svelte-local render state
-5. Re-arm with `watch()`/`watch(...signals)`
-
-Watcher notifications are one-shot. Cleanup is explicit: `cleanupDemo()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
-
-## Adapter Boundaries
-
-`connectRouter` (from `@xmachines/play-sveltekit-router`) is passive infrastructure. It translates pathname URL changes into `play.route` events and reflects actor-approved route changes back to the browser pathname. Business validity remains actor-owned. The shared `Shell.svelte` from `@xmachines/play-svelte-demo` is reused to avoid duplicating view components across router demos.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                                                | Description                      |
-| ---------------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-sveltekit-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-sveltekit-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-sveltekit-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-sveltekit-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-sveltekit-router/examples/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-sveltekit-router/examples/demo
-npm run test:browser -w packages/play-sveltekit-router/examples/demo
-```
-
-Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
-
-## Learn More
-
-- [SvelteKit Router package README](../play-sveltekit-router/README.md)
-- [Svelte package README](../play-svelte/README.md)
-- [Svelte SPA Router demo README](../play-svelte-spa-router-demo/README.md)