@xmachines/play-router 6.0.0 → 7.0.0

package/dist/router-bridge-base.js

@@ -1,1622 +1,1047 @@
-/**
- * RouterBridgeBase — the abstract base class of every framework router adapter
- *
- * The class holds the logic that each router bridge shares, and that is 90% of the
- * code of every bridge:
- * - The atom watcher of the direction from the actor to the router
- * - `lastSyncedPath`, for the echo suppression in the direction from the actor to the router
- * - The `isProcessingNavigation` flag, which stops a loop of a guard redirect in `syncActorFromRouter` only
- * - `syncRouterFromActor` and `syncActorFromRouter`, with the read of each URL parameter
- * - The connect and disconnect lifecycle of the RouterBridge protocol
- *
- * A subclass implements the 3 abstract methods of its framework only:
- * - navigateRouter(path): how the bridge tells the framework router to navigate
- * - watchRouterChanges(): how the bridge subscribes to each location change of the router
- * - unwatchRouterChanges(): how the bridge cancels that subscription
- *
- * @example
- * ```typescript
- * export class MyRouterBridge extends RouterBridgeBase {
- *   private unsubscribe: (() => void) | null = null;
- *
- *   constructor(private router: MyRouter, actor: RoutableActor, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
- *     super(actor, routeMap);
- *   }
- *
- *   protected navigateRouter(path: string): void {
- *     this.router.navigate(path);
- *   }
- *
- *   protected watchRouterChanges(): void {
- *     this.unsubscribe = this.router.subscribe((state) => {
- *       this.syncActorFromRouter(state.location.pathname, state.location.search);
- *     });
- *   }
- *
- *   protected unwatchRouterChanges(): void {
- *     this.unsubscribe?.();
- *     this.unsubscribe = null;
- *   }
- * }
- * ```
- *
- * @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
- */
-import { NO_BASE_PATH, sanitizePathname, splitLocation, holdsUnsubstitutedParam, joinBasePath, parsePattern, resolveBasePath, stripBasePath, } from "@xmachines/play-url";
+import { DuplicateBridgeError, InvalidRoutePatternError, RouterSyncError } from "./errors.js";
+import { buildPlayRouteEvent, extractQuery, extractRouteParams, matchRouteMap } from "./router-sync.js";
+import { NO_BASE_PATH, holdsUnsubstitutedParam, joinBasePath, parsePattern, resolveBasePath, sanitizePathname, splitLocation, stripBasePath } from "@xmachines/play-url";
 import { watchAtom } from "@xmachines/play-atom";
-import { DuplicateBridgeError, RouterSyncError, InvalidRoutePatternError } from "./errors.js";
-import { buildPlayRouteEvent, extractQuery, extractRouteParams, matchRouteMap, } from "./router-sync.js";
+//#region packages/play-router/src/router-bridge-base.ts
 /**
- * The registry of the actors with an active bridge connection, at the module level.
- *
- * The key is the actor instance, and the registry is a WeakMap, which holds no
- * reference. The class uses it to find and refuse a second `connect()` call of the
- * same actor. Such a call makes two `play.route` events for one navigation, and it
- * makes two `lastSyncedPath` values of the echo suppression that contradict each
- * other.
- *
- * @internal
- */
-const activeBridges = new WeakMap();
-export class RouterBridgeBase {
-    actor;
-    routeMap;
-    // ── The common state. It is identical in each of the 4 bridges ──
-    isConnected = false;
-    hasConnectedOnce = false;
-    /**
-     * The machine-side location that the router holds, as far as this bridge knows. It
-     * carries the query and the fragment, and it carries NO `basePath`.
-     *
-     * Only code that saw a location, or that wrote one, writes this field:
-     * `performInitialSync` when it finds the two sides in step, `takeReturnUnderMount`
-     * for the same test under a mount, `pushResolvedRoute` after it resolves a route to
-     * a concrete path, and `syncActorFromRouter` for the location that the router
-     * reports. `null` means that this bridge placed no location yet, so it knows nothing
-     * about the address bar, and every test against this field must then answer "no".
-     *
-     * The field held the route of the actor as well, from the seed of the constructor
-     * and from a route that resolves to no URL. Those two values describe no location
-     * that a router ever showed, and each reader of this field asks about a location, so
-     * each of them read them wrongly. {@link lastActorRoute} holds them now.
-     */
-    lastSyncedPath = null;
-    /**
-     * The raw value of `actor.currentRoute` that this bridge accounted for already.
-     *
-     * The field answers ONE question: "did the bridge see this value of the atom
-     * before?". It is therefore a string, and not a location — a route that resolves to
-     * no URL, such as an unknown stateId or a parameterized pattern, still stops a
-     * second attempt at the same value.
-     *
-     * The constructor and `connect()` seed it, so that the first fire of the watcher of
-     * the atom pushes nothing for a route that moved nowhere.
-     */
-    lastActorRoute = null;
-    /**
-     * The flag guards `syncActorFromRouter` against a re-entrant call from a guard
-     * redirect of the actor itself. Such a call has this sequence: the bridge sends to
-     * the actor, the atom fires, the bridge pushes to the router, and a second
-     * `syncActorFromRouter` call starts before the first one returns.
-     *
-     * The flag is NOT the echo suppression of the direction from the actor to the
-     * router. `lastSyncedPath` does that work alone: the bridge writes it before the
-     * `navigateRouter()` call. Therefore each router callback of the same location stops
-     * at the {@link isEchoOfLastSync} test in `syncActorFromRouter`.
-     */
-    isProcessingNavigation = false;
-    /**
-     * Who owns the address bar, and what this bridge owes it.
-     *
-     * - `"under-mount"` — the location lies under the mount, so this bridge owns the
-     *   address bar and it writes the location for every route of its actor.
-     * - `"outside"` — the location lies outside the mount, so the HOST owns it. The
-     *   bridge sends no event and it corrects no URL, which is what lets the routes of
-     *   the host and the routes of the machine share one router.
-     * - `"outside-push-owed"` — outside, AND the route of the actor changed while the
-     *   host owned the address bar. The push waits here instead of going to the router,
-     *   and {@link RouterBridgeBase.takeReturnUnderMount} spends it when the location
-     *   comes back. The machine therefore keeps its place while the user reads a page of
-     *   the host.
-     *
-     * ONE value, and not a latch plus a memory. The memory only ever means something
-     * while the latch is up, so two fields could hold a fourth combination that says
-     * "the bridge owns the address bar AND a push waits for a return" — a state with no
-     * meaning, which a return would spend at a location the router already holds. Two
-     * writes also cannot happen together: every site that lowered the latch wrote the
-     * memory on the NEXT line, and the value between the two lines was that fourth
-     * combination. `takeReturnUnderMount` reads the value it replaces instead.
-     *
-     * `syncActorFromRouter` is the one place that sees a location, so it is the one
-     * place that decides between `"under-mount"` and `"outside"`.
-     * `performInitialSync` decides it for the location that the page loaded with.
-     *
-     * A bridge with no mount never leaves its mount: `stripBasePath` returns the path
-     * unchanged for an empty prefix, and never `null`. The value therefore stays
-     * `"under-mount"` for every bridge that takes no `basePath`.
-     */
-    mountState = "under-mount";
-    /**
-     * True once the first synchronization ran against a location INSIDE the mount.
-     *
-     * `performInitialSync` separates a deep link from a restore, and it can make that
-     * decision only for a location that lies under the mount. A bridge that connects
-     * while the host owns the address bar therefore reaches no decision at all: it
-     * raises the latch and returns. The flag says that the decision is still owed, and
-     * `syncActorFromRouter` pays it at the first location that IS under the mount —
-     * through {@link RouterBridgeBase.takeReturnUnderMount} for a RETURN, which needs the
-     * decision itself, and directly for every other location under the mount.
-     *
-     * A bridge with no mount never leaves its mount, so `performInitialSync` writes this
-     * flag on the first `connect()` and nothing reads it again.
-     */
-    hasSynchronizedUnderMount = false;
-    routeWatcher = null;
-    /**
-     * The mount point of the machine inside the host router: the resolved prefix, and
-     * the values of each `:param` of that prefix.
-     *
-     * The prefix lives here, and NOT in the route map, for two reasons. 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. And
-     * the bridge is the boundary between a location of the host router and a path of
-     * the machine already, which is exactly what the prefix separates.
-     *
-     * `lastSyncedPath` stays MACHINE-side, and it carries no prefix. The code adds the
-     * prefix at the one `navigateRouter()` call in `pushResolvedRoute`, and it removes
-     * the prefix at the one inbound entry point `syncActorFromRouter`. Every test of
-     * the echo suppression therefore keeps comparing like with like.
-     */
-    mount = NO_BASE_PATH;
-    /**
-     * The caches that every parse and every compilation of this bridge reads.
-     *
-     * `resolveNavigationPath` and `isActorAtPath` parse a CONCRETE location, and an
-     * application writes one for each value that it puts in a param.
-     */
-    compileOptions;
-    /**
-     * @param actor    - A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.
-     * @param routeMap - The route map of both directions, for the resolution between a
-     *   `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A
-     *   framework adapter usually wraps the result of `createRouteMap(machine)`, or an
-     *   equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the
-     *   bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
-     *   of your own, for example a plain test object, handles one form only.
-     */
-    constructor(actor, routeMap, options) {
-        this.actor = actor;
-        this.routeMap = routeMap;
-        // The caches of this bridge, or the shared defaults. `resolveNavigationPath` and
-        // `isActorAtPath` parse a CONCRETE location — one for each value that the
-        // application puts in a param — so a server that holds a bridge for each request
-        // passes caches that the request owns and drops.
-        this.compileOptions = {
-            patternCache: options?.patternCache,
-            compiledCache: options?.compiledCache,
-        };
-        // Resolve the mount BEFORE the seed of lastSyncedPath: an invalid basePath must
-        // fail here, at the construction, and not on the first navigation.
-        this.mount = resolveBasePath(options?.basePath, options?.basePathParams);
-        // Record the route of the actor as accounted for. This stops a loop in the first
-        // synchronization: the watcher of the atom fires once when `connect()` arms it,
-        // and a route that moved nowhere must push nothing.
-        //
-        // The seed goes to `lastActorRoute`, and NOT to `lastSyncedPath`. The route of the
-        // actor describes no location that the router ever showed — the bridge has written
-        // nothing yet — and every reader of `lastSyncedPath` asks about a location.
-        this.lastActorRoute = this.actor.currentRoute.get() ?? null;
-    }
-    /**
-     * The resolved URL prefix that the machine of this bridge is mounted under, or `""`
-     * when the machine owns the complete router.
-     */
-    get basePath() {
-        return this.mount.path;
-    }
-    /**
-     * The resolved values of the `:param` segments of the mount, or `{}` for a prefix
-     * without a param.
-     *
-     * These params belong to the HOST: the host wrote the prefix and resolved the
-     * values, and they describe the route of the host and not the route of the machine.
-     * They therefore 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.
-     *
-     * They live here instead, because a value that reached the actor on a navigation
-     * ALONE would go stale: `setBasePath()` can move the mount while the machine stays
-     * on the same route, no event goes out, and `event.params` would then contradict
-     * `basePath`. A read of this accessor cannot go stale.
-     *
-     * 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.
-     *
-     * @example
-     * ```typescript
-     * bridge.basePath;        // "/abc123/play"
-     * bridge.basePathParams;  // { machineId: "abc123" }
-     * ```
-     */
-    get basePathParams() {
-        return this.mount.params;
-    }
-    /**
-     * Moves the machine to a different mount point, while it stays connected.
-     *
-     * This is the "load and unload" half of a shared router. It moves WHERE an actor is
-     * mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU
-     * cache all stay, and nothing goes away.
-     *
-     * An actor never changes identity. A 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. The segments that move here are the
-     * ones that LOCATE: a region, a locale, a tenant, a workspace slug.
-     *
-     * The call then brings the location in step with the NEW prefix. A location inside
-     * the new mount runs the same first-synchronization decision as `connect()`: it
-     * drives the actor, and a restore keeps the route of the actor. A location OUTSIDE
-     * the new mount is the old mount in practice, so the bridge writes the new one
-     * itself, and it keeps the route of the actor while it does so — nothing else moves
-     * the address bar. A call that resolves to the current prefix changes no location,
-     * and it therefore reconciles nothing.
-     *
-     * @param basePath - The new prefix, as a pattern or as a concrete path. An absent
-     *   value, `""`, and `"/"` all remove the prefix, and they give the machine the
-     *   complete router again.
-     * @param basePathParams - The values of the `:param` segments of `basePath`.
-     * @throws {InvalidBasePathError} For a prefix that resolves to one concrete path never.
-     * @throws {MissingBasePathParamError} When a `:param` of the prefix has no value.
-     *
-     * @example
-     * ```typescript
-     * // The host moved this actor to another place in its URL space. `machineId` names
-     * // WHICH document the actor runs, and it does not change: a new identity is a new
-     * // actor, and therefore a new bridge, because one actor takes one bridge.
-     * bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
-     * ```
-     */
-    setBasePath(basePath, basePathParams) {
-        const next = resolveBasePath(basePath, basePathParams);
-        const samePath = next.path === this.mount.path;
-        // Take the new mount in every case, also when the prefix STRING does not change: a
-        // caller can move between a literal that holds the value already ("/abc123/play")
-        // and the equal pattern ("/:machineId/play" with `{ machineId }`). The two give the
-        // same path and different params, and `basePathParams` reports those params. They
-        // travel in NO `play.route` event: the machine is authoritative over its own
-        // params, and a param of the mount belongs to the host.
-        this.mount = next;
-        // The same prefix means that no location changed, so there is nothing to bring in
-        // step, and `lastSyncedPath` still describes a location that is still current.
-        if (samePath)
-            return;
-        if (this.isConnected) {
-            // The machine was at no location under the NEW prefix yet, and lastSyncedPath
-            // describes the old one. A clear of that field lets the first synchronization
-            // below push or send without a stop at the dedup guard.
-            //
-            // The clear stays INSIDE this guard, with the three records below: each of them
-            // is a statement about a connection, and a bridge that is not connected has
-            // none to correct. `connect()` clears the same record for the next one.
-            this.lastSyncedPath = null;
-            // Both records of the OLD mount go with it. The latch says "the location lies
-            // outside the mount", and the memory says "the actor is not where the address bar
-            // says" — each of them is a statement about the prefix that this call replaces, so
-            // neither survives it. `reconcileLocationWithMount` writes both again for a
-            // location that it can read; for a location that it CANNOT read — an adapter whose
-            // `getInitialRouterPath()` returns `null` or `undefined` at this moment — a stale
-            // latch silenced the direction from the actor to the router for the rest of the
-            // session, at a mount that may well cover the location already.
-            this.mountState = "under-mount";
-            // The first synchronization of the NEW prefix is owed again. The one that ran
-            // against the old prefix says nothing about this one: a location that the old
-            // mount covered can lie outside the new mount, and the decision between a deep
-            // link and a restore therefore has to run again for the prefix that replaces it.
-            this.hasSynchronizedUnderMount = false;
-            // No rollback here, unlike in `connect()`. A throw there escapes a call that
-            // returned never, so the caller holds nothing for a cleanup. Here the bridge is
-            // connected already, and the caller holds its `disconnect` already. A teardown
-            // on a failed move of the mount would make that handle a silent no-op, and it
-            // would stop a bridge that the caller still believes in. A throw from here leaves
-            // the NEW mount in place — `resolveBasePath` above refuses an invalid prefix
-            // before the assignment — so the caller sees the throw and it decides.
-            this.reconcileLocationWithMount();
-        }
-    }
-    /**
-     * Brings the location of the router in step with a mount that just moved.
-     *
-     * **The location lies under the new mount:** run the same first-synchronization
-     * decision as `connect()`, so a location inside the mount drives the actor and a
-     * restore keeps the route of the actor.
-     *
-     * **The location lies outside it:** the bridge writes the new mount ITSELF, and it
-     * keeps the route of the actor while it does so. A host that re-points a mount
-     * changes no location by itself, and nothing else moves the address bar. Without
-     * this push the machine sits at a mount that no location is under: it hears no
-     * `play.route`, `lastSyncedPath` is clear already, and the stale prefix stays in the
-     * URL until the route of the actor happens to change — which then jumps the URL with
-     * no reason that the history of the user explains.
-     *
-     * `pushResolvedRoute` writes `lastSyncedPath` before it navigates, so the callback
-     * of the router for this push stops at the echo suppression, and it sends no event.
-     */
-    reconcileLocationWithMount() {
-        const routerPath = this.getInitialRouterPath();
-        // `sanitizePathname` refuses a path of more than 2048 characters, and the RAW value
-        // is no substitute for the clean one: it still carries a query, a fragment, and a
-        // duplicate slash, so a compare against the mount reads a location of the host as
-        // "inside the mount", or the opposite. Such a location is one that this bridge
-        // cannot place, exactly like a location that the adapter cannot read.
-        const sanitized = typeof routerPath === "string" ? sanitizePathname(routerPath) : null;
-        // A location that reads as `null` because the adapter cannot read its router
-        // synchronously is NOT a location outside the mount. Leave that case to
-        // `performInitialSync`, which handles an absent location already, and which
-        // refuses a path that is too long.
-        if (typeof routerPath !== "string" || sanitized === null) {
-            this.performInitialSync(routerPath);
-            return;
-        }
-        const machinePath = stripBasePath(sanitized, this.mount.path);
-        if (machinePath !== null) {
-            // Hand the location on, so that the adapter is asked for it ONE time: a read of
-            // `getInitialRouterPath()` belongs to the adapter, it can walk the state of a
-            // router, and a second read can answer differently from the first.
-            this.performInitialSync(routerPath);
-            return;
-        }
-        const currentActorRoute = this.actor.currentRoute.get();
-        if (!currentActorRoute) {
-            // Nothing to write yet. The location still belongs to the HOST, and recording
-            // that is the whole job of this branch: without it the first route of the actor
-            // would write over the page of the host.
-            this.markOutside();
-            return;
-        }
-        // The route of the actor has to resolve to a concrete path BEFORE the latch comes
-        // down. `pushResolvedRoute` writes nothing for an unknown stateId and for a
-        // parameterized pattern, and it reports nothing either: a lowered latch then said
-        // that the bridge owns an address bar that still holds a location of the HOST, and
-        // the next route change of the actor — an `after` timer, a guard that settles —
-        // wrote over the page of the host with no URL event that asked for it.
-        //
-        // Keep the latch UP for that case, and remember the push, exactly as the branch
-        // above does for an actor with no route yet.
-        const resolved = this.resolveNavigationPath(currentActorRoute);
-        if (resolved === null) {
-            this.mountState = "outside-push-owed";
-            return;
-        }
-        // The bridge owns the address bar again the moment it writes the new mount.
-        this.mountState = "under-mount";
-        // The push below IS the first synchronization of this mount: the actor won it, and
-        // the bridge wrote the location. A debt that stayed said the opposite, and
-        // `takeReturnUnderMount` paid it at the first LATER return under the mount: it read
-        // the route of the actor as a restore and pushed it, so a deliberate navigation of
-        // the host to the mount point landed the user somewhere else, with no `play.route`
-        // event for the location they chose.
-        this.hasSynchronizedUnderMount = true;
-        // The resolution above travels with the route, so `resolveNavigationPath` runs one
-        // time: the method is `protected`, a subclass can override it, and a second call
-        // can answer differently from the first.
-        this.pushHoldingNavigation(currentActorRoute, resolved);
-    }
-    /**
-     * Pushes a route to the router, and it holds {@link isProcessingNavigation} across
-     * the write.
-     *
-     * Every corrective push of the bridge needs that flag: `navigateRouter` makes the
-     * router call `syncActorFromRouter` again inside it, and a router that NORMALIZES the
-     * location it receives — a `validateSearch` that injects a default, a trailing slash
-     * that a history adds — reports a value that the echo test misses. The bridge would
-     * then answer its own write with a `play.route` event, and on a press of BACK that
-     * answer is a history entry that FORWARD cannot return to.
-     *
-     * The one push that does NOT come through here is `syncRouterFromActor`: that push
-     * follows the actor, and the echo suppression of `lastSyncedPath` is what stops it.
-     *
-     * @param route    - The raw value of the actor route.
-     * @param resolved - The concrete path of that route, when the caller resolved it
-     *   already. `undefined` resolves it in `pushResolvedRoute`.
-     */
-    pushHoldingNavigation(route, resolved) {
-        this.isProcessingNavigation = true;
-        try {
-            this.pushResolvedRoute(route, resolved);
-        }
-        finally {
-            this.isProcessingNavigation = false;
-        }
-    }
-    // ── The RouterBridge protocol. It is final: a subclass must override nothing here ──
-    /**
-     * Connects the router bridge to the Actor.
-     *
-     * The method installs the atom watcher of the direction from the actor to the
-     * router. It then starts the watch of the router changes, which each framework does
-     * in its own way.
-     *
-     * The order of these steps is part of the contract of the bridge:
-     * - The constructor seeds `lastActorRoute` from `actor.currentRoute`, and it records no location
-     * - The method installs the actor watcher before the router subscriptions of the adapter
-     * - The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
-     *
-     * An adapter that needs a different behavior of the first synchronization overrides
-     * `getInitialRouterPath()`. It does not change the order of the steps of
-     * `connect()`.
-     */
-    connect() {
-        if (this.isConnected) {
-            return;
-        }
-        // Permit one bridge for each actor: two connected bridges of the same actor both
-        // receive every navigation event of the router. They therefore send two play.route
-        // events, and their lastSyncedPath values of the echo suppression contradict each
-        // other.
-        const existingBridge = activeBridges.get(this.actor);
-        if (existingBridge !== undefined && existingBridge !== this) {
-            throw new DuplicateBridgeError();
-        }
-        activeBridges.set(this.actor, this);
-        // Seed the dedup again, exactly as the constructor does, and for the same reason:
-        // the field must describe the route of the actor at the moment this connection
-        // starts. `disconnect()` leaves the value of the PREVIOUS connection there, and the
-        // actor can move while nothing watches it — a provider that unmounts and mounts
-        // again does that, and so does the pair of `<StrictMode>`. The write also covers
-        // the gap between the constructor and the first `connect()`, which the Vue provider
-        // reaches through `await router.isReady()`.
-        //
-        this.lastActorRoute = this.actor.currentRoute.get() ?? null;
-        // This connection has observed NO location yet: `performInitialSync` below is the
-        // first read of the router. Say so, rather than keep the location of the previous
-        // connection — `disconnect()` leaves that value behind, and `setBasePath` can move
-        // the prefix while nothing is connected, so the value can describe a location under
-        // a prefix that is gone. `isEchoOfLastSync` then read the real location of the
-        // router as an echo of this bridge, and the first synchronization sent no
-        // `play.route` for it: the URL and the actor separated with no error.
-        this.lastSyncedPath = null;
-        this.isConnected = true;
-        this.hasConnectedOnce = true;
-        // From here on, connect() gives all or nothing. THREE steps below can throw, and
-        // the rollback has to cover each of them:
-        //   - `createRouteWatcher`, on an atom that refuses a watcher
-        //   - `watchRouterChanges()`, which belongs to the adapter: `afterNavigate()` of
-        //     SvelteKit raises `lifecycle_outside_component` outside the initialization of
-        //     a component, and a host reaches that by calling `connectRouter` from a module
-        //     scope or a store
-        //   - `performInitialSync()`, with an InvalidRoutePatternError for a route that
-        //     URLPattern refuses, and a RouterSyncError for each other failure of the send
-        //     to the actor
-        //
-        // The throw needs an action of the caller, and it therefore goes to the caller
-        // without a change.
-        //
-        // connect() then returns never, and the caller holds therefore NO handle for a
-        // cleanup. Every part above must go away again, or it leaks:
-        //   - the router listener keeps firing, and it drives the actor through a bridge
-        //     that the caller believes to be dead
-        //   - the atom watcher keeps pushing each actor route to the router
-        //   - the activeBridges entry keeps the actor, so the NEXT connect() call of the
-        //     caller for this actor throws a DuplicateBridgeError. A repair of the real
-        //     cause, for example a correction of the route pattern, rescues that actor
-        //     never.
-        try {
-            // The atom watcher of the direction from the actor to the router.
-            this.routeWatcher = createRouteWatcher(this.actor.currentRoute, (route) => {
-                this.syncRouterFromActor(route);
-            });
-            // The watch of the router changes. Each framework does this in its own way.
-            this.watchRouterChanges();
-            this.performInitialSync(this.getInitialRouterPath());
-        }
-        catch (error) {
-            // disconnect() is exactly this teardown, and it is idempotent. It runs inside a
-            // guard of its own, because `unwatchRouterChanges()` belongs to the adapter and
-            // it can throw: a Vue scope that stops, a Solid disposer, a SvelteKit teardown.
-            // That error must NOT replace the one the rollback exists to surface — a caller
-            // that receives it learns neither which route pattern URLPattern refused nor
-            // which event the actor refused.
-            try {
-                this.disconnect();
-            }
-            catch {
-                // The teardown failed, so the slot of the actor may still be taken. The
-                // original error still reaches the caller, which is the one that names a
-                // cause it can repair.
-            }
-            throw error;
-        }
-    }
-    /**
-     * Brings the actor and the router in step one time, and decides which side wins.
-     *
-     * The method is separate from `connect()`, so that `connect()` can roll the whole
-     * first synchronization back when it throws. See the `try` block there.
-     *
-     * The first synchronization: the direction from the router to the actor has the
-     * priority over the other direction.
-     *
-     * The page can load on a URL that is not the initial state of the actor. For
-     * example, the user types "/about", or the user follows a deep link. The router
-     * holds the correct path then, and the actor is still at its initial state ("/").
-     * The code must therefore drive the actor to the URL, and it must not write the
-     * default of the actor to the URL.
-     *
-     * router.subscribe() fires on a *later* navigation event only. It does NOT fire for
-     * the location that the page loaded. A subclass that can read the current location
-     * of its router synchronously overrides getInitialRouterPath().
-     *
-     * @param initialRouterPath - The location of the router. Every caller reads it and
-     *   passes it, and this parameter carries NO default: a default fires for an
-     *   explicit `undefined` too, so `reconcileLocationWithMount` asked the adapter a
-     *   SECOND time for exactly the value that says "the adapter does the first
-     *   synchronization itself" — and a read belongs to the adapter, which can walk the
-     *   state of a router and answer differently on the second call.
-     */
-    performInitialSync(initialRouterPath) {
-        const initialActorRoute = this.actor.currentRoute.get();
-        // ONE read of the query of the router, and a LAZY one. The read belongs to the
-        // adapter and it can walk the state of a router, so a second call can answer
-        // differently — and most branches below reach no query at all.
-        let search;
-        let searchRead = false;
-        const routerSearch = () => {
-            if (!searchRead) {
-                search = this.getInitialRouterSearch();
-                searchRead = true;
-            }
-            return search;
-        };
-        if (typeof initialRouterPath === "string") {
-            // `sanitizePathname` refuses a path of more than 2048 characters, and the RAW
-            // value is no substitute for the clean one: it still carries a query, a
-            // fragment, and a duplicate slash, so a compare against the mount reads a
-            // location of the host as "inside the mount", or the opposite. The route
-            // resolution refuses such a path anyway — `syncActorFromRouter` sanitizes it
-            // again and returns — so touch no latch for it and reconcile nothing.
-            const sanitized = sanitizePathname(initialRouterPath);
-            if (sanitized === null)
-                return;
-            // Take the machine half of the location of the router. A location OUTSIDE the
-            // mount belongs to the host, so the bridge stays out of it completely: it sends
-            // no event, and — this part makes a shared router work — it runs no corrective
-            // navigation either. A correction here would drag the user off a page of the
-            // host at the moment when the bridge connects.
-            const machinePath = stripBasePath(sanitized, this.mount.path);
-            if (machinePath === null) {
-                this.markOutside();
-                return;
-            }
-            // The symmetric write, and the reason this method has to make it: a location
-            // that lies INSIDE the mount means the bridge owns the address bar, and this
-            // method is reached without a router event — by `connect()`, and by a
-            // `setBasePath()` that moves the mount to where the location already is. A
-            // latch that only ever went up silenced the machine for the rest of the
-            // session, because nothing else here lowers it.
-            // The synchronization below brings the two sides in step, so a push that waited
-            // for the address bar to come back is spent with the same write. A memory that
-            // survived would replay that push on the next return, at a location the router
-            // already holds.
-            this.mountState = "under-mount";
-            // The decision below IS the first synchronization, and it runs against a location
-            // under the mount, so nothing is owed any more.
-            this.hasSynchronizedUnderMount = true;
-            // Test if the actor is at the current location of the router already. The PATH
-            // and the QUERY are two answers of ONE lookup: the path decides whether a restore
-            // is possible at all, and the query decides whether the two sides are in step
-            // there. `routerSearch` runs behind the `&&`, so a branch that answers on the
-            // path alone reads no query.
-            const actorAtRouterPath = this.isActorAtPath(machinePath, initialActorRoute);
-            const actorAlreadyAtRouterLocation = actorAtRouterPath &&
-                initialActorRoute != null &&
-                sameQuery(initialActorRoute, routerSearch());
-            // The two are in step already, so nothing is synchronized — but the location has
-            // to be RECORDED, or the echo suppression starts disarmed. `setBasePath` clears
-            // `lastSyncedPath` on a move of the prefix, and this branch left it null: the
-            // next callback of the router for that same location then read as a real move
-            // and sent a redundant `play.route`, and the next route change of the actor
-            // pushed a location the router already held.
-            //
-            // The write is UNCONDITIONAL, and a test for a null field is wrong here: the field
-            // must describe the location that this method just found in step, whatever it
-            // held before. `setBasePath` can re-point the mount between two synchronizations
-            // of one connection, and the record of the old prefix says nothing about this
-            // location.
-            if (actorAlreadyAtRouterLocation) {
-                this.lastSyncedPath = withSearch(machinePath, routerSearch());
-            }
-            else {
-                // The path of the router is different from the actor route. Is this a deep link, or
-                // is it a restore?
-                //
-                // A deep link: the router is at a URL that is not the initial one, and the actor saw
-                // that URL not yet.
-                //   → the router wins: syncActorFromRouter. The guards then decide the access.
-                //
-                // A restore: the browser is at the initial URL of the machine, and a snapshot
-                // restored the actor to a different route.
-                //   → the actor wins: push the restored route of the actor to the router.
-                //
-                // The detection: the URL of the router is the initial route of the machine, AND the
-                // actor is at a different route. This is then a restore.
-                //
-                // The branch reads the LOCATION test above, through the `else` that carries it,
-                // and not the path test alone: a fragment that the actor carries and the router
-                // reports never — `sanitizePathname` cuts it off — is a difference that only
-                // this push can place in the address bar. A query of the ACTOR is such a
-                // difference too, and issue #18 carries the decision about it.
-                //
-                // `carriesNoOwnSuffix` is what keeps the two apart. An actor that stands on the
-                // PATH of the router and carries no query and no fragment of its own restores
-                // NOTHING: the address bar already shows its place, and a push only rewrites the
-                // location that the user opened. The raw comparison against `initialRoute` cannot
-                // see that, because a stateId is never string-equal to a path — an actor at
-                // `"#home"` against a router at `"/?ref=nav"` read as a move, so the bridge
-                // pushed `"/"` over the query the user opened and sent no `play.route` that
-                // carried it. The router keeps the priority for such a location, which is the
-                // answer that the same bridge gives for the actor route `"/"`.
-                if (initialActorRoute &&
-                    machinePath === this.actor.initialRoute &&
-                    initialActorRoute !== this.actor.initialRoute &&
-                    !(actorAtRouterPath && carriesNoOwnSuffix(initialActorRoute))) {
-                    this.pushHoldingNavigation(initialActorRoute);
-                }
-                else {
-                    // The search is read through `routerSearch`, which reads it one time and only
-                    // when a branch needs it: the read belongs to the adapter, and it can walk
-                    // the state of a router.
-                    this.syncActorFromRouter(initialRouterPath, routerSearch());
-                }
-            }
-        }
-        else if (initialActorRoute && initialRouterPath === null) {
-            // An explicit null: no path of the router is available, from a restore or from a
-            // bootstrap → push the actor route.
-            // The value undefined means that the adapter does the first synchronization itself.
-            // Continue.
-            this.pushHoldingNavigation(initialActorRoute);
-            // The push IS the first synchronization of this mount, and the actor won it. A
-            // debt that stayed said the opposite, and `takeReturnUnderMount` paid it at the
-            // first LATER return under the mount: it read the route of the actor as a restore
-            // and pushed it, so a deliberate navigation of the host to the mount point landed
-            // the user somewhere else, with no `play.route` event for the location they chose.
-            this.hasSynchronizedUnderMount = true;
-        }
-        else if (initialActorRoute && initialActorRoute !== this.lastActorRoute) {
-            // No path of the router replaces the actor route → write the router from the actor, as before
-            this.syncRouterFromActor(initialActorRoute);
-            this.hasSynchronizedUnderMount = true;
-        }
-    }
-    /**
-     * Disconnects the router bridge from the Actor.
-     *
-     * The method stops the watch of the atom, and it removes the router listener of the
-     * framework.
-     */
-    disconnect() {
-        const hadRouteWatcher = this.routeWatcher !== null;
-        if (this.routeWatcher) {
-            try {
-                this.routeWatcher.unwatch();
-            }
-            catch {
-                // Ignore an error of a detached watcher. disconnect() therefore stays idempotent.
-            }
-        }
-        this.routeWatcher = null;
-        // `unwatchRouterChanges()` belongs to the adapter, and it can throw: a Vue scope
-        // that stops, a disposed Solid root, a SvelteKit teardown. Everything below it
-        // still has to run — a `finally`, and not a plain sequence. Without it the state
-        // stayed connected and the slot of the actor stayed taken, so every later
-        // `connect()` for that actor threw a DuplicateBridgeError, which is the one error
-        // that naming the real cause cannot repair. That also makes `disconnect()`
-        // idempotent, which the rollback of `connect()` depends on.
-        try {
-            if (this.isConnected || hadRouteWatcher) {
-                this.unwatchRouterChanges();
-            }
-        }
-        catch {
-            // Ignore an error of the teardown of the adapter, exactly as the watcher above
-            // ignores one. `disconnect()` is what a provider calls on an unmount, and a
-            // failure to release one subscription must not break that unmount — nor the
-            // rollback of `connect()`, which calls this method and needs the error of the
-            // first synchronization to reach the caller.
-        }
-        finally {
-            this.isProcessingNavigation = false;
-            this.isConnected = false;
-            // A push that waited for the address bar to come back dies with the connection,
-            // and so does the record of where the location lay. A later `connect()` runs its
-            // own first synchronization, and it decides all three again.
-            this.mountState = "under-mount";
-            this.hasSynchronizedUnderMount = false;
-            // Free the slot of the actor, so that a new bridge can connect to the same
-            // actor. Clear the slot only when this bridge is the registered one: a second
-            // bridge that connect() refused must not remove the legitimate bridge.
-            if (activeBridges.get(this.actor) === this) {
-                activeBridges.delete(this.actor);
-            }
-        }
-    }
-    // ── The sync methods. They are protected, and a subclass overrides one for its own behavior ──
-    /**
-     * Writes the location of the router when the route atom of the actor changes.
-     *
-     * The method resolves the actor route to a concrete URL path, then it calls
-     * navigateRouter() for the navigation of the framework. When it cannot resolve the
-     * route, which happens for an unknown stateId and for a parameterized pattern
-     * without concrete values, it skips the push completely: `navigateRouter` receives a
-     * raw stateId or a pattern never.
-     *
-     * `lastSyncedPath` does the complete echo suppression, which stops the callback of
-     * the router from a send to the actor: the method writes the resolved path to
-     * `lastSyncedPath` before the `navigateRouter()` call. Therefore each
-     * `syncActorFromRouter` call of the same path stops at the
-     * `sanitized === lastSyncedPath` test, and it sends no event. This is correct for a
-     * synchronous callback and for an asynchronous callback.
-     *
-     * The method does NOT set `isProcessingNavigation`. That flag lives inside
-     * `syncActorFromRouter`, and it guards against a re-entrant loop of a guard
-     * redirect.
-     */
-    syncRouterFromActor(route) {
-        if (this.hasConnectedOnce && !this.isConnected)
-            return;
-        if (!route || typeof route !== "string")
-            return;
-        // The host owns the address bar, so this bridge writes no URL. The inbound
-        // direction stays silent for the same location, and the two directions have to
-        // agree: a route that changes for a reason that is NOT a URL event — an `after`
-        // timer, an async guard that settles, a restore of a snapshot, a sibling that
-        // sends an event — would otherwise drag the user off a page of the host.
-        //
-        // The memory holds ONE fact: the actor is not where the address bar says. The
-        // test therefore runs on each change, and an echo CLEARS it — a route that
-        // wanders away and back leaves the URL correct, and a memory that stayed set
-        // would push a location the router already holds, which is a history entry that
-        // BACK cannot escape.
-        const echo = this.testEchoOfLastPush(route);
-        if (this.mountState !== "under-mount") {
-            this.mountState = echo.isEcho ? "outside" : "outside-push-owed";
-            return;
-        }
-        if (echo.isEcho)
-            return;
-        this.pushResolvedRoute(route, echo.resolved);
-    }
-    /**
-     * Records that the location lies outside the mount, so the HOST owns the address bar.
-     *
-     * A bridge that is outside ALREADY keeps the value it holds: `"outside-push-owed"`
-     * says that a push waits for the address bar to come back, and a second location of
-     * the host is no reason to forget it.
-     */
-    markOutside() {
-        if (this.mountState === "under-mount")
-            this.mountState = "outside";
-    }
-    /**
-     * Takes the return of the address bar under the mount.
-     *
-     * The actor wins that return when it moved while the host owned the location AND the
-     * address bar came back to the location it still held: the method pushes the route of
-     * the actor, and the caller sends no `play.route` event. A return to any other route
-     * of the mount belongs to the host, so the memory goes and the caller drives the
-     * actor from the location instead.
-     *
-     * The method also pays the first synchronization that the mount still owes. A bridge
-     * that connected while the host owned the address bar reached no decision between a
-     * deep link and a restore: `performInitialSync` can decide only for a location under
-     * the mount, and it found none. This is the first such location, so the decision runs
-     * here, with the same rule.
-     *
-     * The method holds `isProcessingNavigation` across each push, because
-     * `navigateRouter` makes the router call `syncActorFromRouter` again.
-     *
-     * @returns `true` when the method handled the location, so the caller returns.
-     */
-    takeReturnUnderMount(machinePath, search) {
-        const previous = this.mountState;
-        if (previous === "under-mount")
-            return false;
-        // The bridge owns the address bar again from here. The memory of a push that waited
-        // travels in `previous`, and the write below spends it in the SAME step: no branch
-        // has to clear it, and no branch can forget to.
-        this.mountState = "under-mount";
-        // The first synchronization of this mount never ran: `connect()`, or a
-        // `setBasePath()` that moved the mount, found the location outside the prefix, so
-        // `performInitialSync` raised the latch and returned before it could separate a
-        // deep link from a restore. Make that decision HERE, at the first location that
-        // lies under the mount, with the rule of `performInitialSync`: the router is at
-        // the initial route of the machine AND the actor is at another one, so a snapshot
-        // restored the actor and the actor wins.
-        //
-        // Without this the restore was lost the moment the host showed the machine: the
-        // location drove the actor back to the route of the mount point, while the SAME
-        // bridge connected at the SAME location kept the restored route. Which of the two
-        // happened depended on where the one shared router stood at the moment of
-        // `connect()`, which is the arbitrary part.
-        const owesFirstSync = !this.hasSynchronizedUnderMount;
-        this.hasSynchronizedUnderMount = true;
-        const restoredRoute = this.actor.currentRoute.get();
-        // `isActorAtPath` is the test that `performInitialSync` makes BEFORE it looks
-        // for a restore, and both branches of the owed synchronization below need it. The
-        // actor route can be a stateId, and a stateId is never string-equal to
-        // `initialRoute`, which is a path: an actor that sits at "#home" of the mount point
-        // read as a restore, so the bridge pushed "/abc123/play" over the location the HOST
-        // chose, dropped its query, and returned `true` — so no `play.route` carried that
-        // location to the machine either.
-        //
-        // ONE call, because `getStateIdByPath` and `getPathByStateId` belong to the route
-        // map: a map of a consumer can answer differently on a second call, and the two
-        // branches would then disagree about the same location. The PATH and the QUERY are
-        // two answers of that one lookup, exactly as `performInitialSync` reads them.
-        const actorAtPath = owesFirstSync && this.isActorAtPath(machinePath, restoredRoute);
-        const actorAtLocation = actorAtPath && restoredRoute != null && sameQuery(restoredRoute, search);
-        // The RESTORE reads the LOCATION test, exactly as `performInitialSync` does, and it
-        // refuses the same empty restore: an actor that stands on the PATH of the location
-        // and carries no query and no fragment of its own has nothing to put in the address
-        // bar. Without that test an actor at `"#home"` met a host that came back to the
-        // mount point with a query, and the bridge pushed the mount point over it and
-        // returned `true` — so no `play.route` carried that location to the machine either,
-        // which is the fault that the comment above this block names.
-        if (owesFirstSync &&
-            restoredRoute &&
-            machinePath === this.actor.initialRoute &&
-            restoredRoute !== this.actor.initialRoute &&
-            !actorAtLocation &&
-            !(actorAtPath && carriesNoOwnSuffix(restoredRoute))) {
-            return this.pushUnderMount(restoredRoute);
-        }
-        if (owesFirstSync) {
-            // The restore does not apply, and the bridge held the address bar under this
-            // mount NEVER: `performInitialSync` found the location outside the prefix and
-            // returned before it could record one. This location is therefore the first one
-            // that the mount can place.
-            //
-            // The memory is dropped already, so hand the location back to the caller. The
-            // caller then drives the actor from it, which is the deep-link half of the rule
-            // that `performInitialSync` applies.
-            //
-            // The FIRST half of that rule, and this branch owes it too: `performInitialSync`
-            // asks whether the actor stands at the location already, and it records the
-            // location and sends NOTHING when it does. Without the same test here, the same
-            // two situations answered differently — the bridge that connected under the mount
-            // stayed quiet, and the bridge that connected outside it re-entered the state the
-            // actor was already in, which runs every entry action of that state again. Which
-            // of the two happened depended on where the one shared router stood at the moment
-            // of `connect()`, which is the arbitrary part.
-            if (actorAtLocation) {
-                this.lastSyncedPath = withSearch(machinePath, search);
-                return true;
-            }
-            this.lastSyncedPath = null;
-            return false;
-        }
-        if (previous !== "outside-push-owed")
-            return false;
-        // The actor wins a return to the location that the address bar STILL HELD. That is
-        // the machine keeping its place while the user read a page of the host.
-        //
-        // It must not win a return to another route of the mount. A location that the
-        // address bar did not hold is a choice of the host — a link that the user pressed,
-        // a deep link they opened — and a push of the route of the actor would land them
-        // on a page they did not ask for, with no explanation. Drop the memory instead,
-        // and let the caller send the event for the location they chose.
-        if (!this.isEchoOfLastSync(machinePath, search))
-            return false;
-        // The route that the block above read already. One read, because
-        // `actor.currentRoute` belongs to the consumer and a second read can answer
-        // differently from the first.
-        //
-        // A falsy route has nothing to write, and the bridge owns the address bar again
-        // from the top of this method: `syncRouterFromActor` pushes the first real route of
-        // the actor by itself, so no replay is needed. A memory kept here could be spent
-        // only by a LATER return, at which point it pushes a location the router already
-        // holds — a history entry that BACK cannot escape.
-        if (!restoredRoute)
-            return false;
-        return this.pushUnderMount(restoredRoute);
-    }
-    /**
-     * Writes the route of the actor to a router that just came under the mount.
-     *
-     * The method holds `isProcessingNavigation` across the push, because
-     * `navigateRouter` makes the router call `syncActorFromRouter` again inside it.
-     *
-     * A re-entrant call pushes nothing inside another push, and the memory of a
-     * suppressed push DOES survive that case: the outer push is still in flight, and a
-     * clear here would throw the remembered route away with nothing left to replay it.
-     *
-     * @param route - The raw value of the actor route.
-     * @returns `true` when the method wrote the location, so that the caller returns and
-     *   sends no event. `false` when the route resolves to no concrete path, so that the
-     *   caller drives the actor from the location instead.
-     */
-    pushUnderMount(route) {
-        if (this.isProcessingNavigation)
-            return true;
-        // The route has to resolve to a concrete path BEFORE the method reports that it
-        // handled the location. `pushResolvedRoute` navigates nowhere for an unknown stateId
-        // and for a parameterized pattern, and it records the RAW value in `lastActorRoute`
-        // alone: a `true` return then left the location in neither side — the URL kept the
-        // page of the host, and the actor heard no `play.route`. The record of the location
-        // that the address bar holds says nothing about it either, so no later return could
-        // be recognized. `reconcileLocationWithMount` guards the same case.
-        //
-        // The resolution travels with the route, so `resolveNavigationPath` runs one time:
-        // the method is `protected`, a subclass can override it, and a second call can
-        // answer differently from the first.
-        const resolved = this.resolveNavigationPath(route);
-        if (resolved === null) {
-            // Clear the record of the location, or the `false` return reaches the caller
-            // and changes nothing. The caller hands the location back for the SAME location
-            // that `lastSyncedPath` describes — the suppressed-push branch tests
-            // `isEchoOfLastSync` before it calls this method — so the caller read its own
-            // record as an echo and returned. The actor then stayed on a route that resolves
-            // to no URL, the location it was given reached it never, and no error said so.
-            this.lastSyncedPath = null;
-            return false;
-        }
-        this.pushHoldingNavigation(route, resolved);
-        return true;
-    }
-    /**
-     * Tests a route of the actor against the last synchronized location.
-     *
-     * The exact string test covers a stateId, for example `"#home"`, which
-     * `pushResolvedRoute` writes to the field when it cannot resolve a path. The query
-     * test covers a location that carries a query: the order of the keys of a query is
-     * not significant, so `?b=2&a=1` and `?a=1&b=2` are the same location, and the
-     * bridge must push neither of them back.
-     *
-     * The FRAGMENT counts in this direction, and the inbound test ignores it. The two
-     * are different questions. `navigateRouter` writes the whole value that the actor
-     * gave — `buildRouteUrl` appends `context.hash` — so `"/docs"` and `"/docs#intro"`
-     * are two locations to write, and a test that read them as one left the fragment out
-     * of the address bar for ever. `isEchoOfLastSync` compares against what the ROUTER
-     * reports, and `sanitizePathname` has removed the fragment from that already.
-     */
-    testEchoOfLastPush(route) {
-        // The FIRST question: did the bridge account for this value of the atom already?
-        // The test is an exact string compare, because it asks about the VALUE. A route
-        // that resolves to no URL — an unknown stateId, a parameterized pattern — is
-        // therefore covered too, and the bridge tries it one time only.
-        if (route === this.lastActorRoute)
-            return { isEcho: true };
-        const location = this.lastSyncedPath;
-        // The bridge placed no location yet, so it knows nothing about the address bar.
-        // Resolve for the caller, and let it push.
-        if (location === null) {
-            return { isEcho: false, resolved: this.resolveNavigationPath(route) };
-        }
-        // The SECOND question: does the router hold the location that this route describes
-        // already? A route that IS a path answers it directly.
-        if (sameLocation(route, location))
-            return { isEcho: true };
-        // A route that is a stateId answers it only after the resolution. The machine that
-        // mirrors an inbound `play.route` back into its route atom reaches this line:
-        // the bridge wrote "/about" and the actor answers "#about", which is ONE location.
-        // A compare of the raw value alone missed, and the bridge pushed a location that
-        // the router already held — one history entry that BACK cannot escape.
-        //
-        // The resolution travels back to the caller, so `resolveNavigationPath` runs one
-        // time: the method is `protected`, a subclass can override it, and a second call
-        // can answer differently from the first.
-        const resolved = this.resolveNavigationPath(route);
-        if (resolved !== null && sameLocation(resolved, location))
-            return { isEcho: true };
-        return { isEcho: false, resolved };
-    }
-    /**
-     * Resolves an actor route to its concrete URL path, and pushes that path to the
-     * router.
-     *
-     * lastSyncedPath must hold the concrete path, because the callback of the router
-     * fires with the concrete path. The two values therefore match, and
-     * syncActorFromRouter stops. A raw stateId in that field, for example "#home", does
-     * not match the sanitized path ("/") in the watcher.
-     *
-     * When resolveNavigationPath returns null, which happens for a parameterized
-     * pattern, for a wildcard pattern, and for an unknown id, the method skips the push
-     * completely: a push of the raw value writes a stateId, a `:param` pattern, or a
-     * literal `*` into the browser URL. The method still writes the raw route to
-     * lastActorRoute, and it leaves lastSyncedPath as it stands, because that field
-     * records a LOCATION and no location changed. Therefore the dedup guard fires
-     * correctly on the next identical value of the atom.
-     *
-     * @param route    - The raw value of the actor route.
-     * @param resolved - The concrete path of that route. The default resolves it here. A
-     *   caller that resolved it already passes it, so that `resolveNavigationPath` runs
-     *   one time: the method is `protected`, and a subclass can override it.
-     */
-    pushResolvedRoute(route, resolved = this.resolveNavigationPath(route)) {
-        // The VALUE is accounted for either way, so the dedup stops the next identical fire
-        // of the atom even when the route resolves to no URL.
-        this.lastActorRoute = route;
-        // The LOCATION record takes the concrete path only. A raw stateId here described no
-        // location that a router ever showed, and `isEchoOfLastSync` compares this field
-        // against the location that the router reports: it read a real move as an echo of
-        // this bridge, and the actor heard nothing of it.
-        if (resolved === null)
-            return;
-        this.lastSyncedPath = resolved;
-        // This is the ONE place that adds the base path. `lastSyncedPath` keeps the
-        // machine-side path above, with no prefix, so it still compares directly against
-        // an actor route in `syncRouterFromActor`; `navigateRouter` receives the location
-        // of the host router, because that is the location the framework navigates to.
-        this.navigateRouter(joinBasePath(this.mount.path, resolved));
-    }
-    /**
-     * Writes the actor state when the location of the router changes.
-     *
-     * **A known path:** the method sends a `play.route` event to the actor, with the
-     * stateId of the match, the params, and the query. The `isProcessingNavigation` flag
-     * stops a circular update.
-     *
-     * **An unknown path, or a path with no entry in the map:** the method sends NO
-     * `play.route` event, and the actor state stays as it is. It corrects the browser URL
-     * instead, with a `navigateRouter(actor.currentRoute.get())` call. The URL therefore
-     * follows the actor state, also when the user types an invalid path in the address
-     * bar, or when the code pushes such a path during a session. The method writes the
-     * resolved concrete path to `lastSyncedPath` before the `navigateRouter` call.
-     * Therefore the callback of the router for that navigation stops at the guard of the
-     * echo suppression, and it sends no false event.
-     */
-    syncActorFromRouter(pathname, search) {
-        if (this.hasConnectedOnce && !this.isConnected)
-            return;
-        if (typeof pathname !== "string")
-            return;
-        const sanitized = sanitizePathname(pathname);
-        if (sanitized === null)
-            return; // The path is too long. Refuse it
-        // Take the machine half of the location. A `null` value means that the location
-        // lies OUTSIDE the mount, so it belongs to the host: return without a send of an
-        // event, and without a correction of the URL. That silence lets the routes of the
-        // host and the routes of the machine share one router.
-        const machinePath = stripBasePath(sanitized, this.mount.path);
-        if (machinePath === null) {
-            this.markOutside();
-            return;
-        }
-        // The test runs BEFORE the echo suppression. The location of a return matches
-        // `lastSyncedPath` in the common case — the host comes back to the mount point it
-        // left — and an early stop there would drop the suppressed push for good.
-        if (this.takeReturnUnderMount(machinePath, search))
-            return;
-        // The location lies under the mount, and this bridge is about to place it, so the
-        // first synchronization of this mount is owed no more. `takeReturnUnderMount`
-        // records it for a RETURN, and it returns at its first line for a bridge that never
-        // left, so the debt survived a first synchronization that reached no decision — an
-        // adapter whose `getInitialRouterPath()` gave `undefined`, or gave `null` to an
-        // actor with no route yet. The first later excursion of the host then came back to
-        // the mount point and read that stale debt as a restore: it pushed the route of the
-        // actor over the location that the user chose, with no `play.route` event for it.
-        this.hasSynchronizedUnderMount = true;
-        if (this.isEchoOfLastSync(machinePath, search))
-            return;
-        if (this.isProcessingNavigation)
-            return;
-        this.isProcessingNavigation = true;
-        try {
-            const nextRoute = buildPlayRouteEvent({
-                pathname: machinePath,
-                search,
-                match: (nextPathname) => matchRouteMap(nextPathname, this.routeMap, (resolvedPathname, stateId) => this.extractParams(resolvedPathname, stateId)),
-            });
-            if (!nextRoute) {
-                // The path is unknown, because the map holds no route of it.
-                // Push the current route of the actor back to the router. The browser URL therefore
-                // follows the actor state, and this corrects an invalid entry in the address bar on a
-                // cold load, and also a navigation to a path that is absent during a session.
-                //
-                // The code calls pushResolvedRoute() directly, and not syncRouterFromActor(). It
-                // therefore passes around the dedup guard, because lastSyncedPath holds the route of
-                // the actor already. pushResolvedRoute sets lastSyncedPath to the resolved concrete
-                // path before the push. Therefore the callback of the router for this navigation, a
-                // hashchange event or a history event, stops at the
-                // sanitized === lastSyncedPath guard, and it sends no false play.route event to the
-                // actor.
-                //
-                // isProcessingNavigation stays true here. The finally block below clears it after
-                // navigateRouter returns. That block therefore guards synchronously against a
-                // re-entrance of each router callback that fires at once.
-                const currentActorRoute = this.actor.currentRoute.get();
-                if (currentActorRoute) {
-                    this.pushResolvedRoute(currentActorRoute);
-                }
-                return;
-            }
-            // Record the location BEFORE the send, and record it with its query.
-            //
-            // The route atom of the actor notifies the watcher of the other direction
-            // for this same move, and `syncRouterFromActor` then tests the route of the
-            // actor against this field. Two details decide that test:
-            //
-            // - The write must happen first. A write after the send leaves the previous
-            //   path in the field while the watcher runs, so the test misses and the
-            //   bridge pushes the location that the router already holds. On a press on
-            //   BACK that push is a new history entry, and it replaces the entry that
-            //   FORWARD returns to.
-            // - The write must carry the query. A machine that republishes the query
-            //   holds `/second?id=1` as its route, and a pathname alone in this field
-            //   never matches it.
-            this.lastSyncedPath = withSearch(nextRoute.pathname, search);
-            // The router moved, and the actor has not answered yet, so the value that the
-            // bridge accounted for describes the agreement of the two sides NO MORE. A value
-            // that stayed read the answer of the actor as a repeat of the atom: a guard
-            // redirect BACK to the route the actor came from — the route that the seed of
-            // `connect()` recorded — stopped at the dedup, the bridge pushed nothing, and the
-            // address bar kept the location that the guard refused.
-            this.lastActorRoute = null;
-            this.actor.send(nextRoute.event);
-        }
-        catch (error) {
-            // An InvalidRoutePatternError needs an action of the DEVELOPER: a route of the
-            // machine declares a pattern that URLPattern refuses, and no location can fix it.
-            // It goes to the caller without a change, so that the caller can find it and read
-            // the pattern that it names.
-            if (error instanceof InvalidRoutePatternError) {
-                throw error;
-            }
-            throw new RouterSyncError("Failed to sync actor state from router location.", {
-                cause: error,
-            });
-        }
-        finally {
-            this.isProcessingNavigation = false;
-        }
-    }
-    // ── The utilities. They are protected, and a subclass overrides one to read the params of its framework ──
-    /**
-     * Reads the path parameters of a URL, with the URLPattern API.
-     *
-     * The API is always present: `@xmachines/play-router` uses the native URLPattern of the
-     * runtime, and it falls back to `urlpattern-polyfill`, which it carries as an ordinary
-     * dependency. A consumer therefore loads nothing, whatever the runtime.
-     *
-     * @param pathname - The real URL path, for example '/profile/john'
-     * @param stateId - The stateId of the match, for the lookup of the route pattern
-     * @returns The path parameters of the read, or an empty object when nothing matches
-     * @throws {InvalidRoutePatternError} When URLPattern cannot compile the route pattern
-     */
-    extractParams(pathname, stateId) {
-        const pattern = this.routeMap.getPathByStateId(stateId);
-        if (!pattern)
-            return {};
-        return extractRouteParams(pathname, pattern, this.compileOptions);
-    }
-    /**
-     * Resolves a value of an actor route to a concrete URL path for a navigation.
-     *
-     * A bridge that receives a raw `actor.currentRoute` value in `navigateRouter` calls
-     * this method to convert a stateId, with a `#` prefix or without one, into a path.
-     * The method returns `null` when a navigation is not possible:
-     * - an unknown stateId, with no entry in the route map
-     * - a parameterized pattern or a wildcard pattern, for example `/profile/:id` or
-     *   `/docs/*`, because no concrete value is available for a real URL
-     * - a string that is no path and no known stateId
-     *
-     * A LITERAL route of the map comes back with each escape resolved: `/tags/c\+\+` gives
-     * the path `/tags/c++`, which is the path that the route matches.
-     *
-     * A lookup of a stateId tries the form `"#stateId"` and the bare form `"stateId"`,
-     * through `lookupPathByStateId`. Therefore a route map of your own that holds one
-     * form only still resolves the path.
-     *
-     * The result is MACHINE-side: it carries no `basePath`, because it is also the
-     * value that `lastSyncedPath` stores and that the code compares against an actor
-     * route. The code adds the prefix one time, at the `navigateRouter()` call in
-     * `pushResolvedRoute`.
-     *
-     * @param route - The raw value of the actor route: a stateId, a stateId with a `#`, or a concrete path
-     * @returns The concrete machine-side URL path, or `null` when the bridge must skip the navigation
-     */
-    resolveNavigationPath(route) {
-        const mapped = this.lookupPathByStateId(route);
-        const path = mapped ?? (route.startsWith("/") ? route : null);
-        if (path === null)
-            return null;
-        // A LITERAL route resolves to the one path that it matches, and the source of a
-        // pattern is not always that path: `/tags/c\+\+` matches `/tags/c++`, and
-        // `/i18n/{en}` matches `/i18n/en`. A bridge that pushed the source wrote the
-        // backslashes and the braces into the address bar, where `getStateIdByPath` answered
-        // that location never — so the URL stopped following the actor, and its next move to
-        // the same route was suppressed as an echo of that push.
-        //
-        // The two branches above resolve DIFFERENT amounts, and the difference is what the
-        // string is:
-        //
-        // - A route of the MAP is a pattern source, so every construct in it is grammar and
-        //   the parse resolves all of it.
-        // - A route that the ACTOR built is a path already. `buildRouteUrl` of
-        //   `@xmachines/play-xstate` reads the whole grammar and resolves every escape, so
-        //   a route that IT built carries no backslash. An actor of another kind can still
-        //   write one, and a BACKSLASH is the one construct that means grammar in such a
-        //   path — and nothing else does. A brace in such a path is a real brace, and
-        //   `/i18n/{en}` from an actor is the location `/i18n/{en}`.
-        //
-        // A route of the map is a pattern source WHOLE, and its `?` is a modifier and never
-        // a query. The parse therefore reads all of it, and its answer is complete: a `null`
-        // literal path says that the pattern describes a SET of paths, so the bridge pushes
-        // nothing. A fall to the concrete-path test below answered that question with the
-        // characters of the string instead, and it let every pattern whose grammar carries
-        // no ":" and no "*" through — `/docs/rfc(2119)`, `/books{/v2}?` and `/files/(\d+)`
-        // all reached the address bar as they stand, where `getStateIdByPath` answers them
-        // never.
-        if (mapped != null)
-            return parsePattern(path, this.compileOptions).literalPath;
-        // A route of the ACTOR carries its query, because `context.query` travels in
-        // `currentRoute`, and the PATHNAME half alone reaches the grammar for it. A query
-        // holds a ":" and a "*" legally — a time in "?at=10:30", a URL in "?next=https://x",
-        // a glob in "?q=a*" — and it holds the "?" that the grammar reads as a modifier. A
-        // parse of the whole string called such a route malformed and resolved nothing of
-        // it, so `/tags/c\+\+?ref=nav` went to the address bar with both backslashes; a
-        // PATTERN test of the whole string called it a pattern, so `pushResolvedRoute` wrote
-        // `lastSyncedPath` and navigated nowhere, and the dedup guard then suppressed the
-        // next attempt at the same route as an echo. The suffix carries no grammar, and it
-        // travels to the router unchanged.
-        const { pathname, suffix } = splitLocation(path);
-        // A BACKSLASH is the one construct that reaches an actor route unresolved, and this
-        // is where it resolves.
-        if (pathname.includes("\\")) {
-            const literal = parsePattern(pathname, this.compileOptions).literalPath;
-            // The resolution FAILED, so this route resolves to no concrete path and the
-            // bridge pushes nothing. A fall to the test below refused none of it — a backslash
-            // is neither a ":" nor a "*" — so the SOURCE went to the address bar with its
-            // backslashes, where `getStateIdByPath` answers that location never, and
-            // `pushResolvedRoute` then recorded it and suppressed the next attempt at the same
-            // route as an echo. `encodeURIComponent` leaves "(", ")", "!", "'" and "~" as they
-            // stand, so a param value of `f(x)` under a template that carries an escape —
-            // `/files/c\+\+/:name` — reaches this line and derives no literal path.
-            return literal === null ? null : `${literal}${suffix}`;
-        }
-        // The test is `holdsUnsubstitutedParam` and NOT `isParameterizedPattern`, because
-        // this string is a concrete path and not a pattern. Its own documentation gives the
-        // reason: a real param value carries a character of the grammar often enough, and
-        // the grammar reads a modifier in "/tags/c++" and a group in "/i18n/{en}".
-        if (holdsUnsubstitutedParam(pathname))
-            return null;
-        return path;
-    }
-    /**
-     * Tells you whether the actor already stands on the PATH of a location of the router.
-     *
-     * The `currentRoute` of the actor can be a stateId, for example `"#app.home"`, while a
-     * location of the router is a URL path, for example `"/home"`. Therefore the method
-     * resolves the path to a stateId before it compares. Without this step, a false "the
-     * two are different" starts a synchronization that nothing needs — and, in
-     * `takeReturnUnderMount`, it reads a location that the HOST chose as a restore of the
-     * actor and writes over it.
-     *
-     * The actor is on the path in three cases: the stateId of the match IS the actor
-     * route, the path of the match IS the actor route, or the actor route is a stateId
-     * that resolves to the same registered path as the stateId of the match. Each lookup
-     * goes through {@link lookupPathByStateId}, which tries the form `"#stateId"` and also
-     * the bare form `"stateId"`. Therefore a route map with `"#about"` recognizes an actor
-     * route of `"about"`, and the opposite also works, and this is correct for a
-     * structural map of your own that holds one form.
-     *
-     * An actor route with a concrete path, which starts with `"/"`, goes to a direct
-     * comparison of the pathname against `machinePath`. That comparison runs BEFORE the
-     * map, because a location the map does not hold is still a location the actor can
-     * stand on.
-     *
-     * The QUERY is a question of its own, and {@link sameQuery} answers it. Each caller
-     * asks BOTH, and the two answers do different work. "The two sides are in step" needs
-     * the path AND the query, so a router that carries the only query is a deep link that
-     * the actor has to follow — for a stateId route as much as for a path route. The
-     * RESTORE needs the path, beside `carriesNoOwnSuffix`: an actor that stands here and
-     * carries no query and no fragment of its own has nothing to put in the address bar,
-     * and a push would only rewrite the location the user opened.
-     *
-     * A query that the ACTOR carries is a difference that this branch still reads as a
-     * restore, so an actor at `/?ref=nav` wins against a router at `/?other=1`. `main`
-     * answers the same way, and whether that is a deep link or a restore is a decision
-     * about the rule: issue #18 carries it, and a test pins the behaviour.
-     *
-     * Each lookup runs ONE time, and a caller that needs both answers calls this method
-     * one time too. `getPathByStateId` belongs to the route map: a map of a consumer can
-     * answer differently on a second call, and `RouteMap` pays a cache lookup for each of
-     * them.
-     *
-     * @param machinePath - The machine half of the location of the router, with no query.
-     * @param actorRoute  - The raw value of the actor route. It CAN carry a query.
-     */
-    isActorAtPath(machinePath, actorRoute) {
-        if (actorRoute == null)
-            return false;
-        // The PATHNAME half of the actor route.
-        //
-        // An actor route carries its QUERY, because `context.query` travels in
-        // `currentRoute`, and `machinePath` carries none — `sanitizePathname` cut it off
-        // before the caller stripped the prefix. The two are therefore never the identical
-        // string for a route with a query, and a comparison of the whole strings reported an
-        // actor standing exactly at this location as "somewhere else": `performInitialSync`
-        // read that as a deep link and sent a `play.route` for the state the actor was in
-        // already, so every entry action of that state ran a second time.
-        const { pathname: actorPath } = splitLocation(actorRoute);
-        // An ESCAPED literal route resolves on that same half, and its two forms are never
-        // the identical string: the actor carries `/tags/c\+\+`, which is what the template
-        // writes, and the router stands at `/tags/c++`, which is the path that the route
-        // matches and the path that `resolveNavigationPath` pushes. The resolution reads the
-        // PATHNAME, and not the whole string, for two reasons: a `?` is a modifier of the
-        // grammar that makes `/tags/c\+\+?ref=nav` malformed, and a query would key the
-        // bounded parse cache on a string that no route map holds.
-        const literalPath = actorPath.includes("\\")
-            ? parsePattern(actorPath, this.compileOptions).literalPath
-            : null;
-        // The pathname test answers with no map at all, and it has to run FIRST: the lookup
-        // below returns nothing for a location that the map does not hold, and the early
-        // return then reported an actor standing exactly at that location as "somewhere
-        // else". The seed of the constructor hid this for as long as one field carried the
-        // route of the actor AND the location.
-        if (machinePath === (literalPath ?? actorPath))
-            return true;
-        const resolvedStateId = this.routeMap.getStateIdByPath(machinePath);
-        if (resolvedStateId === null || resolvedStateId === undefined)
-            return false;
-        if (resolvedStateId === actorRoute)
-            return true;
-        if (actorRoute.startsWith("/"))
-            return false;
-        const actorStateIdPath = this.lookupPathByStateId(actorRoute);
-        return (actorStateIdPath != null &&
-            actorStateIdPath === this.lookupPathByStateId(resolvedStateId));
-    }
-    /**
-     * Returns the path of the route map for a value of an actor route, and it tries both
-     * forms of a stateId.
-     *
-     * The actor can emit `"#stateId"` while a route map of your own holds the bare form
-     * `"stateId"`, and also the opposite. `RouteMap` makes the canonical form
-     * internally, but the constructor accepts every structural
-     * `{ getStateIdByPath, getPathByStateId }` object: a plain test object and a map of
-     * one adapter are legal, and the documentation says so. Therefore this method tries
-     * both forms: the raw form first, then the form without the `#`, then the form with
-     * the `#`.
-     *
-     * @param route - The raw value of the actor route: a stateId, with a `#` prefix or without one
-     * @returns The path of the map, or `null` or `undefined` when no form is registered
-     */
-    lookupPathByStateId(route) {
-        const direct = this.routeMap.getPathByStateId(route);
-        if (direct != null)
-            return direct;
-        const alternate = route.startsWith("#") ? route.slice(1) : `#${route}`;
-        return this.routeMap.getPathByStateId(alternate);
-    }
-    /**
-     * Reads the query parameters of a URL search string.
-     *
-     * @param search - The URL search string, for example '?tab=security&page=1'
-     * @returns The query parameters of the read, or an empty object
-     */
-    extractQuery(search) {
-        return extractQuery(search);
-    }
-    /**
-     * True when a location of the router is the location that this bridge pushed.
-     *
-     * `lastSyncedPath` holds the value of `actor.currentRoute`, and that value carries
-     * the query string of `context.query`, for example `"/dates?trip=one-way"`. A router
-     * callback reports the pathname and the search SEPARATELY, and `sanitizePathname`
-     * removes the query. A comparison of the pathname alone therefore misses for every
-     * route with a query, and the push of this bridge comes back as a `play.route` event
-     * of its own navigation. That echo is not only wasted work: the bridge sends a
-     * `play.route` for a location that the actor stands on already, so every entry action
-     * of that state runs a second time, and a guard that refuses the repeat moves the
-     * actor to a state that no user asked for.
-     *
-     * The query is compared as a MAP, and not as a string: a framework can re-serialize
-     * a search string in another order, and `URLSearchParams` also accepts the form with
-     * a leading `?` and the form without one.
-     *
-     * @param sanitized - The clean pathname of the router callback, with no query.
-     * @param search - The search string of the router callback, when it has one.
-     * @returns True when the location is the echo of the last push of this bridge.
-     */
-    isEchoOfLastSync(sanitized, search) {
-        const last = this.lastSyncedPath;
-        if (last === null)
-            return false;
-        if (sanitized === last && (search ?? "") === "")
-            return true;
-        // Compare the query of BOTH sides. A pathname test alone reports an echo for a
-        // move that keeps the path and changes the query, which a filter link does, and
-        // which a `validateSearch` of a route does when it injects a default. The actor
-        // then never hears of the move, and the URL and the actor diverge.
-        const { pathname: lastPath, query: lastQuery } = splitLocation(last);
-        if (lastPath !== sanitized)
-            return false;
-        return sortedQuery(lastQuery) === sortedQuery(search ?? "");
-    }
-    /**
-     * Cleans a raw URL pathname of the router, and checks it.
-     *
-     * The method applies the limit of the path length, which is 2048 characters. It
-     * removes a query string and a fragment from the segment of the pathname, and it
-     * normalizes each sequence of slashes.
-     *
-     * An implementation that passes around `syncActorFromRouter()`, for example with a
-     * reactive watcher of its framework that receives a route object of a parse before,
-     * MUST call this method before it gives the path to a lookup in the route map.
-     * `syncActorFromRouter()` calls the method internally. Therefore a bridge that uses
-     * that method calls `sanitizePath` never itself.
-     *
-     * @param pathname - The raw URL pathname of the framework router.
-     * @returns The clean pathname, or `null` when the path is invalid or too long.
-     */
-    sanitizePath(pathname) {
-        return sanitizePathname(pathname);
-    }
-    /**
-     * Returns the current pathname of the router at the moment of `connect()`.
-     *
-     * `connect()` calls this method one time, for the first synchronization from the URL
-     * to the actor. router.subscribe() fires on a *later* navigation event only. It does
-     * not repeat the location that the router loaded before. A subclass that can read the
-     * current location of its router synchronously, for example with
-     * `router.state.location.pathname`, overrides this method. A deep link and a direct
-     * URL then drive the actor to the correct state, and they leave it not at the default
-     * of its machine.
-     *
-     * The meaning of each return value:
-     * - `string` → the router has a current path, and the base `connect()` writes the actor state from the router
-     * - `null` → the router is active, but it has no current path yet, and the base `connect()` writes the router from the actor
-     * - `undefined` → the adapter does the first synchronization itself, and the base `connect()` does nothing
-     *
-     * The default value is `undefined`. Therefore a bridge without this hook keeps its
-     * earlier behavior.
-     */
-    getInitialRouterPath() {
-        return undefined;
-    }
-    /**
-     * Returns the current search string of the router at the moment of `connect()`.
-     *
-     * This method is the pair of `getInitialRouterPath()`. `connect()` calls it one time,
-     * to give the query string of the first URL to `syncActorFromRouter()`. It returns
-     * `undefined` when the current URL of the router has no search string, and also when
-     * the subclass overrides the method not. `syncActorFromRouter` then makes an empty
-     * `query: {}` in the event.
-     *
-     * A subclass that overrides `getInitialRouterPath()` and has a query string
-     * overrides this method too.
-     *
-     * @returns The URL search string, for example `"?tab=security"`, or `undefined` when it is not available.
-     */
-    getInitialRouterSearch() {
-        return undefined;
-    }
-}
+* RouterBridgeBase — the abstract base class of every framework router adapter
+*
+* The class holds the logic that each router bridge shares, and that is 90% of the
+* code of every bridge:
+* - The atom watcher of the direction from the actor to the router
+* - `lastSyncedPath`, for the echo suppression in the direction from the actor to the router
+* - The `isProcessingNavigation` flag, which stops a loop of a guard redirect in `syncActorFromRouter` only
+* - `syncRouterFromActor` and `syncActorFromRouter`, with the read of each URL parameter
+* - The connect and disconnect lifecycle of the RouterBridge protocol
+*
+* A subclass implements the 3 abstract methods of its framework only:
+* - navigateRouter(path): how the bridge tells the framework router to navigate
+* - watchRouterChanges(): how the bridge subscribes to each location change of the router
+* - unwatchRouterChanges(): how the bridge cancels that subscription
+*
+* @example
+* ```typescript
+* export class MyRouterBridge extends RouterBridgeBase {
+*   private unsubscribe: (() => void) | null = null;
+*
+*   constructor(private router: MyRouter, actor: RoutableActor, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
+*     super(actor, routeMap);
+*   }
+*
+*   protected navigateRouter(path: string): void {
+*     this.router.navigate(path);
+*   }
+*
+*   protected watchRouterChanges(): void {
+*     this.unsubscribe = this.router.subscribe((state) => {
+*       this.syncActorFromRouter(state.location.pathname, state.location.search);
+*     });
+*   }
+*
+*   protected unwatchRouterChanges(): void {
+*     this.unsubscribe?.();
+*     this.unsubscribe = null;
+*   }
+* }
+* ```
+*
+* @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
+*/
+/**
+* The registry of the actors with an active bridge connection, at the module level.
+*
+* The key is the actor instance, and the registry is a WeakMap, which holds no
+* reference. The class uses it to find and refuse a second `connect()` call of the
+* same actor. Such a call makes two `play.route` events for one navigation, and it
+* makes two `lastSyncedPath` values of the echo suppression that contradict each
+* other.
+*
+* @internal
+*/
+var activeBridges = /* @__PURE__ */ new WeakMap();
+var RouterBridgeBase = class {
+	actor;
+	routeMap;
+	isConnected = false;
+	hasConnectedOnce = false;
+	/**
+	* The machine-side location that the router holds, as far as this bridge knows. It
+	* carries the query and the fragment, and it carries NO `basePath`.
+	*
+	* Only code that saw a location, or that wrote one, writes this field:
+	* `performInitialSync` when it finds the two sides in step, `takeReturnUnderMount`
+	* for the same test under a mount, `pushResolvedRoute` after it resolves a route to
+	* a concrete path, and `syncActorFromRouter` for the location that the router
+	* reports. `null` means that this bridge placed no location yet, so it knows nothing
+	* about the address bar, and every test against this field must then answer "no".
+	*
+	* The field held the route of the actor as well, from the seed of the constructor
+	* and from a route that resolves to no URL. Those two values describe no location
+	* that a router ever showed, and each reader of this field asks about a location, so
+	* each of them read them wrongly. {@link lastActorRoute} holds them now.
+	*/
+	lastSyncedPath = null;
+	/**
+	* The raw value of `actor.currentRoute` that this bridge accounted for already.
+	*
+	* The field answers ONE question: "did the bridge see this value of the atom
+	* before?". It is therefore a string, and not a location — a route that resolves to
+	* no URL, such as an unknown stateId or a parameterized pattern, still stops a
+	* second attempt at the same value.
+	*
+	* The constructor and `connect()` seed it, so that the first fire of the watcher of
+	* the atom pushes nothing for a route that moved nowhere.
+	*/
+	lastActorRoute = null;
+	/**
+	* The flag guards `syncActorFromRouter` against a re-entrant call from a guard
+	* redirect of the actor itself. Such a call has this sequence: the bridge sends to
+	* the actor, the atom fires, the bridge pushes to the router, and a second
+	* `syncActorFromRouter` call starts before the first one returns.
+	*
+	* The flag is NOT the echo suppression of the direction from the actor to the
+	* router. `lastSyncedPath` does that work alone: the bridge writes it before the
+	* `navigateRouter()` call. Therefore each router callback of the same location stops
+	* at the {@link isEchoOfLastSync} test in `syncActorFromRouter`.
+	*/
+	isProcessingNavigation = false;
+	/**
+	* Who owns the address bar, and what this bridge owes it.
+	*
+	* - `"under-mount"` — the location lies under the mount, so this bridge owns the
+	*   address bar and it writes the location for every route of its actor.
+	* - `"outside"` — the location lies outside the mount, so the HOST owns it. The
+	*   bridge sends no event and it corrects no URL, which is what lets the routes of
+	*   the host and the routes of the machine share one router.
+	* - `"outside-push-owed"` — outside, AND the route of the actor changed while the
+	*   host owned the address bar. The push waits here instead of going to the router,
+	*   and {@link RouterBridgeBase.takeReturnUnderMount} spends it when the location
+	*   comes back. The machine therefore keeps its place while the user reads a page of
+	*   the host.
+	*
+	* ONE value, and not a latch plus a memory. The memory only ever means something
+	* while the latch is up, so two fields could hold a fourth combination that says
+	* "the bridge owns the address bar AND a push waits for a return" — a state with no
+	* meaning, which a return would spend at a location the router already holds. Two
+	* writes also cannot happen together: every site that lowered the latch wrote the
+	* memory on the NEXT line, and the value between the two lines was that fourth
+	* combination. `takeReturnUnderMount` reads the value it replaces instead.
+	*
+	* `syncActorFromRouter` is the one place that sees a location, so it is the one
+	* place that decides between `"under-mount"` and `"outside"`.
+	* `performInitialSync` decides it for the location that the page loaded with.
+	*
+	* A bridge with no mount never leaves its mount: `stripBasePath` returns the path
+	* unchanged for an empty prefix, and never `null`. The value therefore stays
+	* `"under-mount"` for every bridge that takes no `basePath`.
+	*/
+	mountState = "under-mount";
+	/**
+	* True once the first synchronization ran against a location INSIDE the mount.
+	*
+	* `performInitialSync` separates a deep link from a restore, and it can make that
+	* decision only for a location that lies under the mount. A bridge that connects
+	* while the host owns the address bar therefore reaches no decision at all: it
+	* raises the latch and returns. The flag says that the decision is still owed, and
+	* `syncActorFromRouter` pays it at the first location that IS under the mount —
+	* through {@link RouterBridgeBase.takeReturnUnderMount} for a RETURN, which needs the
+	* decision itself, and directly for every other location under the mount.
+	*
+	* A bridge with no mount never leaves its mount, so `performInitialSync` writes this
+	* flag on the first `connect()` and nothing reads it again.
+	*/
+	hasSynchronizedUnderMount = false;
+	routeWatcher = null;
+	/**
+	* The mount point of the machine inside the host router: the resolved prefix, and
+	* the values of each `:param` of that prefix.
+	*
+	* The prefix lives here, and NOT in the route map, for two reasons. 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. And
+	* the bridge is the boundary between a location of the host router and a path of
+	* the machine already, which is exactly what the prefix separates.
+	*
+	* `lastSyncedPath` stays MACHINE-side, and it carries no prefix. The code adds the
+	* prefix at the one `navigateRouter()` call in `pushResolvedRoute`, and it removes
+	* the prefix at the one inbound entry point `syncActorFromRouter`. Every test of
+	* the echo suppression therefore keeps comparing like with like.
+	*/
+	mount = NO_BASE_PATH;
+	/**
+	* The caches that every parse and every compilation of this bridge reads.
+	*
+	* `resolveNavigationPath` and `isActorAtPath` parse a CONCRETE location, and an
+	* application writes one for each value that it puts in a param.
+	*/
+	compileOptions;
+	/**
+	* @param actor    - A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.
+	* @param routeMap - The route map of both directions, for the resolution between a
+	*   `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A
+	*   framework adapter usually wraps the result of `createRouteMap(machine)`, or an
+	*   equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the
+	*   bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
+	*   of your own, for example a plain test object, handles one form only.
+	*/
+	constructor(actor, routeMap, options) {
+		this.actor = actor;
+		this.routeMap = routeMap;
+		this.compileOptions = {
+			patternCache: options?.patternCache,
+			compiledCache: options?.compiledCache
+		};
+		this.mount = resolveBasePath(options?.basePath, options?.basePathParams);
+		this.lastActorRoute = this.actor.currentRoute.get() ?? null;
+	}
+	/**
+	* The resolved URL prefix that the machine of this bridge is mounted under, or `""`
+	* when the machine owns the complete router.
+	*/
+	get basePath() {
+		return this.mount.path;
+	}
+	/**
+	* The resolved values of the `:param` segments of the mount, or `{}` for a prefix
+	* without a param.
+	*
+	* These params belong to the HOST: the host wrote the prefix and resolved the
+	* values, and they describe the route of the host and not the route of the machine.
+	* They therefore 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.
+	*
+	* They live here instead, because a value that reached the actor on a navigation
+	* ALONE would go stale: `setBasePath()` can move the mount while the machine stays
+	* on the same route, no event goes out, and `event.params` would then contradict
+	* `basePath`. A read of this accessor cannot go stale.
+	*
+	* 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.
+	*
+	* @example
+	* ```typescript
+	* bridge.basePath;        // "/abc123/play"
+	* bridge.basePathParams;  // { machineId: "abc123" }
+	* ```
+	*/
+	get basePathParams() {
+		return this.mount.params;
+	}
+	/**
+	* Moves the machine to a different mount point, while it stays connected.
+	*
+	* This is the "load and unload" half of a shared router. It moves WHERE an actor is
+	* mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU
+	* cache all stay, and nothing goes away.
+	*
+	* An actor never changes identity. A 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. The segments that move here are the
+	* ones that LOCATE: a region, a locale, a tenant, a workspace slug.
+	*
+	* The call then brings the location in step with the NEW prefix. A location inside
+	* the new mount runs the same first-synchronization decision as `connect()`: it
+	* drives the actor, and a restore keeps the route of the actor. A location OUTSIDE
+	* the new mount is the old mount in practice, so the bridge writes the new one
+	* itself, and it keeps the route of the actor while it does so — nothing else moves
+	* the address bar. A call that resolves to the current prefix changes no location,
+	* and it therefore reconciles nothing.
+	*
+	* @param basePath - The new prefix, as a pattern or as a concrete path. An absent
+	*   value, `""`, and `"/"` all remove the prefix, and they give the machine the
+	*   complete router again.
+	* @param basePathParams - The values of the `:param` segments of `basePath`.
+	* @throws {InvalidBasePathError} For a prefix that resolves to one concrete path never.
+	* @throws {MissingBasePathParamError} When a `:param` of the prefix has no value.
+	*
+	* @example
+	* ```typescript
+	* // The host moved this actor to another place in its URL space. `machineId` names
+	* // WHICH document the actor runs, and it does not change: a new identity is a new
+	* // actor, and therefore a new bridge, because one actor takes one bridge.
+	* bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
+	* ```
+	*/
+	setBasePath(basePath, basePathParams) {
+		const next = resolveBasePath(basePath, basePathParams);
+		const samePath = next.path === this.mount.path;
+		this.mount = next;
+		if (samePath) return;
+		if (this.isConnected) {
+			this.lastSyncedPath = null;
+			this.mountState = "under-mount";
+			this.hasSynchronizedUnderMount = false;
+			this.reconcileLocationWithMount();
+		}
+	}
+	/**
+	* Brings the location of the router in step with a mount that just moved.
+	*
+	* **The location lies under the new mount:** run the same first-synchronization
+	* decision as `connect()`, so a location inside the mount drives the actor and a
+	* restore keeps the route of the actor.
+	*
+	* **The location lies outside it:** the bridge writes the new mount ITSELF, and it
+	* keeps the route of the actor while it does so. A host that re-points a mount
+	* changes no location by itself, and nothing else moves the address bar. Without
+	* this push the machine sits at a mount that no location is under: it hears no
+	* `play.route`, `lastSyncedPath` is clear already, and the stale prefix stays in the
+	* URL until the route of the actor happens to change — which then jumps the URL with
+	* no reason that the history of the user explains.
+	*
+	* `pushResolvedRoute` writes `lastSyncedPath` before it navigates, so the callback
+	* of the router for this push stops at the echo suppression, and it sends no event.
+	*/
+	reconcileLocationWithMount() {
+		const routerPath = this.getInitialRouterPath();
+		const sanitized = typeof routerPath === "string" ? sanitizePathname(routerPath) : null;
+		if (typeof routerPath !== "string" || sanitized === null) {
+			this.performInitialSync(routerPath);
+			return;
+		}
+		if (stripBasePath(sanitized, this.mount.path) !== null) {
+			this.performInitialSync(routerPath);
+			return;
+		}
+		const currentActorRoute = this.actor.currentRoute.get();
+		if (!currentActorRoute) {
+			this.markOutside();
+			return;
+		}
+		const resolved = this.resolveNavigationPath(currentActorRoute);
+		if (resolved === null) {
+			this.mountState = "outside-push-owed";
+			return;
+		}
+		this.mountState = "under-mount";
+		this.hasSynchronizedUnderMount = true;
+		this.pushHoldingNavigation(currentActorRoute, resolved);
+	}
+	/**
+	* Pushes a route to the router, and it holds {@link isProcessingNavigation} across
+	* the write.
+	*
+	* Every corrective push of the bridge needs that flag: `navigateRouter` makes the
+	* router call `syncActorFromRouter` again inside it, and a router that NORMALIZES the
+	* location it receives — a `validateSearch` that injects a default, a trailing slash
+	* that a history adds — reports a value that the echo test misses. The bridge would
+	* then answer its own write with a `play.route` event, and on a press of BACK that
+	* answer is a history entry that FORWARD cannot return to.
+	*
+	* The one push that does NOT come through here is `syncRouterFromActor`: that push
+	* follows the actor, and the echo suppression of `lastSyncedPath` is what stops it.
+	*
+	* @param route    - The raw value of the actor route.
+	* @param resolved - The concrete path of that route, when the caller resolved it
+	*   already. `undefined` resolves it in `pushResolvedRoute`.
+	*/
+	pushHoldingNavigation(route, resolved) {
+		this.isProcessingNavigation = true;
+		try {
+			this.pushResolvedRoute(route, resolved);
+		} finally {
+			this.isProcessingNavigation = false;
+		}
+	}
+	/**
+	* Connects the router bridge to the Actor.
+	*
+	* The method installs the atom watcher of the direction from the actor to the
+	* router. It then starts the watch of the router changes, which each framework does
+	* in its own way.
+	*
+	* The order of these steps is part of the contract of the bridge:
+	* - The constructor seeds `lastActorRoute` from `actor.currentRoute`, and it records no location
+	* - The method installs the actor watcher before the router subscriptions of the adapter
+	* - The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
+	*
+	* An adapter that needs a different behavior of the first synchronization overrides
+	* `getInitialRouterPath()`. It does not change the order of the steps of
+	* `connect()`.
+	*/
+	connect() {
+		if (this.isConnected) return;
+		const existingBridge = activeBridges.get(this.actor);
+		if (existingBridge !== void 0 && existingBridge !== this) throw new DuplicateBridgeError();
+		activeBridges.set(this.actor, this);
+		this.lastActorRoute = this.actor.currentRoute.get() ?? null;
+		this.lastSyncedPath = null;
+		this.isConnected = true;
+		this.hasConnectedOnce = true;
+		try {
+			this.routeWatcher = createRouteWatcher(this.actor.currentRoute, (route) => {
+				this.syncRouterFromActor(route);
+			});
+			this.watchRouterChanges();
+			this.performInitialSync(this.getInitialRouterPath());
+		} catch (error) {
+			try {
+				this.disconnect();
+			} catch {}
+			throw error;
+		}
+	}
+	/**
+	* Brings the actor and the router in step one time, and decides which side wins.
+	*
+	* The method is separate from `connect()`, so that `connect()` can roll the whole
+	* first synchronization back when it throws. See the `try` block there.
+	*
+	* The first synchronization: the direction from the router to the actor has the
+	* priority over the other direction.
+	*
+	* The page can load on a URL that is not the initial state of the actor. For
+	* example, the user types "/about", or the user follows a deep link. The router
+	* holds the correct path then, and the actor is still at its initial state ("/").
+	* The code must therefore drive the actor to the URL, and it must not write the
+	* default of the actor to the URL.
+	*
+	* router.subscribe() fires on a *later* navigation event only. It does NOT fire for
+	* the location that the page loaded. A subclass that can read the current location
+	* of its router synchronously overrides getInitialRouterPath().
+	*
+	* @param initialRouterPath - The location of the router. Every caller reads it and
+	*   passes it, and this parameter carries NO default: a default fires for an
+	*   explicit `undefined` too, so `reconcileLocationWithMount` asked the adapter a
+	*   SECOND time for exactly the value that says "the adapter does the first
+	*   synchronization itself" — and a read belongs to the adapter, which can walk the
+	*   state of a router and answer differently on the second call.
+	*/
+	performInitialSync(initialRouterPath) {
+		const initialActorRoute = this.actor.currentRoute.get();
+		let search;
+		let searchRead = false;
+		const routerSearch = () => {
+			if (!searchRead) {
+				search = this.getInitialRouterSearch();
+				searchRead = true;
+			}
+			return search;
+		};
+		if (typeof initialRouterPath === "string") {
+			const sanitized = sanitizePathname(initialRouterPath);
+			if (sanitized === null) return;
+			const machinePath = stripBasePath(sanitized, this.mount.path);
+			if (machinePath === null) {
+				this.markOutside();
+				return;
+			}
+			this.mountState = "under-mount";
+			this.hasSynchronizedUnderMount = true;
+			const actorAtRouterPath = this.isActorAtPath(machinePath, initialActorRoute);
+			if (actorAtRouterPath && initialActorRoute != null && sameQuery(initialActorRoute, routerSearch())) this.lastSyncedPath = withSearch(machinePath, routerSearch());
+			else if (initialActorRoute && isAtInitialLocation(this.actor.initialRoute, machinePath, routerSearch()) && initialActorRoute !== this.actor.initialRoute && !(actorAtRouterPath && carriesNoOwnSuffix(initialActorRoute))) this.pushHoldingNavigation(initialActorRoute);
+			else this.syncActorFromRouter(initialRouterPath, routerSearch());
+		} else if (initialActorRoute && initialRouterPath === null) {
+			this.pushHoldingNavigation(initialActorRoute);
+			this.hasSynchronizedUnderMount = true;
+		} else if (initialActorRoute && initialActorRoute !== this.lastActorRoute) {
+			this.syncRouterFromActor(initialActorRoute);
+			this.hasSynchronizedUnderMount = true;
+		}
+	}
+	/**
+	* Disconnects the router bridge from the Actor.
+	*
+	* The method stops the watch of the atom, and it removes the router listener of the
+	* framework.
+	*/
+	disconnect() {
+		const hadRouteWatcher = this.routeWatcher !== null;
+		if (this.routeWatcher) try {
+			this.routeWatcher.unwatch();
+		} catch {}
+		this.routeWatcher = null;
+		try {
+			if (this.isConnected || hadRouteWatcher) this.unwatchRouterChanges();
+		} catch {} finally {
+			this.isProcessingNavigation = false;
+			this.isConnected = false;
+			this.mountState = "under-mount";
+			this.hasSynchronizedUnderMount = false;
+			if (activeBridges.get(this.actor) === this) activeBridges.delete(this.actor);
+		}
+	}
+	/**
+	* Writes the location of the router when the route atom of the actor changes.
+	*
+	* The method resolves the actor route to a concrete URL path, then it calls
+	* navigateRouter() for the navigation of the framework. When it cannot resolve the
+	* route, which happens for an unknown stateId and for a parameterized pattern
+	* without concrete values, it skips the push completely: `navigateRouter` receives a
+	* raw stateId or a pattern never.
+	*
+	* `lastSyncedPath` does the complete echo suppression, which stops the callback of
+	* the router from a send to the actor: the method writes the resolved path to
+	* `lastSyncedPath` before the `navigateRouter()` call. Therefore each
+	* `syncActorFromRouter` call of the same path stops at the
+	* `sanitized === lastSyncedPath` test, and it sends no event. This is correct for a
+	* synchronous callback and for an asynchronous callback.
+	*
+	* The method does NOT set `isProcessingNavigation`. That flag lives inside
+	* `syncActorFromRouter`, and it guards against a re-entrant loop of a guard
+	* redirect.
+	*/
+	syncRouterFromActor(route) {
+		if (this.hasConnectedOnce && !this.isConnected) return;
+		if (!route || typeof route !== "string") return;
+		const echo = this.testEchoOfLastPush(route);
+		if (this.mountState !== "under-mount") {
+			this.mountState = echo.isEcho ? "outside" : "outside-push-owed";
+			return;
+		}
+		if (echo.isEcho) return;
+		this.pushResolvedRoute(route, echo.resolved);
+	}
+	/**
+	* Records that the location lies outside the mount, so the HOST owns the address bar.
+	*
+	* A bridge that is outside ALREADY keeps the value it holds: `"outside-push-owed"`
+	* says that a push waits for the address bar to come back, and a second location of
+	* the host is no reason to forget it.
+	*/
+	markOutside() {
+		if (this.mountState === "under-mount") this.mountState = "outside";
+	}
+	/**
+	* Takes the return of the address bar under the mount.
+	*
+	* The actor wins that return when it moved while the host owned the location AND the
+	* address bar came back to the location it still held: the method pushes the route of
+	* the actor, and the caller sends no `play.route` event. A return to any other route
+	* of the mount belongs to the host, so the memory goes and the caller drives the
+	* actor from the location instead.
+	*
+	* The method also pays the first synchronization that the mount still owes. A bridge
+	* that connected while the host owned the address bar reached no decision between a
+	* deep link and a restore: `performInitialSync` can decide only for a location under
+	* the mount, and it found none. This is the first such location, so the decision runs
+	* here, with the same rule.
+	*
+	* The method holds `isProcessingNavigation` across each push, because
+	* `navigateRouter` makes the router call `syncActorFromRouter` again.
+	*
+	* @returns `true` when the method handled the location, so the caller returns.
+	*/
+	takeReturnUnderMount(machinePath, search) {
+		const previous = this.mountState;
+		if (previous === "under-mount") return false;
+		this.mountState = "under-mount";
+		const owesFirstSync = !this.hasSynchronizedUnderMount;
+		this.hasSynchronizedUnderMount = true;
+		const restoredRoute = this.actor.currentRoute.get();
+		const actorAtPath = owesFirstSync && this.isActorAtPath(machinePath, restoredRoute);
+		const actorAtLocation = actorAtPath && restoredRoute != null && sameQuery(restoredRoute, search);
+		if (owesFirstSync && restoredRoute && isAtInitialLocation(this.actor.initialRoute, machinePath, search) && restoredRoute !== this.actor.initialRoute && !actorAtLocation && !(actorAtPath && carriesNoOwnSuffix(restoredRoute))) return this.pushUnderMount(restoredRoute);
+		if (owesFirstSync) {
+			if (actorAtLocation) {
+				this.lastSyncedPath = withSearch(machinePath, search);
+				return true;
+			}
+			this.lastSyncedPath = null;
+			return false;
+		}
+		if (previous !== "outside-push-owed") return false;
+		if (!this.isEchoOfLastSync(machinePath, search)) return false;
+		if (!restoredRoute) return false;
+		return this.pushUnderMount(restoredRoute);
+	}
+	/**
+	* Writes the route of the actor to a router that just came under the mount.
+	*
+	* The method holds `isProcessingNavigation` across the push, because
+	* `navigateRouter` makes the router call `syncActorFromRouter` again inside it.
+	*
+	* A re-entrant call pushes nothing inside another push, and the memory of a
+	* suppressed push DOES survive that case: the outer push is still in flight, and a
+	* clear here would throw the remembered route away with nothing left to replay it.
+	*
+	* @param route - The raw value of the actor route.
+	* @returns `true` when the method wrote the location, so that the caller returns and
+	*   sends no event. `false` when the route resolves to no concrete path, so that the
+	*   caller drives the actor from the location instead.
+	*/
+	pushUnderMount(route) {
+		if (this.isProcessingNavigation) return true;
+		const resolved = this.resolveNavigationPath(route);
+		if (resolved === null) {
+			this.lastSyncedPath = null;
+			return false;
+		}
+		this.pushHoldingNavigation(route, resolved);
+		return true;
+	}
+	/**
+	* Tests a route of the actor against the last synchronized location.
+	*
+	* The exact string test covers a stateId, for example `"#home"`, which
+	* `pushResolvedRoute` writes to the field when it cannot resolve a path. The query
+	* test covers a location that carries a query: the order of the keys of a query is
+	* not significant, so `?b=2&a=1` and `?a=1&b=2` are the same location, and the
+	* bridge must push neither of them back.
+	*
+	* The FRAGMENT counts in this direction, and the inbound test ignores it. The two
+	* are different questions. `navigateRouter` writes the whole value that the actor
+	* gave — `buildRouteUrl` appends `context.hash` — so `"/docs"` and `"/docs#intro"`
+	* are two locations to write, and a test that read them as one left the fragment out
+	* of the address bar for ever. `isEchoOfLastSync` compares against what the ROUTER
+	* reports, and `sanitizePathname` has removed the fragment from that already.
+	*/
+	testEchoOfLastPush(route) {
+		if (route === this.lastActorRoute) return { isEcho: true };
+		const location = this.lastSyncedPath;
+		if (location === null) return {
+			isEcho: false,
+			resolved: this.resolveNavigationPath(route)
+		};
+		if (sameLocation(route, location)) return { isEcho: true };
+		const resolved = this.resolveNavigationPath(route);
+		if (resolved !== null && sameLocation(resolved, location)) return { isEcho: true };
+		return {
+			isEcho: false,
+			resolved
+		};
+	}
+	/**
+	* Resolves an actor route to its concrete URL path, and pushes that path to the
+	* router.
+	*
+	* lastSyncedPath must hold the concrete path, because the callback of the router
+	* fires with the concrete path. The two values therefore match, and
+	* syncActorFromRouter stops. A raw stateId in that field, for example "#home", does
+	* not match the sanitized path ("/") in the watcher.
+	*
+	* When resolveNavigationPath returns null, which happens for a parameterized
+	* pattern, for a wildcard pattern, and for an unknown id, the method skips the push
+	* completely: a push of the raw value writes a stateId, a `:param` pattern, or a
+	* literal `*` into the browser URL. The method still writes the raw route to
+	* lastActorRoute, and it leaves lastSyncedPath as it stands, because that field
+	* records a LOCATION and no location changed. Therefore the dedup guard fires
+	* correctly on the next identical value of the atom.
+	*
+	* @param route    - The raw value of the actor route.
+	* @param resolved - The concrete path of that route. The default resolves it here. A
+	*   caller that resolved it already passes it, so that `resolveNavigationPath` runs
+	*   one time: the method is `protected`, and a subclass can override it.
+	*/
+	pushResolvedRoute(route, resolved = this.resolveNavigationPath(route)) {
+		this.lastActorRoute = route;
+		if (resolved === null) return;
+		this.lastSyncedPath = resolved;
+		this.navigateRouter(joinBasePath(this.mount.path, resolved));
+	}
+	/**
+	* Writes the actor state when the location of the router changes.
+	*
+	* **A known path:** the method sends a `play.route` event to the actor, with the
+	* stateId of the match, the params, and the query. The `isProcessingNavigation` flag
+	* stops a circular update.
+	*
+	* **An unknown path, or a path with no entry in the map:** the method sends NO
+	* `play.route` event, and the actor state stays as it is. It corrects the browser URL
+	* instead, with a `navigateRouter(actor.currentRoute.get())` call. The URL therefore
+	* follows the actor state, also when the user types an invalid path in the address
+	* bar, or when the code pushes such a path during a session. The method writes the
+	* resolved concrete path to `lastSyncedPath` before the `navigateRouter` call.
+	* Therefore the callback of the router for that navigation stops at the guard of the
+	* echo suppression, and it sends no false event.
+	*/
+	syncActorFromRouter(pathname, search) {
+		if (this.hasConnectedOnce && !this.isConnected) return;
+		if (typeof pathname !== "string") return;
+		const sanitized = sanitizePathname(pathname);
+		if (sanitized === null) return;
+		const machinePath = stripBasePath(sanitized, this.mount.path);
+		if (machinePath === null) {
+			this.markOutside();
+			return;
+		}
+		if (this.takeReturnUnderMount(machinePath, search)) return;
+		this.hasSynchronizedUnderMount = true;
+		if (this.isEchoOfLastSync(machinePath, search)) return;
+		if (this.isProcessingNavigation) return;
+		this.isProcessingNavigation = true;
+		try {
+			const nextRoute = buildPlayRouteEvent({
+				pathname: machinePath,
+				search,
+				match: (nextPathname) => matchRouteMap(nextPathname, this.routeMap, (resolvedPathname, stateId) => this.extractParams(resolvedPathname, stateId))
+			});
+			if (!nextRoute) {
+				const currentActorRoute = this.actor.currentRoute.get();
+				if (currentActorRoute) this.pushResolvedRoute(currentActorRoute);
+				return;
+			}
+			this.lastSyncedPath = withSearch(nextRoute.pathname, search);
+			this.lastActorRoute = null;
+			this.actor.send(nextRoute.event);
+		} catch (error) {
+			if (error instanceof InvalidRoutePatternError) throw error;
+			throw new RouterSyncError("Failed to sync actor state from router location.", { cause: error });
+		} finally {
+			this.isProcessingNavigation = false;
+		}
+	}
+	/**
+	* Reads the path parameters of a URL, with the URLPattern API.
+	*
+	* The API is always present: `@xmachines/play-url` uses the native URLPattern of the
+	* runtime, and it falls back to `urlpattern-polyfill`, which it carries as an ordinary
+	* dependency. A consumer therefore loads nothing, whatever the runtime.
+	*
+	* @param pathname - The real URL path, for example '/profile/john'
+	* @param stateId - The stateId of the match, for the lookup of the route pattern
+	* @returns The path parameters of the read, or an empty object when nothing matches
+	* @throws {InvalidRoutePatternError} When URLPattern cannot compile the route pattern
+	*/
+	extractParams(pathname, stateId) {
+		const pattern = this.routeMap.getPathByStateId(stateId);
+		if (!pattern) return {};
+		return extractRouteParams(pathname, pattern, this.compileOptions);
+	}
+	/**
+	* Resolves a value of an actor route to a concrete URL path for a navigation.
+	*
+	* A bridge that receives a raw `actor.currentRoute` value in `navigateRouter` calls
+	* this method to convert a stateId, with a `#` prefix or without one, into a path.
+	* The method returns `null` when a navigation is not possible:
+	* - an unknown stateId, with no entry in the route map
+	* - a parameterized pattern or a wildcard pattern, for example `/profile/:id` or
+	*   `/docs/*`, because no concrete value is available for a real URL
+	* - a string that is no path and no known stateId
+	*
+	* A LITERAL route of the map comes back with each escape resolved: `/tags/c\+\+` gives
+	* the path `/tags/c++`, which is the path that the route matches.
+	*
+	* A lookup of a stateId tries the form `"#stateId"` and the bare form `"stateId"`,
+	* through `lookupPathByStateId`. Therefore a route map of your own that holds one
+	* form only still resolves the path.
+	*
+	* The result is MACHINE-side: it carries no `basePath`, because it is also the
+	* value that `lastSyncedPath` stores and that the code compares against an actor
+	* route. The code adds the prefix one time, at the `navigateRouter()` call in
+	* `pushResolvedRoute`.
+	*
+	* @param route - The raw value of the actor route: a stateId, a stateId with a `#`, or a concrete path
+	* @returns The concrete machine-side URL path, or `null` when the bridge must skip the navigation
+	*/
+	resolveNavigationPath(route) {
+		const mapped = this.lookupPathByStateId(route);
+		const path = mapped ?? (route.startsWith("/") ? route : null);
+		if (path === null) return null;
+		if (mapped != null) return parsePattern(path, this.compileOptions).literalPath;
+		const { pathname, suffix } = splitLocation(path);
+		if (pathname.includes("\\")) {
+			const literal = parsePattern(pathname, this.compileOptions).literalPath;
+			return literal === null ? null : `${literal}${suffix}`;
+		}
+		if (holdsUnsubstitutedParam(pathname)) return null;
+		return path;
+	}
+	/**
+	* Tells you whether the actor already stands on the PATH of a location of the router.
+	*
+	* The `currentRoute` of the actor can be a stateId, for example `"#app.home"`, while a
+	* location of the router is a URL path, for example `"/home"`. Therefore the method
+	* resolves the path to a stateId before it compares. Without this step, a false "the
+	* two are different" starts a synchronization that nothing needs — and, in
+	* `takeReturnUnderMount`, it reads a location that the HOST chose as a restore of the
+	* actor and writes over it.
+	*
+	* The actor is on the path in three cases: the stateId of the match IS the actor
+	* route, the path of the match IS the actor route, or the actor route is a stateId
+	* that resolves to the same registered path as the stateId of the match. Each lookup
+	* goes through {@link lookupPathByStateId}, which tries the form `"#stateId"` and also
+	* the bare form `"stateId"`. Therefore a route map with `"#about"` recognizes an actor
+	* route of `"about"`, and the opposite also works, and this is correct for a
+	* structural map of your own that holds one form.
+	*
+	* An actor route with a concrete path, which starts with `"/"`, goes to a direct
+	* comparison of the pathname against `machinePath`. That comparison runs BEFORE the
+	* map, because a location the map does not hold is still a location the actor can
+	* stand on.
+	*
+	* The QUERY is a question of its own, and {@link sameQuery} answers it. Each caller
+	* asks BOTH, and the two answers do different work. "The two sides are in step" needs
+	* the path AND the query, so a router that carries the only query is a deep link that
+	* the actor has to follow — for a stateId route as much as for a path route. The
+	* RESTORE needs the path, beside `carriesNoOwnSuffix`: an actor that stands here and
+	* carries no query and no fragment of its own has nothing to put in the address bar,
+	* and a push would only rewrite the location the user opened.
+	*
+	* A restore also needs the router at the initial URL, and {@link isAtInitialLocation}
+	* compares the query there too. An actor at `/?ref=nav` therefore loses against a
+	* router at `/?other=1`: the user opened a URL that the machine does not start at,
+	* and that is a deep link (issue #18).
+	*
+	* Each lookup runs ONE time, and a caller that needs both answers calls this method
+	* one time too. `getPathByStateId` belongs to the route map: a map of a consumer can
+	* answer differently on a second call, and `RouteMap` pays a cache lookup for each of
+	* them.
+	*
+	* @param machinePath - The machine half of the location of the router, with no query.
+	* @param actorRoute  - The raw value of the actor route. It CAN carry a query.
+	*/
+	isActorAtPath(machinePath, actorRoute) {
+		if (actorRoute == null) return false;
+		const { pathname: actorPath } = splitLocation(actorRoute);
+		if (machinePath === ((actorPath.includes("\\") ? parsePattern(actorPath, this.compileOptions).literalPath : null) ?? actorPath)) return true;
+		const resolvedStateId = this.routeMap.getStateIdByPath(machinePath);
+		if (resolvedStateId === null || resolvedStateId === void 0) return false;
+		if (resolvedStateId === actorRoute) return true;
+		if (actorRoute.startsWith("/")) return false;
+		const actorStateIdPath = this.lookupPathByStateId(actorRoute);
+		return actorStateIdPath != null && actorStateIdPath === this.lookupPathByStateId(resolvedStateId);
+	}
+	/**
+	* Returns the path of the route map for a value of an actor route, and it tries both
+	* forms of a stateId.
+	*
+	* The actor can emit `"#stateId"` while a route map of your own holds the bare form
+	* `"stateId"`, and also the opposite. `RouteMap` makes the canonical form
+	* internally, but the constructor accepts every structural
+	* `{ getStateIdByPath, getPathByStateId }` object: a plain test object and a map of
+	* one adapter are legal, and the documentation says so. Therefore this method tries
+	* both forms: the raw form first, then the form without the `#`, then the form with
+	* the `#`.
+	*
+	* @param route - The raw value of the actor route: a stateId, with a `#` prefix or without one
+	* @returns The path of the map, or `null` or `undefined` when no form is registered
+	*/
+	lookupPathByStateId(route) {
+		const direct = this.routeMap.getPathByStateId(route);
+		if (direct != null) return direct;
+		const alternate = route.startsWith("#") ? route.slice(1) : `#${route}`;
+		return this.routeMap.getPathByStateId(alternate);
+	}
+	/**
+	* Reads the query parameters of a URL search string.
+	*
+	* @param search - The URL search string, for example '?tab=security&page=1'
+	* @returns The query parameters of the read, or an empty object
+	*/
+	extractQuery(search) {
+		return extractQuery(search);
+	}
+	/**
+	* True when a location of the router is the location that this bridge pushed.
+	*
+	* `lastSyncedPath` holds the value of `actor.currentRoute`, and that value carries
+	* the query string of `context.query`, for example `"/dates?trip=one-way"`. A router
+	* callback reports the pathname and the search SEPARATELY, and `sanitizePathname`
+	* removes the query. A comparison of the pathname alone therefore misses for every
+	* route with a query, and the push of this bridge comes back as a `play.route` event
+	* of its own navigation. That echo is not only wasted work: the bridge sends a
+	* `play.route` for a location that the actor stands on already, so every entry action
+	* of that state runs a second time, and a guard that refuses the repeat moves the
+	* actor to a state that no user asked for.
+	*
+	* The query is compared as a MAP, and not as a string: a framework can re-serialize
+	* a search string in another order, and `URLSearchParams` also accepts the form with
+	* a leading `?` and the form without one.
+	*
+	* @param sanitized - The clean pathname of the router callback, with no query.
+	* @param search - The search string of the router callback, when it has one.
+	* @returns True when the location is the echo of the last push of this bridge.
+	*/
+	isEchoOfLastSync(sanitized, search) {
+		const last = this.lastSyncedPath;
+		if (last === null) return false;
+		if (sanitized === last && (search ?? "") === "") return true;
+		const { pathname: lastPath, query: lastQuery } = splitLocation(last);
+		if (lastPath !== sanitized) return false;
+		return sortedQuery(lastQuery) === sortedQuery(search ?? "");
+	}
+	/**
+	* Cleans a raw URL pathname of the router, and checks it.
+	*
+	* The method applies the limit of the path length, which is 2048 characters. It
+	* removes a query string and a fragment from the segment of the pathname, and it
+	* normalizes each sequence of slashes.
+	*
+	* An implementation that passes around `syncActorFromRouter()`, for example with a
+	* reactive watcher of its framework that receives a route object of a parse before,
+	* MUST call this method before it gives the path to a lookup in the route map.
+	* `syncActorFromRouter()` calls the method internally. Therefore a bridge that uses
+	* that method calls `sanitizePath` never itself.
+	*
+	* @param pathname - The raw URL pathname of the framework router.
+	* @returns The clean pathname, or `null` when the path is invalid or too long.
+	*/
+	sanitizePath(pathname) {
+		return sanitizePathname(pathname);
+	}
+	/**
+	* Returns the current pathname of the router at the moment of `connect()`.
+	*
+	* `connect()` calls this method one time, for the first synchronization from the URL
+	* to the actor. router.subscribe() fires on a *later* navigation event only. It does
+	* not repeat the location that the router loaded before. A subclass that can read the
+	* current location of its router synchronously, for example with
+	* `router.state.location.pathname`, overrides this method. A deep link and a direct
+	* URL then drive the actor to the correct state, and they leave it not at the default
+	* of its machine.
+	*
+	* The meaning of each return value:
+	* - `string` → the router has a current path, and the base `connect()` writes the actor state from the router
+	* - `null` → the router is active, but it has no current path yet, and the base `connect()` writes the router from the actor
+	* - `undefined` → the adapter does the first synchronization itself, and the base `connect()` does nothing
+	*
+	* The default value is `undefined`. Therefore a bridge without this hook keeps its
+	* earlier behavior.
+	*/
+	getInitialRouterPath() {}
+	/**
+	* Returns the current search string of the router at the moment of `connect()`.
+	*
+	* This method is the pair of `getInitialRouterPath()`. `connect()` calls it one time,
+	* to give the query string of the first URL to `syncActorFromRouter()`. It returns
+	* `undefined` when the current URL of the router has no search string, and also when
+	* the subclass overrides the method not. `syncActorFromRouter` then makes an empty
+	* `query: {}` in the event.
+	*
+	* A subclass that overrides `getInitialRouterPath()` and has a query string
+	* overrides this method too.
+	*
+	* @returns The URL search string, for example `"?tab=security"`, or `undefined` when it is not available.
+	*/
+	getInitialRouterSearch() {}
+};
 /**
- * True when the query of an actor route and the query of the router are the same query.
- *
- * `isActorAtPath` answers where the actor stands, and this function answers whether the
- * two sides agree about the query there. The order of the keys is not significant, which
- * is what `isEchoOfLastSync` says for the same pair of values.
- *
- * A query that DIFFERS answers `false`, and it must: the first synchronization gives the
- * router the priority, so a location with another query is a deep link that the actor has
- * to follow. An ABSENT query of the actor against a query of the router is such a
- * difference — without this, a deep link of `/settings?ref=nav` reached an actor that
- * stood at `/settings` never, and `context.query` stayed empty for the session while
- * `lastSyncedPath` recorded the query and suppressed every later report of it. A stateId
- * carries no query of its own, so it stands at a location with one never.
- *
- * @param actorRoute - The raw value of the actor route. It CAN carry a query.
- * @param search     - The query of the router, or `undefined` when it has none.
- */
+* True when the query of an actor route and the query of the router are the same query.
+*
+* `isActorAtPath` answers where the actor stands, and this function answers whether the
+* two sides agree about the query there. The order of the keys is not significant, which
+* is what `isEchoOfLastSync` says for the same pair of values.
+*
+* A query that DIFFERS answers `false`, and it must: the first synchronization gives the
+* router the priority, so a location with another query is a deep link that the actor has
+* to follow. An ABSENT query of the actor against a query of the router is such a
+* difference — without this, a deep link of `/settings?ref=nav` reached an actor that
+* stood at `/settings` never, and `context.query` stayed empty for the session while
+* `lastSyncedPath` recorded the query and suppressed every later report of it. A stateId
+* carries no query of its own, so it stands at a location with one never.
+*
+* @param actorRoute - The raw value of the actor route. It CAN carry a query.
+* @param search     - The query of the router, or `undefined` when it has none.
+*/
 function sameQuery(actorRoute, search) {
-    const { query: actorQuery, fragment } = splitLocation(actorRoute);
-    // A FRAGMENT is a difference, always. `sanitizePathname` cuts it off, so the router
-    // reports one never and this comparison can confirm one never — and "unknown" must not
-    // read as "the same". An actor that carries `/#intro` against a router at `/` is the
-    // restore that puts the fragment in the address bar, and a `true` here swallowed it:
-    // the bridge recorded the location, sent nothing, and the fragment reached the URL on
-    // no later navigation either.
-    if (fragment !== "")
-        return false;
-    return sortedQuery(actorQuery) === sortedQuery(search ?? "");
+	const { query: actorQuery, fragment } = splitLocation(actorRoute);
+	if (fragment !== "") return false;
+	return sortedQuery(actorQuery) === sortedQuery(search ?? "");
 }
 /**
- * True when an actor route carries no query and no fragment of its own.
- *
- * The RESTORE branch asks this beside {@link RouterBridgeBase.isActorAtPath}. An actor
- * that stands on the path of the router and answers `true` here restores nothing: the
- * address bar already shows its place, and a push writes the same path back and drops
- * whatever the router carried beside it.
- *
- * A stateId answers `true`, because a stateId carries no query and no fragment. The
- * leading `#` of `"#home"` is no fragment, which is what {@link splitLocation} says at
- * index 0.
- *
- * @param actorRoute - The raw value of the actor route.
- */
+* True when an actor route carries no query and no fragment of its own.
+*
+* The RESTORE branch asks this beside {@link RouterBridgeBase.isActorAtPath}. An actor
+* that stands on the path of the router and answers `true` here restores nothing: the
+* address bar already shows its place, and a push writes the same path back and drops
+* whatever the router carried beside it.
+*
+* A stateId answers `true`, because a stateId carries no query and no fragment. The
+* leading `#` of `"#home"` is no fragment, which is what {@link splitLocation} says at
+* index 0.
+*
+* @param actorRoute - The raw value of the actor route.
+*/
 function carriesNoOwnSuffix(actorRoute) {
-    const { query, fragment } = splitLocation(actorRoute);
-    return query === "" && fragment === "";
+	const { query, fragment } = splitLocation(actorRoute);
+	return query === "" && fragment === "";
+}
+/**
+* True when the router stands at the initial URL of the machine: at the path of
+* `initialRoute` AND at its query.
+*
+* The restore test of `performInitialSync` and of `takeReturnUnderMount` asks this. It
+* compared the path alone, so a router at `/?other=1` read as "at the initial URL `/`"
+* and a restored actor at `/?ref=nav` won: the bridge pushed the query of the actor over
+* the query that the user opened, and no `play.route` carried it (issue #18). A query
+* that the machine did not put there is what a deep link looks like, so the router wins.
+*
+* The cost of the rule: after a reload, a query that the host or the browser added to the
+* initial URL is a deep link too, and the actor loses its restored route to it.
+*
+* @param initialRoute - The initial route of the actor. `null` is no initial route.
+* @param machinePath  - The machine half of the location of the router, with no query.
+* @param search       - The query of the router.
+*/
+function isAtInitialLocation(initialRoute, machinePath, search) {
+	if (typeof initialRoute !== "string") return false;
+	return splitLocation(initialRoute).pathname === machinePath && sameQuery(initialRoute, search);
 }
 /** Joins a pathname and a query into one location value. An empty query adds nothing. */
 function withSearch(pathname, search) {
-    const query = (search ?? "").replace(/^\?/, "");
-    return query === "" ? pathname : `${pathname}?${query}`;
+	const query = (search ?? "").replace(/^\?/, "");
+	return query === "" ? pathname : `${pathname}?${query}`;
 }
 /**
- * The canonical form of a query string, for a comparison that ignores the order:
- * each `key=value` pair, sorted, joined with `&`. An empty search gives `""`.
- *
- * Each name AND each value are escaped, because a raw join ALIASES: with "=" and "&"
- * as literal separators, `?a=1&b=2` and `?a=1%26b%3D2` gave one canonical form for two
- * different locations. `isEchoOfLastSync` then read a real navigation as the echo of
- * its own push, so the actor never heard of the move and the URL and the actor state
- * diverged. `mountKey` of `provider-lifecycle.ts` escapes for the same reason.
- *
- * `toSorted()` and not `sort()`: an in-place sort is safe here, because the array is a
- * fresh one of `map()` and the mutation escapes nowhere. It is still the second spelling
- * of one operation. `mountKey` of `provider-lifecycle.ts` sorts this same shared source
- * with `toSorted()`, so this site uses it too.
- *
- * The copy costs nothing that a profile can find. `resolveViewMeta` of play-xstate holds
- * the measurement for the same question.
- */
+* The canonical form of a query string, for a comparison that ignores the order:
+* each `key=value` pair, sorted, joined with `&`. An empty search gives `""`.
+*
+* Each name AND each value are escaped, because a raw join ALIASES: with "=" and "&"
+* as literal separators, `?a=1&b=2` and `?a=1%26b%3D2` gave one canonical form for two
+* different locations. `isEchoOfLastSync` then read a real navigation as the echo of
+* its own push, so the actor never heard of the move and the URL and the actor state
+* diverged. `mountKey` of `provider-lifecycle.ts` escapes for the same reason.
+*
+* `toSorted()` and not `sort()`: an in-place sort is safe here, because the array is a
+* fresh one of `map()` and the mutation escapes nowhere. It is still the second spelling
+* of one operation. `mountKey` of `provider-lifecycle.ts` sorts this same shared source
+* with `toSorted()`, so this site uses it too.
+*
+* The copy costs nothing that a profile can find. `resolveViewMeta` of play-xstate holds
+* the measurement for the same question.
+*/
 function sortedQuery(search) {
-    const pairs = [...new URLSearchParams(search).entries()].map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
-    return pairs.toSorted().join("&");
+	return [...new URLSearchParams(search).entries()].map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).toSorted().join("&");
 }
-function noopCleanup() { }
+function noopCleanup() {}
 /**
- * Watches the route atom of the actor.
- *
- * The bridge wraps the read in NOTHING. A subscription evaluates a computed atom inside
- * the `set` of the actor state, so a throw from the derivation would unwind into
- * `actor.send` and break the transition for every other observer — and `currentRoute`
- * therefore contains its own failures, reports them through `onError` of the actor, and
- * keeps its last route. Every subscriber benefits from that rule, and not this bridge
- * alone.
- */
+* Watches the route atom of the actor.
+*
+* The bridge wraps the read in NOTHING. A subscription evaluates a computed atom inside
+* the `set` of the actor state, so a throw from the derivation would unwind into
+* `actor.send` and break the transition for every other observer — and `currentRoute`
+* therefore contains its own failures, reports them through `onError` of the actor, and
+* keeps its last route. Every subscriber benefits from that rule, and not this bridge
+* alone.
+*/
 function createRouteWatcher(atom, onRoute) {
-    let cleanup = noopCleanup;
-    const watcher = {
-        watch(nextAtom) {
-            // Release the watch that this handle holds already. `RouteWatcherHandle` is a
-            // published type, so a bridge of a consumer can repoint the handle at the atom of
-            // a new actor — and an assignment alone dropped the reference to the first
-            // cleanup, which left the first subscription live for the life of the process.
-            watcher.unwatch();
-            cleanup = watchAtom(nextAtom, onRoute);
-        },
-        unwatch() {
-            const release = cleanup;
-            cleanup = noopCleanup;
-            release();
-        },
-    };
-    watcher.watch(atom);
-    return watcher;
+	let cleanup = noopCleanup;
+	const watcher = {
+		watch(nextAtom) {
+			watcher.unwatch();
+			cleanup = watchAtom(nextAtom, onRoute);
+		},
+		unwatch() {
+			const release = cleanup;
+			cleanup = noopCleanup;
+			release();
+		}
+	};
+	watcher.watch(atom);
+	return watcher;
 }
 /**
- * True when two machine-side locations are the same place.
- *
- * The order of the keys of a query is not significant, so `?b=2&a=1` and `?a=1&b=2` are
- * one location. The FRAGMENT counts: `navigateRouter` writes the whole value that the
- * actor gave — `buildRouteUrl` appends `context.hash` — so `/docs` and `/docs#intro` are
- * two locations to write, and a test that read them as one left the fragment out of the
- * address bar for ever.
- */
+* True when two machine-side locations are the same place.
+*
+* The order of the keys of a query is not significant, so `?b=2&a=1` and `?a=1&b=2` are
+* one location. The FRAGMENT counts: `navigateRouter` writes the whole value that the
+* actor gave — `buildRouteUrl` appends `context.hash` — so `/docs` and `/docs#intro` are
+* two locations to write, and a test that read them as one left the fragment out of the
+* address bar for ever.
+*/
 function sameLocation(a, b) {
-    const { pathname: aPath, query: aQuery, fragment: aFragment } = splitLocation(a);
-    const { pathname: bPath, query: bQuery, fragment: bFragment } = splitLocation(b);
-    if (aPath !== bPath)
-        return false;
-    if (aFragment !== bFragment)
-        return false;
-    return sortedQuery(aQuery) === sortedQuery(bQuery);
+	const { pathname: aPath, query: aQuery, fragment: aFragment } = splitLocation(a);
+	const { pathname: bPath, query: bQuery, fragment: bFragment } = splitLocation(b);
+	if (aPath !== bPath) return false;
+	if (aFragment !== bFragment) return false;
+	return sortedQuery(aQuery) === sortedQuery(bQuery);
 }
+//#endregion
+export { RouterBridgeBase };
+
 //# sourceMappingURL=router-bridge-base.js.map