@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-router/interfaces/PlayRouteEvent.md

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: [types.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L190)
+
+Enhanced routing event with parameter and query support
+
+Unified routing event used throughout the Play architecture. Supports parameter-aware
+navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
+user navigation intent that the Actor evaluates through guards. Infrastructure proposes
+via `play.route` events, Actor decides via state machine transitions.
+
+**Browser Navigation Flow:**
+
+1. Browser fires `popstate`
+2. Router adapter resolves URL to route target
+3. Adapter sends `PlayRouteEvent` to Actor
+4. Actor validates transition via state machine guards
+
+## Param
+
+Event discriminator (always "play.route")
+
+## Param
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+Merged path + query parameters (path parameters win conflicts)
+
+## Param
+
+Query parameters only (isolated from path params)
+
+## Param
+
+Full URLPattern match result for debugging/observability (optional)
+
+## Examples
+
+Combining base and routing events
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+type AppEvent = PlayEvent | PlayRouteEvent;
+```
+
+Basic navigation to a route
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#home",
+};
+actor.send(event);
+```
+
+Navigation with route parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#profile",
+	params: { userId: "123" },
+};
+actor.send(event);
+// Resolves to route: /profile/123
+```
+
+Navigation with query parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#settings",
+	params: { section: "profile" }, // Merged: path + query
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## Remarks
+
+Use `play.route` when you need parameter-aware navigation with the `route: {}`
+config pattern on your state machine nodes. The `match` field exposes the full
+URLPatternResult for advanced use cases (debugging, pattern analysis).
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                                        |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L195) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L193) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:194](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L194) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L192) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L191) |

package/api/@xmachines/play-router/interfaces/RouteInfo.md

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteInfo
+
+# Interface: RouteInfo
+
+Defined in: [types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L40)
+
+Extracted route information from a state node
+
+## Properties
+
+| Property                                      | Type                                                | Description                                                                                          | Defined in                                                                                                                                      |
+| --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L50) |
+| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L57) |
+| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L48) |
+| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L55) |
+| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L46) |
+| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L42) |
+| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L44) |

package/api/@xmachines/play-router/interfaces/RouteMap.md

@@ -0,0 +1,56 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMap
+
+# Interface: RouteMap
+
+Defined in: [create-route-map.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L27)
+
+Bidirectional route resolution interface returned by `createRouteMap()`.
+
+Resolves incoming URL paths to state IDs (with `#` prefix) and extracts
+route parameters. Used by `RouterBridgeBase` to translate router navigation
+events into `play.route` actor events.
+
+## See
+
+- [createRouteMap](../functions/createRouteMap.md) for the factory function
+- [BaseRouteMap](../classes/BaseRouteMap.md) for direct state ID ↔ path lookups without params extraction
+
+## Methods
+
+### resolve()
+
+```ts
+resolve(path): object;
+```
+
+Defined in: [create-route-map.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L44)
+
+Resolve a URL path to a state ID and params.
+
+#### Parameters
+
+| Parameter | Type     | Description                              |
+| --------- | -------- | ---------------------------------------- |
+| `path`    | `string` | URL pathname (e.g., "/settings/account") |
+
+#### Returns
+
+`object`
+
+Object with `to` (state ID with # prefix) and `params`
+
+Example:
+
+```typescript
+const { to, params } = routeMap.resolve("/settings/account");
+// { to: "#settings", params: { section: "account" } }
+
+if (to) {
+	actor.send({ type: "play.route", to, params });
+}
+```
+
+| Name     | Type                           | Defined in                                                                                                                                                            |
+| -------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L46) |
+| `to`     | `string` \| `null`             | [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L45) |

package/api/@xmachines/play-router/interfaces/RouteNode.md

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteNode
+
+# Interface: RouteNode
+
+Defined in: [types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L63)
+
+Node in the route tree representing a single route
+
+## Properties
+
+| Property                                  | Type                  | Description                                                                                          | Defined in                                                                                                                                      |
+| ----------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-children"></a> `children` | `RouteNode`[]         | Child routes                                                                                         | [types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L80) |
+| <a id="property-fullpath"></a> `fullPath` | `string`              | Full resolved path from root                                                                         | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L69) |
+| <a id="property-id"></a> `id`             | `string`              | Unique identifier (state ID)                                                                         | [types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L65) |
+| <a id="property-metadata"></a> `metadata` | `unknown`             | Original meta.route metadata                                                                         | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L84) |
+| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null` | Parent route (null for root)                                                                         | [types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L82) |
+| <a id="property-path"></a> `path`         | `string`              | Route path segment (relative or absolute)                                                            | [types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L67) |
+| <a id="property-pattern"></a> `pattern?`  | `string`              | Route pattern with parameters (e.g., /profile/:userId) if path contains params                       | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L71) |
+| <a id="property-routable"></a> `routable` | `boolean`             | Whether this state is routable (has meta.route) States with meta.route can receive play.route events | [types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L78) |
+| <a id="property-stateid"></a> `stateId`   | `string`              | XState state ID this route maps to                                                                   | [types.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L73) |

package/api/@xmachines/play-router/interfaces/RouteObject.md

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteObject
+
+# Interface: RouteObject
+
+Defined in: [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L13)
+
+Route object with additional metadata.
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+Additional route metadata (title, breadcrumb, etc.)
+
+## Properties
+
+| Property                          | Type     | Description                             | Defined in                                                                                                                                      |
+| --------------------------------- | -------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L15) |

package/api/@xmachines/play-router/interfaces/RouteTree.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteTree
+
+# Interface: RouteTree
+
+Defined in: [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L94)
+
+Complete route tree with lookup maps
+
+Provides bidirectional mapping between state IDs and URL paths:
+
+- byStateId: Maps state IDs to route nodes (for play.route event targeting)
+- byPath: Maps URL paths to route nodes (for browser navigation)
+
+## Properties
+
+| Property                                    | Type                                           | Description                                                                                       | Defined in                                                                                                                                        |
+| ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map full path -> route node Used to look up state ID from URL path for play.route event targeting | [types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L106) |
+| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map state ID -> route node Used to look up URL path from state ID for browser URL sync            | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L101) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                    | Root route node                                                                                   | [types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L96)   |

package/api/@xmachines/play-router/interfaces/RouterBridge.md

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: [types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L238)
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+the Actor. Infrastructure "bridges" to the Actor by observing its signals and
+managing its own lifecycle accordingly.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+TanStack Router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class TanStackRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: [types.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L254)
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: [types.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L270)
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

package/api/@xmachines/play-router/interfaces/StateVisit.md

@@ -0,0 +1,15 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / StateVisit
+
+# Interface: StateVisit
+
+Defined in: [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L28)
+
+Represents a visit to a state node during graph crawling
+
+## Properties
+
+| Property                              | Type                                                     | Description                                                    | Defined in                                                                                                                                      |
+| ------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-node"></a> `node`     | `StateNode`                                              | The state node being visited                                   | [types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L30) |
+| <a id="property-parent"></a> `parent` | `StateNode`\<`MachineContext`, `EventObject`\> \| `null` | Parent state node (null for root)                              | [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L34) |
+| <a id="property-path"></a> `path`     | `string`[]                                               | Path from root to this state (e.g., ['dashboard', 'overview']) | [types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L32) |

package/api/@xmachines/play-router/interfaces/VanillaRouter.md

@@ -0,0 +1,28 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / VanillaRouter
+
+# Interface: VanillaRouter
+
+Defined in: [create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L4)
+
+## Properties
+
+| Property                                    | Modifier   | Type                                  | Description                          | Defined in                                                                                                                                                      |
+| ------------------------------------------- | ---------- | ------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md) | History instance                     | [create-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L8)   |
+| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](RouteTree.md)           | Route tree (for structure reference) | [create-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L13) |
+
+## Methods
+
+### destroy()
+
+```ts
+destroy(): void;
+```
+
+Defined in: [create-router.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L18)
+
+Cleanup
+
+#### Returns
+
+`void`

package/api/@xmachines/play-router/type-aliases/RouteMetadata.md

@@ -0,0 +1,11 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMetadata
+
+# Type Alias: RouteMetadata
+
+```ts
+type RouteMetadata = string | RouteObject;
+```
+
+Defined in: [types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/types.ts#L23)
+
+Route metadata from state machine `meta.route` field.

package/api/@xmachines/play-router-demo/README.md

@@ -0,0 +1,137 @@
+[Documentation](../../README.md) / @xmachines/play-router-demo
+
+# Vanilla JavaScript Router Demo
+
+Pure JavaScript integration proving Play Architecture works without any framework.
+
+## What This Demonstrates
+
+This demo uses **no framework** - just vanilla JavaScript with the Browser History API and DOM manipulation. It proves that Play Architecture's universal abstractions work at the lowest level, making framework integrations simpler by comparison.
+
+## Key Features
+
+- **Zero Framework Dependencies**: Pure JavaScript and DOM
+- **Browser History API**: Direct integration with `window.history`
+- **Same Auth Machine**: Identical authentication logic as React/Vue/SolidJS demos
+- **Reference Implementation**: This demo serves as the visual reference for all framework demos
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w packages/play-router/examples/demo
+```
+
+Visit `http://localhost:5174`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the demo implementation:
+
+1. `src/main.ts` creates the actor from the shared machine/catalog and starts it.
+2. `src/router.ts` extracts machine routes, builds browser-history routing primitives, and connects actor <-> router sync.
+3. `src/shell.ts` subscribes to actor signals and renders state-projected DOM views.
+4. Navigation and auth interactions dispatch actor events (`play.route`, `auth.login`, `auth.logout`) rather than mutating URL/state directly.
+5. Browser tests in `test/browser/` validate startup rendering and the auth route flow end-to-end.
+
+```ts
+// src/main.ts (shape)
+const actor = createActorFromSharedMachine();
+actor.start();
+
+const cleanupRouter = initRouter(actor);
+const app = document.getElementById("app");
+if (app) {
+	initShell(actor, app);
+}
+```
+
+```ts
+// src/router.ts (shape)
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(routeTree);
+const history = createBrowserHistory();
+const router = createRouter({ history, routeMap });
+connectRouter({ actor, router, routeMap });
+```
+
+```ts
+// src/shell.ts (shape)
+actor.currentView.watch(() => {
+	renderView(actor.currentView.get());
+});
+
+loginButton.onclick = () => actor.send({ type: "auth.login", username, password });
+logoutButton.onclick = () => actor.send({ type: "auth.logout" });
+```
+
+## Key Files
+
+- `src/main.ts` - actor startup, router initialization, and shell bootstrap
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `src/shell.ts` - DOM rendering and reactive watcher loop for state-driven updates
+- `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
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants at the lowest level:
+
+1. **Actor Authority:** Intercepting browser `popstate` events or link 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 text based on what `actor.currentView.get()` yields.
+3. **Signal-Only Reactivity:** The integration registers manual `Signal.subtle.Watcher` observers that manually trigger DOM reconciliation, illustrating the underlying mechanism abstraction used by framework adapters.
+
+## Watcher Lifecycle and Cleanup Contract
+
+Even in the vanilla demo, watcher handling follows the same 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 JS, this means retaining the cleanup functions and calling them during hot-module replacement or app unmount.
+
+## Adapter Boundaries
+
+`connectRouter` and browser-history wiring are passive infrastructure. Actor logic remains authoritative for route validity, and shared synchronization policy stays in `RouterBridgeBase` for framework bridges.
+
+## Why Vanilla?
+
+Vanilla JavaScript is the foundation:
+
+- **Universal Patterns**: If it works in vanilla, frameworks are just convenience layers
+- **No Magic**: Every interaction is explicit - great for learning
+- **Performance Baseline**: Shows the minimal overhead of Play Architecture
+
+This demo proves frameworks aren't required for Play Architecture to work.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                      | Description                      |
+| ------------------------------------------------------------ | -------------------------------- |
+| `npm run dev -w packages/play-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-router/examples/demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Validate the operational behavior with package-local tests:
+
+```bash
+npm run test -w packages/play-router/examples/demo
+npm run test:browser -w packages/play-router/examples/demo
+```
+
+Expected result: tests pass, including startup rendering and the full browser auth flow in `test/browser/`.
+
+## Learn More
+
+- **[Play Router Package README](../play-router/README.md)** - Router APIs and integration patterns