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

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

@@ -6,7 +6,7 @@
 function createRouteMap(routeTree): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L74)
+Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map.ts#L74)
 
 Create a RouteMap from a RouteTree for efficient path lookups.
 

package/api/@xmachines/play-router/functions/createRouteMapFromMachine.md

@@ -0,0 +1,38 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromMachine
+
+# Function: createRouteMapFromMachine()
+
+```ts
+function createRouteMapFromMachine(machine): BaseRouteMap;
+```
+
+Defined in: [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
+
+[`BaseRouteMap`](../classes/BaseRouteMap.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-router/functions/createRouteMapFromTree.md

@@ -0,0 +1,45 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromTree
+
+# Function: createRouteMapFromTree()
+
+```ts
+function createRouteMapFromTree(routeTree): BaseRouteMap;
+```
+
+Defined in: [create-route-map-from-tree.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map-from-tree.ts#L31)
+
+Create a `BaseRouteMap` from a `RouteTree` node structure.
+
+Used by framework-router adapters (React Router, TanStack Router) that pass a
+`RouteTree` produced by `extractMachineRoutes()` rather than calling
+`createRouteMapFromMachine()` directly.
+
+Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
+`node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
+which is what `BaseRouteMap` needs for browser URL matching. This matches the
+behaviour of `createRouteMapFromMachine`, which also uses `node.fullPath`.
+
+## Parameters
+
+| Parameter   | Type                                      | Description                                            |
+| ----------- | ----------------------------------------- | ------------------------------------------------------ |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`. |
+
+## Returns
+
+[`BaseRouteMap`](../classes/BaseRouteMap.md)
+
+A `BaseRouteMap` for use with any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+// Preferred — single call for XState machines:
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+const routeMap = createRouteMapFromMachine(machine);
+
+// Equivalent two-step form used by framework adapters:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+```

package/api/@xmachines/play-router/functions/detectDuplicateRoutes.md

@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L51)
+Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/validate-routes.ts#L51)
 
 Detect duplicate route paths
 

package/api/@xmachines/play-router/functions/extractMachineRoutes.md

@@ -6,7 +6,7 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/extract-routes.ts#L93)
+Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/extract-routes.ts#L93)
 
 Extract complete route tree from state machine graph
 

package/api/@xmachines/play-router/functions/extractQuery.md

@@ -6,7 +6,7 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L74)
+Defined in: [router-sync.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L121)
 
 Parse a URL search string into the plain object shape expected by
 `play.route` events.

package/api/@xmachines/play-router/functions/extractRouteParams.md

@@ -0,0 +1,46 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / extractRouteParams
+
+# Function: extractRouteParams()
+
+```ts
+function extractRouteParams(pathname, pattern): Record<string, string>;
+```
+
+Defined in: [router-sync.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L101)
+
+Extract named path parameters from a URL using the URLPattern API.
+
+Takes the pattern string directly — use this when the pattern is already known.
+For extraction via a state ID lookup, see `RouterBridgeBase.extractParams`.
+
+Undefined values (unmatched optional segments, e.g. `/settings` against
+`/settings/:section?`) are omitted from the returned object.
+
+## Parameters
+
+| Parameter  | Type     | Description                                          |
+| ---------- | -------- | ---------------------------------------------------- |
+| `pathname` | `string` | The concrete URL pathname (e.g. `/profile/alice`)    |
+| `pattern`  | `string` | The URL pattern template (e.g. `/profile/:username`) |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+A record of extracted parameter values, or `{}` for static patterns.
+
+## Throws
+
+When `URLPattern` is absent and the pattern is parameterized.
+
+## Example
+
+```typescript
+import { extractRouteParams } from "@xmachines/play-router";
+
+extractRouteParams("/profile/alice", "/profile/:username");
+// → { username: "alice" }
+
+extractRouteParams("/settings", "/settings/:section?");
+// → {}  (optional param absent — not included)
+```

package/api/@xmachines/play-router/functions/findRouteById.md

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/find-route.ts#L52)
+Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/find-route.ts#L52)
 
 Find route node by state ID
 

package/api/@xmachines/play-router/functions/findRouteByPath.md

@@ -6,7 +6,7 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/find-route.ts#L77)
+Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/find-route.ts#L77)
 
 Find route node by URL path
 

package/api/@xmachines/play-router/functions/getNavigableRoutes.md

@@ -6,7 +6,7 @@
 function getNavigableRoutes(tree, stateId): RouteNode[];
 ```
 
-Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L22)
+Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/query.ts#L22)
 
 Get all routes navigable from given state
 

package/api/@xmachines/play-router/functions/getRoutableRoutes.md

@@ -6,7 +6,7 @@
 function getRoutableRoutes(tree): RouteNode[];
 ```
 
-Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L67)
+Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/query.ts#L67)
 
 Get all routable routes from tree as flat array
 

package/api/@xmachines/play-router/functions/getTransitionReachableRoutes.md

@@ -6,7 +6,7 @@
 function getTransitionReachableRoutes(graph, stateId): string[];
 ```
 
-Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L113)
+Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/query.ts#L113)
 
 Get routes reachable via transitions from current state
 

package/api/@xmachines/play-router/functions/isRouteReachable.md

@@ -6,7 +6,7 @@
 function isRouteReachable(graph, fromStateId, toStateId): boolean;
 ```
 
-Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L149)
+Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/query.ts#L149)
 
 Check if a route is reachable from current state via transitions
 

package/api/@xmachines/play-router/functions/machineToGraph.md

@@ -6,7 +6,7 @@
 function machineToGraph(machine): MachineGraph;
 ```
 
-Defined in: [machine-to-graph.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/machine-to-graph.ts#L70)
+Defined in: [machine-to-graph.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/machine-to-graph.ts#L70)
 
 ## Parameters
 

package/api/@xmachines/play-router/functions/routeExists.md

@@ -6,7 +6,7 @@
 function routeExists(tree, path): boolean;
 ```
 
-Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L89)
+Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/query.ts#L89)
 
 Validate route path exists in tree
 

package/api/@xmachines/play-router/functions/sanitizePathname.md

@@ -6,7 +6,7 @@
 function sanitizePathname(pathname): string | null;
 ```
 
-Defined in: [router-sync.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L63)
+Defined in: [router-sync.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L69)
 
 Normalize a pathname before route-map lookup.
 

package/api/@xmachines/play-router/functions/validateRouteFormat.md

@@ -6,7 +6,7 @@
 function validateRouteFormat(routePath, stateId): void;
 ```
 
-Defined in: [validate-routes.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L14)
+Defined in: [validate-routes.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/validate-routes.ts#L14)
 
 Validate route path format
 

package/api/@xmachines/play-router/functions/validateStateExists.md

@@ -6,7 +6,7 @@
 function validateStateExists(stateId, stateIds): void;
 ```
 
-Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L32)
+Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/validate-routes.ts#L32)
 
 Validate state exists in state ID set
 

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

@@ -2,12 +2,12 @@
 
 # Interface: BuildPlayRouteEventOptions
 
-Defined in: [router-sync.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L8)
+Defined in: [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L14)
 
 ## Properties
 
 | Property                                  | Type                                                   | Defined in                                                                                                                        |
 | ----------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L9)   |
-| <a id="property-resolve"></a> `resolve`   | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L11) |
-| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L10) |
+| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L15) |
+| <a id="property-resolve"></a> `resolve`   | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L17) |
+| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L16) |

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / LocationLike
+
+# Interface: LocationLike
+
+Defined in: [types.ts:344](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L344)
+
+Minimal location interface required by adapters that read the current URL at
+`connect()` time. Injectable for SSR and testing — pass a mock instead of the
+global `location` when the DOM is unavailable.
+
+Defined structurally (no `Location` reference) so this package compiles without
+the DOM lib.
+
+## Example
+
+```typescript
+// SSR / test — injected mock
+const mockLoc: LocationLike = { pathname: "/dashboard", search: "?tab=posts" };
+connectRouter({ actor, routeMap, location: mockLoc });
+```
+
+## Properties
+
+| Property                                  | Modifier   | Type     | Defined in                                                                                                              |
+| ----------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:345](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L345) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L346) |

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

@@ -2,7 +2,7 @@
 
 # Interface: MachineEdgeData
 
-Defined in: [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L22)
+Defined in: [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L22)
 
 Data attached to each edge in the machine graph representation.
 Captures transition event and guard information.
@@ -11,5 +11,5 @@ Captures transition event and guard information.
 
 | Property                                     | Type     | Description                                  | Defined in                                                                                                            |
 | -------------------------------------------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L24) |
-| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L26) |
+| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L24) |
+| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L26) |

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

@@ -2,7 +2,7 @@
 
 # Interface: MachineNodeData
 
-Defined in: [types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L7)
+Defined in: [types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L7)
 
 Data attached to each node in the machine graph representation.
 Captures the essential state metadata needed for route extraction and queries.
@@ -11,7 +11,7 @@ Captures the essential state metadata needed for route extraction and queries.
 
 | Property                                | Type                                                                   | Description                                        | Defined in                                                                                                            |
 | --------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L13) |
-| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L15) |
-| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L9)   |
-| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | State type from XState                             | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L11) |
+| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L13) |
+| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L15) |
+| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L9)   |
+| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | State type from XState                             | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L11) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L216)
+Defined in: [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
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -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`                      | [types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [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`\> | [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`\> | [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`                       | [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"`                 | [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-router/interfaces/RouteInfo.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteInfo
 
-Defined in: [types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L54)
+Defined in: [types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L54)
 
 Extracted route information from a state node
 
@@ -10,10 +10,10 @@ Extracted route information from a state node
 
 | Property                                      | Type                                                | Description                                                                                          | Defined in                                                                                                            |
 | --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L64) |
-| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L71) |
-| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L62) |
-| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L69) |
-| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L60) |
-| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L56) |
-| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L58) |
+| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L64) |
+| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L71) |
+| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L62) |
+| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L69) |
+| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L60) |
+| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L56) |
+| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L58) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMap
 
-Defined in: [create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L20)
+Defined in: [create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map.ts#L20)
 
 Bidirectional route resolution interface returned by `createRouteMap()`.
 
@@ -23,7 +23,7 @@ events into `play.route` actor events.
 resolve(path): object;
 ```
 
-Defined in: [create-route-map.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L37)
+Defined in: [create-route-map.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map.ts#L37)
 
 Resolve a URL path to a state ID and params.
 
@@ -52,5 +52,5 @@ if (to) {
 
 | Name     | Type                           | Defined in                                                                                                                                  |
 | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L39) |
-| `to`     | `string` \| `null`             | [create-route-map.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L38) |
+| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map.ts#L39) |
+| `to`     | `string` \| `null`             | [create-route-map.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map.ts#L38) |

package/api/@xmachines/play-router/interfaces/{BaseRouteMapping.md → RouteMapping.md}

@@ -1,8 +1,8 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMapping
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMapping
 
-# Interface: BaseRouteMapping
+# Interface: RouteMapping
 
-Defined in: [base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/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?"`) | [base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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"`)                         | [base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/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?"`) | [base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/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"`)                         | [base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,11 +2,11 @@
 
 # Interface: RouteMatch
 
-Defined in: [router-sync.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L3)
+Defined in: [router-sync.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L9)
 
 ## Properties
 
-| Property                               | Type                              | Defined in                                                                                                                      |
-| -------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L5) |
-| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L4) |
+| Property                               | Type                              | Defined in                                                                                                                        |
+| -------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L11) |
+| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L10) |

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

@@ -2,20 +2,20 @@
 
 # Interface: RouteNode
 
-Defined in: [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L77)
+Defined in: [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L77)
 
 Node in the route tree representing a single route
 
 ## Properties
 
-| Property                                  | Type                                                | Description                                                                                          | Defined in                                                                                                            |
-| ----------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children` | `RouteNode`[]                                       | Child routes                                                                                         | [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L94) |
-| <a id="property-fullpath"></a> `fullPath` | `string`                                            | Full resolved path from root                                                                         | [types.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L83) |
-| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                         | [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L79) |
-| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                         | [types.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L98) |
-| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                         | [types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L96) |
-| <a id="property-path"></a> `path`         | `string`                                            | Route path segment (relative or absolute)                                                            | [types.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L81) |
-| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                       | [types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L85) |
-| <a id="property-routable"></a> `routable` | `boolean`                                           | Whether this state is routable (has meta.route) States with meta.route can receive play.route events | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L92) |
-| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                   | [types.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L87) |
+| Property                                  | Type                                                | Description                                                                                                                                                                                                                             | Defined in                                                                                                              |
+| ----------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-children"></a> `children` | `RouteNode`[]                                       | Child routes                                                                                                                                                                                                                            | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L101) |
+| <a id="property-fullpath"></a> `fullPath` | `string`                                            | The fully resolved absolute path from the root (e.g. `"/dashboard/overview"`). Always use `fullPath` for browser URL matching and route map construction. `createRouteMapFromTree` and `createRouteMapFromMachine` both use this field. | [types.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L90)   |
+| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                                                                                                                                                            | [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L79)   |
+| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                                                                                                                                                            | [types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L105) |
+| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                                                                                                                                                            | [types.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L103) |
+| <a id="property-path"></a> `path`         | `string`                                            | The raw route path segment as declared in `meta.route` — may be relative (e.g. `"overview"`) or absolute (e.g. `"/dashboard"`). Do not use this for URL matching; use `fullPath` instead.                                               | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L84)   |
+| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                                                                                                                                                          | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L92)   |
+| <a id="property-routable"></a> `routable` | `boolean`                                           | Whether this state is routable (has meta.route) States with meta.route can receive play.route events                                                                                                                                    | [types.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L99)   |
+| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                                                                                                                                                      | [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L94)   |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteObject
 
-Defined in: [types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L39)
+Defined in: [types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L39)
 
 Route object with additional metadata.
 
@@ -18,4 +18,4 @@ Additional route metadata (title, breadcrumb, etc.)
 
 | Property                          | Type     | Description                             | Defined in                                                                                                            |
 | --------------------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L41) |
+| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L41) |