@xmachines/docs 1.0.0-beta.51 → 1.0.0-beta.52

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

@@ -6,7 +6,7 @@
 function App(): Element;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/App.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/App.tsx#L34)
+Defined in: [packages/play-solid/examples/demo/src/App.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/App.tsx#L34)
 
 ## Returns
 

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

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

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

@@ -6,4 +6,4 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/About.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/About.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/About.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/About.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Contact.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Contact.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Contact.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Contact.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Dashboard.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Dashboard.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L9)

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

@@ -8,7 +8,7 @@ const DebugPanel: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/DebugPanel.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L10)
+Defined in: [packages/play-solid/examples/demo/src/components/DebugPanel.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L10)
 
 DebugPanel — Live debug footer.
 Observes actor.state and actor.currentRoute via watchSignal;

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

@@ -6,4 +6,4 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Home.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Home.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Home.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Home.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Login.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Login.tsx#L12)
+Defined in: [packages/play-solid/examples/demo/src/components/Login.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Login.tsx#L12)

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

@@ -8,4 +8,4 @@ const NavBar: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/NavBar.tsx#L15)
+Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/NavBar.tsx#L15)

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

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/NavBarView.tsx#L11)
+Defined in: [packages/play-solid/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/NavBarView.tsx#L11)
 
 NavBarView — Catalog-typed NavBar for use in defineRegistry components map.
 

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

@@ -6,4 +6,4 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Navigation.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Navigation.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Navigation.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Navigation.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Overview.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Overview.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Overview.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Overview.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Profile.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Profile.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Profile.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Profile.tsx#L9)

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

@@ -6,4 +6,4 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Settings.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Settings.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Settings.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Settings.tsx#L9)

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

@@ -10,7 +10,7 @@ const Shell: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Shell.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Shell.tsx#L13)
+Defined in: [packages/play-solid/examples/demo/src/components/Shell.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Shell.tsx#L13)
 
 Shell — Demo shell layout component.
 Renders standard demo chrome (header + PlayUIProvider/PlayRenderer + DebugPanel).

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

@@ -6,4 +6,4 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Stats.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/components/Stats.tsx#L9)
+Defined in: [packages/play-solid/examples/demo/src/components/Stats.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/components/Stats.tsx#L9)

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

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-solid/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-solid/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-solid/examples/demo/src/catalog.ts#L5)

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

@@ -1,8 +1,10 @@
 [Examples](../../README.md) / @xmachines/play-solid-router-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-solid-router-demo
 
-Solid + `@solidjs/router` integration demo for the XMachines Play architecture using provider-based router integration.
+SolidJS Router adapter demonstration with authentication flow using the XMachines Play architecture and provider-based router integration.
 
 ## What This Demonstrates
 
@@ -27,46 +29,57 @@ Then open `http://localhost:3002`.
 
 Use this order to understand the implementation:
 
-1. `src/main.tsx` bootstraps the demo and mounts `<App />`.
-2. `src/App.tsx` wires actor lifecycle, shared machine/catalog imports, and router integration.
-3. A `routeMap` is created by calling `createRouteMap(authMachine)`.
-4. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
-5. `Shell` (inside `src/App.tsx`) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell.
-6. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
+1. `src/main.tsx` bootstraps the demo and mounts `<App />` onto `#app`.
+2. `src/runtime.ts` sets up the actor, registry, routes, and route map — all shared module-level singletons.
+3. `src/App.tsx` wires Solid Router routes and the `PlayRouterProvider` using the runtime exports.
+4. A `routeMap` is created by calling `createRouteMap(authMachine)` in `src/runtime.ts`.
+5. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
+6. `Shell` (from `@xmachines/play-solid-demo`) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell.
+7. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
 
 ```tsx
 // src/main.tsx (shape)
-render(() => <App />, document.getElementById("root")!);
+render(() => <App />, document.getElementById("app")!);
 ```
 
 ```tsx
-// src/App.tsx (shape)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
-const actor = createPlayer();
+// src/runtime.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+export const actor = createPlayer();
 actor.start();
 
-const routeMap = createRouteMap(authMachine);
-
-<PlayRouterProvider
-	actor={actor}
-	routeMap={routeMap}
-	router={{ navigate, location, params }}
-	renderer={(currentActor, currentRouter) => (
-		<Shell actor={currentActor} router={currentRouter} />
-	)}
-/>;
+export const routeMap = createRouteMap(authMachine);
 ```
 
 ```tsx
-// src/components/Nav.tsx (shape)
-<button onClick={() => actor.send({ type: "auth.logout" })}>Logout</button>
+// src/App.tsx (shape)
+const Layout: ParentComponent = () => {
+	const navigate = useNavigate();
+	const location = useLocation();
+	const params = useParams();
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			routeMap={routeMap}
+			router={{ navigate, location, params }}
+			renderer={(currentActor, currentRouter) => (
+				<Shell
+					actor={currentActor}
+					router={currentRouter}
+					registryResult={registryResult}
+				/>
+			)}
+		/>
+	);
+};
 ```
 
 ## Key Files
 
-- `src/App.tsx` - actor lifecycle, route map, `PlayRouterProvider` wiring, and renderer composition
+- `src/runtime.ts` - actor lifecycle, registry, route extraction, and route map creation
+- `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, and renderer composition
 - `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
-- `src/components/` - demo view components that send events to the actor
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
 

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

@@ -1,5 +1,7 @@
 [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.
@@ -27,17 +29,18 @@ Then open `http://localhost:5173`.
 
 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`.
+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`.
 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.
+5. `Shell.svelte` renders `<PlayUIProvider><PlayRenderer /></PlayUIProvider>`, `<NavBar>`, and `<DebugPanel>` — the latter two observe actor signals directly via `watchSignal` inside `$effect`.
 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 actor = definePlayer({ machine: authMachine })();
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
 actor.start();
 
 mount(App, { target: document.getElementById("app")!, props: { actor } });
@@ -73,7 +76,7 @@ mount(App, { target: document.getElementById("app")!, props: { actor } });
 
 - `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`, `HeaderNav`, and `DebugPanel`
+- `src/components/Shell.svelte` - shared shell with `PlayUIProvider` + `PlayRenderer`, `NavBar`, 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
@@ -127,7 +130,7 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Svelte](../../../api/@xmachines/play-svelte/README.md)
+- [`@xmachines/play-svelte`](../../../api/@xmachines/play-svelte/README.md) — the Svelte 5 renderer package this demo exercises
 
 ## Type Aliases
 

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.51/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/v1.0.0-beta.52/packages/play-svelte/examples/demo/src/catalog.ts#L6)

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

@@ -169,4 +169,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.51/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/v1.0.0-beta.52/packages/play-svelte/examples/demo/src/catalog.ts#L5)

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

@@ -1,5 +1,7 @@
 [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.
@@ -21,21 +23,21 @@ npm install
 npm run dev -w @xmachines/play-svelte-spa-router-demo
 ```
 
-Then open `http://localhost:5173`.
+Then open `http://localhost:3005`.
 
 ## 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 })`.
+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 `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+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).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
-// src/lib/router.ts (shape)
+// src/runtime.ts (shape)
 const createDemoPlayer = definePlayer({ machine: authMachine });
 export const actor = createDemoPlayer();
 actor.start();
@@ -43,7 +45,7 @@ actor.start();
 export const routeMap = createRouteMap(authMachine);
 export const disconnectRouter = connectRouter({ actor, routeMap });
 
-export function cleanupDemo(): void {
+export function cleanup(): void {
 	disconnectRouter();
 	actor.stop();
 }
@@ -53,7 +55,7 @@ export function cleanupDemo(): void {
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
 	import { Shell } from "@xmachines/play-svelte-demo";
-	import { actor, registryResult } from "./lib/router.js";
+	import { actor, registryResult } from "./runtime.js";
 </script>
 
 <Shell {actor} {registryResult} />
@@ -69,7 +71,7 @@ export function cleanupDemo(): void {
 ## 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/runtime.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
@@ -92,7 +94,7 @@ This demo follows the canonical watcher lifecycle used across all `@xmachines` f
 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.
+Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
 
 ## Adapter Boundaries
 

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

@@ -1,5 +1,7 @@
 [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.
@@ -27,15 +29,15 @@ Then open `http://localhost:5173`.
 
 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 })`.
+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/lib/router.ts` and delegates to the shared `Shell.svelte`.
+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).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
-// src/lib/router.ts (shape)
+// src/runtime.ts (shape)
 const createDemoPlayer = definePlayer({ machine: authMachine });
 export const actor = createDemoPlayer();
 actor.start();
@@ -43,7 +45,7 @@ actor.start();
 export const routeMap = createRouteMap(authMachine);
 export const disconnectRouter = connectRouter({ actor, routeMap });
 
-export function cleanupDemo(): void {
+export function cleanup(): void {
 	disconnectRouter();
 	actor.stop();
 }
@@ -53,7 +55,7 @@ export function cleanupDemo(): void {
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
 	import { Shell } from "@xmachines/play-svelte-demo";
-	import { actor, registryResult } from "./lib/router.js";
+	import { actor, registryResult } from "./runtime.js";
 </script>
 
 <Shell {actor} {registryResult} />
@@ -69,8 +71,9 @@ export function cleanupDemo(): void {
 ## 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/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`
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/shared-demo.browser.test.ts` - browser startup and auth route flow coverage
@@ -93,12 +96,14 @@ This demo follows the canonical watcher lifecycle used across all `@xmachines` f
 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.
+Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
 
 ## 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` is reused to avoid duplicating view components across router 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).
+
 ## Available Scripts
 
 These commands are defined in `package.json`:

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

@@ -1,5 +1,7 @@
 [Examples](../../README.md) / @xmachines/play-tanstack-react-router-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-tanstack-react-router-demo
 
 React + TanStack Router integration demo for the XMachines Play architecture with actor-authoritative routing.
@@ -27,9 +29,9 @@ Then open `http://localhost:3000`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` mounts `<App />`.
-2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor from shared machine + catalog and start it once per mounted app.
-3. `createAppRuntime()` memoizes `routeMap` from `extractMachineRoutes(authMachine)` + `createRouteMapFromTree(routeTree)`.
-4. `createAppRuntime()` also memoizes the TanStack router, then `PlayRouterProvider` bridges it to the actor and renders `Shell` via `renderer(actor, router)`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor from the shared machine and start it once per mounted app.
+3. `src/runtime.ts` exports `createPlayer` (via `definePlayer`), `routeMap` (via `createRouteMap(authMachine)`), and `createRegistryResult` which binds UI components and actor event actions.
+4. `createAppRuntime()` constructs a TanStack `createRootRoute`/`createRouter` instance, then `PlayRouterProvider` bridges it to the actor and renders `Shell` via `renderer(actor, router)`.
 5. `Shell` renders `PlayRenderer`, header/nav, and debug panel from actor state.
 6. Tests in `test/` and `test/browser/` validate invariant and runtime behavior.
 
@@ -39,14 +41,15 @@ function createAppRuntime() {
 	const actor = createPlayer();
 	actor.start();
 
-	const routeTree = extractMachineRoutes(authMachine);
-	const routeMap = createRouteMapFromTree(routeTree);
-	const router = createRouterInstance();
+	const registryResult = createRegistryResult(actor);
+
+	const rootRoute = createRootRoute();
+	const router = createRouter({ routeTree: rootRoute, defaultPreload: "intent" });
 
-	return { actor, routeMap, router };
+	return { actor, router, registryResult };
 }
 
-const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+const { actor, router, registryResult } = useMemo(createAppRuntime, []);
 
 return (
 	<PlayRouterProvider
@@ -54,27 +57,50 @@ return (
 		router={router}
 		routeMap={routeMap}
 		renderer={(currentActor, currentRouter) => (
-			<Shell actor={currentActor} router={currentRouter} />
+			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
 		)}
 	/>
 );
 ```
 
 ```tsx
-// src/components/Login.tsx (shape)
-<button onClick={() => actor.send({ type: "auth.login", username })}>Login</button>
+// src/runtime.ts (shape)
+export const createPlayer = definePlayer({ machine: authMachine });
+export const routeMap = createRouteMap(authMachine);
+
+export function createRegistryResult(actor) {
+	return defineRegistry(authCatalog, {
+		actions: {
+			login: async (args) => actor.send({ type: "auth.login", username: args.username }),
+			logout: async () => actor.send({ type: "auth.logout" }),
+			route: async (args) => actor.send({ type: "play.route", to: args.to, ...args.params }),
+		},
+	});
+}
 ```
 
 ## Key Files
 
 - `src/main.tsx` - React entry point that mounts `<App />`
-- `src/App.tsx` - actor lifecycle, route-map creation, provider wiring, and `Shell` rendering
-- `src/components/` - UI components that send actor events and render state-driven views
+- `src/App.tsx` - actor lifecycle, provider wiring, and `Shell` rendering
+- `src/runtime.ts` - actor factory, route map creation, and registry/action binding
 - `test/actor-authority.test.ts` - actor authority and guarded navigation behavior
+- `test/passive-infra.test.ts` - passive infrastructure separation contracts
 - `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
+- `test/signal-only.test.ts` - signal-only reactivity invariant
+- `test/route-parameters.test.ts` - route parameter handling
+- `test/invalid-route-redirect.test.ts` - invalid route redirect behavior
+- `test/xstate-route-events.test.ts` - XState route event contracts
 - `test/browser/shared-demo.browser.test.tsx` - canonical browser auth flow
 - `test/browser/auth-flow.browser.test.tsx` - extended browser auth flow checks
 - `test/browser/back-forward-sync.browser.test.tsx` - URL sync and history behavior
+- `test/browser/dashboard-logout.browser.test.tsx` - logout and redirection flow
+- `test/browser/guard-rejection.browser.test.tsx` - guard-driven rejection in browser
+- `test/browser/login-flow.browser.test.tsx` - login flow browser coverage
+- `test/browser/navigation.browser.test.tsx` - navigation behavior in browser
+- `test/browser/settings-parameter.browser.test.tsx` - parameterized route in browser
+- `test/browser/invalid-route-redirect.browser.test.tsx` - invalid route redirect in browser
+- `test/browser/tanstack-integration.browser.test.tsx` - TanStack Router integration checks
 
 ## State Machine & Architecture Details
 

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

@@ -1,5 +1,7 @@
 [Examples](../../README.md) / @xmachines/play-tanstack-solid-router-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-tanstack-solid-router-demo
 
 Solid + `@tanstack/solid-router` integration demo for the XMachines Play architecture with actor-authoritative routing.
@@ -27,22 +29,32 @@ Then open `http://localhost:3005`.
 
 Use this order to understand the implementation:
 
-1. `src/main.tsx` bootstraps the demo app and mounts `<App />`.
-2. `src/App.tsx` sets up actor lifecycle, route mapping, and TanStack Solid router integration.
-3. Shared machine/catalog logic comes from the common demo module to keep business logic framework-agnostic.
+1. `src/main.tsx` bootstraps the demo app and mounts `<App />` onto `#app`.
+2. `src/runtime.ts` initializes the actor, builds the registry, and creates the route map using `createRouteMap(authMachine)`.
+3. `src/App.tsx` constructs the TanStack Router route tree from machine routes and wires `PlayRouterProvider` with the actor, router, and route map from `runtime.ts`.
 4. Router infrastructure stays passive: it forwards navigation intent to the actor via the `PlayRouterProvider` and reflects actor-approved route changes back to TanStack.
-5. `Shell` (inside `src/App.tsx`) renders actor-projected state (`PlayRenderer`) and emits actor events.
+5. `Shell` (from `@xmachines/play-solid-demo`) renders actor-projected state (`PlayRenderer`) and emits actor events via the `registryResult` actions.
 6. `test/library-pattern.test.ts` plus `test/browser/` verify invariants and browser routing behavior.
 
 ```tsx
 // src/main.tsx (shape)
-render(() => <App />, document.getElementById("root")!);
+render(() => <App />, document.getElementById("app")!);
+```
+
+```ts
+// src/runtime.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+export const actor = createPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+const routeTree = extractMachineRoutes(authMachine);
+export const routes = getRoutableRoutes(routeTree);
 ```
 
 ```tsx
 // src/App.tsx (shape)
-const routeTree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMap(authMachine);
+import { actor, registryResult, routeMap, routes } from "./runtime.js";
 
 return (
 	<PlayRouterProvider
@@ -50,22 +62,24 @@ return (
 		router={router}
 		routeMap={routeMap}
 		renderer={(currentActor, currentRouter) => (
-			<Shell actor={currentActor} router={currentRouter} />
+			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
 		)}
 	/>
 );
 ```
 
-```tsx
-// src/components/Login.tsx (shape)
-<button onClick={() => actor.send({ type: "auth.login", username, password })}>Login</button>
+```ts
+// src/runtime.ts — actor events wired via registryResult actions
+login: async (args) => actor.send({ type: "auth.login", username: args.username }),
+logout: async () => actor.send({ type: "auth.logout" }),
+route: async (args) => actor.send({ type: "play.route", to: args.to, ...params }),
 ```
 
 ## Key Files
 
-- `src/App.tsx` - actor lifecycle, route map, TanStack router setup, and provider/renderer integration
+- `src/runtime.ts` - actor lifecycle, registry, route map, and routable routes setup
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` wiring
 - `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
-- `src/components/` - demo view components that dispatch machine events
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
 - `test/browser/xstate-route-events.browser.test.ts` - actor route event behavior in the browser