@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/api/@xmachines/play-dom/type-aliases/DomRegistry.md

@@ -6,6 +6,9 @@
 type DomRegistry = Record<string, DomComponentRenderer>;
 ```
 
-Defined in: [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom/src/types.ts#L41)
+Defined in: [json-render/types.ts:263](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L263)
 
-Registry of component renderers keyed by element type.
+Raw registry of `DomComponentRenderer` functions keyed by element type.
+
+Passed to `connectRenderer` or `PlayRenderer`. Build with `defineRegistry`
+to get catalog-typed component functions automatically wrapped.

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

@@ -143,10 +143,20 @@ router.destroy();
 - [BrowserHistory](interfaces/BrowserHistory.md)
 - [BrowserWindow](interfaces/BrowserWindow.md)
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RouteMap](interfaces/RouteMap.md)
+- [RouteMapLike](interfaces/RouteMapLike.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouterBridge](interfaces/RouterBridge.md)
 - [VanillaRouter](interfaces/VanillaRouter.md)
 
+## Type Aliases
+
+- [RoutableActor](type-aliases/RoutableActor.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

@@ -6,66 +6,38 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [connect-router.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/connect-router.ts#L69)
+Defined in: [play-dom-router/src/connect-router.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom-router/src/connect-router.ts#L48)
 
 Connect vanilla router to actor (pure browser integration).
 
-This is the LOW-LEVEL API for maximum control. No JSX, no rendering,
-just actor ↔ router synchronization.
+Returns a cleanup function. Calls `bridge.disconnect()` to stop sync.
 
-Use this when:
-
-- You want manual control over rendering
-- Using non-JSX framework (jQuery, Alpine, HTMX, etc.)
-- Building custom integration
-
-For JSX frameworks, use framework adapters instead:
+## Parameters
 
-- @xmachines/play-react (React components)
-- @xmachines/play-vue (Vue components)
-- @xmachines/play-solid (Solid components)
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
 
-Architecture:
+## Returns
 
-- Subscribes to history changes → sends play.route to actor
-- Watches actor.currentRoute signal → updates browser URL
-- Prevents circular updates (history change triggers actor, actor triggers history)
-- Returns cleanup function
+() => `void`
 
-Usage:
+## Example
 
 ```typescript
-import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
 
 const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
+const routeMap = createRouteMap(machine);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
-
-// Connect router to actor
 const disconnect = connectRouter({ actor, router, routeMap });
-
-// User handles rendering (vanilla JS)
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const view = actor.currentView.get();
-		document.getElementById("app").innerHTML = render(view);
-	});
-});
-watcher.watch(actor.currentView);
-
-// Later: cleanup
+// Later:
 disconnect();
-watcher.unwatch(actor.currentView);
 ```
-
-## Parameters
-
-| Parameter | Type                                                            |
-| --------- | --------------------------------------------------------------- |
-| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
-
-## Returns
-
-() => `void`

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

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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

@@ -0,0 +1,38 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+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.27/packages/play-router/src/create-route-map-from-machine.ts#L26)
+
+Create a `BaseRouteMap` 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. |
+
+## Returns
+
+[`RouteMap`](../interfaces/RouteMap.md)
+
+A `BaseRouteMap` for passing to any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMapFromMachine(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
+```

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

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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 | [create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L5) |
-| `location.hash`                           | `public`   | `string`  | -                          | [create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L8) |
-| `location.pathname`                       | `public`   | `string`  | -                          | [create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L6) |
-| `location.search`                         | `public`   | `string`  | -                          | [create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L7) |
-| `location.state`                          | `public`   | `unknown` | -                          | [create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L9) |
+| 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.27/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.27/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.27/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.27/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.27/packages/play-dom-router/src/create-browser-history.ts#L9) |
 
 ## Methods
 
@@ -22,7 +22,7 @@ Defined in: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachine
 back(): void;
 ```
 
-Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L26)
 
 #### Returns
 
@@ -36,7 +36,7 @@ Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachin
 createHref(path): string;
 ```
 
-Defined in: [create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L47)
 
 Cleanup.
 
@@ -78,7 +78,7 @@ wrapper is destroyed.
 forward(): void;
 ```
 
-Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L27)
 
 #### Returns
 
@@ -92,7 +92,7 @@ Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachin
 go(delta): void;
 ```
 
-Defined in: [create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/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: [create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L59)
 
 Minimal window interface for createBrowserHistory
 
@@ -12,19 +12,19 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 
 ## Properties
 
-| Property                                  | Modifier   | Type      | Defined in                                                                                                                                                  |
-| ----------------------------------------- | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`   | `public`   | `object`  | [create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L60) |
-| `history.state`                           | `readonly` | `unknown` | [create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L61) |
-| `history.back`                            | `public`   | `void`    | [create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L65) |
-| `history.forward`                         | `public`   | `void`    | [create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L66) |
-| `history.go`                              | `public`   | `void`    | [create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L64) |
-| `history.pushState`                       | `public`   | `void`    | [create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L62) |
-| `history.replaceState`                    | `public`   | `void`    | [create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L63) |
-| <a id="property-location"></a> `location` | `public`   | `object`  | [create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L68) |
-| `location.hash`                           | `readonly` | `string`  | [create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L71) |
-| `location.pathname`                       | `readonly` | `string`  | [create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L69) |
-| `location.search`                         | `readonly` | `string`  | [create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/create-browser-history.ts#L70) |
+| 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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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: [create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L73)
 
 #### Parameters
 
@@ -55,7 +55,7 @@ Defined in: [create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachin
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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.27/packages/play-dom-router/src/create-browser-history.ts#L74)
 
 #### Parameters
 

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

@@ -2,14 +2,14 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [connect-router.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/connect-router.ts#L11)
+Defined in: [play-dom-router/src/connect-router.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom-router/src/connect-router.ts#L20)
 
 Options for [connectRouter](../functions/connectRouter.md).
 
 ## Properties
 
-| Property                                  | Type                                                                                                                                                                                                                                                             | Description                                                                 | Defined in                                                                                                                                  |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | [`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`.   | [connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/connect-router.ts#L13) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../../play-router/interfaces/RouteMap.md)                                                                                                                                                                                                           | Route map used to resolve URL pathnames to machine state IDs.               | [connect-router.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/connect-router.ts#L17) |
-| <a id="property-router"></a> `router`     | [`VanillaRouter`](VanillaRouter.md)                                                                                                                                                                                                                              | The vanilla router created by [createRouter](../functions/createRouter.md). | [connect-router.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-dom-router/src/connect-router.ts#L15) |
+| 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.27/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.27/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.27/packages/play-dom-router/src/connect-router.ts#L24) |

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

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L223)
+
+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
+
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+
+## 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" }, // Path-only route parameter
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.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`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/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.27/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.27/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.27/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.27/packages/play-router/src/types.ts#L224) |

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

@@ -0,0 +1,114 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-router](../README.md) / RouteMap
+
+# Interface: RouteMap
+
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L100)
+
+Shared bidirectional route map base class.
+
+All framework adapter `RouteMap` classes extend this — they add no logic of their
+own and inherit the full public API from here.
+
+**Lookup strategy:**
+
+- Static paths (no `:param`) → O(1) `Map` lookup
+- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
+  of routes sharing the same first path segment
+- Results are cached after the first match in an LRU cache (default 500 entries,
+  configurable via the `cacheSize` constructor option)
+
+**Pattern syntax** (`:param` / `:param?`):
+
+- `:param` — required segment, matches exactly one non-`/` segment
+- `:param?` — optional segment, matches zero or one non-`/` segment
+
+## Example
+
+```typescript
+import { BaseRouteMap } from "@xmachines/play-router";
+
+const map = new BaseRouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+map.getStateIdByPath("/"); // "home"
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/settings"); // "settings"
+map.getStateIdByPath("/unknown"); // null
+
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+## Extended by
+
+- [`RouteMap`](../../play-react-router/classes/RouteMap.md)
+- [`RouteMap`](../../play-tanstack-react-router/classes/RouteMap.md)
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+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.27/packages/play-router/src/base-route-map.ts#L209)
+
+Look up the path pattern registered for a state ID.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+---
+
+### getStateIdByPath()
+
+```ts
+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.27/packages/play-router/src/base-route-map.ts#L174)
+
+Resolve a URL path to its mapped state ID.
+
+Strips query strings and hash fragments before matching. Tries an O(1) exact
+lookup first, then falls back to bucket-indexed pattern matching. Results are
+cached after the first pattern match.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```