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

package/dist/router-sync.js

@@ -0,0 +1,87 @@
+/**
+ * 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 function resolveRouteMapMatch(pathname, routeMap, extractParams) {
+    const stateId = routeMap.getStateIdByPath(pathname);
+    if (!stateId) {
+        return { to: null, params: {} };
+    }
+    return {
+        to: stateId,
+        params: extractParams(pathname, stateId),
+    };
+}
+/**
+ * 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 function sanitizePathname(pathname) {
+    if (pathname.length > 2048)
+        return null;
+    const withoutQuery = pathname.split("?")[0];
+    const withoutHash = withoutQuery.split("#")[0];
+    return withoutHash.replace(/\/+/g, "/");
+}
+/**
+ * Parse a URL search string into the plain object shape expected by
+ * `play.route` events.
+ */
+export function extractQuery(search) {
+    try {
+        const params = {};
+        for (const [key, value] of Array.from(new URLSearchParams(search))) {
+            params[key] = value;
+        }
+        return params;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 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 function buildPlayRouteEvent(options) {
+    const pathname = sanitizePathname(options.pathname);
+    if (pathname === null)
+        return null;
+    const match = options.resolve(pathname);
+    if (!match.to)
+        return null;
+    const to = match.to.startsWith("#") ? match.to : `#${match.to}`;
+    return {
+        pathname,
+        event: {
+            type: "play.route",
+            to,
+            params: match.params ?? {},
+            query: extractQuery(options.search ?? ""),
+        },
+    };
+}
+//# sourceMappingURL=router-sync.js.map

package/dist/router-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-sync.js","sourceRoot":"","sources":["../src/router-sync.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAgB,EAChB,QAA0B,EAC1B,aAA4E;IAE5E,MAAM,OAAO,GAAG,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACjC,CAAC;IAED,OAAO;QACN,EAAE,EAAE,OAAO;QACX,MAAM,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC;KACxC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAChD,IAAI,QAAQ,CAAC,MAAM,GAAG,IAAI;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IAC1C,IAAI,CAAC;QACJ,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YACpE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAClC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;IAChE,OAAO;QACN,QAAQ;QACR,KAAK,EAAE;YACN,IAAI,EAAE,YAAY;YAClB,EAAE;YACF,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;YAC1B,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;SACzC;KACD,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -1,16 +1,47 @@
-import type { StateNode } from "xstate";
-import type { RouteMetadata } from "@xmachines/play-xstate";
+import type { Graph } from "@statelyai/graph";
 /**
- * Represents a visit to a state node during graph crawling
+ * Data attached to each node in the machine graph representation.
+ * Captures the essential state metadata needed for route extraction and queries.
  */
-export interface StateVisit {
-    /** The state node being visited */
-    node: StateNode;
-    /** Path from root to this state (e.g., ['dashboard', 'overview']) */
-    path: string[];
-    /** Parent state node (null for root) */
-    parent: StateNode | null;
+export interface MachineNodeData {
+    /** XState state ID (e.g., "test.dashboard.overview") */
+    stateId: string;
+    /** State type from XState */
+    type: "atomic" | "compound" | "parallel" | "final" | "history";
+    /** Original state meta object */
+    meta?: Record<string, unknown>;
+    /** Extracted route path from meta.route (string form) */
+    route?: string;
+}
+/**
+ * Data attached to each edge in the machine graph representation.
+ * Captures transition event and guard information.
+ */
+export interface MachineEdgeData {
+    /** The event type that triggers this transition */
+    eventType: string;
+    /** String representation of guard (if any) */
+    guardType?: string;
+}
+/**
+ * Routing protocol type definitions for @xmachines/play-router
+ *
+ * PlayRouteEvent, RouterBridge, RouteMetadata, and RouteObject live here to keep
+ * routing concerns separate from the base event protocol in @xmachines/play.
+ */
+/**
+ * Route object with additional metadata.
+ */
+export interface RouteObject {
+    /** Route path template (e.g., '/user/:id') */
+    path: string;
+    /** Additional route metadata (title, breadcrumb, etc.) */
+    [key: string]: unknown;
 }
+/**
+ * Route metadata from state machine `meta.route` field.
+ */
+export type RouteMetadata = string | RouteObject;
 /**
  * Extracted route information from a state node
  */
@@ -57,7 +88,7 @@ export interface RouteNode {
     /** Parent route (null for root) */
     parent: RouteNode | null;
     /** Original meta.route metadata */
-    metadata: unknown;
+    metadata: RouteMetadata;
 }
 /**
  * Complete route tree with lookup maps
@@ -79,6 +110,18 @@ export interface RouteTree {
      * Used to look up state ID from URL path for play.route event targeting
      */
     byPath: Map<string, RouteNode>;
+    /**
+     * Graph representation of the state machine for advanced queries.
+     * Populated by extractMachineRoutes() — use for hierarchy queries, reachability checks,
+     * and transition-aware navigation via @statelyai/graph algorithms.
+     *
+     * @example
+     * ```typescript
+     * import { getSuccessors, hasPath } from "@statelyai/graph";
+     * const successors = getSuccessors(tree.graph!, "myMachine.home");
+     * ```
+     */
+    graph?: Graph<MachineNodeData, MachineEdgeData>;
 }
 /**
  * Enhanced routing event with parameter and query support
@@ -90,6 +133,12 @@ export interface RouteTree {
  * user navigation intent that the Actor evaluates through guards. Infrastructure proposes
  * via `play.route` events, Actor decides via state machine transitions.
  *
+ * **Browser Navigation Flow:**
+ * 1. Browser fires `popstate`
+ * 2. Router adapter resolves URL to route target
+ * 3. Adapter sends `PlayRouteEvent` to Actor
+ * 4. Actor validates transition via state machine guards
+ *
  * @param type - Event discriminator (always "play.route")
  * @param to - Target state ID with # prefix (e.g., '#home', '#profile')
  * @param params - Merged path + query parameters (path parameters win conflicts)
@@ -99,6 +148,15 @@ export interface RouteTree {
  * @returns N/A - Interface defines event shape only
  *
  * @example
+ * Combining base and routing events
+ * ```typescript
+ * import type { PlayEvent } from "@xmachines/play";
+ * import type { PlayRouteEvent } from "@xmachines/play-router";
+ *
+ * type AppEvent = PlayEvent | PlayRouteEvent;
+ * ```
+ *
+ * @example
  * Basic navigation to a route
  * ```typescript
  * import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -139,7 +197,7 @@ export interface RouteTree {
  * // Resolves to route: /settings/profile?tab=security
  * ```
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
+ * @see [Play RFC](../../docs/rfc/play.md)
  *
  * @remarks
  * Use `play.route` when you need parameter-aware navigation with the `route: {}`
@@ -151,7 +209,8 @@ export interface PlayRouteEvent {
     readonly to: string;
     readonly params?: Record<string, string>;
     readonly query?: Record<string, string>;
-    readonly match?: any;
+    readonly match?: unknown;
+    [key: string]: unknown;
 }
 /**
  * RouterBridge interface for runtime infrastructure adapters
@@ -190,7 +249,7 @@ export interface PlayRouteEvent {
  * }
  * ```
  *
- * @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
  */
 export interface RouterBridge {
     /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,mCAAmC;IACnC,IAAI,EAAE,SAAS,CAAC;IAChB,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB;IACnB,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,mCAAmC;IACnC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,sBAAsB;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC;;;OAGG;IACH,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;;;;;OAaG;IACH,UAAU,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validate-routes.d.ts

@@ -1,27 +1,27 @@
-import type { StateNode } from "xstate";
 import type { RouteInfo } from "./types.js";
 /**
  * Validate route path format
  *
- * Ensures route paths start with "/" (absolute or relative).
- * Per Route Protocol spec, all routes must have explicit path structure.
+ * Ensures route paths are non-empty strings. Both absolute paths ("/foo")
+ * and relative paths ("foo", "child/nested") are accepted. Relative routes
+ * inherit their parent state's path prefix when the tree is built.
  *
- * @param routePath - Route path to validate
+ * @param routePath - Route path to validate (absolute or relative)
  * @param stateId - State identifier for error messages
- * @throws {Error} If route path doesn't start with /
+ * @throws {Error} If route path is empty
  */
 export declare const validateRouteFormat: (routePath: string, stateId: string) => void;
 /**
- * Validate state exists in state map
+ * Validate state exists in state ID set
  *
  * Ensures referenced state IDs exist in the machine graph.
  * Build-time validation prevents broken route references.
  *
  * @param stateId - State identifier to validate
- * @param stateMap - Map of all state IDs to StateNodes
- * @throws {Error} If state ID doesn't exist in map
+ * @param stateIds - Set of all known state IDs from the machine graph
+ * @throws {Error} If state ID doesn't exist in set
  */
-export declare const validateStateExists: (stateId: string, stateMap: Map<string, StateNode>) => void;
+export declare const validateStateExists: (stateId: string, stateIds: Set<string>) => void;
 /**
  * Detect duplicate route paths
  *

package/dist/validate-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-routes.d.ts","sourceRoot":"","sources":["../src/validate-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,MAAM,EAAE,SAAS,MAAM,KAAG,IAMxE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,KAAG,IAIvF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,SAAS,EAAE,KAAG,IAyB3D,CAAC"}
+{"version":3,"file":"validate-routes.d.ts","sourceRoot":"","sources":["../src/validate-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,MAAM,EAAE,SAAS,MAAM,KAAG,IAMxE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,UAAU,GAAG,CAAC,MAAM,CAAC,KAAG,IAI5E,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,SAAS,EAAE,KAAG,IAyB3D,CAAC"}

package/dist/validate-routes.js

@@ -1,30 +1,31 @@
 /**
  * Validate route path format
  *
- * Ensures route paths start with "/" (absolute or relative).
- * Per Route Protocol spec, all routes must have explicit path structure.
+ * Ensures route paths are non-empty strings. Both absolute paths ("/foo")
+ * and relative paths ("foo", "child/nested") are accepted. Relative routes
+ * inherit their parent state's path prefix when the tree is built.
  *
- * @param routePath - Route path to validate
+ * @param routePath - Route path to validate (absolute or relative)
  * @param stateId - State identifier for error messages
- * @throws {Error} If route path doesn't start with /
+ * @throws {Error} If route path is empty
  */
 export const validateRouteFormat = (routePath, stateId) => {
-    if (!routePath.startsWith("/")) {
-        throw new Error(`Invalid route path "${routePath}" in state "${stateId}": routes must start with /`);
+    if (!routePath) {
+        throw new Error(`Empty route path in state "${stateId}": routes must have a non-empty path`);
     }
 };
 /**
- * Validate state exists in state map
+ * Validate state exists in state ID set
  *
  * Ensures referenced state IDs exist in the machine graph.
  * Build-time validation prevents broken route references.
  *
  * @param stateId - State identifier to validate
- * @param stateMap - Map of all state IDs to StateNodes
- * @throws {Error} If state ID doesn't exist in map
+ * @param stateIds - Set of all known state IDs from the machine graph
+ * @throws {Error} If state ID doesn't exist in set
  */
-export const validateStateExists = (stateId, stateMap) => {
-    if (!stateMap.has(stateId)) {
+export const validateStateExists = (stateId, stateIds) => {
+    if (!stateIds.has(stateId)) {
         throw new Error(`Route references non-existent state ID: ${stateId}`);
     }
 };

package/dist/validate-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-routes.js","sourceRoot":"","sources":["../src/validate-routes.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAE,OAAe,EAAQ,EAAE;IAC/E,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACd,uBAAuB,SAAS,eAAe,OAAO,6BAA6B,CACnF,CAAC;IACH,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAE,QAAgC,EAAQ,EAAE;IAC9F,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,2CAA2C,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAmB,EAAQ,EAAE;IAClE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,wCAAwC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,uCAAuC;IACvC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,KAAK,SAAS,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACd,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YAC9D,kDAAkD;YAClD,6FAA6F,CAC9F,CAAC;IACH,CAAC;AACF,CAAC,CAAC"}
+{"version":3,"file":"validate-routes.js","sourceRoot":"","sources":["../src/validate-routes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAE,OAAe,EAAQ,EAAE;IAC/E,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACd,8BAA8B,OAAO,sCAAsC,CAC3E,CAAC;IACH,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAE,QAAqB,EAAQ,EAAE;IACnF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,2CAA2C,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAmB,EAAQ,EAAE;IAClE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,wCAAwC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,uCAAuC;IACvC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,KAAK,SAAS,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACd,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YAC9D,kDAAkD;YAClD,6FAA6F,CAC9F,CAAC;IACH,CAAC;AACF,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-router",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.21",
   "description": "Route tree extraction from XState v5 state machines. Part of @xmachines/play Universal Player Architecture.",
   "keywords": [
     "routing",
@@ -11,39 +11,57 @@
   ],
   "license": "MIT",
   "author": "XMachines",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./errors": {
+      "source": "./src/errors.ts",
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__",
+    "test": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play-actor": "1.0.0-beta.2",
-    "@xmachines/play-signals": "1.0.0-beta.2",
-    "urlpattern-polyfill": "^10.1.0"
+    "@statelyai/graph": "^0.9.0",
+    "@xmachines/play": "1.0.0-beta.21",
+    "@xmachines/play-actor": "1.0.0-beta.21",
+    "@xmachines/play-signals": "1.0.0-beta.21",
+    "quick-lru": "^7.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.4.0",
-    "typescript": "^5.7.0",
-    "xstate": "^5.28.0"
+    "@types/node": "^25.5.0",
+    "@xmachines/play-xstate": "1.0.0-beta.21",
+    "@xmachines/shared": "1.0.0-beta.21",
+    "typescript": "^5.9.3 || ^6.0.2",
+    "urlpattern-polyfill": "^10.1.0",
+    "vitest": "^4.1.2",
+    "xstate": "^5.30.0"
   },
   "peerDependencies": {
-    "xstate": "^5.28.0"
+    "urlpattern-polyfill": "^10.1.0",
+    "xstate": "^5.30.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "peerDependenciesMeta": {
+    "urlpattern-polyfill": {
+      "optional": true
+    }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
+  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds and tests. peerDependencies declares the consumer version constraint. Both are pinned to ^5.30.0 to prevent drift. urlpattern-polyfill is an optional peer dependency — consumers on Node < 24 or older browsers install it themselves. devDependencies entry ensures workspace test resolution."
 }

package/dist/crawl-machine.d.ts

@@ -1,74 +0,0 @@
-import type { AnyStateMachine } from "xstate";
-import type { StateVisit } from "./types.js";
-/**
- * Crawl state machine graph using breadth-first traversal
- *
- * Visits all state nodes in the machine, including deeply nested states, and returns
- * complete list of visits with path and parent information. This enables systematic
- * discovery of all states for route extraction and tree building.
- *
- * **Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
- * routing information from the state machine definition rather than external configuration.
- * The BFS traversal ensures all nested states are discovered, enabling the Actor to
- * define the complete navigation structure through its machine definition.
- *
- * @param machine - XState v5 state machine to crawl
- * @returns Array of state visits in breadth-first order
- *
- * @example
- * Basic machine crawl
- * ```typescript
- * import { createMachine } from "xstate";
- * import { crawlMachine } from "@xmachines/play-router";
- *
- * const machine = createMachine({
- *   initial: 'home',
- *   states: {
- *     home: {},
- *     dashboard: {
- *       initial: 'overview',
- *       states: {
- *         overview: {},
- *         settings: {}
- *       }
- *     }
- *   }
- * });
- *
- * const visits = crawlMachine(machine);
- * // Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
- * console.log(visits.map(v => v.path.join('.')));
- * // ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']
- * ```
- *
- * @example
- * Extract state paths and parents
- * ```typescript
- * import { crawlMachine } from "@xmachines/play-router";
- *
- * const visits = crawlMachine(machine);
- * visits.forEach(visit => {
- *   console.log({
- *     path: visit.path.join('.') || 'root',
- *     hasParent: !!visit.parent,
- *     hasChildren: Object.keys(visit.node.states).length > 0
- *   });
- * });
- * ```
- *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
- * @see {@link extractRoute} for extracting route from individual states
- * @see {@link extractMachineRoutes} for complete route extraction
- * @see {@link StateVisit} for visit structure
- *
- * @remarks
- * **BFS Traversal:** Breadth-first search ensures systematic discovery of all states
- * at each nesting level before descending deeper. This produces a predictable ordering
- * useful for route tree construction and debugging.
- *
- * **Path Format:** Paths use array notation (`['dashboard', 'settings']`) which can be
- * joined with dots for state IDs (`'dashboard.settings'`) matching XState's hierarchical
- * state naming convention.
- */
-export declare const crawlMachine: (machine: AnyStateMachine) => StateVisit[];
-//# sourceMappingURL=crawl-machine.d.ts.map

package/dist/crawl-machine.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"crawl-machine.d.ts","sourceRoot":"","sources":["../src/crawl-machine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,eAAe,KAAG,UAAU,EA0BjE,CAAC"}

package/dist/crawl-machine.js

@@ -1,95 +0,0 @@
-/**
- * Crawl state machine graph using breadth-first traversal
- *
- * Visits all state nodes in the machine, including deeply nested states, and returns
- * complete list of visits with path and parent information. This enables systematic
- * discovery of all states for route extraction and tree building.
- *
- * **Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
- * routing information from the state machine definition rather than external configuration.
- * The BFS traversal ensures all nested states are discovered, enabling the Actor to
- * define the complete navigation structure through its machine definition.
- *
- * @param machine - XState v5 state machine to crawl
- * @returns Array of state visits in breadth-first order
- *
- * @example
- * Basic machine crawl
- * ```typescript
- * import { createMachine } from "xstate";
- * import { crawlMachine } from "@xmachines/play-router";
- *
- * const machine = createMachine({
- *   initial: 'home',
- *   states: {
- *     home: {},
- *     dashboard: {
- *       initial: 'overview',
- *       states: {
- *         overview: {},
- *         settings: {}
- *       }
- *     }
- *   }
- * });
- *
- * const visits = crawlMachine(machine);
- * // Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
- * console.log(visits.map(v => v.path.join('.')));
- * // ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']
- * ```
- *
- * @example
- * Extract state paths and parents
- * ```typescript
- * import { crawlMachine } from "@xmachines/play-router";
- *
- * const visits = crawlMachine(machine);
- * visits.forEach(visit => {
- *   console.log({
- *     path: visit.path.join('.') || 'root',
- *     hasParent: !!visit.parent,
- *     hasChildren: Object.keys(visit.node.states).length > 0
- *   });
- * });
- * ```
- *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
- * @see {@link extractRoute} for extracting route from individual states
- * @see {@link extractMachineRoutes} for complete route extraction
- * @see {@link StateVisit} for visit structure
- *
- * @remarks
- * **BFS Traversal:** Breadth-first search ensures systematic discovery of all states
- * at each nesting level before descending deeper. This produces a predictable ordering
- * useful for route tree construction and debugging.
- *
- * **Path Format:** Paths use array notation (`['dashboard', 'settings']`) which can be
- * joined with dots for state IDs (`'dashboard.settings'`) matching XState's hierarchical
- * state naming convention.
- */
-export const crawlMachine = (machine) => {
-    const visits = [];
-    const queue = [
-        {
-            node: machine.root,
-            path: [],
-            parent: null,
-        },
-    ];
-    while (queue.length > 0) {
-        const visit = queue.shift();
-        visits.push(visit);
-        // Traverse child states
-        const childStates = Object.entries(visit.node.states);
-        for (const [key, childNode] of childStates) {
-            queue.push({
-                node: childNode,
-                path: [...visit.path, key],
-                parent: visit.node,
-            });
-        }
-    }
-    return visits;
-};
-//# sourceMappingURL=crawl-machine.js.map

package/dist/crawl-machine.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"crawl-machine.js","sourceRoot":"","sources":["../src/crawl-machine.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAwB,EAAgB,EAAE;IACtE,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAiB;QAC3B;YACC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,EAAE;YACR,MAAM,EAAE,IAAI;SACZ;KACD,CAAC;IAEF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEnB,wBAAwB;QACxB,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtD,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC;gBAC1B,MAAM,EAAE,KAAK,CAAC,IAAI;aAClB,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC,CAAC"}

package/dist/extract-route.d.ts

@@ -1,25 +0,0 @@
-import type { StateNode } from "xstate";
-import type { RouteInfo } from "./types.js";
-/**
- * Extract route information from state node with validation
- *
- * States with meta.route are "routable" - they can receive play.route events
- * (when machine is wrapped with formatPlayRouteTransitions).
- *
- * @param node - XState StateNode to extract route from
- * @param path - State path segments from root
- * @param stateMap - Map of all state IDs to StateNodes for validation
- * @returns RouteInfo if state has meta.route, null otherwise
- * @throws {Error} If route path is malformed (missing leading /)
- * @throws {Error} If route references non-existent state
- *
- * @example
- * ```typescript
- * const node = {
- *   id: 'dashboard',
- *   meta: { route: '/dashboard' }
- * };
- * ```
- */
-export declare const extractRoute: (node: StateNode, path: string[], stateMap: Map<string, StateNode>) => RouteInfo | null;
-//# sourceMappingURL=extract-route.d.ts.map

package/dist/extract-route.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extract-route.d.ts","sourceRoot":"","sources":["../src/extract-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GACxB,MAAM,SAAS,EACf,MAAM,MAAM,EAAE,EACd,UAAU,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,KAC9B,SAAS,GAAG,IAiDd,CAAC"}