@xmachines/play-router 2.2.0 → 4.0.0

package/README.md

@@ -2,41 +2,29 @@
 
 Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
 
 This package extracts the routes from a machine graph and looks them up in both directions. The Actor therefore keeps the authority over the navigation.
 
+> **Browser floor: Chrome 110, Firefox 115, Safari 16.4.** This package calls the ES2023
+> change-by-copy array methods, so a browser below that floor throws
+> `TypeError: ... is not a function` at the extraction of the routes. The root README
+> carries the table.
+
 ## Installation
 
 ```bash
-pnpm add xstate@^5.31.0
+pnpm add xstate@^5.33.0
 pnpm add @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^5.31.0 — XState v5 state machine runtime
-
-**URLPattern polyfill (Node.js < 24 / older browsers):**
-
-`@xmachines/play-router` matches each dynamic route with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+).
-
-In an environment without the native API, load a polyfill **before** you import this package:
-
-```typescript
-// Entry point — must run before any @xmachines/play-router import
-import "urlpattern-polyfill";
-```
-
-Install the polyfill:
-
-```bash
-pnpm add urlpattern-polyfill
-```
+- `xstate` ^5.33.0 — XState v5 state machine runtime (an OPTIONAL peer: the `@xmachines/play-router/xstate` subpath alone reads it)
 
-`urlpattern-polyfill` is an optional peer dependency. A package manager does not install it for you. Install it and load it yourself when your runtime has no native URLPattern.
+**URLPattern:** this package matches each route with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). It uses the native API when the runtime has one, and it falls back to `urlpattern-polyfill`, which it carries as an ordinary dependency. **You install nothing and you load nothing.**
 
-**When you need it:** `RouteMap` compiles each parameterized route in its CONSTRUCTOR, and it throws a `URLPatternUnavailableError` there when no URLPattern is available. One route that holds a `:param` or a `*` therefore makes the polyfill a startup requirement on such a runtime. A route map whose paths are all static needs URLPattern never.
+The [routing guide](../docs/guides/routing.md) states the pattern language: the forms, the modifiers, the prefix rule, and the one divergence from the standard.
 
 ## Usage
 
@@ -44,7 +32,7 @@ pnpm add urlpattern-polyfill
 
 ```typescript
 import { createMachine } from "xstate";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
 
 const machine = createMachine({
 	id: "app",
@@ -292,7 +280,7 @@ To register the routes of the machine in a host router that declares real route
 objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
-import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
 
 const tree = extractMachineRoutes(machine);
 
@@ -315,25 +303,25 @@ event always carries the prefixed form.
 > matched a route of the HOST by construction, because the machine owns the suffix of
 > the path only. Those params therefore describe the route of the machine never, even
 > when a name collides — a collision carries the value of the HOST. Both adapters
-> resolve each param from the stripped path with `URLPattern` instead, and they
-> therefore need a polyfill on an older runtime when they are mounted.
+> resolve each param from the stripped path with `URLPattern` instead.
 >
-> Without a prefix both adapters keep the parse of their framework, with its decoding
-> and with no polyfill, but restricted to the names that the pattern of the machine
-> declares. A splat of a catch-all, and a param of a wrapper route, reach the actor
-> never.
+> Without a prefix both adapters keep the parse of their framework, with its decoding,
+> but restricted to the names that the pattern of the machine declares. A splat of a
+> catch-all, and a param of a wrapper route, reach the actor never. A name that the
+> pattern makes OPTIONAL is covered whether the framework reports it or not: a part that
+> did not match has no value, and that is a complete answer.
 >
-> A location that fills NO optional segment reaches URLPattern never. `/settings` is the
-> bare form of `/settings/:section?`, so the params are `{}`, and the adapters read that
-> from the path alone rather than from their framework. The route map that HOLDS that
-> pattern still needed URLPattern when it was built.
+> A location that fills NO optional part runs no match at all. `/settings` is the bare
+> form of `/settings/:section?`, so the params are `{}`, and the adapters read that from
+> the path alone rather than from their framework.
 
 ### How to write a `RouterBridgeBase` adapter
 
 Extend `RouterBridgeBase`, then implement the three abstract methods for your framework:
 
 ```typescript
-import { RouterBridgeBase, createRouteMap } from "@xmachines/play-router";
+import { RouterBridgeBase } from "@xmachines/play-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 import type { RoutableActor } from "@xmachines/play-router";
 
 // Shape of your framework's router — adjust to its real API
@@ -391,13 +379,14 @@ bridge.disconnect();
 
 ### Route Extraction
 
-| Export                                   | Description                                                                       |
-| ---------------------------------------- | --------------------------------------------------------------------------------- |
-| `extractMachineRoutes(machine)`          | Converts an XState machine into a `RouteTree` with the state ID ↔ path maps       |
-| `createRouteMap(machine, options?)`      | Builds a `RouteMap` directly from a machine. An adapter uses this form            |
-| `createRouteMapFromTree(tree, options?)` | Builds a `RouteMap` from a `RouteTree` that you extracted before                  |
-| `buildRouteTree(routes)`                 | Builds a `RouteTree` from an array of `RouteInfo` objects                         |
-| `machineToGraph(machine)`                | Converts a machine into a typed `@statelyai/graph` `Graph`, for a graph algorithm |
+| Export                                   | Description                                                             |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `buildRouteTree(routes)`                 | Builds a `RouteTree` from an array of `RouteInfo` objects               |
+| `createRouteMapFromTree(tree, options?)` | Builds a `RouteMap` from a `RouteTree` that you extracted before        |
+| `ROOT_NODE_ID`                           | The ID of the synthetic root node. A walk of a tree must skip that node |
+
+The MAIN entry point reads no state machine. The machine half is
+`@xmachines/play-router/xstate`, below.
 
 ### Route Matching
 
@@ -407,16 +396,32 @@ bridge.disconnect();
 | `findRouteById(tree, id)`     | Finds a `RouteNode` by its state ID                                                                           |
 | `findRouteByPath(tree, path)` | Finds a `RouteNode` by its URL path. It also matches a dynamic pattern                                        |
 
-### Query Utilities
+### The machine half — subpath `@xmachines/play-router/xstate`
+
+A route of XMachines is a fact about a STATE. This entry point reads that fact out of an
+XState v5 machine. The main entry point reads it never, so `xstate` is an OPTIONAL peer
+dependency of this package, and a bundler drops `@statelyai/graph` for a consumer that
+imports this entry point nowhere.
+
+```typescript
+import { createRouteMap, extractMachineRoutes } from "@xmachines/play-router/xstate";
+```
 
 | Export                                            | Description                                                                                     |
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `extractMachineRoutes(machine)`                   | Converts an XState machine into a `RouteTree` with the state ID ↔ path maps                     |
+| `createRouteMap(machine, options?)`               | Builds a `RouteMap` directly from a machine. An adapter uses this form                          |
+| `machineToGraph(machine)`                         | Converts a machine into a typed `@statelyai/graph` `Graph`, for a graph algorithm               |
 | `getRoutableRoutes(tree)`                         | Returns every routable `RouteNode` in one flat array                                            |
 | `getNavigableRoutes(tree, stateId)`               | Returns the child routes that a state can reach, through the hierarchy and through a transition |
 | `routeExists(tree, path)`                         | Tells you if the tree holds a path                                                              |
 | `getRouteMappings(tree, options?)`                | The `{ stateId, path }` entries for a route table of a host, with an optional prefix            |
 | `getTransitionReachableRoutes(graph, stateId)`    | Returns the route paths that a state can reach through an XState transition                     |
 | `isRouteReachable(graph, fromStateId, toStateId)` | Tells you if a transition path is present between two states                                    |
+| `MachineGraph`                                    | The typed `@statelyai/graph` Graph, with `MachineNodeData` and `MachineEdgeData`                |
+
+No framework router adapter re-exports `createRouteMap`. Each one names no state machine,
+so a consumer of an adapter imports the function from `@xmachines/play-router/xstate`.
 
 ### Router Bridge
 
@@ -472,7 +477,7 @@ own effects and nothing else.
 | `mountKey(basePath, params?)`                         | A key that changes when the mount changes, compared BY VALUE                                |
 | `isMountableBridge(bridge)`                           | The run-time probe for a bridge that can move its mount                                     |
 | `createRouterConnection(bridge)`                      | Wraps a live bridge in the callable `RouterConnection` that `connectRouter` returns         |
-| `RouterConnection`                                    | The callable handle: `disconnect()`, and the mount to read and to move                      |
+| `RouterConnection`                                    | The callable handle: `disconnect()`, the mount to read and to move, and a `Disposable`      |
 
 Nothing here imports a framework, so this package keeps no framework dependency —
 `tests/provider-factory-parity.test.ts` holds that. `TNode` is the only thing in the
@@ -488,43 +493,40 @@ props that a framework decides, which is why it is a type parameter.
 
 ### Key Types
 
-| Export                             | Description                                                                                                                        |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `RouterBridge`                     | The interface of the `connect()` and `disconnect()` lifecycle                                                                      |
-| `MountableRouterBridge`            | A `RouterBridge` whose mount can move — it adds `basePath` and `setBasePath()`                                                     |
-| `RouteTree`                        | The hierarchical tree, with `root`, `byStateId`, `byPath`, and an optional `graph`                                                 |
-| `RouteNode`                        | One node of the tree, with `id`, `path`, `fullPath`, `stateId`, `children`, and `parent`                                           |
-| `RouteInfo`                        | The flat route descriptor that comes from a state node                                                                             |
-| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                                        |
-| `RoutableActor`                    | The minimal actor interface that `RouterBridgeBase` requires: `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`           |
-| `PlayActor`                        | The complete actor interface that `PlayRouterProvider` uses. It extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
-| `RouteMapping`                     | The `{ stateId, path }` pair that builds a `RouteMap`                                                                              |
-| `RouteMapping as BaseRouteMapping` | The alias of `RouteMapping`, for compatibility with an earlier version                                                             |
-| `MachineGraph`                     | The typed `@statelyai/graph` Graph, with `MachineNodeData` and `MachineEdgeData`                                                   |
-| `WindowLike`                       | The minimal `window` interface that you can inject for SSR and for a test                                                          |
-| `LocationLike`                     | The minimal `location` interface that you can inject for SSR and for a test                                                        |
+| Export                  | Description                                                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `RouterBridge`          | The interface of the `connect()` and `disconnect()` lifecycle                                                                            |
+| `MountableRouterBridge` | A `RouterBridge` whose mount can move — it adds `basePath` and `setBasePath()`                                                           |
+| `RouteTree`             | The hierarchical tree, with `root`, `byStateId`, `byPath`, and an optional `graph`                                                       |
+| `RouteNode`             | One node of the tree, with `id`, `path`, `fullPath`, `stateId`, `children`, and `parent`                                                 |
+| `RouteInfo`             | The flat route descriptor that comes from a state node                                                                                   |
+| `PlayRouteEvent`        | Routing event `{ type: "play.route", to, params?, query?, data? }`                                                                       |
+| `Routable`              | The optional routing capability of an actor: `currentRoute` and `initialRoute`                                                           |
+| `RoutableActor`         | The actor interface that `RouterBridgeBase` and `PlayRouterProvider` require: `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
+| `RouteMapping`          | The `{ stateId, path }` pair that builds a `RouteMap`                                                                                    |
+| `RouteObject`           | The object form of `meta.route`: `path`, and the `handler`, `reenter` and `data` fields                                                  |
+| `RouteMetadata`         | The union of the two forms of `meta.route`: the path string, or a `RouteObject`                                                          |
+| `RouteData`             | The resolved extra data of a route, which reaches the machine as `context.data`                                                          |
+| `RouteDataResolver`     | The function form of `RouteObject.data`: `({ context, event }) => RouteData`                                                             |
+| `WindowLike`            | The minimal `window` interface that you can inject for SSR and for a test                                                                |
+| `LocationLike`          | The minimal `location` interface that you can inject for SSR and for a test                                                              |
 
 ### Errors (subpath `@xmachines/play-router/errors`)
 
-| Class                        | Code                                    | When thrown                                                                                                     |
-| ---------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` cannot send a `play.route` event                                                        |
-| `DuplicateBridgeError`       | `PLAY_ROUTER_DUPLICATE_BRIDGE`          | A second bridge tries to connect to an actor that already has one                                               |
-| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | The URLPattern API is absent, and no polyfill is loaded                                                         |
-| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern does not compile, or two of its params land on one URLPattern group                             |
-| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                                                               |
-| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route names a state ID that the machine graph does not hold                                                   |
-| `DuplicateRoutePathError`    | `PLAY_ROUTE_DUPLICATE_PATH`             | Two or more states share the same URL path                                                                      |
-| `UnknownStateTypeError`      | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`         | A state node has an XState `.type` value that the package does not know                                         |
-| `InvalidBasePathError`       | `PLAY_ROUTER_INVALID_BASE_PATH`         | A `basePath` resolves to one concrete prefix never (`*`, `:p?`, `$p`, `?`, `#`, a scheme, `.`/`..`, whitespace) |
-| `MissingBasePathParamError`  | `PLAY_ROUTER_MISSING_BASE_PATH_PARAM`   | A `:param` of a `basePath` has no value in `basePathParams`                                                     |
+| Class                       | Code                                  | When thrown                                                                                                     |
+| --------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `RouterSyncError`           | `PLAY_ROUTER_SYNC_FAILED`             | `syncActorFromRouter()` cannot send a `play.route` event                                                        |
+| `DuplicateBridgeError`      | `PLAY_ROUTER_DUPLICATE_BRIDGE`        | A second bridge tries to connect to an actor that already has one                                               |
+| `InvalidRoutePatternError`  | `PLAY_ROUTE_MAP_INVALID_PATTERN`      | A route pattern does not compile, or two of its params land on one URLPattern group                             |
+| `EmptyRoutePathError`       | `PLAY_ROUTE_EMPTY_PATH`               | A state declares `meta.route: ""`                                                                               |
+| `InvalidStateIdError`       | `PLAY_ROUTE_INVALID_STATE_ID`         | A route names a state ID that the machine graph does not hold                                                   |
+| `DuplicateRoutePathError`   | `PLAY_ROUTE_DUPLICATE_PATH`           | Two or more states share the same URL path                                                                      |
+| `UnknownStateTypeError`     | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`       | A state node has an XState `.type` value that the package does not know                                         |
+| `InvalidBasePathError`      | `PLAY_ROUTER_INVALID_BASE_PATH`       | A `basePath` resolves to one concrete prefix never (`*`, `:p?`, `$p`, `?`, `#`, a scheme, `.`/`..`, whitespace) |
+| `MissingBasePathParamError` | `PLAY_ROUTER_MISSING_BASE_PATH_PARAM` | A `:param` of a `basePath` has no value in `basePathParams`                                                     |
 
 ```typescript
-import {
-	RouterSyncError,
-	DuplicateBridgeError,
-	URLPatternUnavailableError,
-} from "@xmachines/play-router/errors";
+import { RouterSyncError, DuplicateBridgeError } from "@xmachines/play-router/errors";
 
 // bridge from the adapter example above
 try {
@@ -565,6 +567,28 @@ states: {
 }
 ```
 
+### The object form
+
+The object form carries the path and any metadata of your own, such as a title or a
+breadcrumb. It also carries three fields that the routing layer reads:
+
+| Field     | Default  | What it does                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------- |
+| `path`    | required | The template of the route path                                                  |
+| `handler` | `"root"` | Where the generated `play.route` transition sits: `"root"`, `"local"`, `"both"` |
+| `reenter` | `false`  | Whether the transition re-enters its own domain. See the note below.            |
+| `data`    | none     | The extra data of the route: a literal value, or a function of the event        |
+
+`@xmachines/play-xstate` reads `handler`, `reenter`, and `data` when it generates the
+transitions. See the README of that package for what each value does.
+
+**The four names are RESERVED, and this is a change of behaviour.** An earlier release
+read `path` alone, so a state could put any name of its own beside it. A state that
+carries its own `handler` value now throws an `InvalidRouteHandlerError` at the format
+time, and the machine builds never; a state that carries its own `data` value now writes
+that value to `context.data`, where the `/context` projection of every view reads it.
+Give such a field another name.
+
 ### Relative vs absolute paths
 
 A child route that starts with `/` is absolute, and it does not inherit the path of its parent. A child route without the first `/` is relative to its nearest routable ancestor:
@@ -590,47 +614,17 @@ states: {
 
 Always use `node.fullPath` to match a browser URL and to build a route map. Never use `node.path` for this.
 
-## Testing
-
-```bash
-# Run tests for this package
-pnpm --filter @xmachines/play-router test
-
-# Watch mode
-pnpm --filter @xmachines/play-router run test:watch
-```
-
-`@xmachines/play-router-shared` holds a contract test suite of the router bridge, for the
-author of an adapter. That suite drives a real actor. Therefore it is one layer above this
-package, and `@xmachines/play-router` keeps no dependency on an actor runtime.
-`@xmachines/play-router-shared` is a private workspace package. Thus only an adapter author
-in this repository can use the suite:
-
-```typescript
-import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
-
-runBridgeContractTests({
-	name: "MyRouterBridge",
-	createHarness(initialPath) {
-		// return ContractHarness with bridge, actor, simulateNavigation, getLastNavigatedPath
-	},
-	createRestoredHarness(routedPath) {
-		// return ContractHarness whose actor is restored to routedPath
-		// while the mock router starts at the machine's initial route
-	},
-});
-```
-
 ## Related Packages
 
 - **[@xmachines/play](../play/README.md)** — Core protocol types (`PlayEvent`, `PlayError`)
-- **[@xmachines/play-actor](../play-actor/README.md)** — the abstract actor base class (`AbstractActor`, `Routable`). Every `AbstractActor` subclass satisfies `RoutableActor` structurally
+- **[@xmachines/play-actor](../play-actor/README.md)** — the actor contract (`PlayActor`). An actor that adds `Routable` of this package satisfies `RoutableActor` structurally
+- **[@xmachines/play-url](../play-url/README.md)** — the URL language. This package re-exports its base path and its framework params, for an adapter on `RouterBridgeBase`
 - **[@xmachines/play-signals](../play-signals/README.md)** — the TC39 Signals polyfill that observes the actor route
 - **[@xmachines/play-xstate](../play-xstate/README.md)** — the XState v5 logic adapter, which works with a route tree
 - **[@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
+- **[@xmachines/play-react-router](../play-react-router/README.md)** — React Router 7/8 adapter
 - **[@xmachines/play-vue-router](../play-vue-router/README.md)** — Vue Router adapter
 - **[@xmachines/play-solid-router](../play-solid-router/README.md)** — SolidJS Router adapter
 

package/dist/base-route-map.d.ts

@@ -45,11 +45,17 @@ export interface RouteMapping {
  * - The class keeps each result of a first match in an LRU cache. The default size
  *   is 500 entries, and the `cacheSize` constructor option changes it
  *
- * **The syntax of a pattern** (`:param`, `:param?`, and `*`):
+ * **The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+ * often are:
  * - `:param` — a necessary segment. It matches exactly one segment without a `/`
  * - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
  * - `*` — a wildcard. It matches each number of segments, as URLPattern defines
  *
+ * A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+ * too. The [routing guide](../../docs/guides/routing.md) states every form, the prefix
+ * rule, and the one divergence from the standard: a param name of this library can hold a
+ * hyphen.
+ *
  * **The forms of a stateId:** you can register a stateId, and you can look one up,
  * in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
  * canonical form itself. `getStateIdByPath` returns the stateId exactly as you

package/dist/base-route-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,QAAQ;IACpB,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;;;OAiBG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAwCtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}
+{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,QAAQ;IACpB,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;;;OAiBG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IA0CtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA4B7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}

package/dist/base-route-map.js

@@ -10,9 +10,9 @@
  * segment, and that number is much smaller than the number of all the routes. The
  * class matches a parameterized route with URLPattern.
  */
+import { firstMarkIndex, getCandidates, getCompiledPattern, getIndexKey, parsePattern, } from "@xmachines/play-url";
 import QuickLRU from "quick-lru";
-import { getURLPatternCtor, getCompiledPattern, getIndexKey, getCandidates, isParameterizedPattern, } from "./url-pattern-utils.js";
-import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
+import { InvalidRoutePatternError } from "./errors.js";
 /**
  * The canonical key of a stateId: the bare form, without a `#` at its start.
  *
@@ -38,11 +38,17 @@ function canonicalStateIdKey(stateId) {
  * - The class keeps each result of a first match in an LRU cache. The default size
  *   is 500 entries, and the `cacheSize` constructor option changes it
  *
- * **The syntax of a pattern** (`:param`, `:param?`, and `*`):
+ * **The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+ * often are:
  * - `:param` — a necessary segment. It matches exactly one segment without a `/`
  * - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
  * - `*` — a wildcard. It matches each number of segments, as URLPattern defines
  *
+ * A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+ * too. The [routing guide](../../docs/guides/routing.md) states every form, the prefix
+ * rule, and the one divergence from the standard: a param name of this library can hold a
+ * hyphen.
+ *
  * **The forms of a stateId:** you can register a stateId, and you can look one up,
  * in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
  * canonical form itself. `getStateIdByPath` returns the stateId exactly as you
@@ -104,16 +110,18 @@ export class RouteMap {
             // "#stateId" and also "stateId". The map keeps the registered form for its return
             // values.
             this.stateIdToPath.set(canonicalStateIdKey(stateId), path);
-            if (isParameterizedPattern(path)) {
-                const URLPatternCtorFn = getURLPatternCtor();
-                if (!URLPatternCtorFn) {
-                    throw new URLPatternUnavailableError();
-                }
-                const bucketKey = getIndexKey(path);
+            // ONE parse answers both questions: is the path a pattern, and which bucket does
+            // it belong to. The key comes from that parse, and not from a split of the raw
+            // string. A pattern such as `/books{/:id}?` keeps the literal first segment
+            // `books`, and a split on `/` read the key `books{` and put the route in a bucket
+            // that the path `/books/1` reaches never.
+            const parsed = parsePattern(path);
+            if (parsed.parameterized) {
+                const bucketKey = parsed.indexKey;
                 const bucket = this.patternBuckets.get(bucketKey) ?? [];
                 try {
                     bucket.push({
-                        pattern: getCompiledPattern(path, URLPatternCtorFn),
+                        pattern: getCompiledPattern(path),
                         stateId,
                         order: patternOrder++,
                     });
@@ -150,8 +158,13 @@ export class RouteMap {
      * ```
      */
     getStateIdByPath(path) {
-        // Remove the query string and the hash fragment before the match
-        const cleanPath = path.split("?")[0].split("#")[0];
+        // Remove the query string and the hash fragment before the match. `firstMarkIndex`
+        // is the ONE answer to "where does a pathname end", and `RouterBridgeBase` and
+        // `framework-params.ts` read it too, so the three cannot disagree. Two splits
+        // allocated two arrays of every part on the hottest lookup of the library, and this
+        // function then read one element of each.
+        const mark = firstMarkIndex(path);
+        const cleanPath = mark === -1 ? path : path.slice(0, mark);
         const exactMatch = this.pathToStateId.get(cleanPath);
         if (exactMatch !== undefined)
             return exactMatch;

package/dist/base-route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-route-map.js","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-route-map.js","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"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"}

package/dist/build-tree.d.ts

@@ -1,4 +1,15 @@
 import type { RouteInfo, RouteTree } from "./types.js";
+/**
+ * The ID and the state ID of the synthetic root node of every `RouteTree`.
+ *
+ * `buildRouteTree` always makes this node, and no state of a machine declares it. It
+ * gives the tree one parent for each absolute route, and it holds `routable: false`.
+ *
+ * A consumer that walks a tree must SKIP this node. `createRouteMapFromTree` skips it,
+ * and `getRoutableRoutes` of `@xmachines/play-router/xstate` skips it. A walk that keeps
+ * it maps the path `/` to a state that the machine does not hold.
+ */
+export declare const ROOT_NODE_ID = "__root__";
 /**
  * Builds the hierarchical route tree from the flat list of the routes
  *
@@ -13,9 +24,13 @@ import type { RouteInfo, RouteTree } from "./types.js";
  * strings that resolve to the same complete path are not: those two overwrite each
  * other in `byPath` in silence.
  *
+ * `TGraph` names the type of the graph that a CALLER attaches afterwards. The builder
+ * attaches none: it reads a list of routes and writes the maps of the tree.
+ * `extractMachineRoutes` of `@xmachines/play-router/xstate` binds it to `MachineGraph`.
+ *
  * @param routes - The flat list of the RouteInfo objects, from the extraction
  * @returns The RouteTree, with its root, its byStateId map, and its byPath map
  * @throws {DuplicateRoutePathError} When two states resolve to the same complete path
  */
-export declare const buildRouteTree: (routes: RouteInfo[]) => RouteTree;
+export declare const buildRouteTree: <TGraph = unknown>(routes: RouteInfo[]) => RouteTree<TGraph>;
 //# sourceMappingURL=build-tree.d.ts.map

package/dist/build-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4B,SAAS,EAAE,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,KAAG,SAyEpD,CAAC"}
+{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,SAAS,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,GAAG,OAAO,EAAE,QAAQ,SAAS,EAAE,KAAG,SAAS,CAAC,MAAM,CA0EtF,CAAC"}

package/dist/build-tree.js

@@ -1,4 +1,15 @@
 import { detectDuplicateRoutes } from "./validate-routes.js";
+/**
+ * The ID and the state ID of the synthetic root node of every `RouteTree`.
+ *
+ * `buildRouteTree` always makes this node, and no state of a machine declares it. It
+ * gives the tree one parent for each absolute route, and it holds `routable: false`.
+ *
+ * A consumer that walks a tree must SKIP this node. `createRouteMapFromTree` skips it,
+ * and `getRoutableRoutes` of `@xmachines/play-router/xstate` skips it. A walk that keeps
+ * it maps the path `/` to a state that the machine does not hold.
+ */
+export const ROOT_NODE_ID = "__root__";
 /**
  * Builds the hierarchical route tree from the flat list of the routes
  *
@@ -13,6 +24,10 @@ import { detectDuplicateRoutes } from "./validate-routes.js";
  * strings that resolve to the same complete path are not: those two overwrite each
  * other in `byPath` in silence.
  *
+ * `TGraph` names the type of the graph that a CALLER attaches afterwards. The builder
+ * attaches none: it reads a list of routes and writes the maps of the tree.
+ * `extractMachineRoutes` of `@xmachines/play-router/xstate` binds it to `MachineGraph`.
+ *
  * @param routes - The flat list of the RouteInfo objects, from the extraction
  * @returns The RouteTree, with its root, its byStateId map, and its byPath map
  * @throws {DuplicateRoutePathError} When two states resolve to the same complete path
@@ -20,10 +35,10 @@ import { detectDuplicateRoutes } from "./validate-routes.js";
 export const buildRouteTree = (routes) => {
     // 1. Create the root node
     const root = {
-        id: "__root__",
+        id: ROOT_NODE_ID,
         path: "/",
         fullPath: "/",
-        stateId: "__root__",
+        stateId: ROOT_NODE_ID,
         routable: false, // The root is a state without a route
         children: [],
         parent: null,
@@ -33,8 +48,7 @@ export const buildRouteTree = (routes) => {
     const byStateId = new Map([[root.stateId, root]]);
     const byPath = new Map([[root.fullPath, root]]);
     // 3. Sort the routes by their depth. The shallowest route comes first, for the link to each parent
-    // oxlint-disable-next-line unicorn/no-array-sort
-    const sorted = routes.slice().sort((a, b) => a.statePath.length - b.statePath.length);
+    const sorted = routes.toSorted((a, b) => a.statePath.length - b.statePath.length);
     // 4. Build the tree, and collect each node for the detection of a duplicate resolved path
     const insertedNodes = [];
     for (const route of sorted) {
@@ -45,8 +59,11 @@ export const buildRouteTree = (routes) => {
         let parentNode = root;
         for (let i = route.statePath.length - 2; i >= 0; i--) {
             const parentStateId = route.statePath[i]; // nosemgrep: gitlab.eslint.detect-object-injection
-            if (byStateId.has(parentStateId)) {
-                parentNode = byStateId.get(parentStateId);
+            if (parentStateId === undefined)
+                continue;
+            const candidate = byStateId.get(parentStateId);
+            if (candidate !== undefined) {
+                parentNode = candidate;
                 break;
             }
         }

package/dist/build-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"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"}

package/dist/create-route-map-from-tree.d.ts

@@ -1,11 +1,11 @@
-import type { RouteTree } from "./types.js";
+import type { RouteTree, RouteMapOptions } from "./types.js";
 import { RouteMap } from "./base-route-map.js";
-import type { RouteMapOptions } from "./create-route-map.js";
 /**
  * Creates a `RouteMap` from the node structure of a `RouteTree`.
  *
- * A framework router adapter uses this function when it gives a `RouteTree` from
- * `extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
+ * A framework router adapter uses this function when it holds a `RouteTree`, for example
+ * from `extractMachineRoutes()` of `@xmachines/play-router/xstate`, and not when it calls
+ * `createRouteMap()` of that package directly.
  *
  * The function walks every node, and it collects the pairs
  * `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
@@ -13,6 +13,11 @@ import type { RouteMapOptions } from "./create-route-map.js";
  * that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
  * same way, because it also uses `node.fullPath`.
  *
+ * The walk SKIPS the synthetic root node. `buildRouteTree` makes that node to hold each
+ * absolute route, and no state of a machine declares it. `createRouteMap` skips it as
+ * well, through `getRoutableRoutes`, and the two functions therefore answer the same map
+ * for the same tree.
+ *
  * @param routeTree - A `RouteTree`, as `extractMachineRoutes()` returns it.
  * @param options - The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache.
  * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
@@ -20,11 +25,12 @@ import type { RouteMapOptions } from "./create-route-map.js";
  * @example
  * ```typescript
  * // The preferred form — one call for an XState machine:
- * import { createRouteMap } from '@xmachines/play-router';
+ * import { createRouteMap } from '@xmachines/play-router/xstate';
  * const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
  *
  * // The two-step form, for a framework adapter that works with a route tree:
- * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
+ * import { createRouteMapFromTree } from '@xmachines/play-router';
+ * import { extractMachineRoutes } from '@xmachines/play-router/xstate';
  * const routeTree = extractMachineRoutes(machine);
  * const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
  * ```