@xmachines/docs 1.0.0-beta.33 → 1.0.0-beta.35

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

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

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

@@ -6,4 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/About.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/About.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Contact.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Contact.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Dashboard.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Dashboard.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Home.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Home.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Login.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Login.ts#L7)
+Defined in: [play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,11 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/NavBarView.ts#L13)
+Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Navigation.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Navigation.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Overview.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Overview.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Profile.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Profile.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Settings.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Settings.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,8 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Stats.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Stats.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

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

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

@@ -27,22 +27,22 @@ Then open `http://localhost:5174`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` creates the actor from the shared machine and starts it.
-2. `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.
-3. `initShell(actor, app)` from `src/shell.ts` builds the DOM scaffold and sets up the `connectRenderer` loop for view switching.
-4. Navigation buttons and links dispatch `play.route`, `auth.login`, and `auth.logout` events directly to the actor — no URL mutations from the shell.
-5. Browser tests in `test/browser/` validate startup rendering and the full auth route flow.
+1. `src/main.ts` looks up the host element, calls `initApp(app)` from `src/runtime.ts`, and registers unload cleanup.
+2. `src/runtime.ts` creates the actor from the shared machine, 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 actor = createPlayer();
-actor.start();
-
-const cleanupRouter = initRouter(actor);
 const app = document.getElementById("app");
+let cleanup;
 if (app) {
-	initShell(actor, app);
+	cleanup = initApp(app);
 }
+
+window.addEventListener("beforeunload", () => cleanup?.());
 ```
 
 ```ts
@@ -62,22 +62,26 @@ export function initRouter(actor) {
 ```
 
 ```ts
-// src/shell.ts (shape)
-const disconnectRenderer = connectRenderer({ actor, registry, container: viewContent });
+// src/runtime.ts (shape)
+const actor = createPlayer();
+actor.start();
 
-const unwatchState = watchSignal(actor.state, () => {
-	navLogin.hidden = snapshot.context.isAuthenticated;
-	navLogout.hidden = !snapshot.context.isAuthenticated;
-});
+const cleanupRouter = initRouter(actor);
+const cleanupShell = initShell(actor, host);
 
-navLogin.addEventListener("click", () => actor.send({ type: "play.route", to: "#login" }));
+return () => {
+	cleanupShell();
+	cleanupRouter();
+	actor.stop();
+};
 ```
 
 ## Key Files
 
-- `src/main.ts` - actor startup, router initialization, and shell bootstrap
+- `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
-- `src/shell.ts` - DOM scaffold, `DomRegistry` construction, `connectRenderer`, and reactive watcher loop
+- `@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/startup.browser.test.ts` - startup rendering assertion for public home + login action
 - `test/browser/auth-flow.browser.test.ts` - login → dashboard → profile → logout browser flow
@@ -131,6 +135,6 @@ Expected result: tests pass, including startup rendering and the full browser au
 
 ## Learn More
 
-- [Play DOM Router package README](../../README.md)
-- [Play DOM demo README](../../../play-dom/examples/demo/README.md)
-- [Play Router package README](../../../play-router/README.md)
+- [Play DOM Router](../../README.md)
+- [Play DOM](../../../play-dom/examples/demo)
+- [Play Router](../../../play-router)

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

@@ -27,64 +27,71 @@ Then open `http://localhost:5173`.
 
 Use this order to understand the implementation:
 
-1. `src/main.tsx` mounts `<App />` inside `<StrictMode>`.
-2. `src/App.tsx` creates the actor via `definePlayer({ machine: authMachine })` inside `useMemo` so it is started once per mounted app.
-3. `defineRegistry(authCatalog, { components, actions })` builds the typed component registry from the shared catalog.
-4. `<PlayRenderer actor={actor} registry={registry} actions={...} />` observes actor view signals and renders the current component.
-5. A `useEffect` cleanup calls `actor.stop()` on unmount.
-6. Browser tests in `test/browser/` validate startup and interaction behavior.
+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(
-	<StrictMode>
-		<App />
-	</StrictMode>,
-);
+createRoot(document.getElementById("root")!).render(<App />);
 ```
 
 ```tsx
 // src/App.tsx (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-
-const { registry } = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-	},
-	actions: { login: async () => {}, logout: async () => {} },
-});
+const actor: AuthActor = definePlayer({ machine: authMachine })();
+actor.start();
 
 export function App() {
-	const actor = useMemo((): DemoActor => {
-		const a = createPlayer();
-		a.start();
-		return a;
-	}, []);
-
-	useEffect(
-		() => () => {
-			actor.stop();
-		},
-		[actor],
+	const registryResult = useMemo(
+		() =>
+			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 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>
-				<PlayRenderer
-					actor={actor}
-					registry={registry}
-					actions={{ login: "auth.login", logout: "auth.logout" }}
-				/>
+				<PlayUIProvider actor={actor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
 			</main>
 			<DebugPanel actor={actor} />
 		</div>
@@ -94,8 +101,8 @@ export function App() {
 
 ## Key Files
 
-- `src/main.tsx` - React entry point that mounts `<App />` inside `StrictMode`
-- `src/App.tsx` - actor lifecycle, registry construction, and `PlayRenderer` composition
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `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
@@ -149,8 +156,8 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [React package README](../../README.md)
-- [React Router demo README](../../../play-react-router/examples/demo/README.md)
+- [React](../../README.md)
+- [React Router](../../../play-react-router/examples/demo)
 
 ## Type Aliases
 

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

@@ -6,7 +6,7 @@
 function App(): Element;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/App.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/App.tsx#L36)
+Defined in: [packages/play-react/examples/demo/src/App.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/play-react/examples/demo/src/App.tsx#L36)
 
 ## Returns
 

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

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

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

@@ -6,4 +6,9 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/About.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/About.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/About.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Contact.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,10 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Dashboard.tsx#L15)
+Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -8,4 +8,8 @@ const DebugPanel: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L6)
+Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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.

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

@@ -6,4 +6,9 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Home.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,11 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Login.tsx#L16)
+Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -8,4 +8,9 @@ const NavBar: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/NavBar.tsx#L13)
+Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,10 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/NavBarView.tsx#L12)
+Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Navigation.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Overview.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Profile.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Settings.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -10,4 +10,9 @@ const Shell: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Shell.tsx#L15)
+Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

@@ -6,4 +6,9 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/examples/demo/src/components/Stats.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/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

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

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

@@ -79,7 +79,9 @@ return (
 // src/components/Login.tsx (shape)
 export function Login() {
 	return (
-		<button onClick={() => actor.send({ type: "auth.login", username, password })}>Login</button>
+		<button onClick={() => actor.send({ type: "auth.login", username, password })}>
+			Login
+		</button>
 	);
 }
 ```
@@ -141,5 +143,5 @@ Expected result: tests pass for startup and auth-flow browser scenarios.
 
 ## Learn More
 
-- [React Router package README](../../README.md)
-- [React package README](../../../play-react/README.md)
+- [React Router](../../README.md)
+- [React](../../../play-react)