@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.26

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

@@ -106,8 +106,8 @@ export const machine = setup({
 		context: {} as {
 			isAuthenticated: boolean;
 			username: string | null;
-			routeParams: Record<string, string>;
-			queryParams: Record<string, string>;
+			params: Record<string, string>;
+			query: Record<string, string>;
 		},
 		events: {} as
 			| { type: "auth.login"; username: string }
@@ -118,7 +118,7 @@ export const machine = setup({
 	formatPlayRouteTransitions({
 		id: "app",
 		initial: "login",
-		context: { isAuthenticated: false, username: null, routeParams: {}, queryParams: {} },
+		context: { isAuthenticated: false, username: null, params: {}, query: {} },
 		states: {
 			login: {
 				id: "login",
@@ -272,7 +272,7 @@ When using `formatPlayRouteTransitions`, URL path parameters flow automatically
 
 ```ts
 // spec: { section: undefined, user: "alice" }
-// After play.route to /settings/profile → context.routeParams = { section: "profile" }
+// After play.route to /settings/profile → context.params = { section: "profile" }
 // Component receives: { section: "profile", user: "alice" }
 ```
 

package/api/@xmachines/play-vue/functions/defineRegistry.md

@@ -6,7 +6,7 @@
 function defineRegistry<C>(catalog, options): DefineRegistryResult;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:114](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/define-registry.ts#L114)
+Defined in: [packages/play-vue/src/define-registry.ts:114](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/define-registry.ts#L114)
 
 Create a component registry, automatically wrapping `.vue` SFCs so they work
 correctly with `@json-render/vue`'s rendering pipeline.

package/api/@xmachines/play-vue/functions/useActor.md

@@ -6,7 +6,7 @@
 function useActor(): PlayActor;
 ```
 
-Defined in: [packages/play-vue/src/useActor.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/useActor.ts#L42)
+Defined in: [packages/play-vue/src/useActor.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/useActor.ts#L42)
 
 ## Returns
 

package/api/@xmachines/play-vue/functions/useStateBinding.md

@@ -6,6 +6,8 @@
 function useStateBinding<T>(path): [ComputedRef<T | undefined>, (value) => void];
 ```
 
+Defined in: `@json-render/vue`
+
 Composable to get and set a value from the state model by path.
 
 This is the path-based variant for use in arbitrary composables. For

package/api/@xmachines/play-vue/interfaces/ComponentContext.md

@@ -2,6 +2,8 @@
 
 # Interface: ComponentContext\<C, K\>
 
+Defined in: `@json-render/vue`
+
 Context passed to component render functions
 
 ## Example

package/api/@xmachines/play-vue/interfaces/PlayRendererProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRendererProps\<TLogic\>
 
-Defined in: [packages/play-vue/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/types.ts#L25)
+Defined in: [packages/play-vue/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/types.ts#L25)
 
 Props for PlayRenderer component
 
@@ -16,7 +16,7 @@ Props for PlayRenderer component
 
 | Property                                  | Type                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                               |
 | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actions"></a> `actions?`  | `object`                                                                                                                                                                                            | Optional map of json-render action names to XState event type strings. Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent event type string is a compile error when TLogic is specified.                                                                                                                                           | [packages/play-vue/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/types.ts#L46) |
-| <a id="property-actor"></a> `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                                                                               | [packages/play-vue/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/types.ts#L27) |
-| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                                                                                                                                                                 | Component registry from @json-render/vue defineRegistry                                                                                                                                                                                                                                                                                                             | [packages/play-vue/src/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/types.ts#L30) |
-| <a id="property-store"></a> `store?`      | `StateStore`                                                                                                                                                                                        | Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored and this store is the single source of truth for UI state (form values, etc.). When omitted, a fresh @xstate/store atom is created internally per view transition, seeded from spec.state. | [packages/play-vue/src/types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/types.ts#L39) |
+| <a id="property-actions"></a> `actions?`  | `object`                                                                                                                                                                                            | Optional map of json-render action names to XState event type strings. Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent event type string is a compile error when TLogic is specified.                                                                                                                                           | [packages/play-vue/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/types.ts#L46) |
+| <a id="property-actor"></a> `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                                                                               | [packages/play-vue/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/types.ts#L27) |
+| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                                                                                                                                                                 | Component registry from @json-render/vue defineRegistry                                                                                                                                                                                                                                                                                                             | [packages/play-vue/src/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/types.ts#L30) |
+| <a id="property-store"></a> `store?`      | `StateStore`                                                                                                                                                                                        | Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored and this store is the single source of truth for UI state (form values, etc.). When omitted, a fresh @xstate/store atom is created internally per view transition, seeded from spec.state. | [packages/play-vue/src/types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/types.ts#L39) |

package/api/@xmachines/play-vue/type-aliases/ComponentEntry.md

@@ -6,7 +6,7 @@
 type ComponentEntry<C, K> = ComponentFn<C, K> | Component;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/define-registry.ts#L89)
+Defined in: [packages/play-vue/src/define-registry.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/define-registry.ts#L89)
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/type-aliases/ComponentFn.md

@@ -6,6 +6,8 @@
 type ComponentFn<C, K> = (ctx) => VNode | VNode[] | null | string;
 ```
 
+Defined in: `@json-render/vue`
+
 Component render function type for Vue
 
 ## Type Parameters

package/api/@xmachines/play-vue/type-aliases/ComponentsMap.md

@@ -6,7 +6,7 @@
 type ComponentsMap<C> = { [K in keyof InferCatalogComponents<C>]?: ComponentEntry<C, K> };
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/define-registry.ts#L93)
+Defined in: [packages/play-vue/src/define-registry.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/define-registry.ts#L93)
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/type-aliases/DefineRegistryOptions.md

@@ -6,13 +6,13 @@
 type DefineRegistryOptions<C> = Parameters<typeof defineRegistryBase>[1] & object;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/define-registry.ts#L97)
+Defined in: [packages/play-vue/src/define-registry.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/define-registry.ts#L97)
 
 ## Type Declaration
 
 | Name          | Type                                       | Defined in                                                                                                                                                     |
 | ------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `components?` | [`ComponentsMap`](ComponentsMap.md)\<`C`\> | [packages/play-vue/src/define-registry.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/define-registry.ts#L100) |
+| `components?` | [`ComponentsMap`](ComponentsMap.md)\<`C`\> | [packages/play-vue/src/define-registry.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/define-registry.ts#L100) |
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/type-aliases/PlayActor.md

@@ -6,4 +6,4 @@
 type PlayActor = AbstractActor<AnyActorLogic>;
 ```
 
-Defined in: [packages/play-vue/src/useActor.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/useActor.ts#L25)
+Defined in: [packages/play-vue/src/useActor.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/useActor.ts#L25)

package/api/@xmachines/play-vue/variables/PlayRenderer.md

@@ -6,4 +6,4 @@
 const PlayRenderer: DefineComponent<{}, {}, unknown>;
 ```
 
-Defined in: [packages/play-vue/src/vue-shim.d.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue/src/vue-shim.d.ts#L3)
+Defined in: [packages/play-vue/src/vue-shim.d.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue/src/vue-shim.d.ts#L3)

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

@@ -125,7 +125,7 @@ class VueRouterBridge {
 
 **Methods:**
 
-- `connect()` - Start bidirectional synchronization.
+- `connect()` - Start bidirectional synchronization. Both pathname and query string from `router.currentRoute.value.fullPath` are forwarded to the actor on first connect, so users landing on `/profile?tab=posts` have `query: { tab: "posts" }` in the initial `play.route` event.
 - `disconnect()` - Stop synchronization and unhook listeners.
 - `dispose()` - Alias of `disconnect()` for ergonomic teardown.
 
@@ -133,7 +133,7 @@ class VueRouterBridge {
 
 - Watches `actor.currentRoute` signal via `Signal.subtle.Watcher`
 - Updates Vue Router via `router.push({ name, params })` when actor state changes
-- Listens to router navigation via `router.afterEach()` hook
+- Listens to router navigation via `router.afterEach()` hook using Vue's native `to.params` / `to.query` for accurate extraction (no URLPattern re-parsing)
 - Applies `sanitizePathname()` to all incoming router paths before route-map lookup (defense-in-depth: rejects malformed/oversized paths)
 - Sends `play.route` events to actor when user navigates
 - Prevents circular updates with multi-layer guards

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

@@ -2,31 +2,11 @@
 
 # Class: RouteMap
 
-Defined in: [play-vue-router/src/route-map.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/route-map.ts#L14)
+Defined in: [play-vue-router/src/route-map.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-vue-router/src/route-map.ts#L10)
 
-VueBaseRouteMap — intermediate base class for Vue Router adapters.
+Bidirectional route mapper for Vue Router.
 
-Extends `BaseRouteMap` (bucket-indexed O(k) pattern matching + QuickLRU 500-entry
-cache) and adds the Vue-specific adapter layer: `routeName` ↔ `stateId` bidirectional
-lookup and optional URL pattern access.
-
-**Why a separate base class?** Vue Router uses named routes (`routeName`) rather than
-URL paths for navigation. `BaseRouteMap` operates on path strings; `VueBaseRouteMap`
-bridges the two by translating `RouteMapping` entries at construction time — only
-mappings with a `pattern` field participate in URL path resolution via `BaseRouteMap`.
-
-Exported from `@xmachines/play-vue-router` for consumers who need to extend or test
-the Vue routing layer directly. Most consumers use `RouteMap` instead.
-
-## Example
-
-```typescript
-import { VueBaseRouteMap } from "@xmachines/play-vue-router";
-
-class MyVueRouteMap extends VueBaseRouteMap {
-	// add custom resolution logic
-}
-```
+Alias for [BaseRouteMap](VueBaseRouteMap.md) from `@xmachines/play-router`.
 
 ## Extends
 
@@ -37,16 +17,24 @@ class MyVueRouteMap extends VueBaseRouteMap {
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-vue-router/src/vue-base-route-map.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L32)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L125)
+
+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 `URLPattern` and grouped into first-segment
+buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                              |
-| ---------- | ------------------------------------------------- |
-| `mappings` | [`RouteMapping`](../interfaces/RouteMapping.md)[] |
+| 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
 
@@ -64,7 +52,7 @@ Defined in: [play-vue-router/src/vue-base-route-map.ts:32](https://gitlab.com/xm
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -93,91 +81,13 @@ map.getPathByStateId("missing"); // null
 
 ---
 
-### getPattern()
-
-```ts
-getPattern(stateId): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L58)
-
-Get the URL path pattern for a given state ID (e.g. `"/profile/:userId"`).
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `stateId` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
-#### Inherited from
-
-[`VueBaseRouteMap`](VueBaseRouteMap.md).[`getPattern`](VueBaseRouteMap.md#getpattern)
-
----
-
-### getRouteName()
-
-```ts
-getRouteName(stateId): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L48)
-
-Get the Vue Router route name for a given state ID.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `stateId` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
-#### Inherited from
-
-[`VueBaseRouteMap`](VueBaseRouteMap.md).[`getRouteName`](VueBaseRouteMap.md#getroutename)
-
----
-
-### getStateId()
-
-```ts
-getStateId(routeName): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L53)
-
-Get the state ID for a given Vue Router route name.
-
-#### Parameters
-
-| Parameter   | Type     |
-| ----------- | -------- |
-| `routeName` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
-#### Inherited from
-
-[`VueBaseRouteMap`](VueBaseRouteMap.md).[`getStateId`](VueBaseRouteMap.md#getstateid)
-
----
-
 ### getStateIdByPath()
 
 ```ts
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

package/api/@xmachines/play-vue-router/classes/VueBaseRouteMap.md

@@ -2,35 +2,45 @@
 
 # Class: VueBaseRouteMap
 
-Defined in: [play-vue-router/src/vue-base-route-map.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L28)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L100)
 
-VueBaseRouteMap — intermediate base class for Vue Router adapters.
+Shared bidirectional route map base class.
 
-Extends `BaseRouteMap` (bucket-indexed O(k) pattern matching + QuickLRU 500-entry
-cache) and adds the Vue-specific adapter layer: `routeName` ↔ `stateId` bidirectional
-lookup and optional URL pattern access.
+All framework adapter `RouteMap` classes extend this — they add no logic of their
+own and inherit the full public API from here.
 
-**Why a separate base class?** Vue Router uses named routes (`routeName`) rather than
-URL paths for navigation. `BaseRouteMap` operates on path strings; `VueBaseRouteMap`
-bridges the two by translating `RouteMapping` entries at construction time — only
-mappings with a `pattern` field participate in URL path resolution via `BaseRouteMap`.
+**Lookup strategy:**
 
-Exported from `@xmachines/play-vue-router` for consumers who need to extend or test
-the Vue routing layer directly. Most consumers use `RouteMap` instead.
+- 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
 
 ## Example
 
 ```typescript
-import { VueBaseRouteMap } from "@xmachines/play-vue-router";
+import { BaseRouteMap } from "@xmachines/play-router";
 
-class MyVueRouteMap extends VueBaseRouteMap {
-	// add custom resolution logic
-}
-```
+const map = new BaseRouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
 
-## 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
+```
 
 ## Extended by
 
@@ -41,24 +51,28 @@ class MyVueRouteMap extends VueBaseRouteMap {
 ### Constructor
 
 ```ts
-new VueBaseRouteMap(mappings): VueBaseRouteMap;
+new VueBaseRouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: [play-vue-router/src/vue-base-route-map.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L32)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L125)
 
-#### Parameters
+Build a route map from an array of state ID ↔ path mappings.
 
-| Parameter  | Type                                              |
-| ---------- | ------------------------------------------------- |
-| `mappings` | [`RouteMapping`](../interfaces/RouteMapping.md)[] |
+Static paths (no `:param`) are indexed in an O(1) `Map`.
+Parameterized paths are compiled to `URLPattern` and grouped into first-segment
+buckets for efficient candidate selection.
 
-#### Returns
+#### Parameters
 
-`VueBaseRouteMap`
+| 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`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
-#### Overrides
+#### Returns
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+`BaseRouteMap`
 
 ## Methods
 
@@ -68,7 +82,7 @@ Defined in: [play-vue-router/src/vue-base-route-map.ts:32](https://gitlab.com/xm
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -91,76 +105,6 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
-
----
-
-### getPattern()
-
-```ts
-getPattern(stateId): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L58)
-
-Get the URL path pattern for a given state ID (e.g. `"/profile/:userId"`).
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `stateId` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
----
-
-### getRouteName()
-
-```ts
-getRouteName(stateId): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L48)
-
-Get the Vue Router route name for a given state ID.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `stateId` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
----
-
-### getStateId()
-
-```ts
-getStateId(routeName): string | undefined;
-```
-
-Defined in: [play-vue-router/src/vue-base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-vue-router/src/vue-base-route-map.ts#L53)
-
-Get the state ID for a given Vue Router route name.
-
-#### Parameters
-
-| Parameter   | Type     |
-| ----------- | -------- |
-| `routeName` | `string` |
-
-#### Returns
-
-`string` \| `undefined`
-
 ---
 
 ### getStateIdByPath()
@@ -169,7 +113,7 @@ Get the state ID for a given Vue Router route name.
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -195,7 +139,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)