@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/api/@xmachines/play-tanstack-react-router/classes/TanStackReactRouterBridge.md

@@ -1,15 +1,16 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackReactRouterBridge
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackReactRouterBridge
 
 # Class: TanStackReactRouterBridge
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L78)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
 
-TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase
+Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
 
 ## Remarks
 
-Extends RouterBridgeBase to handle all common lifecycle and sync logic.
-Only 3 TanStack-specific methods are implemented here.
+Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
+the TanStack-specific navigation and subscription methods shared by the React
+and Solid adapters.
 
 Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
 back/forward browser navigation (popstate events) are also captured. The
@@ -24,10 +25,14 @@ Architectural Invariants:
 - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
 - Actor validates all navigation via guards before URL changes
 
+The class is concrete — it can be instantiated directly. The framework
+packages re-export or subclass it purely to bind the public adapter name
+(and, for Solid, to add the `dispose()` alias).
+
 ## Example
 
 ```typescript
-const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+const bridge = new TanStackRouterBridgeBase(router, actor, routeMap);
 bridge.connect();
 return () => bridge.disconnect();
 ```
@@ -44,43 +49,29 @@ return () => bridge.disconnect();
 new TanStackReactRouterBridge(
    router,
    actor,
-   routeMap): TanStackReactRouterBridge;
+   routeMap): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L88)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
 
-Create TanStack React Router bridge
+Create a TanStack Router bridge
 
 #### Parameters
 
-| Parameter  | Type                                                                                                                                    | Description                                       |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                                                                           | TanStack React Router instance                    |
-| `actor`    | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | XMachines actor instance                          |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                                                                                               | Bidirectional mapping between state IDs and paths |
+| Parameter  | Type                                                                                      | Description                                       |
+| ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                             | TanStack Router instance (from `createRouter`)    |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                      | XMachines actor instance                          |
+| `routeMap` | [`TanStackRouteMapLike`](../../play-tanstack-router/type-aliases/TanStackRouteMapLike.md) | Bidirectional mapping between state IDs and paths |
 
 #### Returns
 
-`TanStackReactRouterBridge`
+`TanStackRouterBridgeBase`
 
 #### Overrides
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
 
-## Properties
-
-| Property                                                              | Modifier    | Type                                                                                                                                    | Description                                           | Inherited from                                                                                                                                                                | Defined in                                  |
-| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | Actor with currentRoute signal and send method        | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | play-router/dist/router-bridge-base.d.ts:55 |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                               | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | play-router/dist/router-bridge-base.d.ts:61 |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                               | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | play-router/dist/router-bridge-base.d.ts:60 |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                               | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | play-router/dist/router-bridge-base.d.ts:63 |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                                | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | play-router/dist/router-bridge-base.d.ts:62 |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                | Bidirectional route map for stateId ↔ path resolution | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | play-router/dist/router-bridge-base.d.ts:56 |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | -                                                     | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:58 |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | -                                                     | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:57 |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                                     | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | play-router/dist/router-bridge-base.d.ts:64 |
-
 ## Methods
 
 ### connect()
@@ -89,13 +80,22 @@ Create TanStack React Router bridge
 connect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:81
+Defined in: [play-router/src/router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
 Sets up the TC39 Signal watcher for actor → router direction and
 starts watching router changes (framework-specific).
 
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
 #### Returns
 
 `void`
@@ -112,7 +112,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:87
+Defined in: [play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -125,224 +125,3 @@ Stops signal watching and unregisters framework-specific router listener.
 #### Inherited from
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
-
----
-
-### extractParams()
-
-```ts
-protected extractParams(pathname, stateId): Record<string, string>;
-```
-
-Defined in: play-router/dist/router-bridge-base.d.ts:134
-
-Extract path parameters from URL using the URLPattern API.
-
-Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
-polyfill), this method returns `{}` silently (graceful degradation — routing still
-works, params will be empty).
-
-#### Parameters
-
-| Parameter  | Type     | Description                                       |
-| ---------- | -------- | ------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')       |
-| `stateId`  | `string` | The matched state ID for looking up route pattern |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
-
-#### Inherited from
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`extractParams`](../../play-router/classes/RouterBridgeBase.md#extractparams)
-
----
-
-### extractQuery()
-
-```ts
-protected extractQuery(search): Record<string, string>;
-```
-
-Defined in: play-router/dist/router-bridge-base.d.ts:141
-
-Extract query parameters from URL search string.
-
-#### Parameters
-
-| Parameter | Type     | Description                                      |
-| --------- | -------- | ------------------------------------------------ |
-| `search`  | `string` | URL search string (e.g., '?tab=security&page=1') |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted query parameters or empty object
-
-#### Inherited from
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`extractQuery`](../../play-router/classes/RouterBridgeBase.md#extractquery)
-
----
-
-### getInitialRouterPath()
-
-```ts
-protected getInitialRouterPath(): string | null;
-```
-
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L110)
-
-Read the router's current pathname for initial sync.
-
-Called once in connect() to handle cold-load / deep-link scenarios where
-the URL differs from the actor's initial state.
-
-#### Returns
-
-`string` \| `null`
-
-#### Overrides
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`getInitialRouterPath`](../../play-router/classes/RouterBridgeBase.md#getinitialrouterpath)
-
----
-
-### navigateRouter()
-
-```ts
-protected navigateRouter(path): void;
-```
-
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L100)
-
-Navigate the framework router to the given path.
-
-Called when actor's currentRoute signal changes to a new path.
-Must trigger the framework router's navigation (e.g., router.navigate(path)).
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-#### Returns
-
-`void`
-
-#### Overrides
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`navigateRouter`](../../play-router/classes/RouterBridgeBase.md#navigaterouter)
-
----
-
-### syncActorFromRouter()
-
-```ts
-protected syncActorFromRouter(pathname, search?): void;
-```
-
-Defined in: play-router/dist/router-bridge-base.d.ts:101
-
-Sync actor state when router location changes.
-
-Sends play.route event to actor with resolved stateId, params, and query.
-Prevents circular updates via isProcessingNavigation flag.
-
-#### Parameters
-
-| Parameter  | Type     |
-| ---------- | -------- |
-| `pathname` | `string` |
-| `search?`  | `string` |
-
-#### Returns
-
-`void`
-
-#### Inherited from
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`syncActorFromRouter`](../../play-router/classes/RouterBridgeBase.md#syncactorfromrouter)
-
----
-
-### syncRouterFromActor()
-
-```ts
-protected syncRouterFromActor(route): void;
-```
-
-Defined in: play-router/dist/router-bridge-base.d.ts:94
-
-Sync router location when actor route signal changes.
-
-Calls navigateRouter() for framework-specific navigation.
-Prevents circular updates via isProcessingNavigation flag.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `route`   | `unknown` |
-
-#### Returns
-
-`void`
-
-#### Inherited from
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`syncRouterFromActor`](../../play-router/classes/RouterBridgeBase.md#syncrouterfromactor)
-
----
-
-### unwatchRouterChanges()
-
-```ts
-protected unwatchRouterChanges(): void;
-```
-
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L131)
-
-Stop watching for router location changes.
-
-Called by disconnect(). Should clean up the framework-specific subscription.
-
-#### Returns
-
-`void`
-
-#### Overrides
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`unwatchRouterChanges`](../../play-router/classes/RouterBridgeBase.md#unwatchrouterchanges)
-
----
-
-### watchRouterChanges()
-
-```ts
-protected watchRouterChanges(): void;
-```
-
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L123)
-
-Subscribe to ALL navigation events via router.history.
-
-router.history.subscribe fires for PUSH, POP, BACK, FORWARD, REPLACE, and GO —
-covering both link clicks and browser back/forward button presses.
-
-The subscriber callback receives { location, action } where location is the
-new history location with pathname and search already updated.
-
-#### Returns
-
-`void`
-
-#### Overrides
-
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`watchRouterChanges`](../../play-router/classes/RouterBridgeBase.md#watchrouterchanges)

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

@@ -0,0 +1,45 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createPlayRouterProvider
+
+# Function: createPlayRouterProvider()
+
+```ts
+function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
+```
+
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L92)
+
+Create a React `PlayRouterProvider` component bound to a specific bridge class.
+
+The returned component connects a `PlayerActor` to the framework router,
+keeping actor state and browser URL in sync bidirectionally.
+
+The bridge is created once on mount and torn down on unmount. It is also
+rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
+props must be **stable references** (created outside JSX or memoized).
+Under React `<StrictMode>` the effect runs twice on mount
+(connect → disconnect → connect), which the bridges support.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TRouter`      |
+
+## Parameters
+
+| Parameter    | Type                                                                                         | Description                                                            |
+| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | Bridge class constructed as `new BridgeCtor(router, actor, routeMap)`. |
+
+## Returns
+
+A `PlayRouterProvider` component, generic over the actor type so the
+`renderer` callback receives the same concrete actor type that was passed in.
+
+\<`TActor`\>(`__namedParameters`) => `Element`
+
+## Example
+
+```tsx
+export const PlayRouterProvider = createPlayRouterProvider(TanStackReactRouterBridge);
+```

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

@@ -1,53 +1,39 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createRouteMap
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createRouteMap
 
 # Function: createRouteMap()
 
 ```ts
-function createRouteMap(routeTree): RouteMap;
+function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: play-router/dist/create-route-map.d.ts:65
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/create-route-map.ts#L45)
 
-Create a RouteMap from a RouteTree for efficient path lookups.
+Create a `RouteMap` from an XState state machine.
 
-Architecture:
+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.
 
-- Pure function - no side effects
-- O(1) lookups for exact matches via Map
-- O(k) bucket-indexed pattern matching with URLPattern, where k = routes in the
-  first-segment bucket (typically << total routes)
-- Returns formatted state IDs (with # prefix)
-- Extracts params from matched patterns
+## Parameters
 
-**URLPattern requirement:** Dynamic route pattern matching requires `URLPattern`
-to be available on `globalThis`. On Node.js < 24 and older browsers, load a polyfill
-before calling this function:
+| Parameter  | Type                                                                      | Description                                                                                                         |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
 
-```typescript
-import "urlpattern-polyfill"; // before importing @xmachines/play-router
-```
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)
 
-If `URLPattern` is unavailable, parameterized routes will not match and a
-`console.warn` is emitted. Static (exact) routes are unaffected.
+A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
 
-Usage:
+## Example
 
 ```typescript
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
+import { createRouteMap } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
 
-const { to, params } = routeMap.resolve("/settings/account");
-if (to) {
-	actor.send({ type: "play.route", to, params });
-}
+const routeMap = createRouteMap(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
 ```
-
-## Parameters
-
-| Parameter   | Type                                                     |
-| ----------- | -------------------------------------------------------- |
-| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) |
-
-## Returns
-
-[`RouteMap`](../../play-router/interfaces/RouteMap.md)

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.0.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.0.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.0.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.0.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.0.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.0.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.0.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)