@xmachines/play-router 2.0.0 → 2.1.0

package/dist/router-bridge-base.d.ts

@@ -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,35 +40,35 @@
  * }
  * ```
  *
- * @see [Play RFC](../../docs/rfc/play.md) - Invariant INV-04
+ * @see [Play RFC](../../docs/rfc/play.md) - invariant INV-04
  */
 import { Signal } from "@xmachines/play-signals";
 import type { RoutableActor } from "./types.js";
 import type { RouterBridge } from "./types.js";
 /**
- * Narrow interface for the TC39 Signal watcher used by `RouterBridgeBase` to
- * monitor `actor.currentRoute` changes.
+ * The narrow interface of the TC39 Signal watcher. `RouterBridgeBase` uses it to
+ * observe each change of `actor.currentRoute`.
  *
- * This interface hides the full `Signal.subtle.Watcher` surface and exposes only
- * the two operations that `RouterBridgeBase` actually needs:
- * - `watch(signal)` — arm the watcher on a specific signal
- * - `unwatch()` — stop watching and release resources
+ * The interface hides the complete `Signal.subtle.Watcher` surface. It exposes the
+ * two operations that `RouterBridgeBase` needs:
+ * - `watch(signal)` — it arms the watcher on one signal
+ * - `unwatch()` — it stops the watch and frees the resources
  *
- * Framework adapter subclasses never interact with this handle directly; it is
- * created and managed internally by `RouterBridgeBase`.
+ * A framework adapter subclass touches this handle never. `RouterBridgeBase` makes
+ * it and manages it internally.
  */
 export interface RouteWatcherHandle {
-    /** Arm the watcher to observe the given signal. */
+    /** Arms the watcher on the given signal. */
     watch(signal: Signal.Computed<string | null>): void;
-    /** Stop observing and release the watcher. */
+    /** Stops the observation and frees the watcher. */
     unwatch(): void;
 }
 /**
- * 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 declare abstract class RouterBridgeBase implements RouterBridge {
     protected readonly actor: RoutableActor;
@@ -79,237 +80,254 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
     protected hasConnectedOnce: boolean;
     protected lastSyncedPath: string | 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 path stops at
+     * the `sanitized === lastSyncedPath` test in `syncActorFromRouter`.
      */
     protected isProcessingNavigation: boolean;
     protected routeWatcher: RouteWatcherHandle | 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: RoutableActor, routeMap: {
         getStateIdByPath(path: string): string | null | undefined;
         getPathByStateId(id: string): string | null | undefined;
     });
     /**
-     * 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(): void;
     /**
-     * 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(): void;
     /**
-     * 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.
      */
     protected syncRouterFromActor(route: string | null | unknown): void;
     /**
-     * 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.
+     * 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.
      */
     private pushResolvedRoute;
     /**
-     * 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.
      */
     protected syncActorFromRouter(pathname: string, search?: string): void;
     /**
-     * Extract path parameters from URL using 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).
-     *
-     * @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
+     * 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.
+     *
+     * @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
      */
     protected extractParams(pathname: string, stateId: string): Record<string, string>;
     /**
-     * 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
      */
     protected resolveNavigationPath(route: string): string | null;
     /**
-     * Look up a route map path for an actor route value, trying both stateId forms.
-     *
-     * 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.
-     *
-     * @param route - Raw actor route value (stateId with or without `#` prefix)
-     * @returns The mapped path, or `null`/`undefined` if no form is registered
+     * Returns the path of the route map for a value of an actor route, and it tries both
+     * forms of a stateId.
+     *
+     * The actor can emit `"#stateId"` while a route map of your own holds the bare form
+     * `"stateId"`, and also the opposite. `RouteMap` makes the canonical form
+     * internally, but the constructor accepts every structural
+     * `{ getStateIdByPath, getPathByStateId }` object: a plain test object and a map of
+     * one adapter are legal, and the documentation says so. Therefore this method tries
+     * both forms: the raw form first, then the form without the `#`, then the form with
+     * the `#`.
+     *
+     * @param route - The raw value of the actor route: a stateId, with a `#` prefix or without one
+     * @returns The path of the map, or `null` or `undefined` when no form is registered
      */
     private lookupPathByStateId;
     /**
-     * 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
      */
     protected extractQuery(search: string): Record<string, string>;
     /**
-     * Must trigger the framework router's navigation (e.g., router.navigate(path)).
-     *
-     * Contract: `path` is always a RESOLVED concrete URL path (e.g. `"/home"`).
-     * The base class resolves actor route values (stateIds like `"#home"`,
-     * parameterized patterns) via `resolveNavigationPath()` before calling this
-     * method and skips the push entirely when resolution fails — implementations
-     * must NOT re-resolve and can push the value as-is.
+     * The method must start the navigation of the framework router, for example with a
+     * router.navigate(path) call.
+     *
+     * The contract: `path` is always a RESOLVED concrete URL path, for example
+     * `"/home"`. The base class resolves each value of an actor route, which includes a
+     * stateId such as `"#home"` and a parameterized pattern, with
+     * `resolveNavigationPath()` before this call. It skips the push completely when the
+     * resolution fails. Therefore an implementation must NOT resolve the value again,
+     * and it pushes the value without a change.
      */
     protected abstract navigateRouter(path: string): void;
     /**
-     * Sanitize and validate a raw URL pathname received from the router.
+     * Cleans a raw URL pathname of the router, and checks it.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+     * 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 - Raw URL pathname from the framework router.
-     * @returns Sanitized pathname, or `null` if the path is invalid / too long.
+     * @param pathname - The raw URL pathname of the framework router.
+     * @returns The clean pathname, or `null` when the path is invalid or too long.
      */
     protected sanitizePath(pathname: string): string | null;
     /**
-     * Start watching for router location changes.
+     * Starts the watch of the location changes of the router.
      *
-     * Called by connect(). Should set up the framework-specific subscription
-     * for location changes and call syncActorFromRouter() on each change.
+     * `connect()` calls this method. The method installs the subscription of the
+     * framework for each location change, and it calls syncActorFromRouter() on each
+     * change.
      *
-     * **Implementations that call `syncActorFromRouter`** get path sanitization
-     * applied automatically — no extra work needed.
+     * **An implementation that calls `syncActorFromRouter`** receives the clean path
+     * automatically, and it needs no more work.
      *
-     * **Implementations that bypass `syncActorFromRouter`** (e.g. `VueRouterBridge`,
-     * which builds the `play.route` event directly from framework-native route params)
-     * MUST call `this.sanitizePath(path)` and return early when it returns `null`.
-     * Skipping this allows oversized or malformed paths through without the length
-     * and content guards that protect the route-map lookup.
+     * **An implementation that passes around `syncActorFromRouter`**, for example
+     * `VueRouterBridge`, which builds the `play.route` event from the route params of its
+     * framework, MUST call `this.sanitizePath(path)` and return at once when that
+     * method returns `null`. Without this call, a path that is too long or malformed
+     * passes the guards of the length and of the contents, and those guards protect the
+     * lookup in the route map.
      */
     protected abstract watchRouterChanges(): void;
     /**
-     * Stop watching for router location changes.
+     * Stops the watch of the location changes of the router.
      *
-     * Called by disconnect(). Should clean up the framework-specific subscription.
+     * `disconnect()` calls this method. The method removes the subscription of the
+     * framework.
      */
     protected abstract unwatchRouterChanges(): void;
     /**
-     * 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.
      */
     protected getInitialRouterPath(): string | null | 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.
      */
     protected getInitialRouterSearch(): string | undefined;
 }

package/dist/router-bridge-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router-bridge-base.d.ts","sourceRoot":"","sources":["../src/router-bridge-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"router-bridge-base.d.ts","sourceRoot":"","sources":["../src/router-bridge-base.ts"],"names":[],"mappings":"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"}