@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,104 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L341)
+
+RouterBridge interface for runtime infrastructure adapters
+
+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.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+Framework router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class MyRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L357)
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L373)
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

package/api/@xmachines/play-sveltekit-router/type-aliases/RoutableActor.md

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RoutableActor
+
+# Type Alias: RoutableActor
+
+```ts
+type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
+```
+
+Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-sveltekit-router/src/types.ts#L10)

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

@@ -1,194 +1,220 @@
-[Documentation](../../README.md) / @xmachines/play-tanstack-react-router
+[API](../../README.md) / @xmachines/play-tanstack-react-router
 
-# @xmachines/play-tanstack-react-router
+<!-- generated-by: gsd-doc-writer -->
 
-**TanStack React Router adapter for XMachines Play using the RouterBridge pattern.**
+# @xmachines/play-tanstack-react-router
 
-## Overview
+TanStack Router (React) adapter for XMachines Play — synchronizes browser URL with actor state through passive infrastructure.
 
-`@xmachines/play-tanstack-react-router` connects a Play actor to TanStack Router through `TanStackReactRouterBridge`.
+Part of the [xmachines-js monorepo](../../README.md).
 
-The bridge extends `RouterBridgeBase` from `@xmachines/play-router`, so adapter behavior stays consistent across frameworks:
+## Installation
 
-- 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).
+```bash
+pnpm add @xmachines/play-tanstack-react-router
+```
 
-## Installation
+**Peer dependencies** (install separately):
 
 ```bash
-npm install @tanstack/react-router react
-npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachines/play-react
+pnpm add @tanstack/react-router react react-dom xstate
 ```
 
-## Current Exports
+Requires:
 
-- `TanStackReactRouterBridge`
-- `RouteMap`, `createRouteMapFromTree`, `RouteMapping` (type)
-- `extractParams`, `extractQueryParams`
-- `PlayRouterProvider` + `PlayRouterProviderProps`
-- re-exports: `extractMachineRoutes`, `createRouteMap`, `RouterBridge`, `PlayRouteEvent`
+- `@tanstack/react-router` `^1.168.8`
+- `react` `^18.0.0` or `^19.0.0`
+- `react-dom` `^18.0.0` or `^19.0.0`
+- `xstate` `^5.31.0`
 
-Peer dependencies:
+## Usage
 
-- `@tanstack/react-router` `^1.166.7`
-- `react` `^18 || ^19`
-- `xstate` `^5.0.0`
+### `PlayRouterProvider` — React component (recommended)
 
-## URLPattern Support
+`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount, keeps it connected for the component lifetime, and tears it down on unmount.
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via `@xmachines/play-router`.
+```tsx
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import {
+	PlayRouterProvider,
+	createRouteMapFromTree,
+	extractMachineRoutes,
+} from "@xmachines/play-tanstack-react-router";
+import { definePlayer } from "@xmachines/play-xstate";
 
-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.
+function createAppRuntime() {
+	const actor = definePlayer({ machine, catalog })();
+	actor.start();
 
-## Quick Start
+	const routeTree = extractMachineRoutes(machine);
+	const routeMap = createRouteMapFromTree(routeTree);
+	const rootRoute = createRootRoute();
+	const router = createRouter({ routeTree: rootRoute });
 
-```tsx
+	return { actor, routeMap, router };
+}
+
+export function App() {
+	// All three props must be stable references — memoize to avoid reconnecting on every render
+	const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+
+	useEffect(() => () => actor.stop(), [actor]);
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				<Shell actor={currentActor} router={currentRouter} />
+			)}
+		/>
+	);
+}
+```
+
+> **Stable references:** `actor`, `router`, and `routeMap` must be stable across renders. If any prop changes identity, the bridge disconnects and reconnects. Use `useMemo` to create them once.
+
+### `TanStackReactRouterBridge` — headless class
+
+Use the bridge directly when you don't need the React wrapper, or when integrating with a custom lifecycle:
+
+```typescript
 import { createRouter } from "@tanstack/react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
 import {
 	TanStackReactRouterBridge,
 	createRouteMapFromTree,
+	extractMachineRoutes,
 } from "@xmachines/play-tanstack-react-router";
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-
-const router = createRouter({ routeTree: tanstackRouteTree });
-
+const router = createRouter({ routeTree });
 const actor = definePlayer({ machine, catalog })();
-actor.start();
+const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
 
 const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
-// later
+// Cleanup when done
 bridge.disconnect();
 ```
 
-### React convenience wrapper
+## API Summary
 
-Use `PlayRouterProvider` when you want bridge lifecycle wiring in a component:
+### `TanStackReactRouterBridge`
 
-```tsx
-import { PlayRenderer } from "@xmachines/play-react";
-
-<PlayRouterProvider
-	actor={actor}
-	router={router}
-	routeMap={routeMap}
-	renderer={(currentActor, currentRouter) => (
-		<PlayRenderer actor={currentActor} components={components} />
-	)}
-/>;
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements bidirectional sync between actor state signals and TanStack Router history.
+
+```typescript
+class TanStackReactRouterBridge extends RouterBridgeBase {
+	constructor(router: TanStackRouterLike, actor: RoutableActor, routeMap: RouteMap);
+
+	connect(): void; // Start sync; subscribe to router.history and actor signals
+	disconnect(): void; // Stop sync; unsubscribe all listeners
+}
 ```
 
-## API
+Subscribes to `router.history` (not `router.subscribe("onBeforeLoad")`) so that back/forward browser navigation (popstate events) are captured even without a `<RouterProvider>` mounted.
 
-### `TanStackReactRouterBridge`
+### `PlayRouterProvider`
 
-Primary adapter class.
+React component that wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
 
-```ts
-class TanStackReactRouterBridge implements RouterBridge {
-	constructor(
-		router: TanStackRouterLike,
-		actor: AbstractActor<AnyActorLogic> & Routable,
-		routeMap: RouteMap,
-	);
-	connect(): void;
-	disconnect(): void;
+```typescript
+interface PlayRouterProviderProps<TActor> {
+	actor: TActor; // Must be stable
+	router: TanStackRouterInstance; // Must be stable
+	routeMap: RouteMap; // Must be stable
+	renderer: (actor: TActor, router: TanStackRouterInstance) => ReactNode;
 }
 ```
 
-### `RouteMap` and `createRouteMapFromTree`
-
-Map state IDs to URL paths and resolve URLs back to state IDs.
-
-`RouteMap` extends `BaseRouteMap` from `@xmachines/play-router`, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
+### `TanStackRouterLike`
+
+Structural type for the router instance — accepts any object with the required `navigate` and `history` shape, making it testable without creating a full TanStack Router:
+
+```typescript
+type TanStackRouterLike = {
+	navigate(args: { to: string }): void;
+	load?(): void | Promise<void>;
+	history: {
+		location: { pathname: string; search?: string };
+		subscribe(
+			handler: (event: { location: { pathname: string; search?: string } }) => void,
+		): () => void;
+	};
+};
+```
 
-```ts
-// RouteMap is a thin subclass of BaseRouteMap — no extra methods
-class RouteMap extends BaseRouteMap {}
+### `RouteNavigateEvent`
 
-// Inherited API:
-routeMap.getStateIdByPath(path: string): string | null
-routeMap.getPathByStateId(stateId: string): string | null
+Event sent to the actor when the browser navigates:
 
-// Factory from a machine route tree:
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap
+```typescript
+interface RouteNavigateEvent {
+	readonly type: "route.navigate";
+	readonly path: string; // e.g. "/dashboard" or "/posts/123"
+}
 ```
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+### Re-exported from `@xmachines/play-router`
 
-```ts
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
+```typescript
+// Route map construction
+RouteMap
+createRouteMap(mappings: RouteMapping[]): RouteMap
+createRouteMapFromTree(routeTree): RouteMap
+extractMachineRoutes(machine): RouteTree
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-routeMap.getStateIdByPath("/unknown"); // null
+// Types
+type RouteMapOptions
+type RouteMapping
+type RouterBridge
+type PlayRouteEvent
 ```
 
-### `PlayRouterProvider`
+## How It Works
 
-React wrapper around `TanStackReactRouterBridge`.
-
-```ts
-interface PlayRouterProviderProps {
-	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
-	router: TanStackRouterLike;
-	routeMap: RouteMap;
-	renderer: (
-		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
-		router: TanStackRouterLike,
-	) => ReactNode;
-}
-```
+The bridge implements the **Passive Infrastructure** invariant from the XMachines RFC:
 
-### Utilities and re-exports
+1. **Actor → Router:** When `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL updates to reflect the new actor state.
+2. **Router → Actor:** When `router.history.subscribe` fires (link clicks, `back`/`forward` buttons, `history.pushState`), the bridge sends a `play.route` event to the actor. The actor's guards decide whether navigation is valid — the router never enforces business logic.
+3. **Circular update prevention:** A `lastSyncedPath` guard suppresses round-trip updates so an actor → router navigation does not trigger a redundant router → actor send.
+4. **Deep-link and restore:** On `connect()`, the bridge reads `router.history.location.pathname` (which reflects `window.location` immediately, before `router.load()` runs) and determines whether to sync the actor from the URL (deep-link) or push the actor's restored route to the URL (snapshot restore).
 
-- `extractParams`, `extractQueryParams`
-- `extractMachineRoutes`, `createRouteMap` (re-exported from `@xmachines/play-router`)
-- `RouterBridge`, `PlayRouteEvent` types
+## Testing
 
-## Examples
+Run tests for this package in isolation:
 
-- Multi-router integration guide: `docs/examples/multi-router-integration.md`
-- Routing patterns guide: `docs/examples/routing-patterns.md`
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router test
+```
 
-## Architecture
+From the monorepo root:
 
-Bridge-first flow:
+```bash
+pnpm test
+```
 
-1. `RouterBridgeBase.connect()` performs initial actor/router synchronization.
-2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
-3. TanStack history updates are subscribed and translated to `play.route` events.
-4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional sync, circular update prevention, deep-link and snapshot-restore scenarios, and `PlayRouterProvider` lifecycle (mount/unmount/reconnect).
 
-This keeps routing infrastructure passive while preserving business-logic control.
+## Demo
 
-## Historical Note
+A runnable React + TanStack Router integration demo is available under `examples/demo/`. To run it from the repository root:
 
-`SignalSyncedHistory` and `createPlayRouter` are legacy migration-era APIs and are not part of the current quick-start path. Use `TanStackReactRouterBridge` + `RouteMap` for new integrations.
+```bash
+pnpm install
+pnpm --filter @xmachines/play-tanstack-react-router-demo run dev
+```
 
-## Related Packages
+Then open `http://localhost:3000`.
 
-- [@xmachines/play-router](../play-router/README.md)
-- [@xmachines/play-xstate](../play-xstate/README.md)
-- [@xmachines/play-react](../play-react/README.md)
+The demo shows actor-authoritative routing with a shared auth machine: TanStack Router updates the URL, `PlayRouterProvider` translates it to a `play.route` event, and the actor's guards decide whether access is permitted.
 
 ## 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).
 
 @xmachines/play-tanstack-react-router
 
@@ -202,25 +228,28 @@ Synchronizes browser URL with actor state through passive infrastructure.
 
 ## 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)
 - [RouteNavigateEvent](interfaces/RouteNavigateEvent.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases
 
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 
 ## Variables
 
-- [extractMachineRoutes](variables/extractMachineRoutes.md)
+- [PlayRouterProvider](variables/PlayRouterProvider.md)
 
 ## Functions
 
+- [createPlayRouterProvider](functions/createPlayRouterProvider.md)
 - [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [extractParams](functions/extractParams.md)
-- [extractQueryParams](functions/extractQueryParams.md)
-- [PlayRouterProvider](functions/PlayRouterProvider.md)
+- [extractMachineRoutes](functions/extractMachineRoutes.md)

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

@@ -1,67 +1,82 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMap
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMap
 
 # Class: RouteMap
 
-Defined in: [play-tanstack-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L54)
+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)
 
-Bidirectional route mapper for TanStack React Router.
+Shared bidirectional route map base class.
 
-Extends [BaseRouteMap](../../play-router/classes/BaseRouteMap.md) — all matching logic lives there.
-This class exists to provide a TanStack React Router-specific type name and to
-allow future adapter-specific extensions without breaking the shared base.
+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.
 
-**Inherited API:**
+**Lookup strategy:**
 
-- `getStateIdByPath(path): string | null` — path → state ID
-- `getPathByStateId(stateId): string | null` — state ID → path pattern
+- Static paths (no `:param`) → O(1) `Map` lookup
+- 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 in an LRU cache (default 500 entries,
+  configurable via the `cacheSize` constructor option)
+
+**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
-const routeMap = new RouteMap([
+import { RouteMap } from "@xmachines/play-router";
+
+const map = new RouteMap([
 	{ stateId: "home", path: "/" },
 	{ stateId: "profile", path: "/profile/:userId" },
 	{ stateId: "settings", path: "/settings/:section?" },
 ]);
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-```
-
-## Extends
+map.getStateIdByPath("/"); // "home"
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/settings"); // "settings"
+map.getStateIdByPath("/unknown"); // null
 
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
 
 ## 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()
@@ -70,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                                               |
@@ -90,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()
@@ -105,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.
 
@@ -131,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)