@xmachines/play-router 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/query.js

@@ -1,3 +1,4 @@
+import { getSuccessors, hasPath } from "@statelyai/graph";
 /**
  * Get all routes navigable from given state
  *
@@ -19,9 +20,21 @@ 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
+    if (tree.graph) {
+        const transitionRoutes = getTransitionReachableRoutes(tree.graph, stateId);
+        const existingPaths = new Set(results.map((r) => r.fullPath));
+        for (const routePath of transitionRoutes) {
+            // Find the RouteNode for this path and add if not already included
+            const routeNode = tree.byPath.get(routePath);
+            if (routeNode && !existingPaths.has(routeNode.fullPath)) {
+                results.push(routeNode);
+                existingPaths.add(routeNode.fullPath);
+            }
+        }
+    }
+    return results;
 };
 /**
  * Get all routable routes from tree as flat array
@@ -66,4 +79,68 @@ 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.
+ *
+ * @param graph - Machine graph from RouteTree.graph
+ * @param stateId - Current state ID (e.g., "test.home")
+ * @returns Array of route paths 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) => {
+    try {
+        return getSuccessors(graph, stateId)
+            .filter((n) => n.data.route !== undefined)
+            .map((n) => n.data.route);
+    }
+    catch (err) {
+        if (err instanceof Error && /not found|does not exist/i.test(err.message)) {
+            return [];
+        }
+        throw err;
+    }
+};
+/**
+ * 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) => {
+    try {
+        return hasPath(graph, fromStateId, toStateId);
+    }
+    catch (err) {
+        if (err instanceof Error && /not found|does not exist/i.test(err.message)) {
+            return false;
+        }
+        throw err;
+    }
+};
 //# 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

@@ -17,7 +17,7 @@
  * export class MyRouterBridge extends RouterBridgeBase {
  *   private unsubscribe: (() => void) | null = null;
  *
- *   constructor(private router: MyRouter, actor: any, routeMap: any) {
+ *   constructor(private router: MyRouter, actor: AbstractActor<AnyActorLogic> & Routable, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
  *     super(actor, routeMap);
  *   }
  *
@@ -38,12 +38,30 @@
  * }
  * ```
  *
- * @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 { 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.State<unknown>): void;
+    /** Stop observing and release the watcher. */
+    unwatch(): void;
+}
 /**
  * Abstract base class for all `@xmachines` router adapter bridges.
  *
@@ -54,21 +72,23 @@ import type { RouterBridge } from "./types.js";
 export declare abstract class RouterBridgeBase implements RouterBridge {
     protected readonly actor: AbstractActor<AnyActorLogic> & Routable;
     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 lastSyncedPath: string;
+    protected isConnected: boolean;
+    protected hasConnectedOnce: boolean;
+    protected lastSyncedPath: string | null;
     protected isProcessingNavigation: boolean;
-    protected routeWatcher: Signal.subtle.Watcher | null;
+    protected routeWatcher: RouteWatcherHandle | null;
     /**
-     * Constructor receives the 3 things all bridges need.
-     *
-     * @param actor - Actor with currentRoute signal and send method
-     * @param routeMap - Bidirectional route map for stateId ↔ path resolution
+     * @param actor    - A `Routable` actor exposing `currentRoute` and `send`.
+     * @param routeMap - Bidirectional route map for `stateId ↔ path` resolution.
+     *   Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters
+     *   typically wrap the result of `createRouteMap()` or an equivalent.
      */
     constructor(actor: AbstractActor<AnyActorLogic> & Routable, routeMap: {
-        getStateIdByPath(path: string): string | undefined;
-        getPathByStateId(id: string): string | undefined;
+        getStateIdByPath(path: string): string | null | undefined;
+        getPathByStateId(id: string): string | null | undefined;
     });
     /**
      * Connect the router bridge to the Actor.
@@ -98,11 +118,16 @@ export declare abstract class RouterBridgeBase implements RouterBridge {
      */
     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 (Node.js < 24, older browsers without a
+     * polyfill), this method returns `{}` silently (graceful degradation — routing still
+     * works, params will be empty).
      *
      * @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 URLPattern is unavailable or no match
      */
     protected extractParams(pathname: string, stateId: string): Record<string, string>;
     /**
@@ -133,7 +158,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
@@ -142,9 +167,14 @@ 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;
+    protected getInitialRouterPath(): string | null | 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;IAa5D,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;IAfF,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;IAsCf;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAOlB;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI;IAanE;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAyCtE;;;;;;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;IAU9D;;;;;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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,MAAM,EAAe,MAAM,yBAAyB,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAO5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IAClC,mDAAmD;IACnD,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C,8CAA8C;IAC9C,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;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,IAAI,GAAG,SAAS,CAAC;QAC1D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;KACxD;IAjBF,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IACvC,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAS;IAC5C,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC/C,SAAS,CAAC,sBAAsB,EAAE,OAAO,CAAS;IAClD,SAAS,CAAC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAQ;IAEzD;;;;;OAKG;gBAEiB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE;QAC5B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;QAC1D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;KACxD;IASF;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IA+Df;;;;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;IAwCtE;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAqBlF;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAM9D;;;;;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;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,oBAAoB,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS;CAG3D"}

package/dist/router-bridge-base.js

@@ -17,7 +17,7 @@
  * export class MyRouterBridge extends RouterBridgeBase {
  *   private unsubscribe: (() => void) | null = null;
  *
- *   constructor(private router: MyRouter, actor: any, routeMap: any) {
+ *   constructor(private router: MyRouter, actor: AbstractActor<AnyActorLogic> & Routable, routeMap: { getStateIdByPath(path: string): string | undefined; getPathByStateId(id: string): string | undefined; }) {
  *     super(actor, routeMap);
  *   }
  *
@@ -38,9 +38,11 @@
  * }
  * ```
  *
- * @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 { Signal, watchSignal } from "@xmachines/play-signals";
+import { RouterSyncError } from "./errors.js";
+import { buildPlayRouteEvent, extractQuery, resolveRouteMapMatch, sanitizePathname, } from "./router-sync.js";
 /**
  * Abstract base class for all `@xmachines` router adapter bridges.
  *
@@ -52,21 +54,23 @@ export class RouterBridgeBase {
     actor;
     routeMap;
     // ── Common state (identical across all 4 existing bridges) ──
-    lastSyncedPath = "";
+    isConnected = false;
+    hasConnectedOnce = false;
+    lastSyncedPath = null;
     isProcessingNavigation = false;
     routeWatcher = null;
     /**
-     * Constructor receives the 3 things all bridges need.
-     *
-     * @param actor - Actor with currentRoute signal and send method
-     * @param routeMap - Bidirectional route map for stateId ↔ path resolution
+     * @param actor    - A `Routable` actor exposing `currentRoute` and `send`.
+     * @param routeMap - Bidirectional route map for `stateId ↔ path` resolution.
+     *   Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters
+     *   typically wrap the result of `createRouteMap()` or an equivalent.
      */
     constructor(actor, routeMap) {
         this.actor = actor;
         this.routeMap = routeMap;
-        // Initialize lastSyncedPath to actor's current route (prevents initial sync loop)
-        // Pattern from VueRouterBridge and SolidRouterBridge
-        this.lastSyncedPath = this.actor.currentRoute.get() || "";
+        // Initialize lastSyncedPath to actor's current route (prevents initial sync loop).
+        // null means "nothing synced yet" — distinct from any real path string.
+        this.lastSyncedPath = this.actor.currentRoute.get() ?? null;
     }
     // ── RouterBridge protocol (final — subclasses must not override) ──
     /**
@@ -76,16 +80,15 @@ export class RouterBridgeBase {
      * starts watching router changes (framework-specific).
      */
     connect() {
+        if (this.isConnected) {
+            return;
+        }
+        this.isConnected = true;
+        this.hasConnectedOnce = true;
         // Set up TC39 Signal watcher for actor → router direction
-        this.routeWatcher = new Signal.subtle.Watcher(() => {
-            queueMicrotask(() => {
-                this.routeWatcher?.getPending(); // Acknowledge notification
-                const route = this.actor.currentRoute.get();
-                this.syncRouterFromActor(route);
-                this.routeWatcher?.watch(this.actor.currentRoute); // Re-watch (one-shot)
-            });
+        this.routeWatcher = createRouteWatcher(this.actor.currentRoute, (route) => {
+            this.syncRouterFromActor(route);
         });
-        this.routeWatcher.watch(this.actor.currentRoute);
         // Start watching router changes (framework-specific)
         this.watchRouterChanges();
         // Initial sync: router → actor takes priority over actor → router.
@@ -101,9 +104,33 @@ export class RouterBridgeBase {
         // current location synchronously should override getInitialRouterPath().
         const initialRouterPath = this.getInitialRouterPath();
         const initialActorRoute = this.actor.currentRoute.get();
-        if (initialRouterPath && initialRouterPath !== initialActorRoute) {
-            // Router path differs from actor state → sync actor from router
-            this.syncActorFromRouter(initialRouterPath);
+        if (typeof initialRouterPath === "string" && initialRouterPath !== initialActorRoute) {
+            // Router path differs from actor route — but is this a deep-link or a restore?
+            //
+            // Deep-link: router is at a non-initial URL the actor hasn't seen yet.
+            //   → router wins: syncActorFromRouter (guards then evaluate 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.
+            //
+            // Detection: if the router URL equals the machine's initial route AND the
+            // actor is at a different route, this is a restore scenario.
+            if (initialActorRoute &&
+                initialRouterPath === this.actor.initialRoute &&
+                initialActorRoute !== this.actor.initialRoute) {
+                this.lastSyncedPath = initialActorRoute;
+                this.navigateRouter(initialActorRoute);
+            }
+            else {
+                this.syncActorFromRouter(initialRouterPath);
+            }
+        }
+        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.
+            this.lastSyncedPath = initialActorRoute;
+            this.navigateRouter(initialActorRoute);
         }
         else if (initialActorRoute && initialActorRoute !== this.lastSyncedPath) {
             // No router path override → sync router from actor (original behaviour)
@@ -116,8 +143,22 @@ export class RouterBridgeBase {
      * Stops signal watching and unregisters framework-specific router listener.
      */
     disconnect() {
+        const hadRouteWatcher = this.routeWatcher !== null;
+        if (this.routeWatcher) {
+            try {
+                this.routeWatcher.unwatch();
+            }
+            catch {
+                // Ignore detached watcher errors to keep disconnect idempotent.
+            }
+        }
         this.routeWatcher = null;
-        this.unwatchRouterChanges();
+        if (this.isConnected || hadRouteWatcher) {
+            this.unwatchRouterChanges();
+        }
+        this.isProcessingNavigation = false;
+        // (removed: this.hasConnectedOnce = true; — copy-paste artifact from connect(), per CONS-07)
+        this.isConnected = false;
     }
     // ── Sync methods (protected, overridable if subclass needs custom behavior) ──
     /**
@@ -127,6 +168,8 @@ export class RouterBridgeBase {
      * Prevents circular updates via isProcessingNavigation flag.
      */
     syncRouterFromActor(route) {
+        if (this.hasConnectedOnce && !this.isConnected)
+            return;
         if (!route || typeof route !== "string")
             return;
         if (route === this.lastSyncedPath)
@@ -147,37 +190,35 @@ export class RouterBridgeBase {
      * Prevents circular updates via isProcessingNavigation flag.
      */
     syncActorFromRouter(pathname, search) {
+        if (this.hasConnectedOnce && !this.isConnected)
+            return;
         if (typeof pathname !== "string")
             return;
-        if (pathname === this.lastSyncedPath)
+        const sanitized = sanitizePathname(pathname);
+        if (sanitized === null)
+            return; // Path too long — reject
+        if (sanitized === this.lastSyncedPath)
             return;
         if (this.isProcessingNavigation)
             return;
         this.isProcessingNavigation = true;
         try {
-            const stateId = this.routeMap.getStateIdByPath(pathname);
-            if (!stateId) {
+            const nextRoute = buildPlayRouteEvent({
+                pathname,
+                search,
+                resolve: (nextPathname) => resolveRouteMapMatch(nextPathname, this.routeMap, (resolvedPathname, stateId) => this.extractParams(resolvedPathname, stateId)),
+            });
+            if (!nextRoute) {
                 this.isProcessingNavigation = false;
                 return;
             }
-            const params = this.extractParams(pathname, stateId);
-            const query = this.extractQuery(search || "");
-            // formatPlayRouteTransitions generates guards that match event.to === "#stateId"
-            // RouteMap stateIds from extractMachineRoutes don't include the "#" prefix,
-            // so we normalise here. If the routeMap already stores "#stateId" (as some
-            // manually-constructed maps do) we avoid doubling the prefix.
-            const eventTarget = stateId.startsWith("#") ? stateId : `#${stateId}`;
-            const event = {
-                type: "play.route",
-                to: eventTarget,
-                params,
-                query,
-            };
-            this.actor.send(event);
-            this.lastSyncedPath = pathname;
+            this.actor.send(nextRoute.event);
+            this.lastSyncedPath = nextRoute.pathname;
         }
         catch (error) {
-            console.error("[RouterBridgeBase] Error sending event:", error);
+            throw new RouterSyncError("Failed to sync actor state from router location.", {
+                cause: error,
+            });
         }
         finally {
             this.isProcessingNavigation = false;
@@ -185,18 +226,26 @@ export class RouterBridgeBase {
     }
     // ── Utilities (protected, overridable for framework-native param extraction) ──
     /**
-     * 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 (Node.js < 24, older browsers without a
+     * polyfill), this method returns `{}` silently (graceful degradation — routing still
+     * works, params will be empty).
      *
      * @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 URLPattern is unavailable or no match
      */
     extractParams(pathname, stateId) {
         const pattern = this.routeMap.getPathByStateId(stateId);
         if (!pattern || !pattern.includes(":"))
             return {};
         try {
-            const urlPattern = new URLPattern({ pathname: pattern });
+            const URLPatternCtor = globalThis["URLPattern"];
+            if (!URLPatternCtor)
+                return {};
+            const urlPattern = new URLPatternCtor({ pathname: pattern });
             const result = urlPattern.exec({ pathname });
             if (!result)
                 return {};
@@ -213,15 +262,10 @@ export class RouterBridgeBase {
      * @returns Extracted query parameters or empty object
      */
     extractQuery(search) {
-        try {
-            return Object.fromEntries(new URLSearchParams(search));
-        }
-        catch {
-            return {};
-        }
+        return extractQuery(search);
     }
     /**
-     * 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
@@ -230,11 +274,31 @@ export class RouterBridgeBase {
      * 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.
      */
     getInitialRouterPath() {
-        return null;
+        return undefined;
     }
 }
+function createRouteWatcher(signal, onRoute) {
+    let cleanup = () => { };
+    const watcher = {
+        watch(nextSignal) {
+            // Signal.Computed<string | null> extends Signal.State structurally;
+            // cast bridges the variance since RouteWatcherHandle hides implementation detail.
+            cleanup = watchSignal(nextSignal, onRoute);
+        },
+        unwatch() {
+            cleanup();
+        },
+    };
+    watcher.watch(signal);
+    return watcher;
+}
 //# sourceMappingURL=router-bridge-base.js.map

package/dist/router-bridge-base.js.map

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

package/dist/router-sync.d.ts

@@ -0,0 +1,62 @@
+import type { PlayRouteEvent } from "./types.js";
+interface RouteMatch {
+    to: string | null | undefined;
+    params?: Record<string, string>;
+}
+interface BuildPlayRouteEventOptions {
+    pathname: string;
+    search?: string | undefined;
+    resolve: (sanitizedPathname: string) => RouteMatch;
+}
+export interface RouterStateIdMap {
+    getStateIdByPath(path: string): string | null | undefined;
+    getPathByStateId(id: string): string | null | undefined;
+}
+/**
+ * Resolve a sanitized pathname against a route map and extract any matched params.
+ *
+ * Shared by low-level and framework router sync paths to keep route-map matching
+ * semantics aligned.
+ */
+export declare function resolveRouteMapMatch(pathname: string, routeMap: RouterStateIdMap, extractParams: (pathname: string, stateId: string) => Record<string, string>): RouteMatch;
+/**
+ * Normalize a pathname before route-map lookup.
+ *
+ * This strips query/hash fragments, collapses duplicate slashes, and rejects
+ * implausibly long paths that should never enter route resolution.
+ *
+ * Returns `null` for paths exceeding 2048 characters (malformed/adversarial input).
+ * Adapters that bypass `RouterBridgeBase.syncActorFromRouter()` (e.g. `VueRouterBridge`)
+ * must call this function directly and return early on `null` to apply the same
+ * defense-in-depth security guarantee as the shared base class.
+ *
+ * @param pathname - Raw path string from router navigation event.
+ * @returns Normalized path string, or `null` if the path is malformed/too long.
+ *
+ * @example
+ * ```typescript
+ * import { sanitizePathname } from "@xmachines/play-router";
+ *
+ * const clean = sanitizePathname(to.path);
+ * if (clean === null) return; // reject malformed path
+ * ```
+ */
+export declare function sanitizePathname(pathname: string): string | null;
+/**
+ * Parse a URL search string into the plain object shape expected by
+ * `play.route` events.
+ */
+export declare function extractQuery(search: string): Record<string, string>;
+/**
+ * Build a normalized `play.route` event from raw router/browser input.
+ *
+ * Both `connectRouter()` and `RouterBridgeBase` use this helper so low-level and
+ * framework adapters share the same pathname sanitization, route resolution, and
+ * query extraction behavior.
+ */
+export declare function buildPlayRouteEvent(options: BuildPlayRouteEventOptions): {
+    pathname: string;
+    event: PlayRouteEvent;
+} | null;
+export {};
+//# sourceMappingURL=router-sync.d.ts.map

package/dist/router-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-sync.d.ts","sourceRoot":"","sources":["../src/router-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,UAAU,UAAU;IACnB,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,UAAU,0BAA0B;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,UAAU,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAChC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,EAC1B,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1E,UAAU,CAUZ;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,0BAA0B,GACjC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAAG,IAAI,CAiBpD"}