@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,272 @@
+[API](../../README.md) / @xmachines/play-dom-router
+
+# @xmachines/play-dom-router
+
+**Vanilla DOM router (Browser History API) for XMachines Play Architecture.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
+
+Framework-agnostic router integration that synchronizes a Play actor's `currentRoute` TC39 Signal with the browser's `window.history` API — no framework required. Implements the same [`RouterBridgeBase`](../play-router/README.md) pattern as all other router adapters in the XMachines ecosystem.
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-dom-router @xmachines/play-router @xmachines/play-actor
+```
+
+Peer dependency:
+
+```bash
+pnpm add xstate@^5.31.0
+```
+
+## Overview
+
+[`@xmachines/play-dom-router`](README.md) connects a Play actor to the browser URL through the `DomRouterBridge` (extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md)):
+
+- Actor route signal (`actor.currentRoute`) drives `history.push()` — actor is authoritative.
+- Browser navigation events (`popstate`, `pushState`, `replaceState`) send `play.route` intents back to the actor.
+- Guarded state transitions remain actor-owned (Actor Authority).
+- Circular update prevention via `isProcessingNavigation` flag — inherited from `RouterBridgeBase`.
+
+## Key Exports
+
+| Export                                        | Description                                                                                                        |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `createBrowserHistory(options)`               | Wraps `window.history` with a subscribable `BrowserHistory` interface                                              |
+| `createRouter(options)`                       | Creates a `VanillaRouter` combining `BrowserHistory` and `RouteTree`                                               |
+| `connectRouter(options)`                      | Connects a `VanillaRouter` to a `Routable` actor — returns a `disconnect` cleanup function                         |
+| `createRouteMap`                              | Re-exported from `@xmachines/play-router` — builds bidirectional path ↔ state ID map                               |
+| `BrowserHistory`                              | Interface for the history wrapper                                                                                  |
+| `BrowserWindow`                               | Structural window interface (accepts `Window`, JSDOM, or any test double)                                          |
+| `VanillaRouter`                               | Interface for the router wrapper                                                                                   |
+| `ConnectRouterOptions`                        | Options type for `connectRouter`                                                                                   |
+| `RouteLookupContract`                         | Structural interface for bidirectional route lookup                                                                |
+| `RoutableActor`                               | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
+| `RouterBridge`, `PlayRouteEvent`              | Types re-exported from `@xmachines/play-router`                                                                    |
+| `RouteMap`, `RouteMapping`, `RouteMapOptions` | Types re-exported from `@xmachines/play-router`                                                                    |
+
+## Quick Start
+
+```typescript
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+// 1. Extract route tree and build route map from your XState machine
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(machine);
+
+// 2. Create browser history wrapper (accepts window or any BrowserWindow-compatible object)
+const history = createBrowserHistory({ window });
+
+// 3. Create router
+const router = createRouter({ routeTree, history });
+
+// 4. Start actor and connect
+const actor = definePlayer({ machine, catalog })();
+actor.start();
+
+const disconnect = connectRouter({ actor, router, routeMap });
+
+// Cleanup (e.g. on page unload)
+window.addEventListener("beforeunload", () => {
+	disconnect();
+	router.destroy();
+});
+```
+
+## API
+
+### `createBrowserHistory(options)`
+
+Wraps `window.history` to provide a subscribable history interface. Patches `pushState`/`replaceState` to detect programmatic navigations in addition to `popstate` events for back/forward.
+
+```typescript
+const history = createBrowserHistory({ window });
+
+// Subscribe to URL changes
+const unsubscribe = history.subscribe((location) => {
+	console.log("URL changed:", location.pathname, location.search);
+});
+
+// Programmatic navigation
+history.push("/dashboard");
+history.replace("/login");
+history.back();
+
+// Cleanup — safe to call more than once; cooperates with other wrappers on the same window
+unsubscribe();
+history.destroy();
+```
+
+**`BrowserHistory` interface:**
+
+| Method                  | Description                                                                |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `location`              | Read-only `{ pathname, search, hash, state }`                              |
+| `push(path, state?)`    | Push a new entry to history                                                |
+| `replace(path, state?)` | Replace the current history entry                                          |
+| `go(delta)`             | Navigate relative to current position                                      |
+| `back()`                | Navigate backward                                                          |
+| `forward()`             | Navigate forward                                                           |
+| `subscribe(listener)`   | Subscribe to location changes — returns unsubscribe function               |
+| `createHref(path)`      | Create an href from a path                                                 |
+| `destroy()`             | Cleanup — removes listeners and restores patched methods when last wrapper |
+
+**`BrowserWindow` interface:**
+
+Accepts `window`, a JSDOM window, or any object implementing the structural interface. Covers only properties actually used — avoids coupling to `Window & typeof globalThis`.
+
+### `createRouter(options)`
+
+Creates a `VanillaRouter` wrapping `history` and `routeTree`. Designed for parity with TanStack Router's setup flow.
+
+```typescript
+const router = createRouter({ routeTree, history });
+// router.history — the BrowserHistory instance
+// router.routeTree — for structure reference
+// router.destroy() — calls history.destroy()
+```
+
+### `connectRouter(options)`
+
+Connects a `VanillaRouter` to a `Routable` actor. Handles all bidirectional synchronization:
+
+- On connect: syncs initial URL → actor or actor route → browser (restore vs. deep-link detection).
+- While connected: actor route changes push to history; browser navigations send `play.route` events.
+- Returns a cleanup function that disconnects the bridge.
+
+```typescript
+const disconnect = connectRouter({
+	actor, // RoutableActor — any AbstractActor subclass satisfies this structurally
+	router, // VanillaRouter from createRouter()
+	routeMap, // RouteLookupContract — any object with getStateIdByPath / getPathByStateId
+});
+
+// Later:
+disconnect();
+```
+
+**`ConnectRouterOptions`:**
+
+| Option     | Type                  | Description                               |
+| ---------- | --------------------- | ----------------------------------------- |
+| `actor`    | `RoutableActor`       | Actor to synchronize with the browser URL |
+| `router`   | `VanillaRouter`       | Router from `createRouter()`              |
+| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup      |
+
+**`RouteLookupContract`:**
+
+```typescript
+interface RouteLookupContract {
+	getStateIdByPath(path: string): string | null | undefined;
+	getPathByStateId(id: string): string | null | undefined;
+}
+```
+
+Any object satisfying this structural interface is accepted — including `RouteMap` instances from `@xmachines/play-router`, subclasses, or test doubles.
+
+### `createRouteMap` (re-export)
+
+Re-exported from `@xmachines/play-router`. Builds a bidirectional `RouteMap` from an XState machine:
+
+```typescript
+import { createRouteMap } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMap(machine);
+routeMap.getStateIdByPath("/dashboard"); // "dashboard"
+routeMap.getPathByStateId("dashboard"); // "/dashboard"
+```
+
+## URLPattern Support
+
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via [`@xmachines/play-router`](../play-router/README.md). URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router`](../play-router/README.md) for details.
+
+## Testing
+
+Run tests in isolation:
+
+```bash
+pnpm test
+# or from monorepo root:
+pnpm --filter @xmachines/play-dom-router test
+```
+
+Tests run in Node.js environment with `URLPattern` polyfill setup. Browser-specific tests are in `test/browser/` and run separately via `vitest.browser.config.ts`.
+
+Coverage thresholds:
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
+
+## Architecture
+
+The bridge-first data flow:
+
+1. `connectRouter` instantiates `DomRouterBridge` (extends `RouterBridgeBase`) and calls `bridge.connect()`.
+2. On connect, `RouterBridgeBase` performs initial sync: if browser URL differs from actor route, a `play.route` event is sent; if actor route differs and browser is at the machine's initial route (restore scenario), the actor wins and history is updated.
+3. Actor route changes (via `currentRoute` Signal) trigger `history.push(path)`.
+4. Browser URL changes (popstate, patched pushState/replaceState) call `syncActorFromRouter(pathname, search)`, which sends a `play.route` event.
+5. Circular updates are prevented by the `isProcessingNavigation` flag in `RouterBridgeBase`.
+
+```
+Browser URL
+    │  popstate / pushState / replaceState
+    ▼
+DomRouterBridge
+    │  play.route event
+    ▼
+Actor (XState machine)
+    │  currentRoute Signal change
+    ▼
+DomRouterBridge
+    │  history.push(path)
+    ▼
+Browser URL
+```
+
+## Related Packages
+
+- [@xmachines/play-router](../play-router/README.md) — `RouterBridgeBase`, `createRouteMap`, `extractMachineRoutes`
+- [@xmachines/play-actor](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`; all subclasses satisfy `RoutableActor` structurally
+- [@xmachines/play-dom](../play-dom/README.md) — Vanilla DOM renderer for view rendering alongside routing
+- [@xmachines/play-xstate](../play-xstate/README.md) — `definePlayer`, `PlayerActor`
+
+## Part of the XMachines monorepo
+
+This package is part of the [xmachines-js](../../README.md) monorepo.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Interfaces
+
+- [BrowserHistory](interfaces/BrowserHistory.md)
+- [BrowserWindow](interfaces/BrowserWindow.md)
+- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RoutableActor](interfaces/RoutableActor.md)
+- [RouteLookupContract](interfaces/RouteLookupContract.md)
+- [RouteMap](interfaces/RouteMap.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+- [VanillaRouter](interfaces/VanillaRouter.md)
+
+## Functions
+
+- [connectRouter](functions/connectRouter.md)
+- [createBrowserHistory](functions/createBrowserHistory.md)
+- [createRouteMap](functions/createRouteMap.md)
+- [createRouter](functions/createRouter.md)

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

@@ -0,0 +1,43 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / connectRouter
+
+# Function: connectRouter()
+
+```ts
+function connectRouter(options): () => void;
+```
+
+Defined in: [play-dom-router/src/connect-router.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/connect-router.ts#L51)
+
+Connect vanilla router to actor (pure browser integration).
+
+Returns a cleanup function. Calls `bridge.disconnect()` to stop sync.
+
+## Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
+
+## Returns
+
+() => `void`
+
+## Example
+
+```typescript
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(machine);
+const history = createBrowserHistory({ window });
+const router = createRouter({ routeTree, history });
+const disconnect = connectRouter({ actor, router, routeMap });
+// Later:
+disconnect();
+```

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createBrowserHistory
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / createBrowserHistory
 
 # Function: createBrowserHistory()
 
@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [create-browser-history.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L99)
+Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L120)
 
 Create browser history that wraps window.history
 
@@ -35,6 +35,14 @@ unsubscribe();
 history.destroy();
 ```
 
+`destroy()` is idempotent and cooperates with other wrappers created for the
+same `window` instance.
+
+**Warning**: `createBrowserHistory()` mutates global `window.history` methods
+(`pushState` and `replaceState`) and coordinates wrappers with shared ref-count state.
+To mitigate leakage, create one history wrapper per browser window at the application
+boundary and always pair it with `destroy()` during teardown.
+
 ## Parameters
 
 | Parameter        | Type                                                               |

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

@@ -0,0 +1,39 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+function createRouteMap(machine, options?): RouteMap;
+```
+
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L45)
+
+Create a `RouteMap` from an XState state machine.
+
+Extracts all routable states (those with `meta.route`) and builds a bidirectional
+path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
+subclasses to translate browser URL changes into `play.route` actor events and
+vice-versa.
+
+## Parameters
+
+| Parameter  | Type                                                                      | Description                                                                                                         |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+
+## Returns
+
+[`RouteMap`](../interfaces/RouteMap.md)
+
+A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+import { createRouteMap } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMap(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
+```

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

@@ -0,0 +1,54 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / createRouter
+
+# Function: createRouter()
+
+```ts
+function createRouter(options): VanillaRouter;
+```
+
+Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-router.ts#L52)
+
+Create vanilla router for framework-agnostic routing.
+
+Architecture:
+
+- Just wraps history and routeTree
+- Does NOT embed routeMap (providers need it as prop)
+- Framework-agnostic history management only
+
+Why no routeMap:
+
+- Router doesn't know about state IDs (that's Play-specific)
+- RouteMap is the bridge between router and actor
+- Provider receives routeMap as prop to do path → state ID resolution
+
+Usage (parallel to TanStack mode):
+
+```typescript
+// Both modes: identical setup
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+const history = createBrowserHistory({ window });
+
+// Vanilla router
+const router = createRouter({ routeTree, history });
+
+// Connect router to actor (handles all bidirectional sync)
+const disconnect = connectRouter({ actor, router, routeMap });
+
+// Later: cleanup
+disconnect();
+router.destroy();
+```
+
+## Parameters
+
+| Parameter           | Type                                                                                                                                         |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | \{ `history`: [`BrowserHistory`](../interfaces/BrowserHistory.md); `routeTree`: [`RouteTree`](../../play-router/interfaces/RouteTree.md); \} |
+| `options.history`   | [`BrowserHistory`](../interfaces/BrowserHistory.md)                                                                                          |
+| `options.routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md)                                                                                     |
+
+## Returns
+
+[`VanillaRouter`](../interfaces/VanillaRouter.md)

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

@@ -0,0 +1,176 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / BrowserHistory
+
+# Interface: BrowserHistory
+
+Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/packages/play-dom-router/src/create-browser-history.ts#L9) |
+
+## Methods
+
+### back()
+
+```ts
+back(): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L26)
+
+#### Returns
+
+`void`
+
+---
+
+### createHref()
+
+```ts
+createHref(path): string;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L38)
+
+Create href from path
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+#### Returns
+
+`string`
+
+---
+
+### destroy()
+
+```ts
+destroy(): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L47)
+
+Cleanup.
+
+Safe to call more than once. When multiple wrappers share the same
+`window.history`, the original methods are restored only after the last
+wrapper is destroyed.
+
+#### Returns
+
+`void`
+
+---
+
+### forward()
+
+```ts
+forward(): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L27)
+
+#### Returns
+
+`void`
+
+---
+
+### go()
+
+```ts
+go(delta): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L25)
+
+Go back/forward
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `delta`   | `number` |
+
+#### Returns
+
+`void`
+
+---
+
+### push()
+
+```ts
+push(path, state?): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L15)
+
+Push new URL to history
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `path`    | `string`  |
+| `state?`  | `unknown` |
+
+#### Returns
+
+`void`
+
+---
+
+### replace()
+
+```ts
+replace(path, state?): void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L20)
+
+Replace current URL in history
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `path`    | `string`  |
+| `state?`  | `unknown` |
+
+#### Returns
+
+`void`
+
+---
+
+### subscribe()
+
+```ts
+subscribe(listener): () => void;
+```
+
+Defined in: [play-dom-router/src/create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom-router/src/create-browser-history.ts#L33)
+
+Subscribe to history changes
+Returns unsubscribe function
+
+#### Parameters
+
+| Parameter  | Type                   |
+| ---------- | ---------------------- |
+| `listener` | (`location`) => `void` |
+
+#### Returns
+
+() => `void`