@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,137 @@
+[Examples](../../README.md) / @xmachines/play-solid-router-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-solid-router-demo
+
+SolidJS Router adapter demonstration with authentication flow using the XMachines Play architecture and provider-based router integration.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Solid Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle integration with Solid's fine-grained reactivity
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-solid-router-demo run dev
+```
+
+Then open `http://localhost:3007`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+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("app")!);
+```
+
+```tsx
+// src/runtime.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+export const actor = createPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+```
+
+```tsx
+// 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/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`
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user navigates to a protected route, the Solid Router updates the URL. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g., is the user logged in?) and transitions to the appropriate state.
+2. **Passive Infrastructure:** Solid components hold no business state. They observe `actor.currentView` to know what to render, and `actor.currentRoute` to reflect the active path.
+3. **Signal-Only Reactivity:** Instead of React-like re-renders, Solid uses `createEffect` internally within the `RouterBridge` to react precisely when signals update.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and update Solid-local render triggers
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: Solid teardown uses `onCleanup`, and provider/bridge teardown must call `disconnect`/`unwatch` paths rather than relying on GC-only cleanup. This is crucial to prevent memory leaks during component unmounting.
+
+## Adapter Boundaries
+
+Solid Router integration remains passive infrastructure. `RouterBridgeBase` stays the shared policy point; the Solid adapter only implements framework port behavior (calling `navigate()` and tracking `location.pathname`).
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                            | Description                                    |
+| ------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-solid-router-demo run dev`          | Start Vite dev server (http://localhost:3007/) |
+| `pnpm --filter @xmachines/play-solid-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-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-solid-router-demo run test
+pnpm --filter @xmachines/play-solid-router-demo run test:browser
+```
+
+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](../../../api/@xmachines/play-solid-router/README.md)
+- [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [TanStack Solid Router](../play-tanstack-solid-router-demo/README.md)

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

@@ -0,0 +1,143 @@
+[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.
+
+## 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
+pnpm install
+pnpm --filter @xmachines/play-svelte-demo run dev
+```
+
+Then open `http://localhost:3003`.
+
+## Step-by-Step Code Flow
+
+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`.
+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`.
+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 }: { actor: AuthActor } = $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 }) });
+			},
+		},
+	});
+</script>
+
+<Shell {actor} {registryResult} />
+```
+
+## 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/` - 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                                    |
+| ------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-demo run dev`          | Start Vite dev server (http://localhost:3003/) |
+| `pnpm --filter @xmachines/play-svelte-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-demo run preview`      | Preview built bundle                           |
+| `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
+
+## Type Aliases
+
+- [App](type-aliases/App.md)
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+
+## Variables
+
+- [App](variables/App.md)
+- [authCatalog](variables/authCatalog.md)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / App
+
+# Type Alias: App
+
+```ts
+type App = SvelteComponent;
+```
+
+Defined in: `svelte`

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+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/packages/play-svelte/examples/demo/src/catalog.ts#L6)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / App
+
+# Variable: App
+
+```ts
+const App: LegacyComponentType;
+```
+
+Defined in: `svelte`

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

@@ -0,0 +1,172 @@
+[Examples](../../../README.md) / [@xmachines/play-svelte-demo](../README.md) / authCatalog
+
+# Variable: authCatalog
+
+```ts
+const authCatalog: Catalog<
+	{
+		catalog: SchemaType<
+			"object",
+			{
+				actions: SchemaType<
+					"map",
+					{
+						description: SchemaType<"string", unknown>;
+						params: SchemaType<"zod", unknown>;
+					}
+				>;
+				components: SchemaType<
+					"map",
+					{
+						description: SchemaType<"string", unknown>;
+						example: SchemaType<"any", unknown>;
+						props: SchemaType<"zod", unknown>;
+						slots: SchemaType<"array", SchemaType<"string", unknown>>;
+					}
+				>;
+			}
+		>;
+		spec: SchemaType<
+			"object",
+			{
+				elements: SchemaType<
+					"record",
+					SchemaType<
+						"object",
+						{
+							children: SchemaType<"array", SchemaType<"string", unknown>>;
+							props: SchemaType<"propsOf", string>;
+							type: SchemaType<"ref", string>;
+							visible: SchemaType<"any", unknown>;
+						}
+					>
+				>;
+				root: SchemaType<"string", unknown>;
+			}
+		>;
+	},
+	{
+		actions: {
+			login: {
+				description: "Login with username";
+				params: ZodObject<
+					{
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			logout: {
+				description: "Logout and return to home";
+			};
+			route: {
+				description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
+				params: ZodObject<
+					{
+						params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+						to: ZodString;
+					},
+					$strip
+				>;
+			};
+		};
+		components: {
+			About: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Contact: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Dashboard: {
+				props: ZodObject<
+					{
+						username: ZodString;
+						welcome: ZodBoolean;
+					},
+					$strip
+				>;
+			};
+			Home: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Login: {
+				props: ZodObject<
+					{
+						title: ZodString;
+						username: ZodOptional<ZodString>;
+					},
+					$strip
+				>;
+			};
+			NavBar: {
+				props: ZodObject<
+					{
+						isAuthenticated: ZodBoolean;
+						username: ZodNullable<ZodString>;
+					},
+					$strip
+				>;
+			};
+			Navigation: {
+				props: ZodObject<
+					{
+						currentPath: ZodString;
+						isAuthenticated: ZodBoolean;
+					},
+					$strip
+				>;
+			};
+			Overview: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Profile: {
+				props: ZodObject<
+					{
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			Settings: {
+				props: ZodObject<
+					{
+						section: ZodOptional<ZodString>;
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			Stats: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+		};
+	}
+>;
+```
+
+Defined in: [packages/play-svelte/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/examples/demo/src/catalog.ts#L5)

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

@@ -0,0 +1,129 @@
+[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.
+
+## 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
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-svelte-spa-router-demo run dev
+```
+
+Then open `http://localhost:3008`.
+
+## Step-by-Step Code Flow
+
+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).
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/runtime.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 cleanup(): void {
+	disconnectRouter();
+	actor.stop();
+}
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	import { Shell } from "@xmachines/play-svelte-demo";
+	import { actor, registryResult } from "./runtime.js";
+</script>
+
+<Shell {actor} {registryResult} />
+```
+
+```svelte
+<!-- Shell.svelte — rendering (shape) -->
+<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `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
+
+## 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: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-svelte-spa-router`](../../../api/@xmachines/play-svelte-spa-router/README.md)) 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                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-svelte-spa-router-demo run dev`          | Start Vite dev server (http://localhost:3008/) |
+| `pnpm --filter @xmachines/play-svelte-spa-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-svelte-spa-router-demo run preview`      | Preview built bundle                           |
+| `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)