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

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

@@ -0,0 +1,130 @@
+[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 @xmachines/play-sveltekit-router-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
+2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` synchronizes 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 @xmachines/play-sveltekit-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-sveltekit-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-sveltekit-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-sveltekit-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-sveltekit-router-demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w @xmachines/play-sveltekit-router-demo
+npm run test:browser -w @xmachines/play-sveltekit-router-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](../../README.md)
+- [Svelte package README](../../../play-svelte/README.md)

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

@@ -125,6 +125,6 @@ Expected result: invariant test suite and the browser shared-demo suite both pas
 
 ## Learn More
 
-- [TanStack React Router package README](../play-tanstack-react-router/README.md)
-- [React package README](../play-react/README.md)
-- [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)
+- [TanStack React Router package README](../../README.md)
+- [React package README](../../../play-react/README.md)
+- [TanStack Solid Router demo README](../../../play-tanstack-solid-router/examples/demo/README.md)

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

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

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

@@ -141,5 +141,5 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Vue package README](../play-vue/README.md)
-- [Vue Router demo README](../play-vue-router-demo/README.md)
+- [Vue package README](../../README.md)
+- [Vue Router demo README](../../../play-vue-router/examples/demo/README.md)

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

@@ -136,5 +136,5 @@ Expected result: reactivity integration tests and the browser shared-demo suite
 
 ## Learn More
 
-- [Vue Router package README](../play-vue-router/README.md)
-- [Vue package README](../play-vue/README.md)
+- [Vue Router package README](../../README.md)
+- [Vue package README](../../../play-vue/README.md)

package/examples/README.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # XMachines Examples
 
 Practical code examples demonstrating current XMachines Play patterns and use cases.
@@ -27,28 +25,38 @@ Complete working implementations of actor-authoritative routing with all archite
 
 ## Complete Demo Applications
 
-### Framework-Agnostic Baseline
-
-- **[Vanilla JavaScript Router Demo](../api/@xmachines/play-dom-router-demo/README.md)** — Pure browser integration: `connectRouter` + `connectRenderer` + DOM components. The lowest-level reference implementation.
+### Renderer Demos
 
-### React Integrations
+<!-- typedoc:renderer-demos:start -->
 
-- **[TanStack React Router Demo](../api/@xmachines/play-tanstack-react-router-demo/README.md)** — Canonical reference implementation with all 5 invariants, comprehensive routing, authentication guards, and browser tests.
-- **[React Router Demo](../api/@xmachines/play-react-router-demo/README.md)** — React Router v7 data-router integration using a catch-all route and `ReactRouterBridge`.
+- [@xmachines/play-dom-demo](@xmachines/play-dom-demo/README.md)
+- [@xmachines/play-react-demo](@xmachines/play-react-demo/README.md)
+- [@xmachines/play-solid-demo](@xmachines/play-solid-demo/README.md)
+- [@xmachines/play-svelte-demo](@xmachines/play-svelte-demo/README.md)
+- [@xmachines/play-vue-demo](@xmachines/play-vue-demo/README.md)
+  <!-- typedoc:renderer-demos:end -->
 
-### Vue Integration
+### Router Demos
 
-- **[Vue Router Demo](../api/@xmachines/play-vue-router-demo/README.md)** — Vue Composition API integration with `PlayRouterProvider` and the shared `authMachine`.
+<!-- typedoc:router-demos:start -->
 
-### Svelte Integrations
+- [@xmachines/play-dom-router-demo](@xmachines/play-dom-router-demo/README.md)
+- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
+- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-svelte-spa-router-demo](@xmachines/play-svelte-spa-router-demo/README.md)
+- [@xmachines/play-sveltekit-router-demo](@xmachines/play-sveltekit-router-demo/README.md)
+- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
+- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
+  <!-- typedoc:router-demos:end -->
 
-- **[SvelteKit Router Demo](../api/@xmachines/play-sveltekit-router-demo/README.md)** — SvelteKit-style routing with `connectRouter` + `afterNavigate`/`goto` and Svelte 5 runes.
-- **[Svelte SPA Router Demo](../api/@xmachines/play-svelte-spa-router-demo/README.md)** — Hash-based SPA routing using `svelte-spa-router` with the same actor-authoritative flow.
+### Shared Fixtures
 
-### SolidJS Integrations
+<!-- typedoc:shared-fixtures:start -->
 
-- **[Solid Router Demo](../api/@xmachines/play-solid-router-demo/README.md)** — `@solidjs/router` integration with `PlayRouterProvider` and SolidJS fine-grained reactivity.
-- **[TanStack Solid Router Demo](../api/@xmachines/play-tanstack-solid-router-demo/README.md)** — TanStack Router for Solid with dynamic route creation from the machine's route tree.
+- [@xmachines/play-actor-shared](@xmachines/play-actor-shared/README.md)
+- [@xmachines/play-router-shared](@xmachines/play-router-shared/README.md)
+  <!-- typedoc:shared-fixtures:end -->
 
 ## Running the Code Examples
 
@@ -62,25 +70,45 @@ npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
 npx tsx my-example.ts
 ```
 
-To run a complete demo application, `cd` into the relevant package and start its dev server:
+To run a complete demo application, use the workspace package name:
 
 ```bash
-# Example: vanilla DOM router demo
-cd packages/play-dom-router/examples/demo
-npm install
-npm run dev
+npm run dev -w @xmachines/play-dom-router-demo
 ```
 
 ## Key Packages
 
+### Core
+
 | Package                   | Role                                                        |
 | ------------------------- | ----------------------------------------------------------- |
 | `@xmachines/play-xstate`  | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
 | `@xmachines/play-actor`   | `AbstractActor`, `typedSpec`                                |
 | `@xmachines/play-signals` | TC39 Signals polyfill, `watchSignal`                        |
 | `@xmachines/play-router`  | `extractMachineRoutes`, `getRoutableRoutes`                 |
-| `@xmachines/play-dom`     | `connectRenderer`, `defineRegistry` (vanilla)               |
-| `@xmachines/play-react`   | `PlayRenderer`, `defineRegistry` (React)                    |
+
+### Renderers
+
+| Package                  | Role                                |
+| ------------------------ | ----------------------------------- |
+| `@xmachines/play-dom`    | `connectRenderer`, `defineRegistry` |
+| `@xmachines/play-react`  | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-solid`  | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-svelte` | `PlayRenderer`, `defineRegistry`    |
+| `@xmachines/play-vue`    | `PlayRenderer`, `defineRegistry`    |
+
+### Router Adapters
+
+| Package                                 | Router                  |
+| --------------------------------------- | ----------------------- |
+| `@xmachines/play-dom-router`            | Vanilla browser history |
+| `@xmachines/play-react-router`          | React Router v7         |
+| `@xmachines/play-tanstack-react-router` | TanStack Router (React) |
+| `@xmachines/play-solid-router`          | SolidJS Router          |
+| `@xmachines/play-tanstack-solid-router` | TanStack Router (Solid) |
+| `@xmachines/play-vue-router`            | Vue Router              |
+| `@xmachines/play-svelte-spa-router`     | svelte-spa-router       |
+| `@xmachines/play-sveltekit-router`      | SvelteKit               |
 
 ## Related Documentation
 
@@ -88,7 +116,3 @@ npm run dev
 - **[Installation Guide](../guides/installation.md)** — Package installation and TypeScript setup
 - **[API Reference](../api/README.md)** — Generated API docs for all public packages
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification
-
----
-
-**Contributing Examples:** Have a useful example to share? See the repository contribution guidelines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.28",
+  "version": "1.0.0-beta.29",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -45,14 +45,16 @@
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "typedoc": "typedoc"
+    "typedoc": "typedoc",
+    "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.28",
+    "@xmachines/shared": "1.0.0-beta.29",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.57.0",
     "typedoc": "^0.28.18",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.11.0"
+    "typedoc-plugin-markdown": "^4.11.0",
+    "vitest": "^4.1.2"
   }
 }