@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / App
+
+# Function: App()
+
+```ts
+function App(): Element;
+```
+
+Defined in: [packages/play-react/examples/demo/src/App.tsx:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/App.tsx#L72)
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-react-demo/functions/DebugPanel.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / DebugPanel
+
+# Function: DebugPanel()
+
+```ts
+function DebugPanel(__namedParameters): Element;
+```
+
+Defined in: [components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L5)
+
+## Parameters
+
+| Parameter                 | Type                        |
+| ------------------------- | --------------------------- |
+| `__namedParameters`       | \{ `actor`: `AuthActor`; \} |
+| `__namedParameters.actor` | `AuthActor`                 |
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-react-demo/functions/HeaderNav.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / HeaderNav
+
+# Function: HeaderNav()
+
+```ts
+function HeaderNav(__namedParameters): Element;
+```
+
+Defined in: [components/HeaderNav.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/HeaderNav.tsx#L13)
+
+## Parameters
+
+| Parameter                 | Type                        |
+| ------------------------- | --------------------------- |
+| `__namedParameters`       | \{ `actor`: `AuthActor`; \} |
+| `__namedParameters.actor` | `AuthActor`                 |
+
+## Returns
+
+`Element`

package/examples/@xmachines/play-react-demo/functions/Shell.md

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Shell
+
+# Function: Shell()
+
+```ts
+function Shell(__namedParameters): Element;
+```
+
+Defined in: [components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/Shell.tsx#L14)
+
+## Parameters
+
+| Parameter                    | Type                                                                               | Description                                                                      |
+| ---------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `__namedParameters`          | \{ `actor`: `AuthActor`; `registry`: `ComponentRegistry`; `router?`: `unknown`; \} | -                                                                                |
+| `__namedParameters.actor`    | `AuthActor`                                                                        | -                                                                                |
+| `__namedParameters.registry` | `ComponentRegistry`                                                                | -                                                                                |
+| `__namedParameters.router?`  | `unknown`                                                                          | Bridged router instance — accepted for prop parity with router demos but unused. |
+
+## Returns
+
+`Element`

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

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

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/About.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/About.tsx#L10)
+
+About — Public information page
+
+Uses ComponentFn<AuthCatalog, "About"> for catalog-typed props.
+Navigation is handled by HeaderNav — this component only renders content.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Contact.tsx#L10)
+
+Contact — Public contact page
+
+Uses ComponentFn<AuthCatalog, "Contact"> for catalog-typed props.
+Navigation is handled by HeaderNav — this component only renders content.

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

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Dashboard.tsx#L12)
+
+Dashboard — Protected authenticated home
+
+Uses ComponentFn<AuthCatalog, "Dashboard"> for catalog-typed props.
+Emits "logout" to trigger the auth.logout event via PlayRenderer actions map.
+Navigation is handled by HeaderNav — this component only handles auth actions.

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / DebugPanel
+
+# Variable: DebugPanel
+
+```ts
+const DebugPanel: FC<{
+	actor: AuthActor;
+	inspector: DemoInspector;
+}>;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L11)
+
+DebugPanel — Live debug footer. Observes actor.state and actor.currentRoute
+via useSignalEffect and displays current state value, can-logout status,
+and active route, plus the button that opens the Stately inspector window.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Home.tsx#L10)
+
+Home - Public landing page component
+
+Uses ComponentFn<AuthCatalog, "Home"> for catalog-typed props.
+Navigation is handled by HeaderNav — this component only renders content.

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Login.tsx#L14)
+
+Login — Authentication form
+
+Uses ComponentFn<AuthCatalog, "Login"> for catalog-typed props.
+Username is bound via $bindState from the spec — useStateBinding provides reactive two-way
+binding to the @xstate/store atom backing the current view's state store.
+Emits "submit" on form submit — spec resolves the username state and calls login handler.

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / NavBar
+
+# Variable: NavBar
+
+```ts
+const NavBar: FC<{
+	actor: AuthActor;
+}>;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/NavBar.tsx#L12)
+
+NavBar — App-shell navigation component.
+
+Framework component (takes `actor`) used in the App shell header.
+Calls actor.send() directly for navigation — ActionProvider not needed here.

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

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / NavBarView
+
+# Variable: NavBarView
+
+```ts
+const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/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-react-demo/variables/Navigation.md

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Navigation.tsx#L10)
+
+Navigation - Status display component
+
+Uses ComponentFn<AuthCatalog, "Navigation"> for catalog-typed props.
+This component displays navigation state info. Actual navigation is handled by HeaderNav.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Overview.tsx#L10)
+
+Overview - Dashboard overview child route component
+
+Uses ComponentFn<AuthCatalog, "Overview"> for catalog-typed props.
+Relative route "overview" resolves to /dashboard/overview.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Profile.tsx#L11)
+
+Profile — Protected user profile page
+
+Uses ComponentFn<AuthCatalog, "Profile"> for catalog-typed props.
+Navigation is handled by HeaderNav — this component only renders content.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Settings.tsx#L11)
+
+Settings — Protected settings page
+
+Uses ComponentFn<AuthCatalog, "Settings"> for catalog-typed props.
+Navigation is handled by HeaderNav — this component only renders content.

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

@@ -0,0 +1,19 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Shell
+
+# Variable: Shell
+
+```ts
+const Shell: FC<{
+	actor: AuthActor;
+	inspector: DemoInspector;
+	registryResult: DefineRegistryResult;
+	router?: unknown;
+}>;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Shell.tsx#L14)
+
+Demo Shell layout component.
+
+Wraps NavBar, PlayRenderer, and DebugPanel in the standard demo chrome.
+Router-agnostic — all navigation is driven via play.route events on the actor.

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/examples/demo/src/components/Stats.tsx#L10)
+
+Stats - Dashboard stats child route component
+
+Uses ComponentFn<AuthCatalog, "Stats"> for catalog-typed props.
+Relative route "stats" resolves to /dashboard/stats.

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

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

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

@@ -0,0 +1,151 @@
+[Examples](../../README.md) / @xmachines/play-react-router-demo
+
+# @xmachines/play-react-router-demo
+
+React Router v7 integration demo for the XMachines Play architecture.
+
+[![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
+- `PlayRouterProvider` renderer-based integration with React Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle mapped to React's rendering loop
+- Browser E2E coverage via a shared demo browser suite
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-react-router-demo run dev
+```
+
+Then open `http://localhost:3006`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and browser router, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(authMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` creates the actor, builds a `registryResult` from the registry, and constructs a React Router data router with a `RoutedShell` wrapper.
+5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
+6. `Shell` (inside `App.tsx`) receives `actor`, `router`, and `registryResult`, matching the other router demos.
+7. The `renderer` prop renders `<RouterProvider router={currentRouter} />` directly — no intermediate `ReactRouterApp` wrapper is needed.
+8. Browser tests in `test/browser/` validate startup and auth navigation flow via a shared demo suite.
+
+```tsx
+// src/main.tsx (shape)
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+```ts
+// src/runtime.ts (shape)
+export const createPlayer = definePlayer({ machine: authMachine });
+export const routeMap = createRouteMap(authMachine);
+
+export function createRegistryResult(actor: ReturnType<typeof createPlayer>) {
+	return defineRegistry(authCatalog, {
+		components: { Home, About, Contact, Login, Dashboard /* … */ },
+		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 }),
+		},
+	});
+}
+```
+
+```tsx
+// src/App.tsx (shape)
+function createAppRuntime() {
+	const actor = createPlayer();
+	actor.start();
+
+	const registryResult = createRegistryResult(actor);
+
+	let router!: BrowserRouterInstance;
+
+	function RoutedShell() {
+		return <Shell actor={actor} router={router} registryResult={registryResult} />;
+	}
+
+	router = createBrowserRouter([{ path: "*", element: <RoutedShell /> }]);
+
+	return { actor, router };
+}
+
+const { actor, router } = useMemo(createAppRuntime, []);
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(_, currentRouter) => <RouterProvider router={currentRouter} />}
+	/>
+);
+```
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, provider wiring, and `RoutedShell` composition
+- `test/browser/shared-demo.browser.test.tsx` - browser E2E suite for startup and auth navigation flow
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** Navigation triggers URL changes, which the `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates whether navigation is permitted. The React application only triggers renders.
+3. **Signal-Only Reactivity:** The bridge leverages React's `useSyncExternalStore` (internally within the hooks) to react precisely when signals update, without polluting the React component tree with `useState` or `useEffect` for business logic.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the same watcher lifecycle used across [`@xmachines/play-signals`](../../../api/@xmachines/play-signals/README.md) and framework adapters:
+
+1. `notify`
+2. `queueMicrotask`
+3. Drain pending work with `getPending()`
+4. Read actor signals and project framework-local state
+5. Re-arm via `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: bridge/provider teardown must call `disconnect`/`unwatch` paths, never rely on GC-only cleanup. The `PlayRouterProvider` handles this natively on component unmount.
+
+## Adapter Boundaries
+
+`PlayRouterProvider` and the React Router bridge stay passive infrastructure. Business validity remains actor-owned, while `RouterBridgeBase` remains the shared policy layer and the concrete React adapter stays a thin port, delegating DOM synchronization to React Router. The demo keeps the same `Shell(actor, router, registryResult)` shape as the other router demos, with `RouterProvider` rendered directly inside the `renderer` callback — no additional wrapper component is required.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                            | Description                                    |
+| ------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-react-router-demo run dev`          | Start Vite dev server (http://localhost:3006/) |
+| `pnpm --filter @xmachines/play-react-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-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-react-router-demo run test
+pnpm --filter @xmachines/play-react-router-demo run test:browser
+```
+
+Expected result: tests pass for startup and auth-flow browser scenarios.
+
+## Learn More
+
+- [React Router](../../../api/@xmachines/play-react-router/README.md)
+- [React](../../../api/@xmachines/play-react/README.md)