@xmachines/play-router 3.0.0 → 5.0.0

package/dist/router-bridge-base.js

@@ -3,7 +3,7 @@
  *
  * The class holds the logic that each router bridge shares, and that is 90% of the
  * code of every bridge:
- * - The TC39 Signal watcher of the direction from the actor to the router
+ * - 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
@@ -42,11 +42,10 @@
  *
  * @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
  */
-import { Signal, watchSignal } from "@xmachines/play-signals";
-import { DuplicateBridgeError, RouterSyncError, URLPatternUnavailableError } from "./errors.js";
-import { buildPlayRouteEvent, extractQuery, extractRouteParams, matchRouteMap, sanitizePathname, } from "./router-sync.js";
-import { isParameterizedPattern } from "./url-pattern-utils.js";
-import { NO_BASE_PATH, firstMarkIndex, joinBasePath, resolveBasePath, stripBasePath, } from "./base-path.js";
+import { NO_BASE_PATH, sanitizePathname, splitLocation, holdsUnsubstitutedParam, joinBasePath, parsePattern, resolveBasePath, 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";
 /**
  * The registry of the actors with an active bridge connection, at the module level.
  *
@@ -85,19 +84,19 @@ export class RouterBridgeBase {
     /**
      * 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
+     * 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 signal pushes nothing for a route that moved nowhere.
+     * 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 signal fires, the bridge pushes to the router, and a second
+     * 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
@@ -169,6 +168,13 @@ export class RouterBridgeBase {
      * 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
@@ -181,11 +187,19 @@ export class RouterBridgeBase {
     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 signal fires once when `connect()` arms it,
+        // 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
@@ -420,7 +434,7 @@ export class RouterBridgeBase {
     /**
      * Connects the router bridge to the Actor.
      *
-     * The method installs the TC39 Signal watcher of the direction from the actor to the
+     * 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.
      *
@@ -467,14 +481,14 @@ export class RouterBridgeBase {
         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 a signal that refuses a watcher
+        //   - `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 a URLPatternUnavailableError for a parameterized
-        //     route on a runtime without URLPattern, and a RouterSyncError for each other
-        //     failure of the send to the actor
+        //   - `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.
@@ -483,12 +497,13 @@ export class RouterBridgeBase {
         // 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 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 load of the polyfill, rescues that actor never.
+        //     cause, for example a correction of the route pattern, rescues that actor
+        //     never.
         try {
-            // The TC39 Signal watcher of the direction from the actor to the router.
+            // The atom watcher of the direction from the actor to the router.
             this.routeWatcher = createRouteWatcher(this.actor.currentRoute, (route) => {
                 this.syncRouterFromActor(route);
             });
@@ -501,7 +516,8 @@ export class RouterBridgeBase {
             // 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.
+            // that receives it learns neither which route pattern URLPattern refused nor
+            // which event the actor refused.
             try {
                 this.disconnect();
             }
@@ -541,6 +557,18 @@ export class RouterBridgeBase {
      */
     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
@@ -575,8 +603,15 @@ export class RouterBridgeBase {
             // 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.
-            const actorAlreadyAtRouterLocation = this.isActorAtLocation(machinePath, initialActorRoute);
+            // 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
@@ -590,7 +625,7 @@ export class RouterBridgeBase {
             // of one connection, and the record of the old prefix says nothing about this
             // location.
             if (actorAlreadyAtRouterLocation) {
-                this.lastSyncedPath = withSearch(machinePath, this.getInitialRouterSearch());
+                this.lastSyncedPath = withSearch(machinePath, routerSearch());
             }
             else {
                 // The path of the router is different from the actor route. Is this a deep link, or
@@ -606,16 +641,33 @@ 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.
+                //
+                // 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) {
+                    initialActorRoute !== this.actor.initialRoute &&
+                    !(actorAtRouterPath && carriesNoOwnSuffix(initialActorRoute))) {
                     this.pushHoldingNavigation(initialActorRoute);
                 }
                 else {
-                    // 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());
+                    // 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());
                 }
             }
         }
@@ -641,7 +693,7 @@ export class RouterBridgeBase {
     /**
      * Disconnects the router bridge from the Actor.
      *
-     * The method stops the watch of the signal, and it removes the router listener of the
+     * The method stops the watch of the atom, and it removes the router listener of the
      * framework.
      */
     disconnect() {
@@ -692,7 +744,7 @@ export class RouterBridgeBase {
     }
     // ── The sync methods. They are protected, and a subclass overrides one for its own behavior ──
     /**
-     * Writes the location of the router when the route signal of the actor changes.
+     * 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
@@ -791,7 +843,7 @@ export class RouterBridgeBase {
         const owesFirstSync = !this.hasSynchronizedUnderMount;
         this.hasSynchronizedUnderMount = true;
         const restoredRoute = this.actor.currentRoute.get();
-        // `isActorAtLocation` is the test that `performInitialSync` makes BEFORE it looks
+        // `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
@@ -801,13 +853,23 @@ export class RouterBridgeBase {
         //
         // 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);
+        // 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) {
+            !actorAtLocation &&
+            !(actorAtPath && carriesNoOwnSuffix(restoredRoute))) {
             return this.pushUnderMount(restoredRoute);
         }
         if (owesFirstSync) {
@@ -879,12 +941,12 @@ export class RouterBridgeBase {
         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.
+        // 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
@@ -920,7 +982,7 @@ export class RouterBridgeBase {
      * 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 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.
@@ -937,7 +999,7 @@ export class RouterBridgeBase {
         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:
+        // 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.
@@ -963,8 +1025,9 @@ export class RouterBridgeBase {
      * 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
-     * lastSyncedPath. Therefore the dedup guard fires correctly on the next identical
-     * value of the signal.
+     * 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
@@ -973,7 +1036,7 @@ export class RouterBridgeBase {
      */
     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.
+        // 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
@@ -1071,7 +1134,7 @@ export class RouterBridgeBase {
             }
             // 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
+            // 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:
             //
@@ -1086,7 +1149,7 @@ export class RouterBridgeBase {
             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
+            // 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.
@@ -1094,10 +1157,11 @@ export class RouterBridgeBase {
             this.actor.send(nextRoute.event);
         }
         catch (error) {
-            // A URLPatternUnavailableError needs an action of the user: it goes to the caller
-            // without a change. The caller can therefore find it, and ask the user for a
-            // URLPattern polyfill.
-            if (error instanceof URLPatternUnavailableError) {
+            // 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.", {
@@ -1112,22 +1176,20 @@ export class RouterBridgeBase {
     /**
      * Reads the path parameters of a URL, with the URLPattern API.
      *
-     * The method reads `globalThis.URLPattern` at run time, because this library imports
-     * no polyfill. When `URLPattern` is absent and the route of the match holds a
-     * parameterized segment, the method throws a `URLPatternUnavailableError`. A caller
-     * must therefore give a polyfill in an environment without the native URLPattern:
-     * Node.js < 24, and an older browser.
+     * 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 {URLPatternUnavailableError} When URLPattern is absent and the route holds a parameter
+     * @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);
+        return extractRouteParams(pathname, pattern, this.compileOptions);
     }
     /**
      * Resolves a value of an actor route to a concrete URL path for a navigation.
@@ -1140,6 +1202,9 @@ export class RouterBridgeBase {
      *   `/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.
@@ -1157,19 +1222,70 @@ export class RouterBridgeBase {
         const path = mapped ?? (route.startsWith("/") ? route : null);
         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)))
+        // 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 at a location of the router.
+     * 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
@@ -1178,33 +1294,69 @@ export class RouterBridgeBase {
      * `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
+     * 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 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.
+     * 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.
      */
-    isActorAtLocation(machinePath, actorRoute) {
+    isActorAtPath(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)
+        // 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)
@@ -1256,10 +1408,10 @@ export class RouterBridgeBase {
      * 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.
+     * 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
@@ -1279,7 +1431,7 @@ export class RouterBridgeBase {
         // 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);
+        const { pathname: lastPath, query: lastQuery } = splitLocation(last);
         if (lastPath !== sanitized)
             return false;
         return sortedQuery(lastQuery) === sortedQuery(search ?? "");
@@ -1344,41 +1496,52 @@ export class RouterBridgeBase {
     }
 }
 /**
- * The pathname half of a location: everything in front of the first `?` or `#`.
+ * 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 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.
+ * 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 pathnameOf(location) {
-    const mark = firstMarkIndex(location);
-    return mark === -1 ? location : location.slice(0, mark);
+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 ?? "");
 }
 /**
- * Splits a location into its path, its query with no leading `?`, and its fragment
- * with its leading `#`.
+ * True when an actor route carries no query and no fragment of its own.
  *
- * 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 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.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * @param actorRoute - The raw value of the actor route.
  */
-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];
+function carriesNoOwnSuffix(actorRoute) {
+    const { query, fragment } = splitLocation(actorRoute);
+    return query === "" && fragment === "";
 }
 /** Joins a pathname and a query into one location value. An empty query adds nothing. */
 function withSearch(pathname, search) {
@@ -1408,17 +1571,34 @@ function sortedQuery(search) {
     return pairs.toSorted().join("&");
 }
 function noopCleanup() { }
-function createRouteWatcher(signal, onRoute) {
+/**
+ * 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(nextSignal) {
-            cleanup = watchSignal(nextSignal, onRoute);
+        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() {
-            cleanup();
+            const release = cleanup;
+            cleanup = noopCleanup;
+            release();
         },
     };
-    watcher.watch(signal);
+    watcher.watch(atom);
     return watcher;
 }
 /**
@@ -1431,8 +1611,8 @@ function createRouteWatcher(signal, onRoute) {
  * address bar for ever.
  */
 function sameLocation(a, b) {
-    const [aPath, aQuery, aFragment] = splitLocation(a);
-    const [bPath, bQuery, bFragment] = splitLocation(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)