@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+type AuthCatalog = typeof authCatalog;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/catalog.ts#L6)

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

@@ -0,0 +1,12 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/About.ts#L8)
+
+About — Public information page. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

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

@@ -0,0 +1,12 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+
+Contact — Public contact page. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+
+Dashboard — Protected authenticated home. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout
+button emits 'logout' action.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+
+Home — Public landing page. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Home'>). Renders static welcome content from
+props.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+
+Login — Authentication form. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Login'>). Binds username input to ctx.store via
+$bindState; emits 'submit' on form submit.

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / NavBarView
+
+# Variable: NavBarView
+
+```ts
+const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
+
+NavBarView — Catalog-typed NavBar component for DOM renderer.
+
+Receives props from spec (isAuthenticated, username) and renders a static nav element.
+Used in the defineRegistry components map.
+
+The actor-driven NavBar (createNavBar) is mounted at the shell level.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
+
+Navigation — Navigation status display. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Navigation'>). Renders current path and auth
+status from props.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
+
+Overview — Dashboard overview child route. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Overview'>). Relative route resolves to
+/dashboard/overview. Logout and goToStats buttons emit actions.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Profile.ts#L9)
+
+Profile — Protected user profile page. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Profile'>). Renders username from route params
+filled into props.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Settings.ts#L9)
+
+Settings — Protected settings page. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Settings'>). Renders active section and username
+from props.

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/Stats.ts#L9)
+
+Stats — Dashboard stats child route. Catalog-typed DOM component
+(ComponentFn<AuthCatalog, 'Stats'>). Relative route resolves to
+/dashboard/stats. goToOverview button emits action.

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

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

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

@@ -0,0 +1,145 @@
+[Examples](../../README.md) / @xmachines/play-dom-router-demo
+
+# @xmachines/play-dom-router-demo
+
+Pure TypeScript integration demo for [`@xmachines/play-dom-router`](../../../api/@xmachines/play-dom-router/README.md) — actor-authoritative routing with the Browser History API and no framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRouter` + `createBrowserHistory` wiring actor ↔ browser History API
+- Shell-driven DOM rendering via `connectRenderer` with actor-authoritative navigation
+- Manual TC39 Signal watcher lifecycle — the mechanism that framework adapters abstract
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-dom-router-demo run dev
+```
+
+Then open `http://localhost:3005`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` looks up the host element (throws if absent), calls `initApp(app)` from `src/runtime.ts`, and registers unload cleanup.
+2. `src/runtime.ts` creates the actor from the shared machine via `definePlayer`, starts it, initializes router sync via `initRouter(actor)`, mounts the shared DOM shell via `initShell(actor, host)`, and returns one cleanup function.
+3. `initRouter(actor)` from `src/router.ts` extracts route metadata, creates a browser history wrapper, instantiates a router, and calls `connectRouter` to wire bidirectional actor ↔ URL sync.
+4. `initShell(actor, host)` is imported from `@xmachines/play-dom-demo`, so the router demo reuses the shared DOM shell instead of duplicating the scaffold and renderer wiring.
+5. Navigation buttons and links dispatch `play.route`, `auth.login`, and `auth.logout` events directly to the actor — no URL mutations from the shell.
+6. Browser tests in `test/browser/` validate startup rendering and the full auth route flow.
+
+```ts
+// src/main.ts (shape)
+const app = document.getElementById("app");
+if (!app) throw new Error("Root element not found");
+
+const cleanup = initApp(app);
+
+window.addEventListener("beforeunload", () => {
+	cleanup();
+});
+```
+
+```ts
+// src/router.ts (shape)
+export function initRouter(actor) {
+	const routeTree = extractMachineRoutes(authMachine);
+	const routeMap = createRouteMap(authMachine);
+	const history = createBrowserHistory({ window });
+	const router = createRouter({ routeTree, history });
+	const disconnect = connectRouter({ actor, router, routeMap });
+
+	return () => {
+		disconnect();
+		router.destroy();
+	};
+}
+```
+
+```ts
+// src/runtime.ts (shape)
+export function initApp(host: HTMLElement): () => void {
+	const createPlayer = definePlayer({ machine: authMachine });
+	const actor = createPlayer();
+	actor.start();
+
+	const cleanupRouter = initRouter(actor);
+	const cleanupShell = initShell(actor, host);
+
+	return () => {
+		cleanupShell();
+		cleanupRouter();
+		actor.stop();
+	};
+}
+```
+
+## Key Files
+
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/runtime.ts` - actor startup, router initialization, and shared shell wiring
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `@xmachines/play-dom-demo` - shared DOM shell, NavBar, DebugPanel, and renderer wiring reused by this router demo
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - startup rendering and full auth route browser flow
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants at the lowest level:
+
+1. **Actor Authority:** Intercepting browser `popstate` events or navigation button clicks dispatches a `play.route` event to the actor. The actor processes the request against the current state, ensuring any auth logic is correctly applied.
+2. **Passive Infrastructure:** The router simply updates `window.history` and the DOM solely renders HTML based on what `actor.currentView` yields. Neither holds business state.
+3. **Signal-Only Reactivity:** The integration registers `watchSignal` observers that trigger DOM reconciliation, illustrating the underlying mechanism that framework adapters abstract.
+
+## Watcher Lifecycle and Cleanup Contract
+
+Even in the vanilla demo, watcher handling follows the canonical lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and project DOM state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot, so re-arm is mandatory. Router/shell teardown must explicitly call cleanup (`disconnect`/`unwatch`) and not rely on GC-only behavior. In vanilla TypeScript, this means retaining cleanup functions and calling them on `beforeunload` or during hot-module replacement.
+
+## Adapter Boundaries
+
+`connectRouter` and browser-history wiring (from [`@xmachines/play-dom-router`](../../../api/@xmachines/play-dom-router/README.md)) are passive infrastructure. Actor logic remains authoritative for route validity, and shared synchronization policy stays in `RouterBridgeBase` for framework bridges. This demo proves frameworks are not required for Play Architecture to work.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                          | Description                                    |
+| ---------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-router-demo run dev`          | Start Vite dev server (http://localhost:3005/) |
+| `pnpm --filter @xmachines/play-dom-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-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-dom-router-demo run test
+pnpm --filter @xmachines/play-dom-router-demo run test:browser
+```
+
+Expected result: tests pass, including startup rendering and the full browser auth flow in `test/browser/`.
+
+## Learn More
+
+- [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
+- [Play DOM](../play-dom-demo/README.md)
+- [Play Router](../../../api/@xmachines/play-router/README.md)

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

@@ -0,0 +1,187 @@
+[Examples](../../README.md) / @xmachines/play-react-demo
+
+# @xmachines/play-react-demo
+
+React renderer demo for [`@xmachines/play-react`](../../../api/@xmachines/play-react/README.md) — actor + `PlayRenderer` without a router.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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 `play.route` routing
+- Canonical TC39 Signals lifecycle surfaced through React's rendering model
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-react-demo run dev
+```
+
+Then open `http://localhost:3001`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` creates the actor at module scope via `definePlayer({ machine: authMachine })()` — created once when the module is first evaluated.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — 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)
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+```tsx
+// src/App.tsx (shape)
+// Both actor and registryResult are module-scope singletons — created once,
+// never recreated, no useMemo needed inside the component.
+const actor: AuthActor = definePlayer({ machine: authMachine })();
+actor.start();
+
+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 }),
+			});
+		},
+	},
+});
+
+export function App() {
+	return (
+		<div className="demo-app" data-demo-shell>
+			<header className="demo-header">
+				<h1 className="demo-title">XMachines Play React Demo</h1>
+				<NavBar actor={actor} />
+			</header>
+			<main className="demo-content" data-demo-content>
+				<PlayUIProvider actor={actor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			</main>
+			<DebugPanel actor={actor} />
+		</div>
+	);
+}
+```
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - actor lifecycle, registry construction, and `PlayUIProvider` + `PlayRenderer` composition
+- `src/catalog.ts` - catalog definition using `defineCatalog` from `@xmachines/json-render-core` with `@xmachines/json-render-react/schema`
+- `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 — React 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 React's rendering model to react precisely when actor signals update, without polluting the component tree with `useState` or `useEffect` 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 React render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: `actor.stop()` is called on component unmount via `useEffect`, and `PlayRenderer` handles internal watcher teardown natively.
+
+## Adapter Boundaries
+
+`PlayRenderer` and `defineRegistry` stay passive infrastructure. Business validity remains actor-owned. The registry maps catalog component keys to React 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-react-demo run dev`          | Start Vite dev server (http://localhost:3001/) |
+| `pnpm --filter @xmachines/play-react-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-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-react-demo run test
+pnpm --filter @xmachines/play-react-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [play-react](../../../api/@xmachines/play-react/README.md)
+- [React Router demo](../play-react-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)