@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-router/classes/RouterBridgeBase.md

@@ -0,0 +1,300 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridgeBase
+
+# Abstract Class: RouterBridgeBase
+
+Defined in: [router-bridge-base.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L56)
+
+Abstract base class for all `@xmachines` router adapter bridges.
+
+Implements RouterBridge protocol and contains all common bridge logic.
+Subclasses only need to implement the 3 abstract methods that differ
+between frameworks.
+
+## Extended by
+
+- [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
+- [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
+- [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
+- [`SolidRouterBridge`](../../play-tanstack-solid-router/classes/SolidRouterBridge.md)
+- [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
+
+## Implements
+
+- [`RouterBridge`](../interfaces/RouterBridge.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
+```
+
+Defined in: [router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L70)
+
+Constructor receives the 3 things all bridges need.
+
+#### Parameters
+
+| Parameter                   | Type                                                                                                                                    | Description                                           |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `actor`                     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | Actor with currentRoute signal and send method        |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                     | Bidirectional route map for stateId ↔ path resolution |
+| `routeMap.getPathByStateId` | -                                                                                                                                       |
+| `routeMap.getStateIdByPath` | -                                                                                                                                       |
+
+#### Returns
+
+`RouterBridgeBase`
+
+## Properties
+
+| Property                                                              | Modifier    | Type                                                                                                                                    | Default value | Description                                           | Defined in                                                                                                                                                                |
+| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | Actor with currentRoute signal and send method        | [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L71) |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L59) |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L58) |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L61) |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                                | `""`          | -                                                     | [router-bridge-base.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L60) |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                | `undefined`   | Bidirectional route map for stateId ↔ path resolution | [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L72) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | `undefined`   | -                                                     | [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L74) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | `undefined`   | -                                                     | [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L73) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                                     | `null`        | -                                                     | [router-bridge-base.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L62) |
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: [router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L90)
+
+Connect the router bridge to the Actor.
+
+Sets up the TC39 Signal watcher for actor → router direction and
+starts watching router changes (framework-specific).
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`RouterBridge`](../interfaces/RouterBridge.md).[`connect`](../interfaces/RouterBridge.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: [router-bridge-base.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L140)
+
+Disconnect the router bridge from the Actor.
+
+Stops signal watching and unregisters framework-specific router listener.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`RouterBridge`](../interfaces/RouterBridge.md).[`disconnect`](../interfaces/RouterBridge.md#disconnect)
+
+---
+
+### extractParams()
+
+```ts
+protected extractParams(pathname, stateId): Record<string, string>;
+```
+
+Defined in: [router-bridge-base.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L276)
+
+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
+
+---
+
+### extractQuery()
+
+```ts
+protected extractQuery(search): Record<string, string>;
+```
+
+Defined in: [router-bridge-base.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L303)
+
+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
+
+---
+
+### getInitialRouterPath()
+
+```ts
+protected getInitialRouterPath(): string | null;
+```
+
+Defined in: [router-bridge-base.ts:353](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L353)
+
+Return the router's current pathname at connect() time, or null if unavailable.
+
+Called once during connect() to perform the initial URL → actor sync.
+router.subscribe() only fires on _future_ navigation events; it does not
+replay the already-loaded location. Subclasses that can read the router's
+current location synchronously (e.g. `router.state.location.pathname`)
+should override this method so that deep-link / direct-URL loads drive the
+actor to the correct state instead of leaving it at its machine default.
+
+The default returns null (no initial router → actor sync), preserving the
+previous behaviour for bridges that have not yet implemented this hook.
+
+#### Returns
+
+`string` \| `null`
+
+---
+
+### navigateRouter()
+
+```ts
+abstract protected navigateRouter(path): void;
+```
+
+Defined in: [router-bridge-base.ts:323](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L323)
+
+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`
+
+---
+
+### syncActorFromRouter()
+
+```ts
+protected syncActorFromRouter(pathname, search?): void;
+```
+
+Defined in: [router-bridge-base.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L187)
+
+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`
+
+---
+
+### syncRouterFromActor()
+
+```ts
+protected syncRouterFromActor(route): void;
+```
+
+Defined in: [router-bridge-base.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L167)
+
+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`
+
+---
+
+### unwatchRouterChanges()
+
+```ts
+abstract protected unwatchRouterChanges(): void;
+```
+
+Defined in: [router-bridge-base.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L338)
+
+Stop watching for router location changes.
+
+Called by disconnect(). Should clean up the framework-specific subscription.
+
+#### Returns
+
+`void`
+
+---
+
+### watchRouterChanges()
+
+```ts
+abstract protected watchRouterChanges(): void;
+```
+
+Defined in: [router-bridge-base.ts:331](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L331)
+
+Start watching for router location changes.
+
+Called by connect(). Should set up the framework-specific subscription
+for location changes and call syncActorFromRouter() on each change.
+
+#### Returns
+
+`void`

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / buildRouteTree
+
+# Function: buildRouteTree()
+
+```ts
+function buildRouteTree(routes): RouteTree;
+```
+
+Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/build-tree.ts#L13)
+
+Build hierarchical route tree from flat route list
+
+Constructs nested tree respecting parent-child state relationships.
+Absolute routes become top-level, relative routes nest under parents.
+Creates bidirectional maps for state ID ↔ path lookup.
+
+## Parameters
+
+| Parameter | Type                                        | Description                            |
+| --------- | ------------------------------------------- | -------------------------------------- |
+| `routes`  | [`RouteInfo`](../interfaces/RouteInfo.md)[] | Flat list of RouteInfo from extraction |
+
+## Returns
+
+[`RouteTree`](../interfaces/RouteTree.md)
+
+RouteTree with root, byStateId map, and byPath map

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

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

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

@@ -0,0 +1,92 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / crawlMachine
+
+# Function: crawlMachine()
+
+```ts
+function crawlMachine(machine): StateVisit[];
+```
+
+Defined in: [crawl-machine.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/crawl-machine.ts#L74)
+
+Crawl state machine graph using breadth-first traversal
+
+Visits all state nodes in the machine, including deeply nested states, and returns
+complete list of visits with path and parent information. This enables systematic
+discovery of all states for route extraction and tree building.
+
+**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
+routing information from the state machine definition rather than external configuration.
+The BFS traversal ensures all nested states are discovered, enabling the Actor to
+define the complete navigation structure through its machine definition.
+
+## Parameters
+
+| Parameter | Type              | Description                      |
+| --------- | ----------------- | -------------------------------- |
+| `machine` | `AnyStateMachine` | XState v5 state machine to crawl |
+
+## Returns
+
+[`StateVisit`](../interfaces/StateVisit.md)[]
+
+Array of state visits in breadth-first order
+
+## Examples
+
+Basic machine crawl
+
+```typescript
+import { createMachine } from "xstate";
+import { crawlMachine } from "@xmachines/play-router";
+
+const machine = createMachine({
+	initial: "home",
+	states: {
+		home: {},
+		dashboard: {
+			initial: "overview",
+			states: {
+				overview: {},
+				settings: {},
+			},
+		},
+	},
+});
+
+const visits = crawlMachine(machine);
+// Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
+console.log(visits.map((v) => v.path.join(".")));
+// ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']
+```
+
+Extract state paths and parents
+
+```typescript
+import { crawlMachine } from "@xmachines/play-router";
+
+const visits = crawlMachine(machine);
+visits.forEach((visit) => {
+	console.log({
+		path: visit.path.join(".") || "root",
+		hasParent: !!visit.parent,
+		hasChildren: Object.keys(visit.node.states).length > 0,
+	});
+});
+```
+
+## See
+
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [extractRoute](extractRoute.md) for extracting route from individual states
+- [extractMachineRoutes](extractMachineRoutes.md) for complete route extraction
+- [StateVisit](../interfaces/StateVisit.md) for visit structure
+
+## Remarks
+
+**BFS Traversal:** Breadth-first search ensures systematic discovery of all states
+at each nesting level before descending deeper. This produces a predictable ordering
+useful for route tree construction and debugging.
+
+**Path Format:** Paths use array notation (`['dashboard', 'settings']`) which can be
+joined with dots for state IDs (`'dashboard.settings'`) matching XState's hierarchical
+state naming convention.

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

@@ -0,0 +1,47 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createBrowserHistory
+
+# Function: createBrowserHistory()
+
+```ts
+function createBrowserHistory(options): BrowserHistory;
+```
+
+Defined in: [create-browser-history.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L99)
+
+Create browser history that wraps window.history
+
+Aligned with TanStack Router's history interface for API parallelism.
+
+Architecture:
+
+- Patches window.history.pushState/replaceState to detect changes
+- Listens to popstate for browser back/forward
+- Provides subscribe() for listeners (like PlayRouterProvider)
+- Testable (accepts window object)
+
+Usage:
+
+```typescript
+const history = createBrowserHistory({ window });
+
+const unsubscribe = history.subscribe((location) => {
+	console.log("URL changed:", location.pathname);
+});
+
+history.push("/new-path");
+
+// Later:
+unsubscribe();
+history.destroy();
+```
+
+## Parameters
+
+| Parameter        | Type                                                               |
+| ---------------- | ------------------------------------------------------------------ |
+| `options`        | \{ `window`: [`BrowserWindow`](../interfaces/BrowserWindow.md); \} |
+| `options.window` | [`BrowserWindow`](../interfaces/BrowserWindow.md)                  |
+
+## Returns
+
+[`BrowserHistory`](../interfaces/BrowserHistory.md)

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

@@ -0,0 +1,53 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+function createRouteMap(routeTree): RouteMap;
+```
+
+Defined in: [create-route-map.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L120)
+
+Create a RouteMap from a RouteTree for efficient path lookups.
+
+Architecture:
+
+- 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
+
+**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:
+
+```typescript
+import "urlpattern-polyfill"; // before importing @xmachines/play-router
+```
+
+If `URLPattern` is unavailable, parameterized routes will not match and a
+`console.warn` is emitted. Static (exact) routes are unaffected.
+
+Usage:
+
+```typescript
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(routeTree);
+
+const { to, params } = routeMap.resolve("/settings/account");
+if (to) {
+	actor.send({ type: "play.route", to, params });
+}
+```
+
+## Parameters
+
+| Parameter   | Type                                      |
+| ----------- | ----------------------------------------- |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md) |
+
+## Returns
+
+[`RouteMap`](../interfaces/RouteMap.md)

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

@@ -0,0 +1,76 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouter
+
+# Function: createRouter()
+
+```ts
+function createRouter(options): VanillaRouter;
+```
+
+Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L73)
+
+Create vanilla router for framework-agnostic routing.
+
+Architecture:
+
+- Just wraps history and routeTree
+- Does NOT embed routeMap (providers need it as prop)
+- Framework-agnostic history management only
+
+Why no routeMap:
+
+- Router doesn't know about state IDs (that's Play-specific)
+- RouteMap is the bridge between router and actor
+- Provider receives routeMap as prop to do path → state ID resolution
+
+Usage (parallel to TanStack mode):
+
+```typescript
+// Both modes: identical setup
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(routeTree);
+const history = createBrowserHistory({ window });
+
+// Vanilla router
+const router = createRouter({ routeTree, history });
+
+// Provider needs routeMap as prop (router doesn't have it)
+<PlayRouterProvider
+  actor={actor}
+  router={router}
+  routeMap={routeMap}  // ← Must pass separately
+  renderer={(currentActor, currentRouter) => {
+    void currentRouter;
+    return <Renderer actor={currentActor} components={components} />;
+  }}
+/>
+```
+
+Compare to TanStack mode:
+
+```typescript
+// TanStack router (external library)
+const router = TanStackCreateRouter({ routeTree, history });
+
+// Provider needs routeMap as prop (same as vanilla!)
+<PlayRouterProvider
+  actor={actor}
+  router={router}
+  routeMap={routeMap}  // ← Must pass separately
+  renderer={(currentActor, currentRouter) => {
+    void currentRouter;
+    return <Renderer actor={currentActor} components={components} />;
+  }}
+/>
+```
+
+## Parameters
+
+| Parameter           | Type                                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | \{ `history`: [`BrowserHistory`](../interfaces/BrowserHistory.md); `routeTree`: [`RouteTree`](../interfaces/RouteTree.md); \} |
+| `options.history`   | [`BrowserHistory`](../interfaces/BrowserHistory.md)                                                                           |
+| `options.routeTree` | [`RouteTree`](../interfaces/RouteTree.md)                                                                                     |
+
+## Returns
+
+[`VanillaRouter`](../interfaces/VanillaRouter.md)