@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,187 @@
+[Examples](../../README.md) / @xmachines/play-solid-demo
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-solid-demo
+
+Solid renderer demo for [`@xmachines/play-solid`](../../../api/@xmachines/play-solid/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
+- 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
+pnpm install
+pnpm --filter @xmachines/play-solid-demo run dev
+```
+
+Then open `http://localhost:3002`.
+
+## 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` creates the actor at module scope via `definePlayer({ machine: authMachine })` then calls the returned factory to produce the actor and starts it.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` inside `createMemo` — real async action handlers dispatching to `actor.send()`.
+4. `<PlayUIProvider actor={actor} registryResult={registryResult()}><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` component observes `actor` signals directly for nav visibility.
+6. `<DebugPanel actor={actor} />` shows live state, auth status, and current route.
+7. 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();
+
+export function App() {
+	const registryResult = createMemo(() =>
+		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 }),
+					});
+				},
+			},
+		}),
+	);
+
+	return (
+		<div class="demo-app" data-demo-shell>
+			<header class="demo-header">
+				<h1 class="demo-title">XMachines Play Solid Demo</h1>
+				<NavBar actor={actor} />
+			</header>
+			<main class="demo-content" data-demo-content>
+				<PlayUIProvider actor={actor} registryResult={registryResult()}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			</main>
+			<DebugPanel actor={actor} />
+		</div>
+	);
+}
+```
+
+## Key Files
+
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/App.tsx` - actor lifecycle, registry construction, and `PlayUIProvider` + `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                                    |
+| ----------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-solid-demo run dev`          | Start Vite dev server (http://localhost:3002/) |
+| `pnpm --filter @xmachines/play-solid-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-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-demo run test
+pnpm --filter @xmachines/play-solid-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [Solid Router](../play-solid-router-demo/README.md)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [authCatalog](variables/authCatalog.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [DebugPanel](variables/DebugPanel.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [NavBar](variables/NavBar.md)
+- [NavBarView](variables/NavBarView.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Shell](variables/Shell.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [App](functions/App.md)

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / App
+
+# Function: App()
+
+```ts
+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/packages/play-solid/examples/demo/src/App.tsx#L34)
+
+## 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/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)
+
+## Parameters
+
+| Parameter     | Type                        |
+| ------------- | --------------------------- |
+| `props`       | \{ `actor`: `AuthActor`; \} |
+| `props.actor` | `AuthActor`                 |
+
+## 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/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/HeaderNav.tsx#L5)
+
+## Parameters
+
+| Parameter     | Type                        |
+| ------------- | --------------------------- |
+| `props`       | \{ `actor`: `AuthActor`; \} |
+| `props.actor` | `AuthActor`                 |
+
+## 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/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/Shell.tsx#L7)
+
+## Parameters
+
+| Parameter        | Type                                                                               | Description                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `props`          | \{ `actor`: `AuthActor`; `registry`: `ComponentRegistry`; `router?`: `unknown`; \} | -                                                                                |
+| `props.actor`    | `AuthActor`                                                                        | -                                                                                |
+| `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/type-aliases/AuthCatalog.md

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

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+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/packages/play-solid/examples/demo/src/components/About.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Contact.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L9)

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

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / DebugPanel
+
+# Variable: DebugPanel
+
+```ts
+const DebugPanel: Component<{
+	actor: AuthActor;
+}>;
+```
+
+Defined in: [packages/play-solid/examples/demo/src/components/DebugPanel.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L10)
+
+DebugPanel — Live debug footer.
+Observes actor.state and actor.currentRoute via watchSignal;
+cleans up via onCleanup.

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Home.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Login.tsx#L12)

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

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / NavBar
+
+# Variable: NavBar
+
+```ts
+const NavBar: Component<{
+	actor: AuthActor;
+}>;
+```
+
+Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-solid/examples/demo/src/components/NavBar.tsx#L15)

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

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / NavBarView
+
+# Variable: NavBarView
+
+```ts
+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/packages/play-solid/examples/demo/src/components/NavBarView.tsx#L11)
+
+NavBarView — Catalog-typed NavBar for use in defineRegistry components map.
+
+Receives props from the spec (isAuthenticated, username) and renders a
+static status indicator. Navigation buttons live in the shell-level NavBar
+component which calls actor.send() directly.

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Navigation.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Overview.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Profile.tsx#L9)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Settings.tsx#L9)

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

@@ -0,0 +1,17 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Shell
+
+# Variable: Shell
+
+```ts
+const Shell: Component<{
+	actor: AuthActor;
+	registryResult: DefineRegistryResult;
+	router?: unknown;
+}>;
+```
+
+Defined in: [packages/play-solid/examples/demo/src/components/Shell.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-solid/examples/demo/src/components/Shell.tsx#L13)
+
+Shell — Demo shell layout component.
+Renders standard demo chrome (header + PlayUIProvider/PlayRenderer + DebugPanel).
+Router-agnostic — navigation via play.route events.

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+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/packages/play-solid/examples/demo/src/components/Stats.tsx#L9)

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

@@ -0,0 +1,172 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-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-solid/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-solid/examples/demo/src/catalog.ts#L5)