@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -1,4 +1,6 @@
-[Documentation](../../README.md) / @xmachines/play-tanstack-solid-router
+[API](../../README.md) / @xmachines/play-tanstack-solid-router
+
+<!-- generated-by: gsd-doc-writer -->
 
 # @xmachines/play-tanstack-solid-router
 
@@ -6,280 +8,318 @@
 
 Signals-native integration with TanStack Solid Router enabling logic-driven navigation through Solid.js reactivity.
 
-## Overview
-
-`@xmachines/play-tanstack-solid-router` provides seamless integration between TanStack Solid Router and XMachines state machines. Built on Solid's reactive primitives, it implements the `RouterBridgeBase` pattern for bidirectional synchronization while remaining framework-swappable.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+Part of the [xmachines-js](../../README.md) monorepo.
 
-- **Actor Authority (INV-01):** State machine controls navigation, router reflects decisions
-- **Passive Infrastructure (INV-04):** Router observes `actor.currentRoute` signal
-- **Signal-Only Reactivity (INV-05):** `createEffect` synchronizes URL with actor state
-
-**Key Benefits:**
+## Overview
 
-- **Signals-native:** Zero adaptation layer between Solid signals and TC39 Signals
-- **Bridge-first:** Extends shared `RouterBridgeBase` policy used by other adapters
-- **Automatic tracking:** `createEffect` handles dependency tracking (no manual Watcher setup needed for the bridge)
-- **Logic-driven navigation:** Business logic in state machines, not components
-- **Type-safe parameters:** Route params flow through state machine context
+[`@xmachines/play-tanstack-solid-router`](README.md) connects a Play actor to TanStack Solid Router through `TanStackSolidRouterBridge`.
 
-**Framework Compatibility:**
+The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md), keeping adapter behavior consistent across frameworks:
 
-- TanStack Solid Router 1.100.0+
-- SolidJS 1.8.0+
-- TC39 Signals polyfill integration
+- Actor route signal (`actor.currentRoute`) drives router navigation.
+- Router history events send `play.route` intents back to the actor.
+- Guarded state transitions remain actor-owned (Actor Authority).
+- Circular update prevention built into `RouterBridgeBase`.
 
 ## Installation
 
 ```bash
-npm install @tanstack/solid-router@^1.108.0 solid-js@^1.8.0 @xmachines/play-tanstack-solid-router @xmachines/play-solid
+pnpm add @tanstack/solid-router solid-js
+pnpm add @xmachines/play-tanstack-solid-router @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `@tanstack/solid-router` ^1.108.0 - TanStack Solid Router library
-- `solid-js` ^1.8.0 - SolidJS runtime
-- `@xmachines/play-solid` - Solid renderer (`PlayRenderer`)
-- `@xmachines/play-actor` - Actor base
-- `@xmachines/play-router` - Route extraction
-- `@xmachines/play-signals` - TC39 Signals polyfill
+- `@tanstack/solid-router` `^1.168.7`
+- `solid-js` `^1.8.0`
+- `xstate` `^5.31.0`
+
+## Current Exports
+
+- `TanStackSolidRouterBridge` — primary adapter class
+- `PlayRouterProvider` — Solid component wrapper for bridge lifecycle
+- `PlayRouterProviderProps`, `TanStackRouterInstance` (types)
+- `PlayActor` — canonical actor shape (`AbstractActor & Routable & Viewable`) from `@xmachines/play-router`; use when constructing a typed renderer callback for `PlayRouterProvider`
+- `RoutableActor` — deprecated alias for `PlayActor`; use `PlayActor` from `@xmachines/play-router` instead
+- `RouteMap`, `createRouteMap`, `RouteMapping`, `RouteMapOptions` (re-exported from `@xmachines/play-router`)
+- `TanStackRouterLike` (type)
+- `RouterBridge`, `PlayRouteEvent` (types)
+
+## URLPattern Support
+
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via [`@xmachines/play-router`](../play-router/README.md).
+
+URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router`](../play-router/README.md) for details.
 
 ## Quick Start
 
 ```tsx
-import { Router, createRouter } from "@tanstack/solid-router";
-import { PlayTanStackRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
-import { PlayRenderer } from "@xmachines/play-solid";
+import { createRouter } from "@tanstack/solid-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { routeTree as routerRouteTree } from "./routeTree.gen"; // from TanStack
-
-function App() {
-	// 1. Create player with state machine
-	const createPlayer = definePlayer({
-		machine: authMachine,
-		catalog: componentCatalog,
-	});
-	const actor = createPlayer();
-	actor.start();
-
-	// 2. Create TanStack router instance
-	const router = createRouter({ routeTree: routerRouteTree });
-
-	// 3. Create route mapping from machine routes
-	const routeMap = createRouteMap(authMachine);
-
-	return (
-		// 4. Wrap with provider to sync actor and router
-		<PlayTanStackRouterProvider
-			actor={actor}
-			router={router}
-			routeMap={routeMap}
-			renderer={(currentActor, currentRouter) => (
-				<Router router={currentRouter}>
-					<PlayRenderer actor={currentActor} components={components} />
-				</Router>
-			)}
-		/>
-	);
-}
-```
-
-## API Reference
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { TanStackSolidRouterBridge, createRouteMap } from "@xmachines/play-tanstack-solid-router";
 
-### `SolidRouterBridge`
+const routeMap = createRouteMap(machine);
+const router = createRouter({ routeTree: tanstackRouteTree });
 
-Router adapter implementing the `RouterBridge` protocol for TanStack Solid Router.
+const actor = definePlayer({ machine })();
+actor.start();
 
-**Type Signature:**
+const bridge = new TanStackSolidRouterBridge(router, actor, routeMap);
+bridge.connect();
 
-```typescript
-class SolidRouterBridge {
-	constructor(router: Router, actor: AbstractActor<any>, routeMap: RouteMap);
-	dispose(): void;
-}
+// later
+bridge.disconnect();
 ```
 
-**Constructor Parameters:**
-
-- `router` - TanStack Solid Router instance
-- `actor` - XMachines actor instance
-- `routeMap` - Bidirectional state ID ↔ path mapping
-
-**Methods:**
+### Solid convenience wrapper
 
-- `connect()` - Start bidirectional synchronization.
-- `disconnect()` - Stop synchronization and cleanup bridge resources.
-- `dispose()` - Alias of `disconnect()`.
+Use `PlayRouterProvider` when you want bridge lifecycle wiring managed by a component:
 
-**Internal Behavior:**
+```tsx
+import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { RouterProvider } from "@tanstack/solid-router";
+
+<PlayRouterProvider
+	actor={actor}
+	router={router}
+	routeMap={routeMap}
+	renderer={(currentActor, currentRouter) => (
+		<RouterProvider router={currentRouter}>{/* your app here */}</RouterProvider>
+	)}
+/>;
+```
 
-- Uses `RouterBridgeBase` TC39 watcher lifecycle for actor→router synchronization
-- Updates TanStack Router via `router.navigate({ to: path })` when actor state changes
-- Uses `router.subscribe` to watch history navigation events
-- Sends `play.route` events to actor when user navigates
+## API
 
-### `PlayTanStackRouterProvider`
+### `TanStackSolidRouterBridge`
 
-A Solid component that automatically sets up, connects, and tears down the `SolidRouterBridge` using Solid's lifecycle.
+Primary adapter class extending `RouterBridgeBase`.
 
-```tsx
-interface PlayTanStackRouterProviderProps {
-	actor: AbstractActor<any>;
-	router: Router;
-	routeMap: RouteMap;
-	renderer: (actor: AbstractActor<any>, router: Router) => JSX.Element;
+```ts
+class TanStackSolidRouterBridge {
+	constructor(router: TanStackRouterLike, actor: RoutableActor, routeMap: RouteMap);
+	connect(): void;
+	disconnect(): void;
+	dispose(): void; // alias for disconnect()
 }
 ```
 
-**Props:**
+**Behavior:**
 
-- `actor` - The XMachines player actor
-- `router` - The TanStack Solid Router instance
-- `routeMap` - Mapping between paths and state IDs
-- `renderer` - A render prop function that receives the active actor and router
+- `connect()` — subscribes to `router.history`, performs initial deep-link sync from `router.history.location`, and starts watching `actor.currentRoute` for state-driven navigation.
+- `disconnect()` — unsubscribes from history and stops all sync.
+- Navigates via `router.navigate({ to: path })`.
+- Subscribes via `router.history.subscribe` — covers PUSH, POP, BACK, FORWARD, REPLACE, and GO, and works without `<RouterProvider>` mounted.
 
-**Behavior:**
+### `PlayRouterProvider`
 
-1. Instantiates `SolidRouterBridge` on mount
-2. Calls `bridge.connect()`
-3. Renders the content returned by the `renderer` function
-4. Calls `bridge.disconnect()` when the component unmounts via `onCleanup`
+Solid component that instantiates, connects, and cleans up a `TanStackSolidRouterBridge` automatically.
 
-### `createRouteMap()`
+```ts
+interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
+	/** The actor to sync with TanStack Solid Router. */
+	actor: TActor;
+	/** The TanStack Router instance returned by `createRouter`. */
+	router: TanStackRouterInstance;
+	/** Bidirectional route map for state ID ↔ URL path lookups. */
+	routeMap: RouteMap;
+	/** Renderer callback receives the same concrete actor type that was passed in. */
+	renderer: (actor: TActor, router: TanStackRouterInstance) => JSX.Element;
+}
+```
 
-Helper to build a `RouteMap` instance directly from an XState machine.
+The bridge is created synchronously at component evaluation time (Solid's execution model) and torn down via `onCleanup` when the component is disposed.
 
-**Signature:**
+### `RouteMap` and `createRouteMap`
 
-```typescript
-function createRouteMap(machine: AnyStateMachine): RouteMap;
-```
+Map state IDs to URL paths and resolve URLs back to state IDs.
 
-**Usage:**
+```ts
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
 
-```typescript
-import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("home"); // "/"
+routeMap.getStateIdByPath("/unknown"); // null
 
+// Or build from a machine directly:
+import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
 const routeMap = createRouteMap(machine);
 ```
 
+`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+
 ## Usage Patterns
 
 ### Dynamic Routes with Parameters
 
-TanStack Router and URLPattern (used internally) support dynamic route matching syntax:
+```ts
+const routeMap = new RouteMap([
+	{ stateId: "post", path: "/users/:userId/posts/:postId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+// Params are extracted and forwarded in the play.route event:
+// { type: "play.route", to: "#post", params: { userId: "123", postId: "456" }, query: {} }
+```
+
+### Protected Routes and Guards
+
+Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
 
-```typescript
-// Machine configuration
+```ts
 const machineConfig = {
 	states: {
-		profile: {
-			meta: {
-				route: "/profile/:userId",
-				view: { component: "Profile" },
+		dashboard: {
+			meta: { route: "/dashboard" },
+			always: {
+				guard: ({ context }) => !context.isAuthenticated,
+				target: "login",
 			},
 		},
 	},
 };
-
-// Route mapping will natively support URLPattern parameters
-routeMap.getStateIdByPath("/profile/123"); // → '#profile'
 ```
 
-### Protected Routes and Guards
+When a user navigates to `/dashboard` while unauthenticated:
 
-With XMachines, auth guards are handled entirely inside the state machine, preventing flashes of unauthorized content.
+1. TanStack Router updates location.
+2. Bridge intercepts and sends `play.route` to the actor.
+3. Actor evaluates the guard — denies transition, moves to `login` instead.
+4. Bridge observes new actor route (`/login`).
+5. Bridge calls `router.navigate({ to: "/login" })`.
 
-```typescript
-// Machine side
-dashboard: {
-  meta: { route: "/dashboard", view: { component: "Dashboard" } },
-  always: {
-    guard: ({ context }) => !context.isAuthenticated,
-    target: "login"
-  }
-}
-```
+### Full App Example
 
-When a user navigates to `/dashboard`:
+```tsx
+import { createRouter, RouterProvider, createRootRoute, createRoute } from "@tanstack/solid-router";
+import { onCleanup } from "solid-js";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const routeMap = createRouteMap(authMachine);
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+
+const rootRoute = createRootRoute({
+	component: () => {
+		onCleanup(() => actor.stop());
+		return (
+			<PlayRouterProvider
+				actor={actor}
+				router={router}
+				routeMap={routeMap}
+				renderer={(currentActor, currentRouter) => (
+					/* your shell/renderer here */
+					<div />
+				)}
+			/>
+		);
+	},
+});
 
-1. TanStack Router updates location
-2. Bridge intercepts and sends `play.route`
-3. Actor evaluates guard -> denies target, transitions to `login` instead
-4. Bridge observes new actor state (`/login`)
-5. Bridge tells TanStack Router to redirect to `/login`
+const tanstackRoutes = routes.map((route) =>
+	createRoute({
+		getParentRoute: () => rootRoute,
+		path: route.fullPath.replace(/:(\w+)/g, "$$$1"),
+		component: () => null,
+	}),
+);
 
-## Circular Update Prevention
+export const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
 
-The `RouterBridgeBase` architecture prevents infinite loops between router and actor using two mechanisms:
+export default function App() {
+	return <RouterProvider router={router} />;
+}
+```
 
-1. **`lastSyncedPath` tracking:** Stores the last synchronized path to prevent redundant navigations back to the identical location.
-2. **`isProcessingNavigation` flag:** Set during a router event, preventing the router from immediately reacting to the actor's synchronous state update.
+## Architecture
 
-## Comparison with @solidjs/router Adapter
+Bridge-first data flow:
 
-| Aspect            | @solidjs/router Adapter          | @tanstack/solid-router Adapter  |
-| ----------------- | -------------------------------- | ------------------------------- |
-| **Router API**    | `navigate(path)`                 | `router.navigate({ to })`       |
-| **Setup Context** | Must be _inside_ Router context  | Can wrap Router instance        |
-| **State Source**  | Uses Solid hooks (`useLocation`) | Subscribes to `router` directly |
-| **Reacting**      | `createEffect` on location       | `router.subscribe` callback     |
+1. `RouterBridgeBase.connect()` performs initial actor/router synchronization — both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
+2. Actor route updates (`actor.currentRoute` signal) call TanStack navigation (`router.navigate({ to })`).
+3. TanStack history updates are subscribed and translated to `play.route` events sent to the actor.
+4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
 
-## Architecture
+This keeps routing infrastructure passive while preserving business-logic control in the state machine.
 
-This package implements standard Play invariants:
+## Testing
 
-### INV-01: Actor Authority
+Run tests for this package in isolation:
 
-State machine has final authority over all transitions. TanStack Router navigation triggers actor events (`play.route`), but the actor's guards and transitions ultimately dictate if the view changes.
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router test
+```
 
-### INV-02: Passive Infrastructure
+Or from the package directory:
 
-Infrastructure reflects actor state. The router observes `actor.currentRoute` and updates the browser URL, never storing independent business state.
+```bash
+pnpm test
+```
 
-### Cleanup Contract
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce: BACK/FORWARD navigation via `router.history.subscribe`, echo suppression under real microtask timing, `navigate({ to })` call verification, and subscriber teardown on `disconnect()` and `dispose()`.
 
-The bridge implements an explicit `dispose()`/`disconnect()` method. `PlayTanStackRouterProvider` wires this automatically to Solid's `onCleanup` hook to prevent memory leaks and duplicate bridge subscriptions in hot-reloading scenarios.
+```bash
+# Run browser tests only
+pnpm exec vitest --config vitest.browser.config.ts --project play-tanstack-solid-router-browser
+```
 
-## URLPattern Support
+Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for robust route pattern matching via `@xmachines/play-router`.
+## Related Packages
 
-URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router` installation](../play-router/README.md) for details.
+- [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
+- [@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md) — TanStack Router (React) equivalent
+- [@xmachines/play-solid](../play-solid/README.md) — SolidJS renderer
+- [@xmachines/play-solid-router](../play-solid-router/README.md) — native `@solidjs/router` adapter
+- [@xmachines/play-xstate](../play-xstate/README.md) — XState v5 player factory
 
-## Related Packages
+## Learn More
 
-- **[@xmachines/play-solid](../play-solid/README.md)** - SolidJS renderer
-- **[@xmachines/play-router](../play-router/README.md)** - Core router primitives
-- **[@xmachines/play-solid-router](../play-solid-router/README.md)** - Native SolidJS Router equivalent
+- [Demo](../../../examples/@xmachines/play-tanstack-solid-router-demo/README.md)
+- [SolidJS renderer](../play-solid/README.md)
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE).
 
 ## Classes
 
 - [RouteMap](classes/RouteMap.md)
-- [SolidRouterBridge](classes/SolidRouterBridge.md)
+- [TanStackSolidRouterBridge](classes/TanStackSolidRouterBridge.md)
 
 ## Interfaces
 
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases
 
-- [RoutableActor](type-aliases/RoutableActor.md)
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
+- [~~RoutableActor~~](type-aliases/RoutableActor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 
+## Variables
+
+- [PlayRouterProvider](variables/PlayRouterProvider.md)
+
 ## Functions
 
+- [createPlayRouterProvider](functions/createPlayRouterProvider.md)
 - [createRouteMap](functions/createRouteMap.md)
-- [PlayRouterProvider](functions/PlayRouterProvider.md)

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

@@ -1,32 +1,40 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / RouteMap
+[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / RouteMap
 
 # Class: RouteMap
 
-Defined in: [play-tanstack-solid-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/route-map.ts#L26)
+Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L101)
 
 Shared bidirectional route map base class.
 
-All framework adapter `RouteMap` classes extend this — they add no logic of their
+All framework adapters use this class as their route map — they add no logic of their
 own and inherit the full public API from here.
 
 **Lookup strategy:**
 
 - Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
   of routes sharing the same first path segment
-- Results are cached after the first match
+- 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
 
 ```typescript
-import { BaseRouteMap } from "@xmachines/play-router";
+import { RouteMap } from "@xmachines/play-router";
 
-const map = new BaseRouteMap([
+const map = new RouteMap([
 	{ stateId: "home", path: "/" },
 	{ stateId: "profile", path: "/profile/:userId" },
 	{ stateId: "settings", path: "/settings/:section?" },
@@ -41,40 +49,34 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-## Extends
-
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
-
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:81
+Defined in: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L127)
 
 Build a route map from an array of state ID ↔ path mappings.
 
 Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `RegExp` and grouped into first-segment
+Parameterized paths are compiled to `URLPattern` and grouped into first-segment
 buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                                                     | Description                                                                                                       |
-| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
 `RouteMap`
 
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
-
 ## Methods
 
 ### getPathByStateId()
@@ -83,10 +85,14 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:111
+Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/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                                               |
@@ -103,13 +109,10 @@ 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
 ```
 
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
-
 ---
 
 ### getStateIdByPath()
@@ -118,7 +121,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:98
+Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L178)
 
 Resolve a URL path to its mapped state ID.
 
@@ -144,7 +147,3 @@ The mapped state ID, or `null` if no route matches
 map.getStateIdByPath("/profile/123"); // "profile"
 map.getStateIdByPath("/unknown"); // null
 ```
-
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)