@xmachines/docs 1.0.0-beta.52 → 1.0.0-beta.54

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L101)
 
 Shared bidirectional route map base class.
 
@@ -17,10 +17,17 @@ own and inherit the full public API from here.
 - Results are cached after the first match in an LRU cache (default 500 entries,
   configurable via the `cacheSize` constructor option)
 
-**Pattern syntax** (`:param` / `:param?`):
+**Pattern syntax** (`:param` / `:param?` / `*`):
 
 - `:param` — required segment, matches exactly one non-`/` segment
 - `:param?` — optional segment, matches zero or one non-`/` segment
+- `*` — wildcard, matches any number of segments (URLPattern semantics)
+
+**StateId forms:** stateIds may be registered and looked up in either
+`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+`getStateIdByPath` returns the stateId exactly as registered;
+`getPathByStateId` accepts both forms. Registering the same stateId in both
+forms refers to one entry (the later registration wins for reverse lookup).
 
 ## Example
 
@@ -50,7 +57,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L127)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,10 +85,14 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L218)
 
 Look up the path pattern registered for a state ID.
 
+Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+which form was used at registration — lookups are canonicalized internally,
+so consumers never need to try both forms.
+
 #### Parameters
 
 | Parameter | Type     | Description                                               |
@@ -98,6 +109,7 @@ The registered path pattern, or `null` if the state ID is unknown
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
 map.getPathByStateId("missing"); // null
 ```
 
@@ -109,7 +121,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L178)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -0,0 +1,45 @@
+[API](../../../README.md) / [@xmachines/play-react-router](../README.md) / createPlayRouterProvider
+
+# Function: createPlayRouterProvider()
+
+```ts
+function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
+```
+
+Defined in: [play-react-router/src/create-play-router-provider.tsx:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L81)
+
+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(ReactRouterBridge);
+```

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

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

@@ -6,11 +6,11 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Create a `RouteMap` from a `RouteTree` node structure.
 
-Used by framework-router adapters (React Router, TanStack Router) that pass a
+Used by framework-router adapters that pass a
 `RouteTree` produced by `extractMachineRoutes()` rather than calling
 `createRouteMap()` directly.
 

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

@@ -2,11 +2,11 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L297)
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L297)
 
 Full actor shape used by `PlayRouterProvider` components across all framework
-adapters (`play-solid-router`, `play-tanstack-solid-router`, `play-vue-router`,
-`play-tanstack-react-router`, `play-react-router`).
+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.
@@ -37,9 +37,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 
 | 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-beta.52/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-beta.52/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-beta.52/packages/play-router/src/types.ts#L267) |
+| <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-beta.54/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-beta.54/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-beta.54/packages/play-router/src/types.ts#L267) |
 
 ## Methods
 
@@ -49,7 +49,7 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L269)
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L269)
 
 Send a route navigation event to the actor.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L225)
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/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
 
+**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
@@ -112,8 +122,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | 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.0.0-beta.52/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.0.0-beta.52/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.0.0-beta.52/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.0.0-beta.52/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.0.0-beta.52/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/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.0.0-beta.54/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.0.0-beta.54/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.0.0-beta.54/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.0.0-beta.54/packages/play-router/src/types.ts#L226) |

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProviderBaseProps
+
+# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
+
+Defined in: [play-react-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L34)
+
+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-react-router` binds `TRouter` to the `createBrowserRouter`
+return 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-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
+| <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-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
+| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

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

@@ -2,7 +2,17 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L9)
+Defined in: [play-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/play-router-provider.tsx#L26)
+
+Props for the React Router `PlayRouterProvider`.
+
+`router` is the React Router instance returned by `createBrowserRouter`.
+See `PlayRouterProviderBaseProps` for the stable-reference requirements on
+`actor`, `router`, and `routeMap`.
+
+## Extends
+
+- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<`BrowserRouterInstance`, `TActor`\>
 
 ## Type Parameters
 
@@ -12,9 +22,9 @@ Defined in: [play-react-router/src/play-router-provider.tsx:9](https://gitlab.co
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                                        |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with React 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-react-router/src/play-router-provider.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L15) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-react-router/src/play-router-provider.tsx:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L32) |
-| <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-react-router/src/play-router-provider.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L30) |
-| <a id="property-router"></a> `router`     | `Router`                             | The React Router instance returned by `createBrowserRouter`.                                                                                                                                                                                                                                                                                                                                                             | [play-react-router/src/play-router-provider.tsx:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L17) |
+| 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-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
+| <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-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
+| <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-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
+| <a id="property-router"></a> `router`     | `Router`                             | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ Options for `createRouteMap` and `createRouteMapFromTree`.
 
 | 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.0.0-beta.52/packages/play-router/src/create-route-map.ts#L20) |
+| <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.0.0-beta.54/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L51)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | 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:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L61) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/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.0.0-beta.54/packages/play-router/src/base-route-map.ts#L53) |

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

@@ -2,11 +2,11 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/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> {
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/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/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

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

@@ -0,0 +1,30 @@
+[API](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterBridgeConstructor
+
+# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
+
+```ts
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+```
+
+Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L20)
+
+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-react-router/{functions → variables}/PlayRouterProvider.md

@@ -1,12 +1,12 @@
 [API](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProvider
 
-# Function: PlayRouterProvider()
+# Variable: PlayRouterProvider
 
 ```ts
-function PlayRouterProvider<TActor>(__namedParameters): Element;
+const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-react-router/src/play-router-provider.tsx#L43)
+Defined in: [play-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/play-router-provider.tsx#L38)
 
 Connects a `PlayerActor` to React Router, keeping actor state and browser URL
 in sync bidirectionally.
@@ -23,9 +23,9 @@ props must be **stable references** (created outside JSX or memoized).
 
 ## Parameters
 
-| Parameter           | Type                                                                              |
-| ------------------- | --------------------------------------------------------------------------------- |
-| `__namedParameters` | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md)\<`TActor`\> |
+| Parameter           | Type                                                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderBaseProps`](../interfaces/PlayRouterProviderBaseProps.md)\<`Router`, `TActor`\> |
 
 ## Returns
 

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

@@ -189,7 +189,6 @@ bridge.disconnect();
 
 | Export                        | Description                                                                                |
 | ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `createRouteMatcher(tree)`    | Create a `RouteMatcher` that matches URL paths to `#stateId` values and extracts params    |
 | `RouteMap`                    | Bidirectional `stateId ↔ path` lookup class; supports O(1) exact and O(k) pattern matching |
 | `findRouteById(tree, id)`     | Look up a `RouteNode` by state ID                                                          |
 | `findRouteByPath(tree, path)` | Look up a `RouteNode` by URL path (supports dynamic patterns)                              |
@@ -216,11 +215,11 @@ bridge.disconnect();
 
 ### Validation
 
-| Export                                   | Description                                       |
-| ---------------------------------------- | ------------------------------------------------- |
-| `validateRouteFormat(route, stateId)`    | Assert route path is non-empty                    |
-| `validateStateExists(stateId, stateIds)` | Assert a state ID is present in the machine graph |
-| `detectDuplicateRoutes(routes)`          | Throw if any two states share the same URL path   |
+| Export                                   | Description                                           |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `validateRouteFormat(route, stateId)`    | Assert route path is non-empty                        |
+| `validateStateExists(stateId, stateIds)` | Assert a state ID is present in the machine graph     |
+| `detectDuplicateRoutes(routes)`          | Throw if any two states resolve to the same full path |
 
 ### Key Types
 
@@ -351,6 +350,7 @@ runBridgeContractTests({
 - **[@xmachines/play-actor](../play-actor/README.md)** — Abstract actor base class (`AbstractActor`, `Routable`); all `AbstractActor` subclasses satisfy `RoutableActor` structurally
 - **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
 - **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v5 logic adapter that integrates with route trees
+- **[@xmachines/play-tanstack-router](../play-tanstack-router/README.md)** — Shared TanStack Router bridge base (framework-agnostic)
 - **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** — TanStack Router adapter (React)
 - **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** — TanStack Router adapter (SolidJS)
 - **[@xmachines/play-react-router](../play-react-router/README.md)** — React Router v7 adapter
@@ -379,7 +379,6 @@ MIT — see [LICENSE](LICENSE).
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouteMatch](interfaces/RouteMatch.md)
-- [RouteMatcher](interfaces/RouteMatcher.md)
 - [RouteNode](interfaces/RouteNode.md)
 - [RouteObject](interfaces/RouteObject.md)
 - [RouterBridge](interfaces/RouterBridge.md)
@@ -398,7 +397,6 @@ MIT — see [LICENSE](LICENSE).
 - [buildRouteTree](functions/buildRouteTree.md)
 - [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [createRouteMatcher](functions/createRouteMatcher.md)
 - [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
 - [extractQuery](functions/extractQuery.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L101)
 
 Shared bidirectional route map base class.
 
@@ -17,10 +17,17 @@ own and inherit the full public API from here.
 - Results are cached after the first match in an LRU cache (default 500 entries,
   configurable via the `cacheSize` constructor option)
 
-**Pattern syntax** (`:param` / `:param?`):
+**Pattern syntax** (`:param` / `:param?` / `*`):
 
 - `:param` — required segment, matches exactly one non-`/` segment
 - `:param?` — optional segment, matches zero or one non-`/` segment
+- `*` — wildcard, matches any number of segments (URLPattern semantics)
+
+**StateId forms:** stateIds may be registered and looked up in either
+`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+`getStateIdByPath` returns the stateId exactly as registered;
+`getPathByStateId` accepts both forms. Registering the same stateId in both
+forms refers to one entry (the later registration wins for reverse lookup).
 
 ## Example
 
@@ -50,7 +57,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L127)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,10 +85,14 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L218)
 
 Look up the path pattern registered for a state ID.
 
+Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+which form was used at registration — lookups are canonicalized internally,
+so consumers never need to try both forms.
+
 #### Parameters
 
 | Parameter | Type     | Description                                               |
@@ -98,6 +109,7 @@ The registered path pattern, or `null` if the state ID is unknown
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
 map.getPathByStateId("missing"); // null
 ```
 
@@ -109,7 +121,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L178)
 
 Resolve a URL path to its mapped state ID.