@xmachines/play-router 2.1.0 → 2.2.0

package/dist/errors.js

@@ -153,13 +153,20 @@ export class UnknownStateTypeError extends PlayError {
     }
 }
 /**
- * The `RouteMap` constructor 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.
+ * 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`
  *
@@ -179,10 +186,96 @@ export class UnknownStateTypeError extends PlayError {
 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) {
-        super("RouteMap", "PLAY_ROUTE_MAP_INVALID_PATTERN", `Invalid route pattern: "${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":"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"}

package/dist/framework-params.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The params of a framework router, reconciled with the pattern of the machine.
+ *
+ * A framework that parses the params itself — Vue Router and SolidJS Router both do —
+ * lets a bridge keep that parse instead of running URLPattern again. The decision that
+ * makes it safe is the same in each of them, and the source of the params is the one
+ * thing that differs, so the decision lives here and each bridge supplies its source.
+ *
+ * @see [Multi-router integration](../../docs/examples/multi-router-integration.md)
+ */
+/**
+ * Reads the names of every `:param` of a route pattern of the route map.
+ *
+ * @param pattern - A route pattern, for example `/profile/:userId`.
+ * @returns The names, in the order that the pattern declares them. A fresh array, because
+ *   `readPatternParams` caches the one it holds.
+ */
+export declare function getPatternParamNames(pattern: string): string[];
+/**
+ * The names of every param the pattern REQUIRES, so `:name?` is left out.
+ *
+ * An optional segment that did not match has no value, and a framework reports none.
+ * That is a complete answer and not a partial one, so a MIXED pattern such as
+ * `/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
+ * A caller that counted that absence as a gap would fall back to the URLPattern
+ * extraction, which THROWS on a runtime with no URLPattern — for a route the framework
+ * had already answered.
+ *
+ * A pattern whose params are ALL optional reports nothing at all, which reads the same
+ * as "the framework matched another route", so {@link pickOwnParams} falls back for it.
+ * {@link resolveFrameworkParams} settles that case from the PATH instead, and it needs
+ * no URLPattern to do it.
+ *
+ * @param pattern - A route pattern, for example `/profile/:userId/:tab?`.
+ * @returns The required names, in the order that the pattern declares them. A fresh
+ *   array, because `readPatternParams` caches the one it holds.
+ */
+export declare function getRequiredPatternParamNames(pattern: string): string[];
+/**
+ * Keeps the entries of `params` whose name the pattern of the machine declares, and
+ * only when the result covers EVERY name of that pattern.
+ *
+ * A complete pick is an answer, and a partial pick is not: a wrapper route of the host
+ * can declare a subset of the params of the machine — a tenant segment, for example,
+ * but not the document one — and keeping that subset drops the rest from a route that
+ * declares them. The caller falls back to its own extraction for `null`.
+ *
+ * The result has a null prototype, so a param named `__proto__` stays an own key.
+ *
+ * An OPTIONAL name of the pattern (`:name?`) is covered whether the framework reports
+ * it or not: a segment that did not match has no value, and that is a complete answer.
+ * At least one declared name must come back, though — a framework that reports none
+ * matched another route, and the path may still hold a value that only the fallback
+ * reads. A pattern whose params are ALL optional therefore always answers `null` here
+ * when the framework reports nothing; {@link resolveFrameworkParams} then reads the PATH,
+ * which settles the question without the framework and without URLPattern.
+ *
+ * @param params - The params of the framework router. {@link cleanFrameworkParams}
+ *   removes each empty value already, and one that reaches here anyway counts as
+ *   absent: an empty value says that the segment did not match, and never that the
+ *   path carries the empty string.
+ * @param names - The names that the pattern of the machine declares.
+ * @param requiredNames - The names the pattern REQUIRES. The default treats every name
+ *   as required, so a two-argument call keeps the strict test.
+ * @returns The params of the machine, or `null` when the framework covers them not.
+ */
+export declare function pickOwnParams(params: Record<string, string>, names: string[], requiredNames?: string[]): Record<string, string> | null;
+/**
+ * The params of a framework router, in the shape that {@link pickOwnParams} reads.
+ *
+ * Every framework reports a param that its own route DECLARES and that the location
+ * did not fill: Vue Router gives `undefined` or `""`, and SolidJS Router does the
+ * same. Such an entry is not an answer, and a pick that kept it would send an empty
+ * value to the actor as though the path carried one. Drop it here instead, one time,
+ * because the rule belongs to the decision of {@link resolveFrameworkParams} and not
+ * to a bridge: `VueRouterBridge` and `SolidRouterBridge` held one copy each.
+ *
+ * A value of an array — the splat of a catch-all route of Vue Router — becomes its
+ * `String()` form, exactly as a single value does.
+ *
+ * The result has a null prototype, for the same reason {@link pickOwnParams} gives: a
+ * plain `{}` accumulator turns `cleaned["__proto__"] = value` into a write of the
+ * PROTOTYPE setter, which drops a string value in silence. `pickOwnParams` then read
+ * `Object.hasOwn(params, "__proto__")` as `false`, called the pick incomplete, and fell
+ * back to the URLPattern extraction — which THROWS on a runtime with no URLPattern, for
+ * a route the framework had answered already.
+ *
+ * @param params - The raw params of the framework router.
+ * @returns The params with no absent value, each one a string.
+ */
+export declare function cleanFrameworkParams(params: Record<string, unknown>): Record<string, string>;
+/** What {@link resolveFrameworkParams} needs from the bridge that calls it. */
+export interface FrameworkParamsSource {
+    /** The route pattern of the match, from `routeMap.getPathByStateId`. */
+    pattern: string | null | undefined;
+    /** The resolved prefix of the mount. `""` means that the machine owns the router. */
+    basePath: string;
+    /**
+     * The machine-side path of the location, with the mount prefix already removed.
+     *
+     * The field is OPTIONAL, so a caller that was written before it keeps its behaviour:
+     * the one branch that reads it falls back without it, exactly as it did.
+     */
+    pathname?: string;
+    /** The params of the framework router, read lazily and cleaned of empty values. */
+    frameworkParams(): Record<string, string>;
+    /** The URLPattern extraction of the base class, read lazily. */
+    fallback(): Record<string, string>;
+}
+/**
+ * Decides which params describe the route of the machine.
+ *
+ * The three branches, in the order that they apply:
+ *
+ * - **The pattern declares no name** — a static path, a bare `*` wildcard, or an
+ *   unknown stateId. The answer is `{}`. The params of the framework must NOT travel
+ *   here: under a catch-all they hold the splat of the host, and that value would reach
+ *   the actor as a param of the machine. This branch also reaches no URLPattern, which
+ *   matters: the extraction needs the constructor even for a pattern with no parameter,
+ *   so a delegation would throw on a runtime without the API.
+ * - **The bridge sits under a mount** — the framework matched a route of the HOST by
+ *   construction, because the machine owns the suffix of the path only. Its params
+ *   therefore describe this pattern never, whatever they are named, and a name that
+ *   happens to collide carries the value of the host. Read the params of the machine
+ *   from its own pattern instead.
+ * - **The framework covers every REQUIRED name** — it matched the machine route. Keep
+ *   its parse, together with its decoding. An optional `:name?` that the framework
+ *   reports not is covered too: a segment that did not match has no value. A gap in a
+ *   required name falls back, because keeping it would drop a name the route declares.
+ * - **The path IS the bare form of the pattern** — every optional segment is absent, so
+ *   `{}` is the complete answer. The branch reads the path and trusts the framework with
+ *   nothing, which is what makes it safe under a catch-all of the host, and it calls
+ *   URLPattern for a location that needs none.
+ *
+ * None of this decides whether the APPLICATION needs a URLPattern polyfill. A `RouteMap`
+ * that holds one parameterized route compiles it in the CONSTRUCTOR, and it throws a
+ * `URLPatternUnavailableError` there when the runtime has no URLPattern. The polyfill
+ * question is therefore settled at startup: only a route map of static paths alone
+ * escapes it. What these branches decide is whether a NAVIGATION calls URLPattern again.
+ *
+ * @returns The path parameters of the machine route, or `{}`.
+ */
+export declare function resolveFrameworkParams({ pattern, basePath, pathname, frameworkParams, fallback, }: FrameworkParamsSource): Record<string, string>;
+//# sourceMappingURL=framework-params.d.ts.map

package/dist/framework-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-params.d.ts","sourceRoot":"","sources":["../src/framework-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9D;AAqCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,KAAK,EAAE,MAAM,EAAE,EACf,aAAa,GAAE,MAAM,EAAU,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAoC/B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc5F;AAkDD,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACrC,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,gEAAgE;IAChE,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,sBAAsB,CAAC,EACtC,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,QAAQ,GACR,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBhD"}

package/dist/framework-params.js

@@ -0,0 +1,291 @@
+/**
+ * The params of a framework router, reconciled with the pattern of the machine.
+ *
+ * A framework that parses the params itself — Vue Router and SolidJS Router both do —
+ * lets a bridge keep that parse instead of running URLPattern again. The decision that
+ * makes it safe is the same in each of them, and the source of the params is the one
+ * thing that differs, so the decision lives here and each bridge supplies its source.
+ *
+ * @see [Multi-router integration](../../docs/examples/multi-router-integration.md)
+ */
+/**
+ * The expression reads each NAMED parameter of a route pattern of the route map, for
+ * example `userId` of `/profile/:userId`, `section` of `/settings/:section?`, and
+ * `cat-id` of `/docs/:cat-id`. A `*` wildcard carries no name, and the expression
+ * therefore matches it not.
+ */
+const PATTERN_PARAM_NAME_RE = /:([A-Za-z_$][A-Za-z0-9_$-]*)(\?)?/g;
+/**
+ * Reads the names of every `:param` of a route pattern of the route map.
+ *
+ * @param pattern - A route pattern, for example `/profile/:userId`.
+ * @returns The names, in the order that the pattern declares them. A fresh array, because
+ *   `readPatternParams` caches the one it holds.
+ */
+export function getPatternParamNames(pattern) {
+    return [...readPatternParams(pattern).names];
+}
+/**
+ * The names of each pattern that this module has read, kept at the module level.
+ *
+ * {@link resolveFrameworkParams} runs on EVERY navigation, and the answer for one
+ * pattern never changes: a pattern is a static string of the route map. The number of
+ * the route patterns of the application therefore bounds this cache, exactly as it
+ * bounds the compiled-pattern cache of `url-pattern-utils.ts`.
+ */
+const patternParamCache = new Map();
+/**
+ * Reads the declared names and the REQUIRED names of a pattern in ONE scan.
+ *
+ * {@link resolveFrameworkParams} needs both lists for every navigation, and two calls
+ * walked the pattern two times and allocated two match arrays for one answer. The two
+ * exported readers stay, because each one names what a caller asks for.
+ *
+ * The result is CACHED, and each caller therefore treats the two arrays as read-only.
+ */
+function readPatternParams(pattern) {
+    const cached = patternParamCache.get(pattern);
+    if (cached)
+        return cached;
+    const names = [];
+    const required = [];
+    for (const match of pattern.matchAll(PATTERN_PARAM_NAME_RE)) {
+        const name = match[1] ?? "";
+        names.push(name);
+        if (match[2] === undefined)
+            required.push(name);
+    }
+    const read = { names, required };
+    patternParamCache.set(pattern, read);
+    return read;
+}
+/**
+ * The names of every param the pattern REQUIRES, so `:name?` is left out.
+ *
+ * An optional segment that did not match has no value, and a framework reports none.
+ * That is a complete answer and not a partial one, so a MIXED pattern such as
+ * `/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
+ * A caller that counted that absence as a gap would fall back to the URLPattern
+ * extraction, which THROWS on a runtime with no URLPattern — for a route the framework
+ * had already answered.
+ *
+ * A pattern whose params are ALL optional reports nothing at all, which reads the same
+ * as "the framework matched another route", so {@link pickOwnParams} falls back for it.
+ * {@link resolveFrameworkParams} settles that case from the PATH instead, and it needs
+ * no URLPattern to do it.
+ *
+ * @param pattern - A route pattern, for example `/profile/:userId/:tab?`.
+ * @returns The required names, in the order that the pattern declares them. A fresh
+ *   array, because `readPatternParams` caches the one it holds.
+ */
+export function getRequiredPatternParamNames(pattern) {
+    return [...readPatternParams(pattern).required];
+}
+/**
+ * Keeps the entries of `params` whose name the pattern of the machine declares, and
+ * only when the result covers EVERY name of that pattern.
+ *
+ * A complete pick is an answer, and a partial pick is not: a wrapper route of the host
+ * can declare a subset of the params of the machine — a tenant segment, for example,
+ * but not the document one — and keeping that subset drops the rest from a route that
+ * declares them. The caller falls back to its own extraction for `null`.
+ *
+ * The result has a null prototype, so a param named `__proto__` stays an own key.
+ *
+ * An OPTIONAL name of the pattern (`:name?`) is covered whether the framework reports
+ * it or not: a segment that did not match has no value, and that is a complete answer.
+ * At least one declared name must come back, though — a framework that reports none
+ * matched another route, and the path may still hold a value that only the fallback
+ * reads. A pattern whose params are ALL optional therefore always answers `null` here
+ * when the framework reports nothing; {@link resolveFrameworkParams} then reads the PATH,
+ * which settles the question without the framework and without URLPattern.
+ *
+ * @param params - The params of the framework router. {@link cleanFrameworkParams}
+ *   removes each empty value already, and one that reaches here anyway counts as
+ *   absent: an empty value says that the segment did not match, and never that the
+ *   path carries the empty string.
+ * @param names - The names that the pattern of the machine declares.
+ * @param requiredNames - The names the pattern REQUIRES. The default treats every name
+ *   as required, so a two-argument call keeps the strict test.
+ * @returns The params of the machine, or `null` when the framework covers them not.
+ */
+export function pickOwnParams(params, names, requiredNames = names) {
+    const required = new Set(requiredNames);
+    const picked = Object.create(null);
+    for (const name of names) {
+        // `Object.hasOwn` first, and not a bare read: this function is exported, so a
+        // caller can hand it a plain object, and `params["constructor"]` then walks the
+        // prototype chain and answers with a function for a name that the object holds not.
+        const value = Object.hasOwn(params, name)
+            ? params[name] // nosemgrep: gitlab.eslint.detect-object-injection
+            : undefined;
+        // An ABSENT value, and an empty one: {@link cleanFrameworkParams} drops both
+        // already, and this function is exported, so a caller of its own reaches here with
+        // either. A `?? ""` fallback wrote the empty value into the pick instead — the
+        // exact value that cleaning exists to remove — and that entry then counted as "the
+        // framework matched this route", so the pick won over the fallback that reads the
+        // value the PATH carries.
+        if (value === undefined || value === null || value === "") {
+            if (required.has(name))
+                return null;
+            continue;
+        }
+        picked[name] = value; // nosemgrep: gitlab.eslint.detect-object-injection
+    }
+    // NONE of the declared names came back, so the framework matched another route — a
+    // catch-all, in practice — and it knows nothing about this pattern. An empty pick
+    // would then drop a value the PATH carries: `/settings/security` against
+    // `/settings/:section?` holds "security", and only the fallback reads it. One name
+    // present is what says the framework matched this route, and an optional segment that
+    // did not match is genuinely absent.
+    if (names.length > 0 && Object.keys(picked).length === 0)
+        return null;
+    // Spread at the boundary: `event.params` reaches a machine of the user, and it was a
+    // plain object before this release. A spread creates OWN properties, so a param named
+    // "__proto__" stays a key while the value keeps a prototype — `hasOwnProperty` on it
+    // therefore answers instead of throwing.
+    return { ...picked };
+}
+/**
+ * The params of a framework router, in the shape that {@link pickOwnParams} reads.
+ *
+ * Every framework reports a param that its own route DECLARES and that the location
+ * did not fill: Vue Router gives `undefined` or `""`, and SolidJS Router does the
+ * same. Such an entry is not an answer, and a pick that kept it would send an empty
+ * value to the actor as though the path carried one. Drop it here instead, one time,
+ * because the rule belongs to the decision of {@link resolveFrameworkParams} and not
+ * to a bridge: `VueRouterBridge` and `SolidRouterBridge` held one copy each.
+ *
+ * A value of an array — the splat of a catch-all route of Vue Router — becomes its
+ * `String()` form, exactly as a single value does.
+ *
+ * The result has a null prototype, for the same reason {@link pickOwnParams} gives: a
+ * plain `{}` accumulator turns `cleaned["__proto__"] = value` into a write of the
+ * PROTOTYPE setter, which drops a string value in silence. `pickOwnParams` then read
+ * `Object.hasOwn(params, "__proto__")` as `false`, called the pick incomplete, and fell
+ * back to the URLPattern extraction — which THROWS on a runtime with no URLPattern, for
+ * a route the framework had answered already.
+ *
+ * @param params - The raw params of the framework router.
+ * @returns The params with no absent value, each one a string.
+ */
+export function cleanFrameworkParams(params) {
+    const cleaned = Object.create(null);
+    for (const [name, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        // The test runs on the STRING, and not on the raw value: a repeatable segment that
+        // the location did not fill comes back as an EMPTY ARRAY from Vue Router, and `[]`
+        // is not `""`. A raw test therefore let it through as `String([])`, which is the
+        // empty value this function exists to drop — `pickOwnParams` then picked it and the
+        // actor received `{ section: "" }` as though the path carried a value.
+        const text = String(value);
+        if (text === "")
+            continue;
+        cleaned[name] = text; // nosemgrep: gitlab.eslint.detect-object-injection
+    }
+    return cleaned;
+}
+/** A segment that is exactly one optional param, for example `:section?`. */
+const OPTIONAL_SEGMENT_RE = /^:[A-Za-z_$][A-Za-z0-9_$-]*\?$/;
+/**
+ * True when the path IS the pattern with every optional segment absent.
+ *
+ * The test reads the PATH, and it trusts the framework with nothing. A pattern whose
+ * trailing segments are all optional has a bare form that holds no `:` and no `*` —
+ * `/settings/:section?` has the bare form `/settings` — and a path that equals that
+ * form can only match the pattern with every optional group absent. No param has a
+ * value, so `{}` is the complete answer whatever route the framework matched, and the
+ * URLPattern fallback has nothing to add.
+ *
+ * The function answers `false` for anything it cannot prove:
+ *
+ * - An optional segment that is NOT trailing. `/a/:b?/c` matches `/a//c` for URLPattern,
+ *   because the `/` before the group is a literal of its own, so `/a/c` is no bare form.
+ * - A remaining segment that holds a `:` or a `*`. A required param has a value that
+ *   only the fallback reads, and a wildcard matches a path of any length.
+ *
+ * @param pathname - The machine-side path, with the mount prefix already removed.
+ * @param pattern - The route pattern of the machine.
+ */
+function pathIsBareForm(pathname, pattern) {
+    const segments = pattern.split("/");
+    let end = segments.length;
+    while (end > 0 && OPTIONAL_SEGMENT_RE.test(segments.at(end - 1) ?? ""))
+        end -= 1;
+    // Nothing was optional at the end, so the pattern needs a value somewhere.
+    if (end === segments.length)
+        return false;
+    const kept = segments.slice(0, end);
+    if (kept.some((segment) => segment.includes(":") || segment.includes("*")))
+        return false;
+    return trimPath(kept.join("/")) === trimPath(pathname);
+}
+/**
+ * One comparable form for a path: no query, no fragment, and no trailing slash.
+ *
+ * The root stays `"/"`, because a bare pattern of `/:section?` has the bare form `""`
+ * and the path of that page is `"/"`.
+ */
+function trimPath(path) {
+    const cut = path.split(/[?#]/)[0] ?? "";
+    const trimmed = cut.length > 1 && cut.endsWith("/") ? cut.slice(0, -1) : cut;
+    return trimmed === "" ? "/" : trimmed;
+}
+/**
+ * Decides which params describe the route of the machine.
+ *
+ * The three branches, in the order that they apply:
+ *
+ * - **The pattern declares no name** — a static path, a bare `*` wildcard, or an
+ *   unknown stateId. The answer is `{}`. The params of the framework must NOT travel
+ *   here: under a catch-all they hold the splat of the host, and that value would reach
+ *   the actor as a param of the machine. This branch also reaches no URLPattern, which
+ *   matters: the extraction needs the constructor even for a pattern with no parameter,
+ *   so a delegation would throw on a runtime without the API.
+ * - **The bridge sits under a mount** — the framework matched a route of the HOST by
+ *   construction, because the machine owns the suffix of the path only. Its params
+ *   therefore describe this pattern never, whatever they are named, and a name that
+ *   happens to collide carries the value of the host. Read the params of the machine
+ *   from its own pattern instead.
+ * - **The framework covers every REQUIRED name** — it matched the machine route. Keep
+ *   its parse, together with its decoding. An optional `:name?` that the framework
+ *   reports not is covered too: a segment that did not match has no value. A gap in a
+ *   required name falls back, because keeping it would drop a name the route declares.
+ * - **The path IS the bare form of the pattern** — every optional segment is absent, so
+ *   `{}` is the complete answer. The branch reads the path and trusts the framework with
+ *   nothing, which is what makes it safe under a catch-all of the host, and it calls
+ *   URLPattern for a location that needs none.
+ *
+ * None of this decides whether the APPLICATION needs a URLPattern polyfill. A `RouteMap`
+ * that holds one parameterized route compiles it in the CONSTRUCTOR, and it throws a
+ * `URLPatternUnavailableError` there when the runtime has no URLPattern. The polyfill
+ * question is therefore settled at startup: only a route map of static paths alone
+ * escapes it. What these branches decide is whether a NAVIGATION calls URLPattern again.
+ *
+ * @returns The path parameters of the machine route, or `{}`.
+ */
+export function resolveFrameworkParams({ pattern, basePath, pathname, frameworkParams, fallback, }) {
+    if (!pattern)
+        return {};
+    // One scan of the pattern, for both lists: this runs on every navigation.
+    const { names, required } = readPatternParams(pattern);
+    if (names.length === 0)
+        return {};
+    if (basePath !== "")
+        return fallback();
+    const picked = pickOwnParams(frameworkParams(), names, required);
+    if (picked !== null)
+        return picked;
+    // The framework reported none of the names. That is ambiguous on its own — it means
+    // "the segment is absent" or "another route matched" — and the PATH settles it
+    // without the framework and without URLPattern: a path that is the bare form of the
+    // pattern fills no optional segment, so `{}` is the complete answer.
+    //
+    // Only an all-optional pattern reaches this: `pathIsBareForm` refuses a bare form
+    // that still holds a `:`, so a missing REQUIRED name still falls back.
+    if (pathname !== undefined && pathIsBareForm(pathname, pattern))
+        return {};
+    return fallback();
+}
+//# sourceMappingURL=framework-params.js.map

package/dist/framework-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-params.js","sourceRoot":"","sources":["../src/framework-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,oCAAoC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IACnD,OAAO,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAmD,CAAC;AAErF;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,OAAe;IACzC,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACjC,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAe;IAC3D,OAAO,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,aAAa,CAC5B,MAA8B,EAC9B,KAAe,EACf,gBAA0B,KAAK;IAE/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IACxC,MAAM,MAAM,GAA2B,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IACrF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,8EAA8E;QAC9E,gFAAgF;QAChF,oFAAoF;QACpF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;YACxC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,mDAAmD;YAClE,CAAC,CAAC,SAAS,CAAC;QACb,6EAA6E;QAC7E,mFAAmF;QACnF,+EAA+E;QAC/E,mFAAmF;QACnF,kFAAkF;QAClF,0BAA0B;QAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YAC3D,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACpC,SAAS;QACV,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,mDAAmD;IAC1E,CAAC;IAED,mFAAmF;IACnF,kFAAkF;IAClF,yEAAyE;IACzE,mFAAmF;IACnF,sFAAsF;IACtF,qCAAqC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtE,qFAAqF;IACrF,sFAAsF;IACtF,qFAAqF;IACrF,yCAAyC;IACzC,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA+B;IACnE,MAAM,OAAO,GAA2B,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;IACtF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,mFAAmF;QACnF,mFAAmF;QACnF,iFAAiF;QACjF,oFAAoF;QACpF,uEAAuE;QACvE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,mDAAmD;IAC1E,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,6EAA6E;AAC7E,MAAM,mBAAmB,GAAG,gCAAgC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,cAAc,CAAC,QAAgB,EAAE,OAAe;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC1B,OAAO,GAAG,GAAG,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,GAAG,IAAI,CAAC,CAAC;IACjF,2EAA2E;IAC3E,IAAI,GAAG,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAE1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzF,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC7E,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACvC,CAAC;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,sBAAsB,CAAC,EACtC,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,QAAQ,GACe;IACvB,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,0EAA0E;IAC1E,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,EAAE,CAAC;IAEvC,MAAM,MAAM,GAAG,aAAa,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACjE,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAEnC,oFAAoF;IACpF,+EAA+E;IAC/E,oFAAoF;IACpF,qEAAqE;IACrE,EAAE;IACF,kFAAkF;IAClF,uEAAuE;IACvE,IAAI,QAAQ,KAAK,SAAS,IAAI,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAE3E,OAAO,QAAQ,EAAE,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -7,10 +7,15 @@ export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from
 export type { ResolvedRoutePath } from "./validate-routes.js";
 export { buildRouteTree } from "./build-tree.js";
 export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists, getTransitionReachableRoutes, isRouteReachable, } from "./query.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 { 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, MachineNodeData, MachineEdgeData, WindowLike, LocationLike, } from "./types.js";
+export type { RouteInfo, RouteNode, RouteTree, RouteObject, RouteMetadata, PlayRouteEvent, RoutableActor, PlayActor, RouterBridge, MountableRouterBridge, MachineNodeData, MachineEdgeData, 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.

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,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAGpB,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,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"}
+{"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"}

package/dist/index.js

@@ -6,7 +6,19 @@ export { sanitizePathname, buildPlayRouteEvent, extractQuery, extractRouteParams
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
 export { buildRouteTree } from "./build-tree.js";
 export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists, getTransitionReachableRoutes, isRouteReachable, } from "./query.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";
+// 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";
+// 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.

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,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,qFAAqF;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAmBvD,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"}
+{"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"}