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

package/api/@xmachines/shared/README.md

@@ -140,7 +140,7 @@ What the shared Vitest layer provides automatically:
 - Shared setup injection (`config/vitest.setup.ts`) unless already present
 - Node setup injection (`config/vitest.node.setup.ts`) for non-browser projects
 - Runtime preflight:
-  - Node.js runtime/version check (`>=22`) in node setup
+    - Node.js runtime/version check (`>=22`) in node setup
 - DOM matcher extension via `@testing-library/jest-dom/vitest`
 
 ### Vitest Setup Injection Rules
@@ -190,9 +190,9 @@ import { foo } from "./bar"; // ❌ Wrong
 - **Plugins:** TypeScript, Unicorn, Import
 - **Categories:** Correctness (error), Suspicious (warn), Performance (warn)
 - **Key Rules:**
-  - Circular dependency detection (`import/no-cycle`)
-  - Unused variables (allow `_` prefix)
-  - TypeScript-specific checks
+    - Circular dependency detection (`import/no-cycle`)
+    - Unused variables (allow `_` prefix)
+    - TypeScript-specific checks
 
 ### Oxfmt (`config/oxfmt.json`)
 
@@ -206,14 +206,14 @@ import { foo } from "./bar"; // ❌ Wrong
 - **Helper API:** `defineXmVitestConfig(importMetaUrl, overrides)` merges shared defaults with package-specific Vitest config
 - **Auto-aliasing:** `resolve.alias` is wired to `xmAliases(importMetaUrl)` so workspace packages resolve to source
 - **Cross-runtime setup (`config/vitest.setup.ts`):**
-  - extends `expect` with `@testing-library/jest-dom/vitest`
+    - extends `expect` with `@testing-library/jest-dom/vitest`
 - **URLPattern setup (`config/vitest.urlpattern.setup.ts`):**
-  - loads `urlpattern-polyfill` — opt-in per package via `setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"]`
-  - required for packages exercising URLPattern-based route matching (play-router and adapters)
-  - mirrors what consumers must do in production on Node < 24 or older browsers
+    - loads `urlpattern-polyfill` — opt-in per package via `setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"]`
+    - required for packages exercising URLPattern-based route matching (play-router and adapters)
+    - mirrors what consumers must do in production on Node < 24 or older browsers
 - **Node-only setup (`config/vitest.node.setup.ts`):**
-  - asserts Node runtime (`process.release.name === "node"`)
-  - enforces Node version `>=22`
+    - asserts Node runtime (`process.release.name === "node"`)
+    - enforces Node version `>=22`
 - **Browser behavior:** Browser projects do not receive node-only setup injection
 - **Override model:** Package-level config still controls test environment, includes/excludes, plugins, coverage, and browser provider
 
@@ -228,22 +228,22 @@ import { foo } from "./bar"; // ❌ Wrong
 ### Vite Alias Troubleshooting
 
 - **`[xmAliases] Could not find workspace root`**
-  - Ensure `xmAliases` receives `import.meta.url` from the calling config file.
-  - Ensure the config file lives somewhere under the monorepo root.
+    - Ensure `xmAliases` receives `import.meta.url` from the calling config file.
+    - Ensure the config file lives somewhere under the monorepo root.
 - **Workspace package import resolves to missing `dist/` files**
-  - Ensure config includes `resolve.alias: xmAliases(import.meta.url)`.
-  - Re-run after cleaning caches when lockfile/deps changed.
+    - Ensure config includes `resolve.alias: xmAliases(import.meta.url)`.
+    - Re-run after cleaning caches when lockfile/deps changed.
 
 ### Vitest Troubleshooting
 
 - **`URLPattern is unavailable after setup`**
-  - Ensure `test.setupFiles` is not replacing shared setup unexpectedly.
-  - Ensure config is created via `defineXmVitestConfig(...)`.
+    - Ensure `test.setupFiles` is not replacing shared setup unexpectedly.
+    - Ensure config is created via `defineXmVitestConfig(...)`.
 - **`Node runtime is required for this Vitest configuration`**
-  - This indicates node-only setup loaded in a browser project.
-  - Set `test.browser.enabled: true` in that project config.
+    - This indicates node-only setup loaded in a browser project.
+    - Set `test.browser.enabled: true` in that project config.
 - **Workspace import resolution failures (e.g. `@xmachines/play-signals`)**
-  - Confirm config uses `defineXmVitestConfig(import.meta.url, ...)` so aliases are injected.
+    - Confirm config uses `defineXmVitestConfig(import.meta.url, ...)` so aliases are injected.
 
 ## TypeScript Composite Build System
 
@@ -311,31 +311,31 @@ When creating a new package:
 
 1. **Add to root tsconfig.json references:**
 
-   ```json
-   {
-   	"references": [{ "path": "./packages/your-new-package" }]
-   }
-   ```
+    ```json
+    {
+    	"references": [{ "path": "./packages/your-new-package" }]
+    }
+    ```
 
 2. **Enable composite in package tsconfig.json:**
 
-   ```json
-   {
-   	"extends": "@xmachines/shared/tsconfig",
-   	"compilerOptions": {
-   		"composite": true,
-   		"rootDir": "./src",
-   		"outDir": "./dist"
-   	}
-   }
-   ```
+    ```json
+    {
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": {
+    		"composite": true,
+    		"rootDir": "./src",
+    		"outDir": "./dist"
+    	}
+    }
+    ```
 
 3. **Declare dependencies (if any):**
-   ```json
-   {
-   	"references": [{ "path": "../dependency-package" }]
-   }
-   ```
+    ```json
+    {
+    	"references": [{ "path": "../dependency-package" }]
+    }
+    ```
 
 ### IDE Benefits
 
@@ -355,14 +355,14 @@ To add a new shared configuration (e.g., for Jest, Vitest, etc.):
 
 1. Create `config/<tool>.json` (or `.js`, `.ts` as appropriate)
 2. Add exports to `package.json` exports field:
-   ```json
-   {
-   	"exports": {
-   		"./<tool>": "./config/<tool>.json",
-   		"./config/<tool>.json": "./config/<tool>.json"
-   	}
-   }
-   ```
+    ```json
+    {
+    	"exports": {
+    		"./<tool>": "./config/<tool>.json",
+    		"./config/<tool>.json": "./config/<tool>.json"
+    	}
+    }
+    ```
 3. Document in this README with usage examples
 4. Note whether the tool supports package exports or requires relative paths
 

package/api/@xmachines/shared/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/shared/src/index.ts#L10)
+Defined in: [index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/shared/src/index.ts#L10)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/shared/src/index.ts#L20)
+Defined in: [index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/shared/src/index.ts#L20)
 
 Build Vite/Vitest alias entries for all `@xmachines/*` workspace packages.
 

package/api/llms.txt

@@ -54,8 +54,8 @@
 ## Quick Reference
 
 ```javascript
-import { definePlayer, formatPlayRouteTransitions } from '@xmachines/play-xstate';
-import { extractMachineRoutes } from '@xmachines/play-router';
+import { definePlayer } from '@xmachines/play-xstate';
+import { createRouteMap, extractMachineRoutes } from '@xmachines/play-router';
 import { defineRegistry } from '@json-render/react';
 import { PlayRenderer } from '@xmachines/play-react';
 
@@ -66,6 +66,8 @@ actor.start();
 const currentView = actor.currentView.get();
 const currentRoute = actor.currentRoute.get();
 const routeTree = extractMachineRoutes(machine);
+const routeMatcher = createRouteMap(routeTree);
+const routeMatch = routeMatcher.match(currentRoute ?? '/');
 
 const { registry } = defineRegistry(catalog, { components, actions });
 <PlayRenderer actor={actor} registry={registry} actions={{ login: 'auth.login' }} />

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

@@ -144,8 +144,8 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Play DOM package README](../../README.md)
-- [Play DOM Router demo README](../../../play-dom-router/examples/demo/README.md)
+- [Play DOM](../../README.md)
+- [Play DOM Router](../../../play-dom-router/examples/demo)
 
 ## Type Aliases
 

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,10 +6,11 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBar.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/examples/demo/src/components/NavBar.ts#L15)
+Defined in: [play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
-Create and mount a reactive NavBar into the given container element.
-Returns a cleanup function to stop watching.
+NavBar — App-shell navigation factory. Mounts a reactive nav into
+`container`, observes actor.state via watchSignal, and updates button
+visibility based on auth state. Returns a disconnect function.
 
 ## Parameters
 

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -6,7 +6,11 @@
 function initShell(actor, appElement): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/shell.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/examples/demo/src/shell.ts#L35)
+Defined in: [play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+
+Shell — DOM shell layout factory. Renders demo chrome (header + main +
+debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.
+Returns a disconnect function.
 
 ## Parameters
 

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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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

@@ -156,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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.34/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.