@xmachines/play-router 2.1.0 → 2.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.1.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-2.2.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.
 
@@ -36,6 +36,8 @@ pnpm add urlpattern-polyfill
 
 `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.
 
+**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.
+
 ## Usage
 
 ### Extract routes from a machine
@@ -123,6 +125,209 @@ actor.send({
 });
 ```
 
+### Sharing a router with the host (`basePath`)
+
+A machine owns the complete URL space of its router by default. Give a `basePath`,
+and it owns a prefix only: the host keeps the rest of the same router.
+
+The shape that motivates this option is a URL such as `/:machineId/play/dashboard`.
+The host resolves `:machineId` — in a loader of TanStack, in a `useParams()` call, in
+a `load` function of SvelteKit — and the `meta.route` tree of the machine gives
+everything below `/:machineId/play`.
+
+```typescript
+// The route of the host is /$machineId/play/$ and its loader resolved machineId.
+const disconnect = connectRouter({
+	actor,
+	router,
+	routeMap, // unchanged — the route map stays relative to the machine
+	basePath: "/:machineId/play",
+	basePathParams: { machineId },
+});
+
+// The "/dashboard" of the machine is now the URL "/abc123/play/dashboard".
+// The "/"          of the machine is now the URL "/abc123/play".
+```
+
+The prefix can be a pattern, so that you keep one string that mirrors your route
+config, but every `:param` needs a value in `basePathParams`. The bridge writes a
+real browser URL, so it resolves the prefix in advance, and it refuses each shape
+that resolves to one concrete path never: a `*` wildcard, a `:param?`, a `$param`
+(the spelling of TanStack — write `:param`), a query string, and a hash. A base path
+is a PATHNAME, so it also refuses a URL scheme: give `/admin`, and never
+`https://app.example.com/admin`.
+
+It also refuses every segment that a browser REWRITES, and it refuses the resolved
+value of a `:param` on the same rule: a dot segment (`.`, `..`, and their
+percent-encoded forms), a backslash, whitespace, and a character that a URL
+percent-encodes, such as the `é` of `/café`. Each of them makes the prefix that comes
+back differ from the prefix that went out, so every location would read as foreign
+and the machine would go permanently silent. Give the segment in the form that a URL
+carries: `/caf%C3%A9`.
+
+**An unresolved `:param` throws** a `MissingBasePathParamError`, at the construction
+and not on the first navigation. There is no "not ready yet" fallback, on purpose: a
+bridge without a prefix would claim the complete router, and it would start to
+correct the URLs of the host, which is worse than a loud failure. Resolve the value
+before you connect or render — a route loader or a `useParams()` call holds it
+already.
+
+**A location outside the prefix belongs to the host.** The bridge sends no
+`play.route` event there, it runs no corrective navigation there, and it writes no
+route of its actor there. That silence lets the two halves live together, and it holds
+in both directions: a route change that no URL event caused — an `after` timer, an
+async guard that settles, a restore of a snapshot — would otherwise drag the user off
+the page of the host. The bridge remembers such a move, and it writes it when the
+location comes back under the prefix, so the machine keeps its place. Inside the mount
+nothing changes: a path that the machine does not know is still a 404 of its own URL
+space, and the URL still follows the actor.
+
+| Location of the router | `basePath = "/abc123/play"`                           |
+| ---------------------- | ----------------------------------------------------- |
+| `/abc123/play`         | the `/` of the machine → `play.route`                 |
+| `/abc123/play/about`   | the `/about` of the machine → `play.route`            |
+| `/abc123/play/nope`    | unknown INSIDE the mount → the URL follows the actor  |
+| `/account/billing`     | a route of the host → the bridge does nothing         |
+| `/abc123/playground`   | another segment → the host's, the bridge does nothing |
+
+**The machine is authoritative over its own params.** `event.params` holds what the
+pattern of the machine declares, and nothing else. The params of the prefix belong to
+the host — the host wrote the prefix and resolved them — so they travel in no
+`play.route` event, and a param of the host that happens to share a name with one of
+the machine cannot shadow it.
+
+Read the resolved mount from the bridge instead, where it cannot go stale:
+
+```typescript
+bridge.basePath; // "/abc123/play"
+bridge.basePathParams; // { machineId: "abc123" }
+```
+
+A machine that needs the identity of its host — a `machineId`, a tenant — takes it
+through the `input` of the actor, where it belongs: that identity decides WHICH
+machine runs, and it is not a param of a route inside the machine.
+
+#### Several machines alive at once
+
+More than one machine can be alive at a time, each mounted at its own prefix, all
+sharing one router. Every bridge hears every location change of that router, and each
+one recognises its own half and leaves the rest alone — a location under another
+machine's prefix is foreign in exactly the way a route of the host is. So a
+`play.route` reaches the machine that owns the URL and no other, and a correction of
+an unknown path happens only inside the prefix that owns it.
+
+**Each bridge can stay connected, as long as each one has its own prefix.** A bridge
+outside its mount keeps the silence in BOTH directions: it sends no `play.route`, it
+corrects no URL, and it writes no route of its actor. So the machine that the location
+belongs to is the only one that writes, and an actor that nobody is looking at cannot
+take the URL from the one on screen. A route that the hidden machine moved to is not
+lost: the bridge remembers it, and it writes it when the host navigates back under its
+prefix.
+
+**Two bridges contend when neither prefix separates their halves of the URL.** That is
+the case for two bridges with no prefix, for two with the same prefix, and also for two
+whose prefixes NEST: a mount at `/a` and a mount at `/a/b` both claim `/a/b/x`, because
+`/a` is a prefix of it. Give sibling prefixes — `/a/one` and `/a/two` — and no location
+belongs to two machines. Where a prefix cannot separate them, connect the bridge that
+owns the address bar and let the others keep their state with no bridge attached. `connect()` refuses a
+second bridge for one actor, but it cannot know which of two different actors should
+own the URL.
+
+#### How to load and unload routes
+
+The prefix lives on the **bridge**, and not on the `RouteMap`. A route map is static,
+it is shared, and it holds an LRU cache inside, so one map serves every mount without
+a rebuild.
+
+`setBasePath()` moves WHERE an actor is mounted, and never WHICH actor is mounted:
+
+```typescript
+// The host moved this actor from one region of its URL space to another.
+bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
+```
+
+The call also brings the location in step. Nothing else moves the address bar, so a
+move to a prefix that the URL is not under writes the new mount, and it keeps the
+route of the actor: `/eu/abc123/play/about` becomes `/us/abc123/play/about`. A location
+that already lies under the new prefix drives the actor instead, exactly as it does on
+`connect()`.
+
+**An actor never changes identity.** A segment of the prefix that IDENTIFIES the
+actor — a `machineId` that names the document it runs — therefore never moves through
+this method. A new identity is a new ACTOR, and a new actor takes a new bridge,
+because `connect()` permits one bridge for each actor. Give the provider the new actor
+and let it rebuild: that is the correct shape, and it is what the host wants, because
+the new document starts at its own state.
+
+The segments that move here are the ones that LOCATE: a region, a locale, a tenant, a
+workspace slug. They say where the same actor lives, and they decide nothing about
+it.
+
+Nothing goes away: the actor, the route map, and its cache all stay, and the bridge
+runs the same first-synchronization decision against the new prefix. A call that
+resolves to the same prefix reconciles nothing, and it still takes the new params, so
+a move between `"/abc123/play"` and `"/:machineId/play"` with `{ machineId }` keeps
+`event.params` honest. A call with no argument removes the prefix, and it gives the
+machine the complete router again.
+
+Every `PlayRouterProvider` gives `basePath` and `basePathParams` as **reactive
+props**, wired to `setBasePath()`. They need no stable reference, unlike `actor`,
+`router`, and `routeMap`, and they rebuild the bridge never:
+
+```tsx
+// A render with a new `region` moves the mount, and it rebuilds the bridge never. A
+// render with a new `machineId` gives a different `actor` prop, and THAT rebuilds the
+// bridge, which is correct: one actor takes one bridge.
+<PlayRouterProvider
+	actor={actor}
+	router={router}
+	routeMap={routeMap}
+	basePath="/:machineId/play"
+	basePathParams={{ machineId }}
+	renderer={(a) => <PlayRenderer actor={a} registry={registry} />}
+/>
+```
+
+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";
+
+const tree = extractMachineRoutes(machine);
+
+// Concrete, for a route that the host adds after a loader resolved the mount
+getRouteMappings(tree, { basePath: "/:machineId/play", basePathParams: { machineId } });
+// [{ stateId: "home", path: "/abc123/play" },
+//  { stateId: "profile", path: "/abc123/play/profile/:userId" }, ...]
+
+// The pattern, for a static route declaration of the host
+getRouteMappings(tree, { basePath: "/:machineId/play" });
+// [{ stateId: "home", path: "/:machineId/play" }, ...]
+```
+
+Each `stateId` comes from the route tree, so it carries NO `#`. A host that keys its
+route table on the target of a `play.route` event adds the `#` itself, because the
+event always carries the prefixed form.
+
+> Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` read
+> the pre-parsed route params of their framework never: under a prefix the framework
+> 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.
+>
+> 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.
+>
+> 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.
+
 ### How to write a `RouterBridgeBase` adapter
 
 Extend `RouterBridgeBase`, then implement the three abstract methods for your framework:
@@ -209,6 +414,7 @@ bridge.disconnect();
 | `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                                    |
 
@@ -222,6 +428,56 @@ bridge.disconnect();
 | `extractRouteParams(pathname, pattern)` | Reads the path parameters of a URL with URLPattern                                                            |
 | `extractQuery(search)`                  | Reads the query parameters of a URL search string                                                             |
 
+### Base Path
+
+| Export                                  | Description                                                                             |
+| --------------------------------------- | --------------------------------------------------------------------------------------- |
+| `BasePathOptions`                       | `{ basePath?, basePathParams? }` — every bridge, provider, and `connectRouter` takes it |
+| `RouterBridgeBase#basePath`             | The resolved prefix of the mount, or `""` when the machine owns the complete router     |
+| `RouterBridgeBase#basePathParams`       | The values of the `:param` segments of the mount — they travel in no `play.route` event |
+| `RouterBridgeBase#setBasePath(p, prm?)` | Moves the mount of a live bridge, with no teardown, and brings the location in step     |
+| `normalizeBasePath(basePath?)`          | Normalizes a prefix, and it keeps each `:param` segment                                 |
+| `resolveBasePath(basePath?, params?)`   | Resolves a prefix to `{ path, params }`, and it substitutes every `:param`              |
+| `stripBasePath(pathname, basePath)`     | The machine half of a location, or `null` when the location belongs to the host         |
+| `joinBasePath(basePath, path)`          | Adds a prefix to a machine path, and it keeps a query string or a hash at the end       |
+| `NO_BASE_PATH`                          | The frozen `{ path: "", params: {} }` of a bridge that takes no `basePath`              |
+
+### Framework Params
+
+A bridge whose framework parses the path params itself — Vue Router and SolidJS Router
+both do — keeps that parse instead of running URLPattern again. The decision that makes
+it safe is the same in both, so it lives here.
+
+| Export                                         | Description                                                                                                                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `resolveFrameworkParams(source)`               | Decides which params describe the route of the machine: `{}`, the parse of the framework, or the fallback                                                                                                                      |
+| `getPatternParamNames(pattern)`                | The names of every `:param` of a route pattern. A `*` wildcard carries none                                                                                                                                                    |
+| `getRequiredPatternParamNames(pattern)`        | The names the pattern REQUIRES, so an optional `:name?` is left out                                                                                                                                                            |
+| `pickOwnParams(params, names, requiredNames?)` | The params that the pattern declares, or `null` when the framework covers them not. `requiredNames` says which names may NOT be absent; it defaults to every name, so a two-argument call treats an optional `:name?` as a gap |
+| `cleanFrameworkParams(params)`                 | The params of a framework with no absent value, each one a string                                                                                                                                                              |
+
+### Provider Lifecycle
+
+A `PlayRouterProvider` of a framework is two things: the lifecycle of a bridge, and
+about fifteen lines that bind that lifecycle to the effects of the framework. This
+package holds the lifecycle, and it holds every decision in it. An adapter keeps its
+own effects and nothing else.
+
+| Export                                                | Description                                                                                 |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `PlayRouterProviderBaseProps<TRouter, TActor, TNode>` | The documented props. `TNode` is what the framework renders                                 |
+| `PlayRouterBridgeConstructor<TRouter>`                | The constructor shape a bridge class must satisfy                                           |
+| `openProviderBridge(BridgeCtor, args)`                | Builds the bridge, connects it, and returns it with a `close`                               |
+| `repointProviderBridge(bridge, basePath, params?)`    | Moves the mount of a live bridge. A `null` bridge and a bridge with no mount API are no-ops |
+| `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                      |
+
+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
+props that a framework decides, which is why it is a type parameter.
+
 ### Validation
 
 | Export                                   | Description                                          |
@@ -235,6 +491,7 @@ bridge.disconnect();
 | 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                                                                             |
@@ -249,16 +506,18 @@ bridge.disconnect();
 
 ### 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`        | The URLPattern constructor refuses a route pattern string               |
-| `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 |
+| 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`                                                     |
 
 ```typescript
 import {

package/dist/base-path.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The base-path support — it mounts the routes of a machine under a URL prefix.
+ *
+ * A host application often owns a part of its own URL space, and it wants a machine
+ * to own the rest of that space, inside the SAME router. A URL such as
+ * `/:machineId/play/dashboard` has two halves: `/:machineId/play` belongs to the
+ * host, which resolves `:machineId` in a loader, and `/dashboard` belongs to the
+ * `meta.route` tree of the machine.
+ *
+ * This module is the boundary between those two halves:
+ * - {@link resolveBasePath} makes the concrete prefix that the browser URL carries,
+ *   from a base-path pattern and its params.
+ * - {@link stripBasePath} removes that prefix from an inbound location of the router,
+ *   and it reports a location OUTSIDE the prefix as foreign, so that the bridge stays
+ *   out of it.
+ * - {@link joinBasePath} adds the prefix again to an outbound path of the machine.
+ *
+ * The prefix lives on the BRIDGE, and not on the `RouteMap`. A route map is static,
+ * it is shared, and it holds an LRU cache inside, while a mount point is dynamic. One
+ * route map therefore serves every `machineId` without a rebuild.
+ *
+ * @internal The package exports these primitives for an adapter and for a host, but
+ * a consumer normally uses the `basePath` option of a bridge instead.
+ */
+/**
+ * The base-path options that every router bridge, `connectRouter` function, and
+ * `PlayRouterProvider` component accepts.
+ *
+ * @example
+ * ```typescript
+ * // A host that mounts a machine under a route it resolved in a loader
+ * connectRouter({
+ *   actor,
+ *   router,
+ *   routeMap,
+ *   basePath: "/:machineId/play",
+ *   basePathParams: { machineId },
+ * });
+ * ```
+ */
+export interface BasePathOptions {
+    /**
+     * The URL prefix that the routes of the machine hang off, for example `"/admin"`
+     * or `"/:machineId/play"`.
+     *
+     * A `:param` segment is a declarative convenience, so that a host keeps ONE string
+     * that mirrors its own route config. Every `:param` must have a value in
+     * {@link BasePathOptions.basePathParams}, because the bridge writes a real URL. An
+     * optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither
+     * of them resolves to one concrete prefix.
+     *
+     * An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of
+     * every release before this option existed.
+     */
+    readonly basePath?: string | undefined;
+    /**
+     * The values of the `:param` segments of {@link BasePathOptions.basePath}.
+     *
+     * These values belong to the HOST, which wrote the prefix and resolved them, so
+     * they travel in NO `play.route` event: the machine is authoritative over its own
+     * params, and `event.params` holds what the pattern of the machine declares, and
+     * nothing else. A param of the host that shares a name with one of the machine can
+     * therefore shadow it never.
+     *
+     * A host reads them back from `bridge.basePathParams`, where they cannot go stale.
+     * A machine that needs the identity of its host takes it through the `input` of the
+     * actor, where that identity decides WHICH machine runs.
+     */
+    readonly basePathParams?: Record<string, string | number> | undefined;
+}
+/**
+ * A base path that is ready for a use in both directions.
+ */
+export interface ResolvedBasePath {
+    /**
+     * The normalized prefix: it starts with `/`, it carries no trailing `/`, and it
+     * holds no duplicate slash. The empty string means "no prefix".
+     */
+    readonly path: string;
+    /**
+     * The values of each `:param` of the prefix, for the `params` of a `play.route`
+     * event. The object is empty for a prefix without a param, and for a pattern that
+     * nothing resolved.
+     */
+    readonly params: Record<string, string>;
+}
+/**
+ * The base path of a bridge that has no `basePath` option.
+ *
+ * The object is FROZEN, and both levels of it: {@link resolveBasePath} returns this
+ * exact instance for every bridge with no mount, and
+ * `RouterBridgeBase.basePathParams` hands its `params` to the caller.
+ * `Readonly<Record<string, string>>` is gone at run time, so without the freeze one
+ * write in consumer code would leak that key into every other unmounted bridge in
+ * the process.
+ */
+export declare const NO_BASE_PATH: ResolvedBasePath;
+/**
+ * Normalizes a base path, and it substitutes no `:param` segment of that path.
+ *
+ * Use this function when you want the form of the pattern, for example to declare
+ * the routes of a machine in a route config of a host that substitutes each param
+ * itself. {@link resolveBasePath} gives the form that a bridge needs.
+ *
+ * @param basePath - The prefix, as a pattern or as a concrete path. An absent value,
+ *   `""`, and `"/"` all give `""`.
+ * @returns The normalized prefix. It starts with `/`, and it carries no trailing `/`.
+ * @throws {InvalidBasePathError} For a wildcard segment, for an optional `:param?`
+ *   segment, for a `$param` segment, for a query string or a hash fragment, for a URL
+ *   scheme, for a dot segment (`.`, `..`, and their percent-encoded forms), and for any
+ *   segment that a browser rewrites — one that holds whitespace, a backslash, or a
+ *   character that a URL percent-encodes.
+ *
+ * @example
+ * ```typescript
+ * normalizeBasePath("/:machineId/play/");  // "/:machineId/play"
+ * normalizeBasePath("admin");              // "/admin"
+ * normalizeBasePath("/");                  // ""
+ * ```
+ */
+export declare function normalizeBasePath(basePath?: string | undefined): string;
+/**
+ * Resolves a base path and its params to the concrete prefix that a browser URL
+ * carries.
+ *
+ * A bridge calls this function one time, and again on each `setBasePath()` call. The
+ * result is always concrete. {@link stripBasePath} therefore compares a literal
+ * prefix, and no URLPattern match runs on the hot path of a navigation.
+ *
+ * @param basePath - The prefix, as a pattern or as a concrete path.
+ * @param params - The values of the `:param` segments of `basePath`.
+ * @returns The concrete prefix, and the values of each param for a `play.route` event.
+ * @throws {InvalidBasePathError} For a wildcard segment, for an optional `:param?`
+ *   segment, for a `$param` segment, for a query string or a hash fragment, for a URL
+ *   scheme, for a dot segment (`.`, `..`, and their percent-encoded forms), and for any
+ *   segment that a browser rewrites — one that holds whitespace, a backslash, or a
+ *   character that a URL percent-encodes.
+ * @throws {MissingBasePathParamError} When a `:param` of the prefix has no value.
+ *
+ * @example
+ * ```typescript
+ * resolveBasePath("/:machineId/play", { machineId: "abc123" });
+ * // → { path: "/abc123/play", params: { machineId: "abc123" } }
+ *
+ * resolveBasePath("/admin");
+ * // → { path: "/admin", params: {} }
+ * ```
+ */
+export declare function resolveBasePath(basePath?: string | undefined, params?: Record<string, string | number> | undefined): ResolvedBasePath;
+/**
+ * Removes the base path from an inbound location of the router.
+ *
+ * The return value separates the two cases that make a shared router work:
+ * - A string is the MACHINE half of the location, for example `"/dashboard"` of
+ *   `"/abc123/play/dashboard"`. The bridge matches it against the route map.
+ * - `null` means that the location is FOREIGN: it lies outside the mount, so it
+ *   belongs to the host. The bridge sends no `play.route` event, AND it runs no
+ *   corrective navigation. A correction here would drag the user off a page of the
+ *   host.
+ *
+ * The match is exact, and it respects each segment boundary. `"/abc/playground"` is
+ * therefore foreign to the mount `"/abc/play"`.
+ *
+ * @param pathname - A sanitized pathname of the router, with no query and no duplicate slash.
+ * @param basePath - The concrete prefix of {@link resolveBasePath}. `""` removes nothing.
+ * @returns The machine half of the path, or `null` when the location is foreign.
+ *
+ * @example
+ * ```typescript
+ * stripBasePath("/abc123/play/dashboard", "/abc123/play");  // "/dashboard"
+ * stripBasePath("/abc123/play", "/abc123/play");            // "/"
+ * stripBasePath("/settings", "/abc123/play");               // null — the host owns it
+ * ```
+ */
+export declare function stripBasePath(pathname: string, basePath: string): string | null;
+/**
+ * Adds the base path to an outbound path of the machine.
+ *
+ * The function joins the PATHNAME only. A query string and a hash fragment of the
+ * path of the machine stay at the end, because the prefix belongs in front of the
+ * path.
+ *
+ * @param basePath - The concrete prefix of {@link resolveBasePath}. `""` adds nothing.
+ * @param path - The path of the machine, for example `"/dashboard"` or `"/dates?trip=one-way"`.
+ * @returns The location for the router of the host.
+ *
+ * @example
+ * ```typescript
+ * joinBasePath("/abc123/play", "/dashboard");         // "/abc123/play/dashboard"
+ * joinBasePath("/abc123/play", "/");                  // "/abc123/play"
+ * joinBasePath("/abc123/play", "/x?tab=a");           // "/abc123/play/x?tab=a"
+ * joinBasePath("", "/dashboard");                     // "/dashboard"
+ * ```
+ */
+export declare function joinBasePath(basePath: string, path: string): string;
+/**
+ * Gives the index of the first query mark or fragment mark of a path, or `-1`.
+ *
+ * The names say `At`, because both values are an INDEX. A name such as `hash` reads
+ * as a digest to a reader and to a scanner both: `gitlab.eslint.detect-possible-timing-attacks`
+ * fires on a `===` test against an identifier of that name, and it cannot see that
+ * the operands here are two numbers.
+ *
+ * @internal `RouterBridgeBase` splits a location on the same boundary, to read the
+ *   pathname half of an actor route. One function, so the two sides cannot disagree
+ *   about where a pathname ends.
+ */
+export declare function firstMarkIndex(path: string): number;
+//# sourceMappingURL=base-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-path.d.ts","sourceRoot":"","sources":["../src/base-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,gBAGzB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAqBvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,GAClD,gBAAgB,CAkElB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD"}