@xmachines/play-router 2.0.0 → 2.1.1

package/dist/router-bridge-base.js

@@ -1,17 +1,18 @@
 /**
- * RouterBridgeBase — Abstract base class for all framework router adapters
+ * RouterBridgeBase — the abstract base class of every framework router adapter
  *
- * Captures the 90% identical logic from all existing router bridges:
- * - TC39 Signal watcher for actor → router direction
- * - `lastSyncedPath` for echo suppression in the actor→router direction
- * - `isProcessingNavigation` flag for guard-redirect loop prevention in `syncActorFromRouter` only
- * - `syncRouterFromActor` / `syncActorFromRouter` with URL parameter extraction
- * - connect / disconnect lifecycle matching the RouterBridge protocol
+ * 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
+ * - `lastSyncedPath`, for the echo suppression in the direction from the actor to the router
+ * - The `isProcessingNavigation` flag, which stops a loop of a guard redirect in `syncActorFromRouter` only
+ * - `syncRouterFromActor` and `syncActorFromRouter`, with the read of each URL parameter
+ * - The connect and disconnect lifecycle of the RouterBridge protocol
  *
- * Subclasses implement only the 3 framework-specific abstract methods:
- * - navigateRouter(path): How to tell the framework router to navigate
- * - watchRouterChanges(): How to subscribe to router location changes
- * - unwatchRouterChanges(): How to unsubscribe from router location changes
+ * A subclass implements the 3 abstract methods of its framework only:
+ * - navigateRouter(path): how the bridge tells the framework router to navigate
+ * - watchRouterChanges(): how the bridge subscribes to each location change of the router
+ * - unwatchRouterChanges(): how the bridge cancels that subscription
  *
  * @example
  * ```typescript
@@ -39,7 +40,7 @@
  * }
  * ```
  *
- * @see [Play RFC](../../docs/rfc/play.md) - Invariant INV-04
+ * @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
  */
 import { Signal, watchSignal } from "@xmachines/play-signals";
 import { DuplicateBridgeError, RouterSyncError } from "./errors.js";
@@ -47,79 +48,86 @@ import { buildPlayRouteEvent, extractQuery, extractRouteParams, matchRouteMap, s
 import { URLPatternUnavailableError } from "./errors.js";
 import { isParameterizedPattern } from "./url-pattern-utils.js";
 /**
- * Module-level registry of actors that currently have an active bridge connection.
+ * The registry of the actors with an active bridge connection, at the module level.
  *
- * Keyed on the actor instance (WeakMap — no reference retention). Used to detect and
- * reject duplicate `connect()` calls for the same actor, which would produce duplicate
- * `play.route` events and conflicting `lastSyncedPath` echo-suppression state.
+ * The key is the actor instance, and the registry is a WeakMap, which holds no
+ * reference. The class uses it to find and refuse a second `connect()` call of the
+ * same actor. Such a call makes two `play.route` events for one navigation, and it
+ * makes two `lastSyncedPath` values of the echo suppression that contradict each
+ * other.
  *
  * @internal
  */
 const activeBridges = new WeakMap();
 /**
- * Abstract base class for all `@xmachines` router adapter bridges.
+ * The abstract base class of every router adapter bridge of `@xmachines`.
  *
- * Implements RouterBridge protocol and contains all common bridge logic.
- * Subclasses only need to implement the 3 abstract methods that differ
- * between frameworks.
+ * 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;
-    // ── Common state (identical across all 4 existing bridges) ──
+    // ── The common state. It is identical in each of the 4 bridges ──
     isConnected = false;
     hasConnectedOnce = false;
     lastSyncedPath = null;
     /**
-     * Guards `syncActorFromRouter` against re-entrant calls triggered by the
-     * actor's own guard redirects (router→actor send → signal fires → actor→router
-     * push → another syncActorFromRouter before the first one returns).
-     *
-     * NOT used for actor→router echo suppression — that is handled exclusively by
-     * `lastSyncedPath`, which is updated before `navigateRouter()` is called so
-     * any router callback for the same path short-circuits at the
-     * `sanitized === lastSyncedPath` check in `syncActorFromRouter`.
+     * 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
+     * `syncActorFromRouter` call starts before the first one returns.
+     *
+     * The flag is NOT the echo suppression of the direction from the actor to the
+     * router. `lastSyncedPath` does that work alone: the bridge writes it before the
+     * `navigateRouter()` call. Therefore each router callback of the same location stops
+     * at the {@link isEchoOfLastSync} test in `syncActorFromRouter`.
      */
     isProcessingNavigation = false;
     routeWatcher = null;
     /**
-     * @param actor    - A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.
-     * @param routeMap - Bidirectional route map for `stateId ↔ path` resolution.
-     *   Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters
-     *   typically wrap the result of `createRouteMap(machine)` or an equivalent.
-     *   `getPathByStateId` may be keyed on either the `"#stateId"` or the bare
-     *   `"stateId"` form — both forms are tried automatically by the bridge, so
-     *   custom implementations (e.g. plain test objects) need only handle one.
+     * @param actor    - A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.
+     * @param routeMap - The route map of both directions, for the resolution between a
+     *   `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A
+     *   framework adapter usually wraps the result of `createRouteMap(machine)`, or an
+     *   equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the
+     *   bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
+     *   of your own, for example a plain test object, handles one form only.
      */
     constructor(actor, routeMap) {
         this.actor = actor;
         this.routeMap = routeMap;
-        // Initialize lastSyncedPath to actor's current route (prevents initial sync loop).
-        // null means "nothing synced yet" — distinct from any real path string.
+        // 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;
     }
-    // ── RouterBridge protocol (final — subclasses must not override) ──
+    // ── The RouterBridge protocol. It is final: a subclass must override nothing here ──
     /**
-     * Connect the router bridge to the Actor.
+     * Connects the router bridge to the Actor.
      *
-     * Sets up the TC39 Signal watcher for actor → router direction and
-     * starts watching router changes (framework-specific).
+     * The method installs the TC39 Signal 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.
      *
-     * Ordering here is part of the bridge contract:
-     * - `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-     * - the actor watcher is installed before adapter router subscriptions
-     * - initial sync then resolves deep-link vs restore using `actor.initialRoute`
+     * The order of these steps is part of the contract of the bridge:
+     * - The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+     * - 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`
      *
-     * Adapters that need custom initial-sync behavior should override
-     * `getInitialRouterPath()` rather than reordering `connect()` steps.
+     * An adapter that needs a different behavior of the first synchronization overrides
+     * `getInitialRouterPath()`. It does not change the order of the steps of
+     * `connect()`.
      */
     connect() {
         if (this.isConnected) {
             return;
         }
-        // Enforce single-bridge-per-actor: two connected bridges for the same actor
-        // would both receive every router navigation event, sending duplicate play.route
-        // events and producing conflicting lastSyncedPath echo-suppression state.
+        // Permit one bridge for each actor: two connected bridges of the same actor both
+        // receive every navigation event of the router. They therefore send two play.route
+        // events, and their lastSyncedPath values of the echo suppression contradict each
+        // other.
         const existingBridge = activeBridges.get(this.actor);
         if (existingBridge !== undefined && existingBridge !== this) {
             throw new DuplicateBridgeError();
@@ -127,41 +135,42 @@ export class RouterBridgeBase {
         activeBridges.set(this.actor, this);
         this.isConnected = true;
         this.hasConnectedOnce = true;
-        // Set up TC39 Signal watcher for actor → router direction
+        // 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 watching router changes (framework-specific)
+        // Start the watch of the router changes. Each framework does this in its own way
         this.watchRouterChanges();
-        // Initial sync: router → actor takes priority over actor → router.
+        // The first synchronization: the direction from the router to the actor has the
+        // priority over the other direction.
         //
-        // If the page loaded on a URL other than the actor's initial state (e.g. the
-        // user typed "/about" directly, or followed a deep link), the router already
-        // knows the correct path but the actor is still at its initial state ("/").
-        // We must drive the actor to match the URL, not overwrite the URL with the
-        // actor's default.
+        // 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() only fires on *future* navigation events — it does NOT
-        // fire for the already-loaded location. Subclasses that can read the router's
-        // current location synchronously should override getInitialRouterPath().
+        // 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();
         const initialActorRoute = this.actor.currentRoute.get();
         if (typeof initialRouterPath === "string") {
-            // Check if actor is already at the router's current location.
-            // Actor currentRoute may be a stateId (e.g. "#app.home") while initialRouterPath
-            // is a URL path (e.g. "/home"). Resolve the path to a stateId before comparing
-            // to avoid a false "they differ" that would trigger an unnecessary initial sync.
+            // 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 already at the router's location when either side matches
-            // directly, or when the actor route is a stateId that resolves to the same
-            // registered path as the matched stateId. Lookups go through
-            // lookupPathByStateId, which tries both the "#stateId" and bare "stateId"
-            // forms automatically — so a route map storing "#about" recognizes an
-            // actor route of "about" (and vice versa) even when the map is a custom
-            // structural implementation keyed on a single form. Concrete-path actor
-            // routes (starting with "/") are compared directly against the router
-            // path only.
+            // 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 ||
@@ -172,17 +181,19 @@ export class RouterBridgeBase {
                         this.lookupPathByStateId(initialActorRoute) ===
                             this.lookupPathByStateId(resolvedStateId)));
             if (!actorAlreadyAtRouterLocation) {
-                // Router path differs from actor route — but is this a deep-link or a restore?
+                // The path of the router is different from the actor route. Is this a deep link, or
+                // is it a restore?
                 //
-                // Deep-link: router is at a non-initial URL the actor hasn't seen yet.
-                //   → router wins: syncActorFromRouter (guards then evaluate access).
+                // A deep link: the router is at a URL that is not the initial one, and the actor saw
+                // that URL not yet.
+                //   → the router wins: syncActorFromRouter. The guards then decide the access.
                 //
-                // Restore: browser is at the machine's initial URL while the actor was
-                //   restored to a different route from a snapshot.
-                //   → actor wins: push actor's restored route to the router.
+                // A restore: the browser is at the initial URL of the machine, and a snapshot
+                // restored the actor to a different route.
+                //   → the actor wins: push the restored route of the actor to the router.
                 //
-                // Detection: if the router URL equals the machine's initial route AND the
-                // actor is at a different route, this is a restore scenario.
+                // 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 &&
                     initialActorRoute !== this.actor.initialRoute) {
@@ -194,19 +205,22 @@ export class RouterBridgeBase {
             }
         }
         else if (initialActorRoute && initialRouterPath === null) {
-            // Explicit null: no router path available (restore/bootstrap) → push actor route.
-            // undefined means the adapter handles initial sync itself — fall through.
+            // An explicit null: no path of the router is available, from a restore or from a
+            // bootstrap → push the actor route.
+            // The value undefined means that the adapter does the first synchronization itself.
+            // Continue.
             this.pushResolvedRoute(initialActorRoute);
         }
         else if (initialActorRoute && initialActorRoute !== this.lastSyncedPath) {
-            // No router path override → sync router from actor (original behaviour)
+            // No path of the router replaces the actor route → write the router from the actor, as before
             this.syncRouterFromActor(initialActorRoute);
         }
     }
     /**
-     * Disconnect the router bridge from the Actor.
+     * Disconnects the router bridge from the Actor.
      *
-     * Stops signal watching and unregisters framework-specific router listener.
+     * The method stops the watch of the signal, and it removes the router listener of the
+     * framework.
      */
     disconnect() {
         const hadRouteWatcher = this.routeWatcher !== null;
@@ -215,7 +229,7 @@ export class RouterBridgeBase {
                 this.routeWatcher.unwatch();
             }
             catch {
-                // Ignore detached watcher errors to keep disconnect idempotent.
+                // Ignore an error of a detached watcher. disconnect() therefore stays idempotent.
             }
         }
         this.routeWatcher = null;
@@ -224,55 +238,79 @@ export class RouterBridgeBase {
         }
         this.isProcessingNavigation = false;
         this.isConnected = false;
-        // Release the actor slot so a new bridge can connect to the same actor.
-        // Only clear if this bridge is the currently registered one — a second bridge
-        // that was rejected at connect() time must not evict the legitimate bridge.
+        // 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);
         }
     }
-    // ── Sync methods (protected, overridable if subclass needs custom behavior) ──
+    // ── The sync methods. They are protected, and a subclass overrides one for its own behavior ──
     /**
-     * Sync router location when actor route signal changes.
-     *
-     * Resolves the actor route to a concrete URL path and calls navigateRouter()
-     * for framework-specific navigation. When the route cannot be resolved
-     * (unknown stateId, parameterized pattern with no concrete values) the push
-     * is skipped entirely — `navigateRouter` is never called with a raw stateId
-     * or pattern.
-     *
-     * Echo suppression — preventing the router's own callback from re-driving the
-     * actor — is handled entirely by `lastSyncedPath`: it is set to the resolved
-     * path before `navigateRouter()` is called, so any `syncActorFromRouter`
-     * invocation for the same path short-circuits at the
-     * `sanitized === lastSyncedPath` check and sends no event regardless of
-     * whether the callback fires synchronously or asynchronously.
-     *
-     * `isProcessingNavigation` is NOT set here — it is only used inside
-     * `syncActorFromRouter` to guard against re-entrant guard-redirect loops.
+     * Writes the location of the router when the route signal of the actor changes.
+     *
+     * The method resolves the actor route to a concrete URL path, then it calls
+     * navigateRouter() for the navigation of the framework. When it cannot resolve the
+     * route, which happens for an unknown stateId and for a parameterized pattern
+     * without concrete values, it skips the push completely: `navigateRouter` receives a
+     * raw stateId or a pattern never.
+     *
+     * `lastSyncedPath` does the complete echo suppression, which stops the callback of
+     * the router from a send to the actor: the method writes the resolved path to
+     * `lastSyncedPath` before the `navigateRouter()` call. Therefore each
+     * `syncActorFromRouter` call of the same path stops at the
+     * `sanitized === lastSyncedPath` test, and it sends no event. This is correct for a
+     * synchronous callback and for an asynchronous callback.
+     *
+     * The method does NOT set `isProcessingNavigation`. That flag lives inside
+     * `syncActorFromRouter`, and it guards against a re-entrant loop of a guard
+     * redirect.
      */
     syncRouterFromActor(route) {
         if (this.hasConnectedOnce && !this.isConnected)
             return;
         if (!route || typeof route !== "string")
             return;
-        if (route === this.lastSyncedPath)
+        if (this.isEchoOfLastPush(route))
             return;
         this.pushResolvedRoute(route);
     }
     /**
-     * Resolve an actor route to its concrete URL path and push it to the router.
-     *
-     * lastSyncedPath must store the concrete path so that the router callback
-     * (which fires with the concrete path) matches and short-circuits in
-     * syncActorFromRouter. Storing the raw stateId (e.g. "#home") would cause a
-     * mismatch against the sanitized path ("/") in the watcher.
-     *
-     * When resolveNavigationPath returns null (parameterized/wildcard pattern,
-     * unknown id) the push is skipped entirely — pushing the raw value would write
-     * stateIds, `:param` patterns, or a literal `*` into the browser URL.
-     * lastSyncedPath is still set to the
-     * raw route so the dedup guard fires correctly on the next identical signal value.
+     * 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.
+     */
+    isEchoOfLastPush(route) {
+        const last = this.lastSyncedPath;
+        if (last === null)
+            return false;
+        if (route === last)
+            return true;
+        const [routePath, routeQuery] = splitLocation(route);
+        const [lastPath, lastQuery] = splitLocation(last);
+        if (routePath !== lastPath)
+            return false;
+        return sortedQuery(routeQuery) === sortedQuery(lastQuery);
+    }
+    /**
+     * Resolves an actor route to its concrete URL path, and pushes that path to the
+     * router.
+     *
+     * lastSyncedPath must hold the concrete path, because the callback of the router
+     * fires with the concrete path. The two values therefore match, and
+     * syncActorFromRouter stops. A raw stateId in that field, for example "#home", does
+     * not match the sanitized path ("/") in the watcher.
+     *
+     * When resolveNavigationPath returns null, which happens for a parameterized
+     * pattern, for a wildcard pattern, and for an unknown id, the method skips the push
+     * completely: a push of the raw value writes a stateId, a `:param` pattern, or a
+     * literal `*` into the browser URL. The method still writes the raw route to
+     * lastSyncedPath. Therefore the dedup guard fires correctly on the next identical
+     * value of the signal.
      */
     pushResolvedRoute(route) {
         const resolved = this.resolveNavigationPath(route);
@@ -282,20 +320,20 @@ export class RouterBridgeBase {
         this.navigateRouter(resolved);
     }
     /**
-     * Sync actor state when router location changes.
-     *
-     * **Known path:** sends a `play.route` event to the actor with the matched
-     * stateId, params, and query. Prevents circular updates via the
-     * `isProcessingNavigation` flag.
-     *
-     * **Unknown/unmapped path:** does NOT send a `play.route` event (actor state
-     * is unchanged). Instead, actively corrects the browser URL by calling
-     * `navigateRouter(actor.currentRoute.get())` — keeping the URL in sync with
-     * actor state even when the user types an invalid path into the address bar
-     * or pushes one programmatically mid-session. `lastSyncedPath` is set to the
-     * resolved concrete path before calling `navigateRouter` so the router's own
-     * callback for that navigation short-circuits the echo-suppression guard and
-     * sends no spurious event.
+     * Writes the actor state when the location of the router changes.
+     *
+     * **A known path:** the method sends a `play.route` event to the actor, with the
+     * stateId of the match, the params, and the query. The `isProcessingNavigation` flag
+     * stops a circular update.
+     *
+     * **An unknown path, or a path with no entry in the map:** the method sends NO
+     * `play.route` event, and the actor state stays as it is. It corrects the browser URL
+     * instead, with a `navigateRouter(actor.currentRoute.get())` call. The URL therefore
+     * follows the actor state, also when the user types an invalid path in the address
+     * bar, or when the code pushes such a path during a session. The method writes the
+     * resolved concrete path to `lastSyncedPath` before the `navigateRouter` call.
+     * Therefore the callback of the router for that navigation stops at the guard of the
+     * echo suppression, and it sends no false event.
      */
     syncActorFromRouter(pathname, search) {
         if (this.hasConnectedOnce && !this.isConnected)
@@ -304,8 +342,8 @@ export class RouterBridgeBase {
             return;
         const sanitized = sanitizePathname(pathname);
         if (sanitized === null)
-            return; // Path too long — reject
-        if (sanitized === this.lastSyncedPath)
+            return; // The path is too long. Refuse it
+        if (this.isEchoOfLastSync(sanitized, search))
             return;
         if (this.isProcessingNavigation)
             return;
@@ -317,33 +355,49 @@ export class RouterBridgeBase {
                 match: (nextPathname) => matchRouteMap(nextPathname, this.routeMap, (resolvedPathname, stateId) => this.extractParams(resolvedPathname, stateId)),
             });
             if (!nextRoute) {
-                // Unknown path — no matching route in the map.
-                // Push the actor's current route back to the router so the browser URL
-                // stays in sync with actor state (corrects an invalid address-bar entry
-                // on cold-load or mid-session navigation to a non-existent path).
+                // The path is unknown, because the map holds no route of it.
+                // Push the current route of the actor back to the router. The browser URL therefore
+                // follows the actor state, and this corrects an invalid entry in the address bar on a
+                // cold load, and also a navigation to a path that is absent during a session.
                 //
-                // Call pushResolvedRoute() directly rather than syncRouterFromActor() to
-                // avoid the dedup guard (lastSyncedPath is already the actor's route).
-                // It sets lastSyncedPath to the resolved concrete path before pushing so
-                // that the router's own callback for this navigation (hashchange /
-                // history event) short-circuits in the sanitized === lastSyncedPath
-                // guard and does not send a spurious play.route event to the actor.
+                // The code calls pushResolvedRoute() directly, and not syncRouterFromActor(). It
+                // therefore passes around the dedup guard, because lastSyncedPath holds the route of
+                // the actor already. pushResolvedRoute sets lastSyncedPath to the resolved concrete
+                // path before the push. Therefore the callback of the router for this navigation, a
+                // hashchange event or a history event, stops at the
+                // sanitized === lastSyncedPath guard, and it sends no false play.route event to the
+                // actor.
                 //
-                // isProcessingNavigation is left true here; the finally block below
-                // clears it after navigateRouter returns, providing a synchronous
-                // re-entrancy guard for any router callback that fires inline.
+                // isProcessingNavigation stays true here. The finally block below clears it after
+                // navigateRouter returns. That block therefore guards synchronously against a
+                // re-entrance of each router callback that fires at once.
                 const currentActorRoute = this.actor.currentRoute.get();
                 if (currentActorRoute) {
                     this.pushResolvedRoute(currentActorRoute);
                 }
                 return;
             }
+            // Record the location BEFORE the send, and record it with its query.
+            //
+            // The route 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);
             this.actor.send(nextRoute.event);
-            this.lastSyncedPath = nextRoute.pathname;
         }
         catch (error) {
-            // URLPatternUnavailableError is a user-actionable error — propagate as-is
-            // so callers can detect it and prompt the user to add a URLPattern polyfill.
+            // 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) {
                 throw error;
             }
@@ -355,19 +409,20 @@ export class RouterBridgeBase {
             this.isProcessingNavigation = false;
         }
     }
-    // ── Utilities (protected, overridable for framework-native param extraction) ──
+    // ── The utilities. They are protected, and a subclass overrides one to read the params of its framework ──
     /**
-     * Extract path parameters from URL using the URLPattern API.
+     * Reads the path parameters of a URL, with the URLPattern API.
      *
-     * Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-     * library. If `URLPattern` is unavailable and the matched route has parameterized
-     * segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
-     * for environments without native URLPattern support (Node.js < 24, older browsers).
+     * 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.
      *
-     * @param pathname - The actual URL path (e.g., '/profile/john')
-     * @param stateId - The matched state ID for looking up the route pattern
-     * @returns Extracted path parameters, or empty object if no match
-     * @throws {URLPatternUnavailableError} When URLPattern is absent and the route is parameterized
+     * @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
      */
     extractParams(pathname, stateId) {
         const pattern = this.routeMap.getPathByStateId(stateId);
@@ -376,22 +431,22 @@ export class RouterBridgeBase {
         return extractRouteParams(pathname, pattern);
     }
     /**
-     * Resolve an actor route value to a concrete URL path for navigation.
-     *
-     * Bridges that receive raw `actor.currentRoute` values in `navigateRouter`
-     * can call this to normalize stateIds (with or without `#` prefix) to paths.
-     * Returns `null` when navigation is not possible:
-     * - unknown stateId with no route map entry
-     * - parameterized or wildcard pattern (e.g. `/profile/:id`, `/docs/*`) — no
-     *   concrete values available to build a real URL
-     * - non-path string that isn't a known stateId
-     *
-     * StateId lookups try both the `"#stateId"` and bare `"stateId"` forms
-     * automatically (via `lookupPathByStateId`), so custom route maps keyed on
-     * only one form still resolve.
-     *
-     * @param route - Raw actor route value (stateId, `#`-stateId, or concrete path)
-     * @returns Concrete URL path, or `null` if navigation should be skipped
+     * Resolves a value of an actor route to a concrete URL path for a navigation.
+     *
+     * A bridge that receives a raw `actor.currentRoute` value in `navigateRouter` calls
+     * this method to convert a stateId, with a `#` prefix or without one, into a path.
+     * The method returns `null` when a navigation is not possible:
+     * - an unknown stateId, with no entry in the route map
+     * - a parameterized pattern or a wildcard pattern, for example `/profile/:id` or
+     *   `/docs/*`, because no concrete value is available for a real URL
+     * - a string that is no path and no known stateId
+     *
+     * A 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.
+     *
+     * @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
      */
     resolveNavigationPath(route) {
         const mapped = this.lookupPathByStateId(route);
@@ -401,17 +456,19 @@ export class RouterBridgeBase {
         return path;
     }
     /**
-     * Look up a route map path for an actor route value, trying both stateId forms.
+     * Returns the path of the route map for a value of an actor route, and it tries both
+     * forms of a stateId.
      *
-     * The actor may emit `"#stateId"` while a custom route map is keyed on the bare
-     * `"stateId"` form (or vice versa). `RouteMap` canonicalizes internally, but the
-     * constructor accepts any structural `{ getStateIdByPath, getPathByStateId }`
-     * object — plain test objects and adapter-specific maps are documented-legal —
-     * so both forms are tried automatically here: raw first, then the `#`-stripped
-     * form, then the `#`-prefixed form.
+     * The actor can emit `"#stateId"` while a route map of your own holds the bare form
+     * `"stateId"`, and also the opposite. `RouteMap` makes the canonical form
+     * internally, but the constructor accepts every structural
+     * `{ getStateIdByPath, getPathByStateId }` object: a plain test object and a map of
+     * one adapter are legal, and the documentation says so. Therefore this method tries
+     * both forms: the raw form first, then the form without the `#`, then the form with
+     * the `#`.
      *
-     * @param route - Raw actor route value (stateId with or without `#` prefix)
-     * @returns The mapped path, or `null`/`undefined` if no form is registered
+     * @param route - The raw value of the actor route: a stateId, with a `#` prefix or without one
+     * @returns The path of the map, or `null` or `undefined` when no form is registered
      */
     lookupPathByStateId(route) {
         const direct = this.routeMap.getPathByStateId(route);
@@ -421,71 +478,136 @@ export class RouterBridgeBase {
         return this.routeMap.getPathByStateId(alternate);
     }
     /**
-     * Extract query parameters from URL search string.
+     * Reads the query parameters of a URL search string.
      *
-     * @param search - URL search string (e.g., '?tab=security&page=1')
-     * @returns Extracted query parameters or empty object
+     * @param search - The URL search string, for example '?tab=security&page=1'
+     * @returns The query parameters of the read, or an empty object
      */
     extractQuery(search) {
         return extractQuery(search);
     }
     /**
-     * Sanitize and validate a raw URL pathname received from the router.
+     * True when a location of the router is the location that this bridge pushed.
      *
-     * Applies the path-length cap (2048 chars), strips query strings and fragments
-     * that may have been included in the pathname segment, and normalises
-     * consecutive slashes.
+     * `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.
      *
-     * Implementations that bypass `syncActorFromRouter()` (e.g. when using
-     * framework-native reactive watchers that receive pre-parsed route objects)
-     * MUST call this method before passing the path to any route-map lookup.
-     * `syncActorFromRouter()` calls this internally, so bridges that delegate
-     * to it do not need to call `sanitizePath` themselves.
+     * 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 pathname - Raw URL pathname from the framework router.
-     * @returns Sanitized pathname, or `null` if the path is invalid / too long.
+     * @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.
+     *
+     * The method applies the limit of the path length, which is 2048 characters. It
+     * removes a query string and a fragment from the segment of the pathname, and it
+     * normalizes each sequence of slashes.
+     *
+     * An implementation that passes around `syncActorFromRouter()`, for example with a
+     * reactive watcher of its framework that receives a route object of a parse before,
+     * MUST call this method before it gives the path to a lookup in the route map.
+     * `syncActorFromRouter()` calls the method internally. Therefore a bridge that uses
+     * that method calls `sanitizePath` never itself.
+     *
+     * @param pathname - The raw URL pathname of the framework router.
+     * @returns The clean pathname, or `null` when the path is invalid or too long.
      */
     sanitizePath(pathname) {
         return sanitizePathname(pathname);
     }
     /**
-     * Return the router's current pathname at connect() time.
-     *
-     * Called once during connect() to perform the initial URL → actor sync.
-     * router.subscribe() only fires on *future* navigation events; it does not
-     * replay the already-loaded location. Subclasses that can read the router's
-     * current location synchronously (e.g. `router.state.location.pathname`)
-     * should override this method so that deep-link / direct-URL loads drive the
-     * actor to the correct state instead of leaving it at its machine default.
-     *
-     * Return semantics:
-     * - `string` → router has a current path; base connect() will sync actor from router
-     * - `null` → router is active but has no current path yet; base connect() will sync router from actor
-     * - `undefined` → adapter handles initial sync itself and base connect() should stay out of the way
-     *
-     * The default returns `undefined`, preserving the previous behaviour for
-     * bridges that have not yet implemented this hook.
+     * Returns the current pathname of the router at the moment of `connect()`.
+     *
+     * `connect()` calls this method one time, for the first synchronization from the URL
+     * to the actor. router.subscribe() fires on a *later* navigation event only. It does
+     * not repeat the location that the router loaded before. A subclass that can read the
+     * current location of its router synchronously, for example with
+     * `router.state.location.pathname`, overrides this method. A deep link and a direct
+     * URL then drive the actor to the correct state, and they leave it not at the default
+     * of its machine.
+     *
+     * The meaning of each return value:
+     * - `string` → the router has a current path, and the base `connect()` writes the actor state from the router
+     * - `null` → the router is active, but it has no current path yet, and the base `connect()` writes the router from the actor
+     * - `undefined` → the adapter does the first synchronization itself, and the base `connect()` does nothing
+     *
+     * The default value is `undefined`. Therefore a bridge without this hook keeps its
+     * earlier behavior.
      */
     getInitialRouterPath() {
         return undefined;
     }
     /**
-     * Return the router's current search string at connect() time.
+     * Returns the current search string of the router at the moment of `connect()`.
      *
-     * Paired with `getInitialRouterPath()` — called once during connect() to pass
-     * the initial URL query string to `syncActorFromRouter()`. If the router's current
-     * URL has no search (or the subclass doesn't override this), returns `undefined`
-     * and `syncActorFromRouter` will produce an empty `query: {}` in the event.
+     * This method is the pair of `getInitialRouterPath()`. `connect()` calls it one time,
+     * to give the query string of the first URL to `syncActorFromRouter()`. It returns
+     * `undefined` when the current URL of the router has no search string, and also when
+     * the subclass overrides the method not. `syncActorFromRouter` then makes an empty
+     * `query: {}` in the event.
      *
-     * Subclasses that override `getInitialRouterPath()` and have a query string
-     * available should also override this method.
+     * A subclass that overrides `getInitialRouterPath()` and has a query string
+     * overrides this method too.
      *
-     * @returns URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
+     * @returns The URL search string, for example `"?tab=security"`, or `undefined` when it is not available.
      */
     getInitialRouterSearch() {
         return undefined;
     }
 }
+/**
+ * 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 `""`.
+ *
+ * `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. `toSorted()`
+ * is ES2023, and four example packages compile this source through the workspace
+ * aliases with `"lib": ["ES2022", …]`, which would break `tsc --build` of the repo.
+ */
+/** Splits a location into its path and its query, with no leading `?`. */
+function splitLocation(location) {
+    const mark = location.indexOf("?");
+    if (mark === -1)
+        return [location, ""];
+    return [location.slice(0, mark), location.slice(mark + 1)];
+}
+/** 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}`;
+}
+function sortedQuery(search) {
+    const pairs = [...new URLSearchParams(search).entries()].map(([key, value]) => `${key}=${value}`);
+    // oxlint-disable-next-line unicorn/no-array-sort
+    pairs.sort();
+    return pairs.join("&");
+}
 function noopCleanup() { }
 function createRouteWatcher(signal, onRoute) {
     let cleanup = noopCleanup;