@xmachines/docs 1.0.0-beta.26 → 1.0.0-beta.28

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

@@ -0,0 +1,145 @@
+[Documentation](../../README.md) / @xmachines/play-dom-demo
+
+# Vanilla DOM Demo
+
+Vanilla DOM renderer demo for `@xmachines/play-dom` — actor + `connectRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRenderer` wiring `PlayRenderer`-equivalent DOM rendering without a framework
+- Auth machine states (home → login → dashboard) drive DOM updates via TC39 Signal watchers
+- `watchSignal` for reactive nav visibility and debug panel updates
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-dom-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })` and starts the actor.
+2. `initShell(actor, app)` from `src/shell.ts` builds the HTML scaffold and registers all event listeners.
+3. `makeComponents(actor)` constructs a `DomRegistry` of stateless and stateful `DomComponentRenderer` functions.
+4. `connectRenderer({ actor, registry, container })` wires the registry to the actor — view switches happen automatically when actor state changes.
+5. `watchSignal(actor.state, ...)` drives nav login/logout button visibility and the debug panel.
+6. Browser tests in `test/browser/` validate startup rendering and auth interactions.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const app = document.getElementById("app");
+if (app) {
+	initShell(actor, app);
+}
+```
+
+```ts
+// src/shell.ts (shape)
+const disconnectRenderer = connectRenderer({
+	actor,
+	registry,
+	container: viewContent,
+});
+
+const unwatchState = watchSignal(actor.state, () => {
+	const snapshot = actor.getSnapshot();
+	navLogin.hidden = snapshot.context.isAuthenticated;
+	navLogout.hidden = !snapshot.context.isAuthenticated;
+});
+```
+
+```ts
+// src/shell.ts — sending events (shape)
+actor.send({ type: "play.route", to: "#login" });
+actor.send({ type: "auth.login", username });
+actor.send({ type: "auth.logout" });
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation and shell bootstrap
+- `src/shell.ts` - DOM scaffold, `DomRegistry` construction, `connectRenderer` wiring, and `watchSignal` for reactive nav and debug panel
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** Navigation buttons dispatch `play.route` events to the actor. The actor evaluates guards and transitions to the correct state — the DOM never decides which view to show.
+2. **Passive Infrastructure:** `connectRenderer` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
+3. **Signal-Only Reactivity:** `watchSignal` (from `@xmachines/play-signals`) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher 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. Cleanup is explicit: both `disconnectRenderer()` and `unwatchState()` must be called to avoid memory leaks. In this demo, cleanup is returned from `initShell` and called on `beforeunload`.
+
+## Adapter Boundaries
+
+`connectRenderer` (from `@xmachines/play-dom`) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                            | Description                      |
+| -------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-dom-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-dom-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-dom-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-dom-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-dom-demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w @xmachines/play-dom-demo
+npm run test:browser -w @xmachines/play-dom-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Play DOM package README](../play-dom/README.md)
+- [Play DOM Router demo README](../play-dom-router-demo/README.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [initShell](functions/initShell.md)

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

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / initShell
+
+# Function: initShell()
+
+```ts
+function initShell(actor, appElement): () => void;
+```
+
+Defined in: [shell.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/shell.ts#L32)
+
+## Parameters
+
+| Parameter    | Type                                                             |
+| ------------ | ---------------------------------------------------------------- |
+| `actor`      | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md) |
+| `appElement` | `HTMLElement`                                                    |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+Defined in: [components/About.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/About.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+Defined in: [components/Contact.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Contact.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+Defined in: [components/Dashboard.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Dashboard.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+Defined in: [components/Home.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Home.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+Defined in: [components/Login.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Login.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+Defined in: [components/Navigation.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Navigation.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+Defined in: [components/Overview.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Overview.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+Defined in: [components/Profile.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Profile.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+Defined in: [components/Settings.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Settings.ts#L4)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+Defined in: [components/Stats.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Stats.ts#L4)

package/api/@xmachines/play-dom-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L48)
+Defined in: [play-dom-router/src/connect-router.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L48)
 
 Connect vanilla router to actor (pure browser integration).
 

package/api/@xmachines/play-dom-router/functions/createBrowserHistory.md

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L120)
+Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L120)
 
 Create browser history that wraps window.history
 

package/api/@xmachines/play-dom-router/functions/createRouteMap.md

@@ -6,7 +6,7 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map-from-machine.ts#L26)
+Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/create-route-map-from-machine.ts#L26)
 
 Create a `BaseRouteMap` from an XState state machine.
 

package/api/@xmachines/play-dom-router/functions/createRouter.md

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-router.ts#L52)
+Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-router.ts#L52)
 
 Create vanilla router for framework-agnostic routing.
 

package/api/@xmachines/play-dom-router/interfaces/BrowserHistory.md

@@ -2,17 +2,17 @@
 
 # Interface: BrowserHistory
 
-Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L1)
+Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L1)
 
 ## Properties
 
 | Property                                  | Modifier   | Type      | Description                | Defined in                                                                                                                                                                    |
 | ----------------------------------------- | ---------- | --------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [play-dom-router/src/create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L5) |
-| `location.hash`                           | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L8) |
-| `location.pathname`                       | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L6) |
-| `location.search`                         | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L7) |
-| `location.state`                          | `public`   | `unknown` | -                          | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L9) |
+| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [play-dom-router/src/create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L5) |
+| `location.hash`                           | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L8) |
+| `location.pathname`                       | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L6) |
+| `location.search`                         | `public`   | `string`  | -                          | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L7) |
+| `location.state`                          | `public`   | `unknown` | -                          | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L9) |
 
 ## Methods
 
@@ -22,7 +22,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com
 back(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L26)
+Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L26)
 
 #### Returns
 
@@ -36,7 +36,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.co
 createHref(path): string;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L38)
+Defined in: [play-dom-router/src/create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L38)
 
 Create href from path
 
@@ -58,7 +58,7 @@ Create href from path
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L47)
+Defined in: [play-dom-router/src/create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L47)
 
 Cleanup.
 
@@ -78,7 +78,7 @@ wrapper is destroyed.
 forward(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L27)
+Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L27)
 
 #### Returns
 
@@ -92,7 +92,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.co
 go(delta): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L25)
+Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L25)
 
 Go back/forward
 
@@ -114,7 +114,7 @@ Go back/forward
 push(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L15)
+Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L15)
 
 Push new URL to history
 
@@ -137,7 +137,7 @@ Push new URL to history
 replace(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L20)
+Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L20)
 
 Replace current URL in history
 
@@ -160,7 +160,7 @@ Replace current URL in history
 subscribe(listener): () => void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L33)
+Defined in: [play-dom-router/src/create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L33)
 
 Subscribe to history changes
 Returns unsubscribe function

package/api/@xmachines/play-dom-router/interfaces/BrowserWindow.md

@@ -2,7 +2,7 @@
 
 # Interface: BrowserWindow
 
-Defined in: [play-dom-router/src/create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L59)
+Defined in: [play-dom-router/src/create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L59)
 
 Minimal window interface for createBrowserHistory
 
@@ -14,17 +14,17 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 
 | Property                                  | Modifier   | Type      | Defined in                                                                                                                                                                      |
 | ----------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`   | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L60) |
-| `history.state`                           | `readonly` | `unknown` | [play-dom-router/src/create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L61) |
-| `history.back`                            | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L65) |
-| `history.forward`                         | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L66) |
-| `history.go`                              | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L64) |
-| `history.pushState`                       | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L62) |
-| `history.replaceState`                    | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L63) |
-| <a id="property-location"></a> `location` | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L68) |
-| `location.hash`                           | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L71) |
-| `location.pathname`                       | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L69) |
-| `location.search`                         | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L70) |
+| <a id="property-history"></a> `history`   | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L60) |
+| `history.state`                           | `readonly` | `unknown` | [play-dom-router/src/create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L61) |
+| `history.back`                            | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L65) |
+| `history.forward`                         | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L66) |
+| `history.go`                              | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L64) |
+| `history.pushState`                       | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L62) |
+| `history.replaceState`                    | `public`   | `void`    | [play-dom-router/src/create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L63) |
+| <a id="property-location"></a> `location` | `public`   | `object`  | [play-dom-router/src/create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L68) |
+| `location.hash`                           | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L71) |
+| `location.pathname`                       | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L69) |
+| `location.search`                         | `readonly` | `string`  | [play-dom-router/src/create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L70) |
 
 ## Methods
 
@@ -34,7 +34,7 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 addEventListener(type, listener): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L73)
+Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L73)
 
 #### Parameters
 
@@ -55,7 +55,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:73](https://gitlab.co
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/create-browser-history.ts#L74)
+Defined in: [play-dom-router/src/create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L74)
 
 #### Parameters
 

package/api/@xmachines/play-dom-router/interfaces/ConnectRouterOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-dom-router/src/connect-router.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L20)
+Defined in: [play-dom-router/src/connect-router.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L20)
 
 Options for [connectRouter](../functions/connectRouter.md).
 
@@ -10,6 +10,6 @@ Options for [connectRouter](../functions/connectRouter.md).
 
 | Property                                  | Modifier   | Type                                                                                                                                                                                                                                                             | Description                                                                 | Defined in                                                                                                                                                      |
 | ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `readonly` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | The actor to synchronize with the browser URL. Must implement `Routable`.   | [play-dom-router/src/connect-router.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L22) |
-| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMapLike`](RouteMapLike.md)                                                                                                                                                                                                                                | Route map used to resolve URL pathnames to machine state IDs.               | [play-dom-router/src/connect-router.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L26) |
-| <a id="property-router"></a> `router`     | `readonly` | [`VanillaRouter`](VanillaRouter.md)                                                                                                                                                                                                                              | The vanilla router created by [createRouter](../functions/createRouter.md). | [play-dom-router/src/connect-router.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L24) |
+| <a id="property-actor"></a> `actor`       | `readonly` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | The actor to synchronize with the browser URL. Must implement `Routable`.   | [play-dom-router/src/connect-router.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L22) |
+| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMapLike`](RouteMapLike.md)                                                                                                                                                                                                                                | Route map used to resolve URL pathnames to machine state IDs.               | [play-dom-router/src/connect-router.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L26) |
+| <a id="property-router"></a> `router`     | `readonly` | [`VanillaRouter`](VanillaRouter.md)                                                                                                                                                                                                                              | The vanilla router created by [createRouter](../functions/createRouter.md). | [play-dom-router/src/connect-router.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L24) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L223)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L228) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L226) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L227) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L225) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L224) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/types.ts#L224) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -55,7 +55,7 @@ map.getPathByStateId("missing"); // null
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -86,7 +86,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

package/api/@xmachines/play-dom-router/interfaces/RouteMapLike.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapLike
 
-Defined in: [play-dom-router/src/connect-router.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L12)
+Defined in: [play-dom-router/src/connect-router.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L12)
 
 Structural route-map interface accepted by [connectRouter](../functions/connectRouter.md).
 
@@ -17,7 +17,7 @@ Any object with these two methods satisfies the constraint — including
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L14)
+Defined in: [play-dom-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L14)
 
 #### Parameters
 
@@ -37,7 +37,7 @@ Defined in: [play-dom-router/src/connect-router.ts:14](https://gitlab.com/xmachi
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom-router/src/connect-router.ts#L13)
+Defined in: [play-dom-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L13)
 
 #### Parameters
 

package/api/@xmachines/play-dom-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/setting
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L61) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/base-route-map.ts#L59) |