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

package/dist/machine-to-graph.js

@@ -0,0 +1,115 @@
+import { toDirectedGraph } from "xstate/graph";
+import { createGraph } from "@statelyai/graph";
+import { UnknownStateTypeError } from "./errors.js";
+/**
+ * Convert an XState v5 state machine to a typed @statelyai/graph Graph.
+ *
+ * The conversion pipeline is:
+ * `XState Machine → toDirectedGraph() → DirectedGraphNode hierarchy → createGraph() → Graph`
+ *
+ * The resulting graph captures:
+ * - **Hierarchy**: node parentId reflects XState compound/parallel nesting
+ * - **Edges**: all transitions with event types and optional guard types
+ * - **Metadata**: state type, meta object, and extracted route path
+ *
+ * @param machine - XState v5 state machine (any shape)
+ * @returns Typed directed graph with MachineNodeData on nodes and MachineEdgeData on edges
+ *
+ * @example
+ * Convert a simple machine and query its routes
+ * ```typescript
+ * import { createMachine } from "xstate";
+ * import { getChildren, getSuccessors } from "@statelyai/graph";
+ * import { machineToGraph } from "@xmachines/play-router";
+ *
+ * const machine = createMachine({
+ *   id: "app",
+ *   initial: "home",
+ *   states: {
+ *     home: { meta: { route: "/home" }, on: { GO_ABOUT: "about" } },
+ *     about: { meta: { route: "/about" } },
+ *   },
+ * });
+ *
+ * const graph = machineToGraph(machine);
+ * const children = getChildren(graph, "app"); // [home, about]
+ * const successors = getSuccessors(graph, "app.home"); // [about]
+ * ```
+ *
+ * @see {@link MachineNodeData} for node data shape
+ * @see {@link MachineEdgeData} for edge data shape
+ * @see https://github.com/statelyai/graph for @statelyai/graph API reference
+ */
+/**
+ * Set of valid XState state types for runtime validation.
+ * Guards against future XState changes or unexpected machine shapes.
+ */
+const VALID_STATE_TYPES = new Set([
+    "atomic",
+    "compound",
+    "parallel",
+    "final",
+    "history",
+]);
+export const machineToGraph = (machine) => {
+    const dg = toDirectedGraph(machine);
+    // Flatten DirectedGraphNode hierarchy into flat node/edge arrays
+    const nodes = [];
+    const edges = [];
+    let edgeCounter = 0;
+    const walk = (dgNode, parentId) => {
+        const sn = dgNode.stateNode;
+        const meta = sn.meta;
+        const metaRoute = meta?.["route"];
+        const route = typeof metaRoute === "string"
+            ? metaRoute
+            : typeof metaRoute === "object" && metaRoute !== null && "path" in metaRoute
+                ? metaRoute.path
+                : undefined;
+        // Runtime assertion: validate state type before casting
+        if (!VALID_STATE_TYPES.has(sn.type)) {
+            throw new UnknownStateTypeError(sn.type, sn.id, [...VALID_STATE_TYPES]);
+        }
+        const nodeData = {
+            stateId: sn.id,
+            type: sn.type,
+        };
+        if (meta !== undefined)
+            nodeData.meta = meta;
+        if (route !== undefined)
+            nodeData.route = route;
+        if (parentId !== undefined) {
+            nodes.push({ id: dgNode.id, parentId, data: nodeData });
+        }
+        else {
+            nodes.push({ id: dgNode.id, data: nodeData });
+        }
+        // Collect edges from THIS node (edges are on source node, not graph root)
+        for (const edge of dgNode.edges) {
+            const edgeData = {
+                eventType: edge.label.text,
+            };
+            if (edge.transition.guard) {
+                edgeData.guardType = String(edge.transition.guard);
+            }
+            edges.push({
+                id: `e${edgeCounter++}`,
+                sourceId: edge.source.id,
+                targetId: edge.target.id,
+                data: edgeData,
+            });
+        }
+        // Recurse into children with current node as parent
+        for (const child of dgNode.children) {
+            walk(child, dgNode.id);
+        }
+    };
+    walk(dg);
+    return createGraph({
+        mode: "directed",
+        initialNodeId: dg.id,
+        nodes,
+        edges,
+    });
+};
+//# sourceMappingURL=machine-to-graph.js.map

package/dist/machine-to-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-to-graph.js","sourceRoot":"","sources":["../src/machine-to-graph.ts"],"names":[],"mappings":"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"}

package/dist/query.d.ts

@@ -1,4 +1,5 @@
-import type { RouteTree, RouteNode } from "./types.js";
+import type { Graph } from "@statelyai/graph";
+import type { RouteTree, RouteNode, MachineNodeData, MachineEdgeData } from "./types.js";
 /**
  * Get all routes navigable from given state
  *
@@ -49,4 +50,51 @@ export declare const getRoutableRoutes: (tree: RouteTree) => RouteNode[];
  * @returns true if path exists, false otherwise
  */
 export declare const routeExists: (tree: RouteTree, path: string) => boolean;
+/**
+ * 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 declare const getTransitionReachableRoutes: (graph: Graph<MachineNodeData, MachineEdgeData>, stateId: string) => string[];
+/**
+ * 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 declare const isRouteReachable: (graph: Graph<MachineNodeData, MachineEdgeData>, fromStateId: string, toStateId: string) => boolean;
 //# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,EAAE,SAAS,MAAM,KAAG,SAAS,EAO9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,SAAS,KAAG,SAAS,EAW5D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,OAE3D,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAa,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqBzF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,EAAE,SAAS,MAAM,KAAG,SAAS,EAyB9E,CAAC;AAgBF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,SAAS,KAAG,SAAS,EAW5D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,OAE3D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,EAC9C,SAAS,MAAM,KACb,MAAM,EAER,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,GAC5B,OAAO,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,EAC9C,aAAa,MAAM,EACnB,WAAW,MAAM,KACf,OAKF,CAAC"}

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,23 +70,36 @@ 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 | 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: {
+    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;
     });
@@ -77,6 +108,14 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
      *
      * 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,50 +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;
     /**
-     * Sync actor state when router location changes.
+     * Resolve an actor route to its concrete URL path and push it to the router.
      *
-     * Sends play.route event to actor with resolved stateId, params, and query.
-     * Prevents circular updates via isProcessingNavigation flag.
+     * 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.
      */
-    protected syncActorFromRouter(pathname: string, search?: string): void;
+    private pushResolvedRoute;
     /**
-     * Sanitize a raw pathname before routing to prevent injection and DoS.
-     *
-     * - Enforces maximum length (2048 chars) to prevent DoS via expensive URLPattern.exec()
-     * - Strips query string (everything from ? onwards) — some adapters may pass
-     *   a pathname that still contains ? if extraction was imprecise
-     * - Strips hash fragment (everything from # onwards)
-     * - Normalizes consecutive slashes to single slash
-     *
-     * Returns null if the path should be rejected (too long). Returns the
-     * normalized path string otherwise.
+     * Sync actor state when router location changes.
      *
-     * Called at the top of syncActorFromRouter() before any routing logic.
-     * Because all adapters pass through this single method, sanitization
-     * protects Vue, Solid, TanStack, and React Router bridges simultaneously.
+     * **Known path:** sends a `play.route` event to the actor with the matched
+     * stateId, params, and query. Prevents circular updates via the
+     * `isProcessingNavigation` flag.
      *
-     * @param pathname - Raw pathname from router adapter
-     * @returns Sanitized pathname, or null if rejected
+     * **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.
      */
-    private sanitizePathname;
+    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 (Node.js < 24, older browsers without a
-     * polyfill), this method returns `{}` silently (graceful degradation — routing still
-     * works, params will be empty).
+     * 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 if URLPattern is unavailable or no match
+     * @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.
      *
@@ -140,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;
     /**
@@ -160,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
@@ -169,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