@xmachines/play-router 2.1.0 → 2.2.0

package/dist/router-bridge-base.js

@@ -43,10 +43,10 @@
  * @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
  */
 import { Signal, watchSignal } from "@xmachines/play-signals";
-import { DuplicateBridgeError, RouterSyncError } from "./errors.js";
+import { DuplicateBridgeError, RouterSyncError, URLPatternUnavailableError } from "./errors.js";
 import { buildPlayRouteEvent, extractQuery, extractRouteParams, matchRouteMap, sanitizePathname, } from "./router-sync.js";
-import { URLPatternUnavailableError } from "./errors.js";
 import { isParameterizedPattern } from "./url-pattern-utils.js";
+import { NO_BASE_PATH, firstMarkIndex, joinBasePath, resolveBasePath, stripBasePath, } from "./base-path.js";
 /**
  * The registry of the actors with an active bridge connection, at the module level.
  *
@@ -59,20 +59,41 @@ import { isParameterizedPattern } from "./url-pattern-utils.js";
  * @internal
  */
 const activeBridges = new WeakMap();
-/**
- * The abstract base class of every router adapter bridge of `@xmachines`.
- *
- * The class implements the RouterBridge protocol, and it holds every part of the
- * bridge logic that the adapters share. A subclass implements the 3 abstract methods
- * that are different in each framework, and it implements nothing more.
- */
 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 signal
+     * 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 signal 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
@@ -81,11 +102,73 @@ export class RouterBridgeBase {
      *
      * 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 path stops at
-     * the `sanitized === lastSyncedPath` test in `syncActorFromRouter`.
+     * `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;
     /**
      * @param actor    - A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.
      * @param routeMap - The route map of both directions, for the resolution between a
@@ -95,13 +178,243 @@ export class RouterBridgeBase {
      *   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) {
+    constructor(actor, routeMap, options) {
         this.actor = actor;
         this.routeMap = routeMap;
-        // Set lastSyncedPath to the current route of the actor. This stops a loop in the
-        // first synchronization. The value null means "nothing is in step yet", and it is
-        // therefore different from each real path string.
-        this.lastSyncedPath = this.actor.currentRoute.get() ?? null;
+        // 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 signal 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 ──
     /**
@@ -112,7 +425,7 @@ export class RouterBridgeBase {
      * in its own way.
      *
      * The order of these steps is part of the contract of the bridge:
-     * - The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+     * - 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`
      *
@@ -133,54 +446,153 @@ export class RouterBridgeBase {
             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;
-        // Install the TC39 Signal watcher of the direction from the actor to the router
-        this.routeWatcher = createRouteWatcher(this.actor.currentRoute, (route) => {
-            this.syncRouterFromActor(route);
-        });
-        // Start the watch of the router changes. Each framework does this in its own way
-        this.watchRouterChanges();
-        // The first synchronization: the direction from the router to the actor has the
-        // priority over the other direction.
+        // From here on, connect() gives all or nothing. THREE steps below can throw, and
+        // the rollback has to cover each of them:
+        //   - `createRouteWatcher`, on a signal 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 a URLPatternUnavailableError for a parameterized
+        //     route on a runtime without URLPattern, and a RouterSyncError for each other
+        //     failure of the send to the actor
         //
-        // 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.
+        // The throw needs an action of the caller, and it therefore goes to the caller
+        // without a change.
         //
-        // 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().
-        const initialRouterPath = this.getInitialRouterPath();
-        const initialRouterSearch = this.getInitialRouterSearch();
+        // 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 signal 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 load of the polyfill, rescues that actor never.
+        try {
+            // The TC39 Signal 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 never learns that its runtime needs a URLPattern polyfill.
+            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();
         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 currentRoute of the actor can be a stateId, for example "#app.home", and
-            // initialRouterPath is a URL path, for example "/home". Therefore resolve the path
-            // to a stateId before the comparison. Without this step, a false "the two are
-            // different" starts a first synchronization that nothing needs.
-            const resolvedStateId = this.routeMap.getStateIdByPath(sanitizePathname(initialRouterPath) ?? initialRouterPath);
-            // The actor is at the location of the router in two cases: the two values match
-            // directly, or the actor route is a stateId that resolves to the same registered
-            // path as the stateId of the match. Each lookup goes through 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 with the router path only.
-            const actorAlreadyAtRouterLocation = resolvedStateId !== null &&
-                resolvedStateId !== undefined &&
-                (resolvedStateId === initialActorRoute ||
-                    initialRouterPath === initialActorRoute ||
-                    (initialActorRoute != null &&
-                        !initialActorRoute.startsWith("/") &&
-                        this.lookupPathByStateId(initialActorRoute) != null &&
-                        this.lookupPathByStateId(initialActorRoute) ===
-                            this.lookupPathByStateId(resolvedStateId)));
-            if (!actorAlreadyAtRouterLocation) {
+            const actorAlreadyAtRouterLocation = this.isActorAtLocation(machinePath, initialActorRoute);
+            // 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, this.getInitialRouterSearch());
+            }
+            else {
                 // The path of the router is different from the actor route. Is this a deep link, or
                 // is it a restore?
                 //
@@ -195,12 +607,15 @@ export class RouterBridgeBase {
                 // 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.
                 if (initialActorRoute &&
-                    initialRouterPath === this.actor.initialRoute &&
+                    machinePath === this.actor.initialRoute &&
                     initialActorRoute !== this.actor.initialRoute) {
-                    this.pushResolvedRoute(initialActorRoute);
+                    this.pushHoldingNavigation(initialActorRoute);
                 }
                 else {
-                    this.syncActorFromRouter(initialRouterPath, initialRouterSearch);
+                    // The search is read HERE, and not at the top of the method: the read belongs
+                    // to the adapter, it can walk the state of a router, and every branch above
+                    // returns without it.
+                    this.syncActorFromRouter(initialRouterPath, this.getInitialRouterSearch());
                 }
             }
         }
@@ -209,11 +624,18 @@ export class RouterBridgeBase {
             // bootstrap → push the actor route.
             // The value undefined means that the adapter does the first synchronization itself.
             // Continue.
-            this.pushResolvedRoute(initialActorRoute);
+            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.lastSyncedPath) {
+        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;
         }
     }
     /**
@@ -233,16 +655,39 @@ export class RouterBridgeBase {
             }
         }
         this.routeWatcher = null;
-        if (this.isConnected || hadRouteWatcher) {
-            this.unwatchRouterChanges();
+        // `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.
         }
-        this.isProcessingNavigation = false;
-        this.isConnected = 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);
+        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 ──
@@ -271,9 +716,239 @@ export class RouterBridgeBase {
             return;
         if (!route || typeof route !== "string")
             return;
-        if (route === this.lastSyncedPath)
+        // 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;
-        this.pushResolvedRoute(route);
+        }
+        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();
+        // `isActorAtLocation` 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.
+        const actorAtLocation = owesFirstSync && this.isActorAtLocation(machinePath, restoredRoute);
+        if (owesFirstSync &&
+            restoredRoute &&
+            machinePath === this.actor.initialRoute &&
+            restoredRoute !== this.actor.initialRoute &&
+            !actorAtLocation) {
+            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` writes nothing for an unknown stateId
+        // and for a parameterized pattern, and it still records the RAW value in
+        // `lastSyncedPath`: a `true` return then left the location in neither side — the
+        // URL kept the page of the host, the actor heard no `play.route`, and the record of
+        // the location that the address bar holds was gone, so no later return could be
+        // recognized either. `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 signal 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 signal 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
@@ -290,13 +965,28 @@ export class RouterBridgeBase {
      * literal `*` into the browser URL. The method still writes the raw route to
      * lastSyncedPath. Therefore the dedup guard fires correctly on the next identical
      * value of the signal.
+     *
+     * @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) {
-        const resolved = this.resolveNavigationPath(route);
-        this.lastSyncedPath = resolved ?? route;
+    pushResolvedRoute(route, resolved = this.resolveNavigationPath(route)) {
+        // The VALUE is accounted for either way, so the dedup stops the next identical fire
+        // of the signal 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.navigateRouter(resolved);
+        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.
@@ -322,14 +1012,37 @@ export class RouterBridgeBase {
         const sanitized = sanitizePathname(pathname);
         if (sanitized === null)
             return; // The path is too long. Refuse it
-        if (sanitized === this.lastSyncedPath)
+        // 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,
+                pathname: machinePath,
                 search,
                 match: (nextPathname) => matchRouteMap(nextPathname, this.routeMap, (resolvedPathname, stateId) => this.extractParams(resolvedPathname, stateId)),
             });
@@ -356,8 +1069,29 @@ export class RouterBridgeBase {
                 }
                 return;
             }
+            // Record the location BEFORE the send, and record it with its query.
+            //
+            // The route signal 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 signal: 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);
-            this.lastSyncedPath = nextRoute.pathname;
         }
         catch (error) {
             // A URLPatternUnavailableError needs an action of the user: it goes to the caller
@@ -410,16 +1144,79 @@ export class RouterBridgeBase {
      * 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 URL path, or `null` when the bridge must skip the navigation
+     * @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 || isParameterizedPattern(path))
+        if (path === null)
+            return null;
+        // The PATHNAME half alone decides whether this is a pattern. 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 a route of the actor carries its query, because `context.query`
+        // travels in `currentRoute`. A test of the whole string read such a route as a
+        // pattern: `pushResolvedRoute` wrote `lastSyncedPath` and navigated nowhere, so the
+        // URL stopped following the actor, and the dedup guard then suppressed the next
+        // attempt at the same route as an echo.
+        if (isParameterizedPattern(pathnameOf(path)))
             return null;
         return path;
     }
+    /**
+     * Tells you whether the actor already stands at 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 at the location 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 with the path of the router
+     * only.
+     *
+     * Each lookup runs ONE time. `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.
+     * @param actorRoute  - The raw value of the actor route.
+     */
+    isActorAtLocation(machinePath, actorRoute) {
+        if (actorRoute == null)
+            return false;
+        // The identical string answers the question 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". `performInitialSync` read that as a deep link and
+        // drove the actor into the state it was in already. The seed of the constructor hid
+        // this for as long as one field carried the route of the actor AND the location.
+        if (machinePath === actorRoute)
+            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.
@@ -451,6 +1248,42 @@ export class RouterBridgeBase {
     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: it writes to the signal
+     * graph from inside the watcher callback of the actor route, and the watcher then
+     * arms itself again on a computed that is dirty already, which ends the direction
+     * from the actor to the router for the rest of the session.
+     *
+     * 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 [lastPath, lastQuery] = splitLocation(last);
+        if (lastPath !== sanitized)
+            return false;
+        return sortedQuery(lastQuery) === sortedQuery(search ?? "");
+    }
     /**
      * Cleans a raw URL pathname of the router, and checks it.
      *
@@ -510,6 +1343,70 @@ export class RouterBridgeBase {
         return undefined;
     }
 }
+/**
+ * The pathname half of a location: everything in front of the first `?` or `#`.
+ *
+ * A pattern test reads this half alone, because a query and a fragment carry their own
+ * characters and say nothing about the shape of the path.
+ */
+function pathnameOf(location) {
+    const mark = firstMarkIndex(location);
+    return mark === -1 ? location : location.slice(0, mark);
+}
+/**
+ * Splits a location into its path, its query with no leading `?`, and its fragment
+ * with its leading `#`.
+ *
+ * A '#' after index 0 ends the pathname. `pushResolvedRoute` writes what the actor
+ * gave — "/docs#intro" — while the callback of the router reports "/docs", because
+ * `sanitizePathname` strips the fragment: an echo test that compared the two whole
+ * strings missed, so the bridge answered its own push with an event and a history entry
+ * that BACK cannot escape.
+ *
+ * The fragment comes back as the THIRD field, and each caller decides whether it
+ * counts: `isEchoOfLastPush` compares it, because `navigateRouter` writes it, and
+ * `isEchoOfLastSync` drops it, because the router reports it never.
+ *
+ * At index 0 the '#' is NOT a fragment: `lastSyncedPath` legitimately holds a bare
+ * stateId such as "#home", which `pushResolvedRoute` stores when it can resolve no
+ * path. Cutting there would turn that value into the empty string.
+ */
+function splitLocation(location) {
+    const fragmentAt = location.indexOf("#", 1);
+    const withoutFragment = fragmentAt === -1 ? location : location.slice(0, fragmentAt);
+    const fragment = fragmentAt === -1 ? "" : location.slice(fragmentAt);
+    const mark = withoutFragment.indexOf("?");
+    if (mark === -1)
+        return [withoutFragment, "", fragment];
+    return [withoutFragment.slice(0, mark), withoutFragment.slice(mark + 1), fragment];
+}
+/** 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}`;
+}
+/**
+ * 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.
+ *
+ * `sort()` in place, and not `toSorted()`: the array is a fresh one of `map()`, so
+ * nothing else holds a reference to it and the mutation escapes nowhere. Either one
+ * compiles — every example package builds against the ESNext baseline now, and
+ * `mountKey` of `provider-lifecycle.ts` calls `toSorted()` on this same shared source
+ * — so this is a choice of style and not a constraint of the toolchain.
+ */
+function sortedQuery(search) {
+    const pairs = [...new URLSearchParams(search).entries()].map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+    // oxlint-disable-next-line unicorn/no-array-sort
+    pairs.sort();
+    return pairs.join("&");
+}
 function noopCleanup() { }
 function createRouteWatcher(signal, onRoute) {
     let cleanup = noopCleanup;
@@ -524,4 +1421,22 @@ function createRouteWatcher(signal, onRoute) {
     watcher.watch(signal);
     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.
+ */
+function sameLocation(a, b) {
+    const [aPath, aQuery, aFragment] = splitLocation(a);
+    const [bPath, bQuery, bFragment] = splitLocation(b);
+    if (aPath !== bPath)
+        return false;
+    if (aFragment !== bFragment)
+        return false;
+    return sortedQuery(aQuery) === sortedQuery(bQuery);
+}
 //# sourceMappingURL=router-bridge-base.js.map