@xmachines/play-router 3.0.0 → 4.0.0

package/dist/create-route-map-from-tree.js

@@ -1,9 +1,11 @@
 import { RouteMap } from "./base-route-map.js";
+import { ROOT_NODE_ID } from "./build-tree.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
@@ -11,6 +13,11 @@ import { RouteMap } from "./base-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`.
@@ -18,11 +25,12 @@ import { RouteMap } from "./base-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
  * ```
@@ -30,7 +38,7 @@ import { RouteMap } from "./base-route-map.js";
 export function createRouteMapFromTree(routeTree, options) {
     const routes = [];
     function traverse(node) {
-        if (node.id && node.fullPath) {
+        if (node.id && node.fullPath && node.id !== ROOT_NODE_ID) {
             routes.push({ stateId: node.id, path: node.fullPath });
         }
         if (node.children) {

package/dist/create-route-map-from-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-route-map-from-tree.js","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,OAAyB;IACrF,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"create-route-map-from-tree.js","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,OAAyB;IACrF,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,EAAE,KAAK,YAAY,EAAE,CAAC;YAC1D,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
+export { InvalidRoutePatternError, InvalidBasePathError, MissingBasePathParamError, } from "@xmachines/play-url/errors";
 /**
  * The bridge throws this error when `RouterBridgeBase.syncActorFromRouter()`
  * cannot process a location change of the router and send the `play.route` event to
@@ -55,27 +56,6 @@ export declare class RouterSyncError extends PlayError {
 export declare class DuplicateBridgeError extends PlayError {
     constructor();
 }
-/**
- * The `RouteMap` constructor throws this error when the caller registers a
- * parameterized route, the current runtime has no `URLPattern` API, and no polyfill
- * is loaded.
- *
- * **The remedy:** load `urlpattern-polyfill` at the entry point of your application,
- * before each import of `@xmachines/play-router`:
- *
- * ```typescript
- * // the entry point of the application — it must run first
- * import "urlpattern-polyfill";
- * ```
- *
- * URLPattern is native in Node.js ≥ 24 and in a modern browser (Chrome 95+,
- * Firefox 117+, Safari 16.4+). Use the polyfill for an older target.
- *
- * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
- */
-export declare class URLPatternUnavailableError extends PlayError {
-    constructor();
-}
 /**
  * `validateRouteFormat()` throws this error when a state declares a `meta.route`
  * field with an empty string as its path.
@@ -122,116 +102,4 @@ export declare class UnknownStateTypeError extends PlayError {
     readonly nodeId: string;
     constructor(stateType: string, nodeId: string, validTypes: string[]);
 }
-/**
- * The library throws this error when `URLPattern` cannot compile the string of a route
- * pattern. The `pattern` field holds the string in question, and `cause` holds the
- * original error of the `URLPattern` constructor.
- *
- * Every compilation reports through this error, so `extractRouteParams` raises it for a
- * pattern that no `RouteMap` ever held, and not a bare `TypeError`.
- *
- * The common causes:
- * - A parenthesis or a bracket without its pair in the string of the pattern
- * - A character that a URL pathname pattern does not permit
- * - Two params of one pattern that land on the same URLPattern group. A name with a
- *   hyphen compiles with an underscore, so `:cat-id` and `:cat_id` are one group. The
- *   message names the two params and the group, and `cause` is absent: the library
- *   refuses the pattern before URLPattern sees it.
- *
- * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
- *
- * @example
- * ```typescript
- * import { InvalidRoutePatternError } from "@xmachines/play-router/errors";
- *
- * try {
- *   const routeMap = createRouteMap(machine);
- * } catch (err) {
- *   if (err instanceof InvalidRoutePatternError) {
- *     console.error(`Bad route pattern: "${err.pattern}"`, err.cause);
- *   }
- * }
- * ```
- */
-export declare class InvalidRoutePatternError extends PlayError {
-    /** The string of the route pattern. URLPattern could not compile it. */
-    readonly pattern: string;
-    /**
-     * @param pattern - The route pattern that URLPattern could not compile.
-     * @param options - The standard `cause`, and an optional `reason` that says WHY. Give
-     *   a reason whenever the library knows it: the pattern alone shows a caller nothing
-     *   when the fault is a rewrite that the library made, and not the text they wrote.
-     */
-    constructor(pattern: string, options?: ErrorOptions & {
-        reason?: string;
-    });
-}
-/**
- * Thrown when a `basePath` option resolves to one concrete URL prefix never.
- *
- * A bridge writes a real browser URL from its prefix, so every segment must hold
- * exactly one value. A wildcard segment (`*`), an optional segment (`:section?`), a
- * nameless `:` segment, a query string, and a hash fragment each describe a SET of
- * prefixes instead, or no prefix at all. A `$param` segment is the route-param
- * syntax of TanStack Router: a base path writes a param as `:param`, and it takes
- * the value of that param from `basePathParams`.
- *
- * **How to fix it:** mount on the prefix itself, and let the machine own the rest.
- * For the splat route `/$machineId/play/$` of TanStack, the base path is
- * `"/:machineId/play"` with `basePathParams: { machineId }`.
- *
- * **Error code:** `PLAY_ROUTER_INVALID_BASE_PATH`
- *
- * @example
- * ```typescript
- * import { InvalidBasePathError } from "@xmachines/play-router/errors";
- *
- * try {
- *   bridge.setBasePath("/:machineId/play/*");
- * } catch (err) {
- *   if (err instanceof InvalidBasePathError) {
- *     console.error(`Bad base path: "${err.basePath}"`, err.message);
- *   }
- * }
- * ```
- */
-export declare class InvalidBasePathError extends PlayError {
-    /** The `basePath` option of the refusal, exactly as the caller gave it. */
-    readonly basePath: string;
-    constructor(basePath: string, reason: string);
-}
-/**
- * Thrown when a `:param` segment of a `basePath` has no value in `basePathParams`.
- *
- * A base path can be a pattern, so a host keeps one string that mirrors its own
- * route config. The bridge must still resolve that pattern to a concrete prefix,
- * because it writes a real browser URL, and it removes a literal prefix from every
- * inbound location. Every `:param` therefore needs a value.
- *
- * **How to fix it:** give the value that the host resolved already — a loader of
- * TanStack, or a `useParams()` call, holds it — as `basePathParams: { machineId }`.
- * An empty string counts as an absent value, because it would collapse the segment.
- *
- * **Error code:** `PLAY_ROUTER_MISSING_BASE_PATH_PARAM`
- *
- * @example
- * ```typescript
- * import { MissingBasePathParamError } from "@xmachines/play-router/errors";
- *
- * try {
- *   connectRouter({ actor, router, routeMap, basePath: "/:machineId/play" });
- * } catch (err) {
- *   if (err instanceof MissingBasePathParamError) {
- *     console.error(`basePath needs a value for :${err.param}`);
- *   }
- * }
- * ```
- */
-export declare class MissingBasePathParamError extends PlayError {
-    /** The name of the `:param` segment without a value, and without its `:`. */
-    readonly param: string;
-    /** The `basePath` option that declares the param. */
-    readonly basePath: string;
-    constructor(param: string, basePath: string);
-}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAazE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAWnD,OAAO,EACN,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GACzB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE"}

package/dist/errors.js

@@ -1,4 +1,14 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
+// The errors of the URL language live in `@xmachines/play-url`, with the parser that
+// raises them. They are re-exported here, so that a consumer of this package sorts every
+// routing error from one import, exactly as before the split.
+//
+// The specifier is the `./errors` subpath, and not the root barrel. A consumer that
+// imports `@xmachines/play-router/errors` to name a fault in a `catch` then loads the
+// three classes alone: no pattern parser, no base path, and neither `quick-lru` nor
+// `urlpattern-polyfill`. The root barrel of this package reaches the rest of
+// `@xmachines/play-url` for the consumer that needs it.
+export { InvalidRoutePatternError, InvalidBasePathError, MissingBasePathParamError, } from "@xmachines/play-url/errors";
 /**
  * The bridge throws this error when `RouterBridgeBase.syncActorFromRouter()`
  * cannot process a location change of the router and send the `play.route` event to
@@ -62,30 +72,6 @@ export class DuplicateBridgeError extends PlayError {
         this.name = "DuplicateBridgeError";
     }
 }
-/**
- * The `RouteMap` constructor throws this error when the caller registers a
- * parameterized route, the current runtime has no `URLPattern` API, and no polyfill
- * is loaded.
- *
- * **The remedy:** load `urlpattern-polyfill` at the entry point of your application,
- * before each import of `@xmachines/play-router`:
- *
- * ```typescript
- * // the entry point of the application — it must run first
- * import "urlpattern-polyfill";
- * ```
- *
- * URLPattern is native in Node.js ≥ 24 and in a modern browser (Chrome 95+,
- * Firefox 117+, Safari 16.4+). Use the polyfill for an older target.
- *
- * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
- */
-export class URLPatternUnavailableError extends PlayError {
-    constructor() {
-        super("RouteMap", "PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE", "URLPattern is not available. Load a polyfill (e.g. urlpattern-polyfill) before using @xmachines/play-router on Node < 24 or older browsers.");
-        this.name = "URLPatternUnavailableError";
-    }
-}
 /**
  * `validateRouteFormat()` throws this error when a state declares a `meta.route`
  * field with an empty string as its path.
@@ -152,130 +138,4 @@ export class UnknownStateTypeError extends PlayError {
         this.nodeId = nodeId;
     }
 }
-/**
- * The library throws this error when `URLPattern` cannot compile the string of a route
- * pattern. The `pattern` field holds the string in question, and `cause` holds the
- * original error of the `URLPattern` constructor.
- *
- * Every compilation reports through this error, so `extractRouteParams` raises it for a
- * pattern that no `RouteMap` ever held, and not a bare `TypeError`.
- *
- * The common causes:
- * - A parenthesis or a bracket without its pair in the string of the pattern
- * - A character that a URL pathname pattern does not permit
- * - Two params of one pattern that land on the same URLPattern group. A name with a
- *   hyphen compiles with an underscore, so `:cat-id` and `:cat_id` are one group. The
- *   message names the two params and the group, and `cause` is absent: the library
- *   refuses the pattern before URLPattern sees it.
- *
- * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
- *
- * @example
- * ```typescript
- * import { InvalidRoutePatternError } from "@xmachines/play-router/errors";
- *
- * try {
- *   const routeMap = createRouteMap(machine);
- * } catch (err) {
- *   if (err instanceof InvalidRoutePatternError) {
- *     console.error(`Bad route pattern: "${err.pattern}"`, err.cause);
- *   }
- * }
- * ```
- */
-export class InvalidRoutePatternError extends PlayError {
-    /** The string of the route pattern. URLPattern could not compile it. */
-    pattern;
-    /**
-     * @param pattern - The route pattern that URLPattern could not compile.
-     * @param options - The standard `cause`, and an optional `reason` that says WHY. Give
-     *   a reason whenever the library knows it: the pattern alone shows a caller nothing
-     *   when the fault is a rewrite that the library made, and not the text they wrote.
-     */
-    constructor(pattern, options) {
-        const reason = options?.reason;
-        super("RouteMap", "PLAY_ROUTE_MAP_INVALID_PATTERN", reason
-            ? `Invalid route pattern: "${pattern}". ${reason}`
-            : `Invalid route pattern: "${pattern}"`, options);
-        this.name = "InvalidRoutePatternError";
-        this.pattern = pattern;
-    }
-}
-/**
- * Thrown when a `basePath` option resolves to one concrete URL prefix never.
- *
- * A bridge writes a real browser URL from its prefix, so every segment must hold
- * exactly one value. A wildcard segment (`*`), an optional segment (`:section?`), a
- * nameless `:` segment, a query string, and a hash fragment each describe a SET of
- * prefixes instead, or no prefix at all. A `$param` segment is the route-param
- * syntax of TanStack Router: a base path writes a param as `:param`, and it takes
- * the value of that param from `basePathParams`.
- *
- * **How to fix it:** mount on the prefix itself, and let the machine own the rest.
- * For the splat route `/$machineId/play/$` of TanStack, the base path is
- * `"/:machineId/play"` with `basePathParams: { machineId }`.
- *
- * **Error code:** `PLAY_ROUTER_INVALID_BASE_PATH`
- *
- * @example
- * ```typescript
- * import { InvalidBasePathError } from "@xmachines/play-router/errors";
- *
- * try {
- *   bridge.setBasePath("/:machineId/play/*");
- * } catch (err) {
- *   if (err instanceof InvalidBasePathError) {
- *     console.error(`Bad base path: "${err.basePath}"`, err.message);
- *   }
- * }
- * ```
- */
-export class InvalidBasePathError extends PlayError {
-    /** The `basePath` option of the refusal, exactly as the caller gave it. */
-    basePath;
-    constructor(basePath, reason) {
-        super("resolveBasePath", "PLAY_ROUTER_INVALID_BASE_PATH", `Invalid basePath "${basePath}": ${reason}`);
-        this.name = "InvalidBasePathError";
-        this.basePath = basePath;
-    }
-}
-/**
- * Thrown when a `:param` segment of a `basePath` has no value in `basePathParams`.
- *
- * A base path can be a pattern, so a host keeps one string that mirrors its own
- * route config. The bridge must still resolve that pattern to a concrete prefix,
- * because it writes a real browser URL, and it removes a literal prefix from every
- * inbound location. Every `:param` therefore needs a value.
- *
- * **How to fix it:** give the value that the host resolved already — a loader of
- * TanStack, or a `useParams()` call, holds it — as `basePathParams: { machineId }`.
- * An empty string counts as an absent value, because it would collapse the segment.
- *
- * **Error code:** `PLAY_ROUTER_MISSING_BASE_PATH_PARAM`
- *
- * @example
- * ```typescript
- * import { MissingBasePathParamError } from "@xmachines/play-router/errors";
- *
- * try {
- *   connectRouter({ actor, router, routeMap, basePath: "/:machineId/play" });
- * } catch (err) {
- *   if (err instanceof MissingBasePathParamError) {
- *     console.error(`basePath needs a value for :${err.param}`);
- *   }
- * }
- * ```
- */
-export class MissingBasePathParamError extends PlayError {
-    /** The name of the `:param` segment without a value, and without its `:`. */
-    param;
-    /** The `basePath` option that declares the param. */
-    basePath;
-    constructor(param, basePath) {
-        super("resolveBasePath", "PLAY_ROUTER_MISSING_BASE_PATH_PARAM", `basePath "${basePath}" declares ":${param}", but basePathParams has no value for it.`);
-        this.name = "MissingBasePathParamError";
-        this.param = param;
-        this.basePath = basePath;
-    }
-}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,qFAAqF;AACrF,yFAAyF;AACzF,8DAA8D;AAC9D,EAAE;AACF,oFAAoF;AACpF,sFAAsF;AACtF,oFAAoF;AACpF,6EAA6E;AAC7E,wDAAwD;AACxD,OAAO,EACN,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GACzB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC7C,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CAAC,kBAAkB,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD;QACC,KAAK,CACJ,kBAAkB,EAClB,8BAA8B,EAC9B,iEAAiE;YAChE,uEAAuE,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACpC,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IACrC,OAAO,CAAS;IAEzB,YAAY,OAAe;QAC1B,KAAK,CACJ,UAAU,EACV,uBAAuB,EACvB,8BAA8B,OAAO,sCAAsC,CAC3E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACxD,OAAO,CAAS;IAEzB,YAAY,OAAe;QAC1B,KAAK,CACJ,UAAU,EACV,6BAA6B,EAC7B,2CAA2C,OAAO,EAAE,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IAC7E,UAAU,CAAW;IAE9B,YAAY,UAAoB;QAC/B,KAAK,CACJ,UAAU,EACV,2BAA2B,EAC3B,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YAC9D,kDAAkD;YAClD,6FAA6F,CAC9F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IAC1D,SAAS,CAAS;IAC3B,sDAAsD;IAC7C,MAAM,CAAS;IAExB,YAAY,SAAiB,EAAE,MAAc,EAAE,UAAoB;QAClE,KAAK,CACJ,gBAAgB,EAChB,+BAA+B,EAC/B,8BAA8B,SAAS,cAAc,MAAM,KAAK;YAC/D,oBAAoB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC7C,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD"}

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

@@ -1 +1 @@
-{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAsCvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}
+{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAkCvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}

package/dist/find-route.js

@@ -1,21 +1,17 @@
-import { getURLPatternCtor, getCompiledPattern } from "./url-pattern-utils.js";
-import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
+import { getCompiledPattern, isParameterizedPattern } from "@xmachines/play-url";
 /**
  * Tells you if a URL path matches a route pattern, with URLPattern.
  *
- * For a static pattern, which holds no `:param`, the function makes a direct
- * equality test. Therefore an environment with static routes only needs URLPattern
- * never, and it needs no polyfill.
+ * For a static pattern, which holds no param, the function makes a direct equality
+ * test, and it compiles nothing.
  *
  * The function uses the compiled-pattern cache of the module level
  * (`getCompiledPattern`). A repeated lookup therefore compiles the same pattern
  * never again. The cache also normalizes a param name with a hyphen (`:cat-id`)
  * exactly like `RouteMap`: one match engine is below both.
  *
- * The function throws a `URLPatternUnavailableError` when it tests a parameterized
- * pattern and `globalThis` holds no URLPattern.
- * It throws an `InvalidRoutePatternError` when URLPattern cannot compile the
- * pattern.
+ * It throws the `InvalidRoutePatternError` of `getCompiledPattern` when URLPattern
+ * cannot compile the pattern.
  *
  * This function is private. The public API of the package does not export it.
  *
@@ -24,17 +20,16 @@ import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.j
  * @returns True when the path matches the pattern
  */
 function matchesPattern(path, pattern) {
-    if (!pattern.includes(":"))
+    // The test reads the PARSE. `pattern.includes(":")` called `/docs/*` and `/a{/b}?/c`
+    // static, and the equality test below then answered `false` for every path that the
+    // pattern matches.
+    if (!isParameterizedPattern(pattern))
         return path === pattern;
-    const Ctor = getURLPatternCtor();
-    if (!Ctor)
-        throw new URLPatternUnavailableError();
-    try {
-        return getCompiledPattern(pattern, Ctor).test({ pathname: path });
-    }
-    catch (err) {
-        throw new InvalidRoutePatternError(pattern, { cause: err });
-    }
+    // `getCompiledPattern` reports an invalid pattern itself, and with the REASON when it
+    // knows one — two params that land on one URLPattern group, for example. A wrap here
+    // replaced that message with the generic one and pushed the explanation down to
+    // `cause`, which is the same defect that `RouteMap` guards against in its constructor.
+    return getCompiledPattern(pattern).test({ pathname: path });
 }
 /**
  * Finds a route node by its state ID

package/dist/find-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-route.js","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,OAAe;IACpD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,KAAK,OAAO,CAAC;IACpD,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,0BAA0B,EAAE,CAAC;IAClD,IAAI,CAAC;QACJ,OAAO,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,wBAAwB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAe,EAAE,EAAU,EAAyB,EAAE;IACnF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAe,EAAE,IAAY,EAAyB,EAAE;IACvF,wEAAwE;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oFAAoF;IACpF,4BAA4B;IAC5B,gEAAgE;IAChE,0EAA0E;IAC1E,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACzB,SAAS,CAAC,iCAAiC;QAC5C,CAAC;QAED,iDAAiD;QACjD,IAAI,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;IAED,yFAAyF;IACzF,OAAO,IAAI,CAAC;AACb,CAAC,CAAC"}
+{"version":3,"file":"find-route.js","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGjF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,OAAe;IACpD,qFAAqF;IACrF,oFAAoF;IACpF,mBAAmB;IACnB,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,KAAK,OAAO,CAAC;IAC9D,sFAAsF;IACtF,qFAAqF;IACrF,gFAAgF;IAChF,uFAAuF;IACvF,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAe,EAAE,EAAU,EAAyB,EAAE;IACnF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAe,EAAE,IAAY,EAAyB,EAAE;IACvF,wEAAwE;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oFAAoF;IACpF,4BAA4B;IAC5B,gEAAgE;IAChE,0EAA0E;IAC1E,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACzB,SAAS,CAAC,iCAAiC;QAC5C,CAAC;QAED,iDAAiD;QACjD,IAAI,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;IAED,yFAAyF;IACzF,OAAO,IAAI,CAAC;AACb,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,29 +1,19 @@
-import type { RouteMapping } from "./base-route-map.js";
 export { RouterBridgeBase } from "./router-bridge-base.js";
 export type { RouteWatcherHandle } from "./router-bridge-base.js";
 export { sanitizePathname, buildPlayRouteEvent, extractQuery, extractRouteParams, } from "./router-sync.js";
 export type { RouteMatch, BuildPlayRouteEventOptions } from "./router-sync.js";
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
 export type { ResolvedRoutePath } from "./validate-routes.js";
-export { buildRouteTree } from "./build-tree.js";
-export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists, getRouteMappings, getTransitionReachableRoutes, isRouteReachable, } from "./query.js";
-export { normalizeBasePath, resolveBasePath, stripBasePath, joinBasePath, NO_BASE_PATH, } from "./base-path.js";
-export type { BasePathOptions, ResolvedBasePath } from "./base-path.js";
-export { cleanFrameworkParams, getPatternParamNames, getRequiredPatternParamNames, pickOwnParams, resolveFrameworkParams, type FrameworkParamsSource, } from "./framework-params.js";
+export { normalizeBasePath, resolveBasePath, stripBasePath, joinBasePath, NO_BASE_PATH, } from "@xmachines/play-url";
+export type { BasePathOptions, ResolvedBasePath } from "@xmachines/play-url";
+export { cleanFrameworkParams, getPatternParamNames, getRequiredPatternParamNames, pickOwnParams, resolveFrameworkParams, type FrameworkParamsSource, } from "@xmachines/play-url";
 export { isMountableBridge, mountKey, createRouterConnection, openProviderBridge, repointProviderBridge, } from "./provider-lifecycle.js";
 export type { OpenProviderBridgeArgs, PlayRouterBridgeConstructor, PlayRouterProviderBaseProps, RouterConnection, } from "./provider-lifecycle.js";
-export { machineToGraph } from "./machine-to-graph.js";
-export type { MachineGraph } from "./machine-to-graph.js";
-export type { RouteInfo, RouteNode, RouteTree, RouteObject, RouteMetadata, PlayRouteEvent, RoutableActor, PlayActor, RouterBridge, MountableRouterBridge, MachineNodeData, MachineEdgeData, WindowLike, LocationLike, } from "./types.js";
+export type { RouteInfo, RouteNode, RouteTree, RouteObject, RouteMetadata, RouteData, RouteDataResolver, PlayRouteEvent, Routable, RoutableActor, RouterBridge, MountableRouterBridge, WindowLike, LocationLike, } from "./types.js";
 export { RouteMap, type RouteMapping } from "./base-route-map.js";
-/**
- * @deprecated Use {@link RouteMapping}. Will be removed in the next major.
- */
-export type BaseRouteMapping = RouteMapping;
-export { createRouteMap } from "./create-route-map.js";
-export type { RouteMapOptions } from "./create-route-map.js";
 export { createRouteMapFromTree } from "./create-route-map-from-tree.js";
 export { findRouteById, findRouteByPath } from "./find-route.js";
 export { DISPOSE } from "@xmachines/play";
+export { buildRouteTree, ROOT_NODE_ID } from "./build-tree.js";
+export type { RouteMapOptions } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACN,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,KAAK,qBAAqB,GAC1B,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACN,iBAAiB,EACjB,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,gBAAgB,GAChB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,YAAY,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,GACZ,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAI5C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMjE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D,OAAO,EACN,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,GACZ,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG7E,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,KAAK,qBAAqB,GAC1B,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACN,iBAAiB,EACjB,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,gBAAgB,GAChB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,UAAU,EACV,YAAY,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGlE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMjE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAI1C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -4,30 +4,21 @@ export { RouterBridgeBase } from "./router-bridge-base.js";
 export { sanitizePathname, buildPlayRouteEvent, extractQuery, extractRouteParams, } from "./router-sync.js";
 // The route utilities
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
-export { buildRouteTree } from "./build-tree.js";
-export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists, getRouteMappings, getTransitionReachableRoutes, isRouteReachable, } from "./query.js";
 // The base-path mount — it lets a host own a part of the same router as a machine.
 // A consumer normally gives `basePath` to a bridge, to `connectRouter`, or to a
 // `PlayRouterProvider`. These primitives serve an adapter, and a host that builds its
 // own route table.
-export { normalizeBasePath, resolveBasePath, stripBasePath, joinBasePath, NO_BASE_PATH, } from "./base-path.js";
+export { normalizeBasePath, resolveBasePath, stripBasePath, joinBasePath, NO_BASE_PATH, } from "@xmachines/play-url";
 // The params of a framework router, reconciled with the pattern of the machine. A
 // bridge whose framework parses the params itself calls this, and it keeps that parse.
-export { cleanFrameworkParams, getPatternParamNames, getRequiredPatternParamNames, pickOwnParams, resolveFrameworkParams, } from "./framework-params.js";
+export { cleanFrameworkParams, getPatternParamNames, getRequiredPatternParamNames, pickOwnParams, resolveFrameworkParams, } from "@xmachines/play-url";
 // The framework-free half of a PlayRouterProvider: the props, the constructor shape,
 // and the lifecycle of the bridge. A provider of a framework adds its own effects and
 // nothing else. This entry stays framework-agnostic — nothing here imports one.
 export { isMountableBridge, mountKey, createRouterConnection, openProviderBridge, repointProviderBridge, } from "./provider-lifecycle.js";
-// The graph adapter — it converts an XState machine into a Graph of @statelyai/graph
-export { machineToGraph } from "./machine-to-graph.js";
 // The shared base class of the route map for both directions.
-// This module exports RouteMapping directly. BaseRouteMapping stays as an alias, for
-// the compatibility.
 export { RouteMap } from "./base-route-map.js";
 // The factories: each one creates a RouteMap from a machine or from a route tree.
-// Every RouterBridgeBase adapter uses them, and it writes no factory of its own.
-export { createRouteMap } from "./create-route-map.js";
 export { createRouteMapFromTree } from "./create-route-map-from-tree.js";
 // The helpers of a route lookup. matchesPattern stays private inside find-route.ts
 export { findRouteById, findRouteByPath } from "./find-route.js";
@@ -36,4 +27,7 @@ export { findRouteById, findRouteByPath } from "./find-route.js";
 // entry. It names `asCleanup` nowhere: a consumer of this package RECEIVES a
 // release, and builds one only with @xmachines/play itself.
 export { DISPOSE } from "@xmachines/play";
+// The tree builder and its options. `@xmachines/play-router/xstate` reads both: it walks
+// a machine, and it hands the routes here to become a tree and then a route map.
+export { buildRouteTree, ROOT_NODE_ID } from "./build-tree.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,wHAAwH;AACxH,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,sBAAsB;AACtB,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,mFAAmF;AACnF,gFAAgF;AAChF,sFAAsF;AACtF,mBAAmB;AACnB,OAAO,EACN,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,GACZ,MAAM,gBAAgB,CAAC;AAExB,kFAAkF;AAClF,uFAAuF;AACvF,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,GAEtB,MAAM,uBAAuB,CAAC;AAE/B,qFAAqF;AACrF,sFAAsF;AACtF,gFAAgF;AAChF,OAAO,EACN,iBAAiB,EACjB,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,yBAAyB,CAAC;AAQjC,qFAAqF;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoBvD,8DAA8D;AAC9D,qFAAqF;AACrF,qBAAqB;AACrB,OAAO,EAAE,QAAQ,EAAqB,MAAM,qBAAqB,CAAC;AAOlE,kFAAkF;AAClF,iFAAiF;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,mFAAmF;AACnF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEjE,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,wHAAwH;AACxH,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,sBAAsB;AACtB,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,mFAAmF;AACnF,gFAAgF;AAChF,sFAAsF;AACtF,mBAAmB;AACnB,OAAO,EACN,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,GACZ,MAAM,qBAAqB,CAAC;AAE7B,kFAAkF;AAClF,uFAAuF;AACvF,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,qFAAqF;AACrF,sFAAsF;AACtF,gFAAgF;AAChF,OAAO,EACN,iBAAiB,EACjB,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,yBAAyB,CAAC;AAyBjC,8DAA8D;AAC9D,OAAO,EAAE,QAAQ,EAAqB,MAAM,qBAAqB,CAAC;AAElE,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,mFAAmF;AACnF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEjE,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,yFAAyF;AACzF,iFAAiF;AACjF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/provider-lifecycle.d.ts

@@ -17,9 +17,9 @@
  *
  * @see [Multi-router integration](../../docs/examples/multi-router-integration.md)
  */
+import { type BasePathOptions } from "@xmachines/play-url";
 import { DISPOSE } from "@xmachines/play";
-import { type BasePathOptions } from "./base-path.js";
-import type { MountableRouterBridge, PlayActor, RouterBridge } from "./types.js";
+import type { MountableRouterBridge, RoutableActor, RouterBridge } from "./types.js";
 import type { RouteMap } from "./base-route-map.js";
 /**
  * The props that every `PlayRouterProvider` of a framework shares.
@@ -31,7 +31,7 @@ import type { RouteMap } from "./base-route-map.js";
  * An adapter re-exports a two-parameter alias of this type, with `TRouter` bound to
  * the type of its router instance and `TNode` bound to its own node type.
  */
-export interface PlayRouterProviderBaseProps<TRouter, TActor extends PlayActor, TNode> {
+export interface PlayRouterProviderBaseProps<TRouter, TActor extends RoutableActor, TNode> {
     /**
      * The actor to keep in step with the router. It must be a stable reference: give
      * the same actor instance on every render. An actor in the JSX, or a new actor on
@@ -91,13 +91,17 @@ export interface PlayRouterProviderBaseProps<TRouter, TActor extends PlayActor,
 /**
  * The constructor shape that a bridge class must satisfy for a provider factory: `(router, actor, routeMap, options?) → RouterBridge`.
  *
+ * `TActor` carries the actor type of the caller through to the constructor, so the spec
+ * type of that actor reaches the bridge whole. A bridge that reads no spec binds nothing
+ * and receives the default.
+ *
  * The return type is `RouterBridge`, the published contract of a bridge, so a
  * consumer bridge of its own keeps compiling. Every bridge on `RouterBridgeBase` also
  * satisfies `MountableRouterBridge`, and the provider finds that mount API at run
  * time: a bridge without it ignores `basePath`, exactly as it did before the option
  * existed.
  */
-export type PlayRouterBridgeConstructor<TRouter> = new (router: TRouter, actor: PlayActor, routeMap: RouteMap, options?: BasePathOptions) => RouterBridge;
+export type PlayRouterBridgeConstructor<TRouter, TActor extends RoutableActor = RoutableActor> = new (router: TRouter, actor: TActor, routeMap: RouteMap, options?: BasePathOptions) => RouterBridge;
 /**
  * Tells you whether a bridge can move its mount.
  *
@@ -118,7 +122,7 @@ export declare function isMountableBridge(bridge: RouterBridge | null | undefine
  */
 export declare function mountKey(basePath?: BasePathOptions["basePath"], basePathParams?: BasePathOptions["basePathParams"]): string;
 /** What {@link openProviderBridge} needs to build and connect a bridge. */
-export interface OpenProviderBridgeArgs<TRouter, TActor extends PlayActor> extends BasePathOptions {
+export interface OpenProviderBridgeArgs<TRouter, TActor extends RoutableActor> extends BasePathOptions {
     router: TRouter;
     actor: TActor;
     routeMap: RouteMap;
@@ -133,7 +137,7 @@ export interface OpenProviderBridgeArgs<TRouter, TActor extends PlayActor> exten
  *
  * @returns The bridge, and a `close` that disconnects it one time.
  */
-export declare function openProviderBridge<TRouter, TActor extends PlayActor>(BridgeCtor: PlayRouterBridgeConstructor<TRouter>, { router, actor, routeMap, basePath, basePathParams }: OpenProviderBridgeArgs<TRouter, TActor>): {
+export declare function openProviderBridge<TRouter, TActor extends RoutableActor>(BridgeCtor: PlayRouterBridgeConstructor<TRouter, TActor>, { router, actor, routeMap, basePath, basePathParams }: OpenProviderBridgeArgs<TRouter, TActor>): {
     bridge: RouterBridge;
     close: () => void;
 };