@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-tanstack-react-router/functions/createRouteMapFromTree.md

@@ -1,35 +1,46 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createRouteMapFromTree
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createRouteMapFromTree
 
 # Function: createRouteMapFromTree()
 
 ```ts
-function createRouteMapFromTree(routeTree): RouteMap;
+function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [play-tanstack-react-router/src/route-map.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L73)
+Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
-Create RouteMap from RouteTree
+Create a `RouteMap` from a `RouteTree` node structure.
 
-Converts XMachines route tree to RouteMap for use with router adapters.
+Used by framework-router adapters that pass a
+`RouteTree` produced by `extractMachineRoutes()` rather than calling
+`createRouteMap()` 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 `RouteMap` needs for browser URL matching. This matches the
+behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
 
 ## Parameters
 
-| Parameter   | Type                                                     | Description                            |
-| ----------- | -------------------------------------------------------- | -------------------------------------- |
-| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
+| Parameter   | Type                                                     | Description                                                                   |
+| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`.                        |
+| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)    | Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size). |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
 
-RouteMap instance
+A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
 
 ## Example
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+// Preferred — single call for XState machines:
+import { createRouteMap } from "@xmachines/play-router";
+const routeMap = createRouteMap(machine); // takes AnyStateMachine
 
+// Two-step form used by framework adapters that work with route trees:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
 const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
 ```

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

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / extractMachineRoutes
+
+# Function: extractMachineRoutes()
+
+```ts
+function extractMachineRoutes(machine): RouteTree;
+```
+
+Defined in: [play-router/src/extract-routes.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/extract-routes.ts#L89)
+
+Extract complete route tree from state machine graph
+
+Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
+then walks graph nodes to extract route metadata, validate route references,
+and build a hierarchical RouteTree. The graph is attached to the returned
+RouteTree for downstream transition-aware queries.
+
+## Parameters
+
+| Parameter | Type                                                                      | Description             |
+| --------- | ------------------------------------------------------------------------- | ----------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine |
+
+## Returns
+
+[`RouteTree`](../../play-router/interfaces/RouteTree.md)
+
+Route tree with root, byStateId map, byPath map, and graph

package/api/@xmachines/play-tanstack-react-router/interfaces/PlayActor.md

@@ -0,0 +1,68 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayActor
+
+# Interface: PlayActor
+
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L297)
+
+Full actor shape used by `PlayRouterProvider` components across all framework
+adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
+adapters built on the shared framework-router bridge bases).
+
+Extends `RoutableActor` with `currentView` — the provider renders the current
+view spec in addition to synchronizing routes, so it needs both capabilities.
+
+- Use `RoutableActor` when only routing is needed (e.g. `RouterBridgeBase` subclasses,
+  `connectRouter`).
+- Use `PlayActor` when the component also renders the current view spec
+  (e.g. `PlayRouterProvider` renderer callback parameter, `PlayRenderer`).
+
+All `AbstractActor` subclasses that implement both `Routable` and `Viewable`
+satisfy this interface structurally.
+
+## Example
+
+```typescript
+import type { PlayActor } from "@xmachines/play-router";
+
+function MyRouterProvider({ actor }: { actor: PlayActor }) {
+	// access actor.currentRoute (routing) and actor.currentView (rendering)
+}
+```
+
+## Extends
+
+- [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                                                                                                 | Defined in                                                                                                                      |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L261) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L299) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L267) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L269)
+
+Send a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`send`](../../play-dom-router/interfaces/RoutableActor.md#send)

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

@@ -1,8 +1,8 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouteEvent
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouteEvent
 
 # Interface: PlayRouteEvent
 
-Defined in: play-router/dist/types.d.ts:182
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L225)
 
 Enhanced routing event with parameter and query support
 
@@ -22,22 +22,32 @@ via `play.route` events, Actor decides via state machine transitions.
 
 ## Param
 
+**type**
+
 Event discriminator (always "play.route")
 
 ## Param
 
+**to**
+
 Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+**params**
+
+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**
+
 Query parameters only (isolated from path params)
 
 ## Param
 
+**match**
+
 Full URLPattern match result for debugging/observability (optional)
 
 ## Examples
@@ -85,7 +95,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);
@@ -94,7 +104,7 @@ actor.send(event);
 
 ## See
 
-[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md)
 
 ## Remarks
 
@@ -110,10 +120,10 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                      |
-| -------------------------------------- | ---------- | ------------------------------ | ------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | play-router/dist/types.d.ts:187 |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:185 |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:186 |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | play-router/dist/types.d.ts:184 |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | play-router/dist/types.d.ts:183 |
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L226) |

package/api/@xmachines/play-tanstack-react-router/interfaces/PlayRouterProviderBaseProps.md

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProviderBaseProps
+
+# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
+
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L45)
+
+Props shared by every factory-created React `PlayRouterProvider`.
+
+Adapter packages re-export a concrete alias with `TRouter` bound to their
+router instance type (e.g. `PlayRouterProviderProps<TActor>` in
+`@xmachines/play-tanstack-react-router` binds `TRouter` to the TanStack Router
+instance type).
+
+## Extended by
+
+- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
+
+## Type Parameters
+
+| Type Parameter                                 | Default type                |
+| ---------------------------------------------- | --------------------------- |
+| `TRouter`                                      | -                           |
+| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
+
+## Properties
+
+| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                                                                |
+| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [play-tanstack-react-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L51) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-tanstack-react-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L68) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-tanstack-react-router/src/create-play-router-provider.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L66) |
+| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [play-tanstack-react-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L53) |

package/api/@xmachines/play-tanstack-react-router/interfaces/PlayRouterProviderProps.md

@@ -1,14 +1,30 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProviderProps
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProviderProps
 
-# Interface: PlayRouterProviderProps
+# Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L28)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L43)
+
+Props for the TanStack React Router `PlayRouterProvider`.
+
+`router` is the TanStack Router instance returned by `createRouter`.
+See `PlayRouterProviderBaseProps` for the stable-reference requirements on
+`actor`, `router`, and `routeMap`.
+
+## Extends
+
+- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<[`TanStackRouterInstance`](../type-aliases/TanStackRouterInstance.md), `TActor`\>
+
+## Type Parameters
+
+| Type Parameter                                 | Default type                |
+| ---------------------------------------------- | --------------------------- |
+| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
 
 ## Properties
 
-| Property                                  | Type                                                                                                                                                                                            | Defined in                                                                                                                                                                                                                    |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) & [`Viewable`](../../play-actor/interfaces/Viewable.md) | [play-tanstack-react-router/src/play-router-provider.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L29) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                                                                                                                                                              | [play-tanstack-react-router/src/play-router-provider.tsx:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L32) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                            | [play-tanstack-react-router/src/play-router-provider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L31) |
-| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                                                                                                                                   | [play-tanstack-react-router/src/play-router-provider.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L30) |
+| Property                                  | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from                                                                                                                 | Defined in                                                                                                                                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                                                      | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-tanstack-react-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L51) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                            | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-tanstack-react-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L68) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                          | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-tanstack-react-router/src/create-play-router-provider.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L66) |
+| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-tanstack-react-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L53) |

package/api/@xmachines/play-tanstack-react-router/interfaces/RouteMapOptions.md

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L9)
+
+Options for `createRouteMap` and `createRouteMapFromTree`.
+
+## Properties
+
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -1,17 +1,27 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMapping
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMapping
 
 # Interface: RouteMapping
 
-Defined in: [play-tanstack-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L22)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L51)
 
-Mapping between state machine state ID and router path.
+A single state ID ↔ path mapping entry.
 
-Structurally compatible with `BaseRouteMapping` from `@xmachines/play-router`.
-Fields are `readonly` — entries are immutable once passed to `RouteMap`.
+Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`RouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: RouteMapping = { stateId: "home", path: "/" };
+const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                          | Defined in                                                                                                                                                                                            |
-| --------------------------------------- | ---------- | -------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | Router path with optional parameters (e.g., `"/settings/:section?"`) | [play-tanstack-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L26) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State ID from state machine (e.g., `"home"`, `"settings.profile"`)   | [play-tanstack-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L24) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L53) |

package/api/@xmachines/play-tanstack-react-router/interfaces/RouteNavigateEvent.md

@@ -1,8 +1,8 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteNavigateEvent
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteNavigateEvent
 
 # Interface: RouteNavigateEvent
 
-Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L21)
+Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/types.ts#L21)
 
 Event sent to actor when browser navigates.
 
@@ -20,7 +20,7 @@ actor.send({ type: "route.navigate", path: "/dashboard" });
 
 ## Properties
 
-| Property                          | Modifier   | Type               | Description                                                  | Defined in                                                                                                                                                                                    |
-| --------------------------------- | ---------- | ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `readonly` | `string`           | Target route path (may include parameters, e.g., /posts/123) | [play-tanstack-react-router/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L25) |
-| <a id="property-type"></a> `type` | `readonly` | `"route.navigate"` | Event type discriminant (extends XState event pattern)       | [play-tanstack-react-router/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L23) |
+| Property                          | Modifier   | Type               | Description                                                  | Defined in                                                                                                                                                  |
+| --------------------------------- | ---------- | ------------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `readonly` | `string`           | Target route path (may include parameters, e.g., /posts/123) | [play-tanstack-react-router/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/types.ts#L25) |
+| <a id="property-type"></a> `type` | `readonly` | `"route.navigate"` | Event type discriminant (extends XState event pattern)       | [play-tanstack-react-router/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/types.ts#L23) |

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

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouterBridge
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouterBridge
 
 # Interface: RouterBridge
 
-Defined in: play-router/dist/types.d.ts:229
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L341)
 
 RouterBridge interface for runtime infrastructure adapters
 
-Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
 the Actor. Infrastructure "bridges" to the Actor by observing its signals and
 managing its own lifecycle accordingly.
 
@@ -16,13 +16,13 @@ a unidirectional observation pattern. Infrastructure connects to observe Actor s
 
 ## Example
 
-TanStack Router bridge implementation
+Framework router bridge implementation
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
 
-class TanStackRouterBridge implements RouterBridge {
+class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
@@ -44,7 +44,7 @@ class TanStackRouterBridge implements RouterBridge {
 
 ## See
 
-[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
 
 ## Methods
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: play-router/dist/types.d.ts:245
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L357)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: play-router/dist/types.d.ts:260
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-tanstack-react-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -0,0 +1,30 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterBridgeConstructor
+
+# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
+
+```ts
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+```
+
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L31)
+
+Constructor shape a bridge class must satisfy to be used with
+`createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TRouter`      |
+
+## Parameters
+
+| Parameter  | Type                                      |
+| ---------- | ----------------------------------------- |
+| `router`   | `TRouter`                                 |
+| `actor`    | [`PlayActor`](../interfaces/PlayActor.md) |
+| `routeMap` | [`RouteMap`](../classes/RouteMap.md)      |
+
+## Returns
+
+[`RouterBridge`](../interfaces/RouterBridge.md)

package/api/@xmachines/play-tanstack-react-router/type-aliases/TanStackRouterInstance.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterInstance
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterInstance
 
 # Type Alias: TanStackRouterInstance
 
@@ -6,4 +6,4 @@
 type TanStackRouterInstance = ConstructorParameters<typeof TanStackReactRouterBridge>[0];
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L26)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L34)