@xmachines/play-router 1.0.0-beta.8 → 1.0.0

package/dist/query.js

@@ -1,3 +1,19 @@
+import { getSuccessors, hasNode, hasPath } from "@statelyai/graph";
+/**
+ * Get the routable successor nodes of a state — states directly reachable via
+ * transition edges that have a defined `meta.route`.
+ *
+ * Shared traversal core for `getTransitionReachableStateIds` and
+ * `getTransitionReachableRoutes`; returns full nodes so callers can project
+ * whichever field they need (stateId vs raw route string).
+ */
+const getRoutableSuccessors = (graph, stateId) => 
+// A state ID with no graph node (e.g. a non-routable or removed state) is a
+// normal "nothing reachable" outcome, checked explicitly rather than by
+// pattern-matching thrown error messages.
+hasNode(graph, stateId)
+    ? getSuccessors(graph, stateId).filter((n) => n.data.route !== undefined)
+    : [];
 /**
  * Get all routes navigable from given state
  *
@@ -19,9 +35,34 @@ export const getNavigableRoutes = (tree, stateId) => {
     const node = tree.byStateId.get(stateId);
     if (!node)
         return [];
-    return [
-        ...node.children, // Direct child routes
-    ];
+    const results = [...node.children]; // Direct child routes (existing behavior)
+    // If graph is available, also include routes reachable via transitions.
+    // Look nodes up by state ID: graph nodes carry the RAW meta.route string
+    // (possibly relative, e.g. "detail"), while tree.byPath is keyed by resolved
+    // fullPath ("/section/detail") — a path-based lookup would silently drop
+    // every relative route. State IDs are unambiguous in both structures.
+    if (tree.graph) {
+        const reachableStateIds = getTransitionReachableStateIds(tree.graph, stateId);
+        const existingPaths = new Set(results.map((r) => r.fullPath));
+        for (const reachableStateId of reachableStateIds) {
+            const routeNode = tree.byStateId.get(reachableStateId);
+            if (routeNode && !existingPaths.has(routeNode.fullPath)) {
+                results.push(routeNode);
+                existingPaths.add(routeNode.fullPath);
+            }
+        }
+    }
+    return results;
+};
+/**
+ * Get state IDs of routable states reachable via transitions from a state.
+ *
+ * Same traversal as `getTransitionReachableRoutes`, but returns state IDs
+ * instead of raw `meta.route` strings so callers can resolve nodes through
+ * `tree.byStateId` without raw-vs-resolved path ambiguity.
+ */
+const getTransitionReachableStateIds = (graph, stateId) => {
+    return getRoutableSuccessors(graph, stateId).map((n) => n.data.stateId);
 };
 /**
  * Get all routable routes from tree as flat array
@@ -66,4 +107,58 @@ export const getRoutableRoutes = (tree) => {
 export const routeExists = (tree, path) => {
     return tree.byPath.has(path);
 };
+/**
+ * Get routes reachable via transitions from current state
+ *
+ * Uses the @statelyai/graph successor algorithm to find all states
+ * directly reachable via transition edges from the given state,
+ * then filters to those with defined routes.
+ *
+ * Returned values are the RAW `meta.route` strings from the machine — relative
+ * routes (e.g. `"detail"`) are NOT resolved to full paths and cannot be used as
+ * `tree.byPath` keys. For resolved `RouteNode`s use `getNavigableRoutes`, which
+ * resolves reachable states through `tree.byStateId`.
+ *
+ * @param graph - Machine graph from RouteTree.graph
+ * @param stateId - Current state ID (e.g., "test.home")
+ * @returns Array of raw route strings reachable via transitions
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * if (tree.graph) {
+ *   const reachable = getTransitionReachableRoutes(tree.graph, 'auth.loggedIn');
+ *   // ['/dashboard', '/settings'] — routes reachable via transitions
+ * }
+ * ```
+ */
+export const getTransitionReachableRoutes = (graph, stateId) => {
+    return getRoutableSuccessors(graph, stateId).map((n) => n.data.route);
+};
+/**
+ * Check if a route is reachable from current state via transitions
+ *
+ * Uses @statelyai/graph path-finding to determine if there exists
+ * a chain of transition edges from the source state to the target state.
+ *
+ * @param graph - Machine graph from RouteTree.graph
+ * @param fromStateId - Source state ID
+ * @param toStateId - Target state ID
+ * @returns true if a transition path exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * if (tree.graph) {
+ *   const canReach = isRouteReachable(tree.graph, 'auth.login', 'auth.dashboard');
+ *   // true if login → dashboard transition path exists
+ * }
+ * ```
+ */
+export const isRouteReachable = (graph, fromStateId, toStateId) => {
+    // Missing endpoints are a normal "not reachable" outcome.
+    return hasNode(graph, fromStateId) && hasNode(graph, toStateId)
+        ? hasPath(graph, fromStateId, toStateId)
+        : false;
+};
 //# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAe,EAAE,OAAe,EAAe,EAAE;IACnF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,OAAO;QACN,GAAG,IAAI,CAAC,QAAQ,EAAE,sBAAsB;KACxC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAe,EAAe,EAAE;IACjE,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5C,wEAAwE;QACxE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAe,EAAE,IAAY,EAAW,EAAE;IACrE,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC,CAAC"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

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

@@ -3,8 +3,9 @@
  *
  * Captures the 90% identical logic from all existing router bridges:
  * - TC39 Signal watcher for actor → router direction
- * - isProcessingNavigation flag for circular update prevention
- * - syncRouterFromActor / syncActorFromRouter with URL parameter extraction
+ * - `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
  *
  * Subclasses implement only the 3 framework-specific abstract methods:
@@ -17,7 +18,7 @@
  * export class MyRouterBridge extends RouterBridgeBase {
  *   private unsubscribe: (() => void) | null = null;
  *
- *   constructor(private router: MyRouter, actor: AbstractActor<AnyActorLogic> & Routable, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
+ *   constructor(private router: MyRouter, actor: RoutableActor, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
  *     super(actor, routeMap);
  *   }
  *
@@ -38,12 +39,29 @@
  * }
  * ```
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1 - Invariant INV-04}
+ * @see [Play RFC](../../docs/rfc/play.md) - Invariant INV-04
  */
 import { Signal } from "@xmachines/play-signals";
-import type { AbstractActor, Routable } from "@xmachines/play-actor";
-import type { AnyActorLogic } from "xstate";
+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.
+ *
+ * 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
+ *
+ * Framework adapter subclasses never interact with this handle directly; it is
+ * created and managed internally by `RouterBridgeBase`.
+ */
+export interface RouteWatcherHandle {
+    /** Arm the watcher to observe the given signal. */
+    watch(signal: Signal.Computed<string | null>): void;
+    /** Stop observing and release the watcher. */
+    unwatch(): void;
+}
 /**
  * Abstract base class for all `@xmachines` router adapter bridges.
  *
@@ -52,31 +70,52 @@ import type { RouterBridge } from "./types.js";
  * between frameworks.
  */
 export declare abstract class RouterBridgeBase implements RouterBridge {
-    protected readonly actor: AbstractActor<AnyActorLogic> & Routable;
+    protected readonly actor: RoutableActor;
     protected readonly routeMap: {
-        getStateIdByPath(path: string): string | undefined;
-        getPathByStateId(id: string): string | undefined;
+        getStateIdByPath(path: string): string | null | undefined;
+        getPathByStateId(id: string): string | null | undefined;
     };
     protected isConnected: boolean;
     protected hasConnectedOnce: boolean;
-    protected lastSyncedPath: string;
-    protected isProcessingNavigation: boolean;
-    protected routeWatcher: Signal.subtle.Watcher | null;
+    protected lastSyncedPath: string | null;
     /**
-     * Constructor receives the 3 things all bridges need.
+     * 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).
      *
-     * @param actor - Actor with currentRoute signal and send method
-     * @param routeMap - Bidirectional route map for stateId ↔ path resolution
+     * 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`.
      */
-    constructor(actor: AbstractActor<AnyActorLogic> & Routable, routeMap: {
-        getStateIdByPath(path: string): string | undefined;
-        getPathByStateId(id: string): string | undefined;
+    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.
+     */
+    constructor(actor: RoutableActor, routeMap: {
+        getStateIdByPath(path: string): string | null | undefined;
+        getPathByStateId(id: string): string | null | undefined;
     });
     /**
      * Connect the router bridge to the Actor.
      *
      * Sets up the TC39 Signal watcher for actor → router direction and
      * starts watching router changes (framework-specific).
+     *
+     * 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`
+     *
+     * Adapters that need custom initial-sync behavior should override
+     * `getInitialRouterPath()` rather than reordering `connect()` steps.
      */
     connect(): void;
     /**
@@ -88,25 +127,102 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
     /**
      * Sync router location when actor route signal changes.
      *
-     * Calls navigateRouter() for framework-specific navigation.
-     * Prevents circular updates via isProcessingNavigation flag.
+     * 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.
      */
     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.
+     */
+    private pushResolvedRoute;
     /**
      * Sync actor state when router location changes.
      *
-     * Sends play.route event to actor with resolved stateId, params, and query.
-     * Prevents circular updates via isProcessingNavigation flag.
+     * **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.
      */
     protected syncActorFromRouter(pathname: string, search?: string): void;
     /**
-     * Extract path parameters from URL using URLPattern API.
+     * 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 route pattern
-     * @returns Extracted path parameters or empty object
+     * @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
      */
     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
+     */
+    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
+     */
+    private lookupPathByStateId;
     /**
      * Extract query parameters from URL search string.
      *
@@ -115,17 +231,46 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
      */
     protected extractQuery(search: string): Record<string, string>;
     /**
-     * Navigate the framework router to the given path.
-     *
-     * Called when actor's currentRoute signal changes to a new path.
      * 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.
      */
     protected abstract navigateRouter(path: string): void;
+    /**
+     * Sanitize and validate a raw URL pathname received from the router.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * @param pathname - Raw URL pathname from the framework router.
+     * @returns Sanitized pathname, or `null` if the path is invalid / too long.
+     */
+    protected sanitizePath(pathname: string): string | null;
     /**
      * Start watching for router location changes.
      *
      * Called by connect(). Should set up the framework-specific subscription
      * for location changes and call syncActorFromRouter() on each change.
+     *
+     * **Implementations that call `syncActorFromRouter`** get path sanitization
+     * applied automatically — no extra work needed.
+     *
+     * **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.
      */
     protected abstract watchRouterChanges(): void;
     /**
@@ -135,7 +280,7 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
      */
     protected abstract unwatchRouterChanges(): void;
     /**
-     * Return the router's current pathname at connect() time, or null if unavailable.
+     * 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
@@ -144,9 +289,28 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
      * 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.
      *
-     * The default returns null (no initial router → actor sync), preserving the
-     * previous behaviour for bridges that have not yet implemented this hook.
+     * 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.
+     */
+    protected getInitialRouterPath(): string | null | undefined;
+    /**
+     * Return the router's current search string at connect() time.
+     *
+     * 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.
+     *
+     * Subclasses that override `getInitialRouterPath()` and have a query string
+     * available should also override this method.
+     *
+     * @returns URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
      */
-    protected getInitialRouterPath(): string | null;
+    protected getInitialRouterSearch(): string | undefined;
 }
 //# sourceMappingURL=router-bridge-base.d.ts.map

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;GAMG;AACH,8BAAsB,gBAAiB,YAAW,YAAY;IAe5D,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ;IACjE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE;QAC5B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;QACnD,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KACjD;IAjBF,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IACvC,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAS;IAC5C,SAAS,CAAC,cAAc,EAAE,MAAM,CAAM;IACtC,SAAS,CAAC,sBAAsB,EAAE,OAAO,CAAS;IAClD,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,GAAG,IAAI,CAAQ;IAE5D;;;;;OAKG;gBAEiB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE;QAC5B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;QACnD,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KACjD;IASF;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IA6Cf;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAqBlB;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI;IAcnE;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA0CtE;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAalF;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAc9D;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAErD;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,IAAI;IAE7C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,IAAI,IAAI;IAE/C;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,oBAAoB,IAAI,MAAM,GAAG,IAAI;CAG/C"}
+{"version":3,"file":"router-bridge-base.d.ts","sourceRoot":"","sources":["../src/router-bridge-base.ts"],"names":[],"mappings":"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"}