@xmachines/play-router 1.0.0-beta.1

package/dist/crawl-machine.d.ts

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,95 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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/create-browser-history.d.ts

@@ -0,0 +1,68 @@
+export interface BrowserHistory {
+    /**
+     * Get current location state
+     */
+    readonly location: {
+        pathname: string;
+        search: string;
+        hash: string;
+        state: any;
+    };
+    /**
+     * Push new URL to history
+     */
+    push(path: string, state?: any): void;
+    /**
+     * Replace current URL in history
+     */
+    replace(path: string, state?: any): void;
+    /**
+     * Go back/forward
+     */
+    go(delta: number): void;
+    back(): void;
+    forward(): void;
+    /**
+     * Subscribe to history changes
+     * Returns unsubscribe function
+     */
+    subscribe(listener: (location: BrowserHistory["location"]) => void): () => void;
+    /**
+     * Create href from path
+     */
+    createHref(path: string): string;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create browser history that wraps window.history
+ *
+ * Aligned with TanStack Router's history interface for API parallelism.
+ *
+ * Architecture:
+ * - Patches window.history.pushState/replaceState to detect changes
+ * - Listens to popstate for browser back/forward
+ * - Provides subscribe() for listeners (like PlayRouterProvider)
+ * - Testable (accepts window object)
+ *
+ * Usage:
+ * ```typescript
+ * const history = createBrowserHistory({ window });
+ *
+ * const unsubscribe = history.subscribe((location) => {
+ *   console.log('URL changed:', location.pathname);
+ * });
+ *
+ * history.push('/new-path');
+ *
+ * // Later:
+ * unsubscribe();
+ * history.destroy();
+ * ```
+ */
+export declare function createBrowserHistory(options: {
+    window: any;
+}): BrowserHistory;
+//# sourceMappingURL=create-browser-history.d.ts.map

package/dist/create-browser-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-browser-history.d.ts","sourceRoot":"","sources":["../src/create-browser-history.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,GAAG,CAAC;KACX,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAEtC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,IAAI,IAAI,CAAC;IACb,OAAO,IAAI,IAAI,CAAC;IAEhB;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEhF;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEjC;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC7C,MAAM,EAAE,GAAG,CAAC;CACZ,GAAG,cAAc,CAmFjB"}

package/dist/create-browser-history.js

@@ -0,0 +1,94 @@
+/**
+ * Create browser history that wraps window.history
+ *
+ * Aligned with TanStack Router's history interface for API parallelism.
+ *
+ * Architecture:
+ * - Patches window.history.pushState/replaceState to detect changes
+ * - Listens to popstate for browser back/forward
+ * - Provides subscribe() for listeners (like PlayRouterProvider)
+ * - Testable (accepts window object)
+ *
+ * Usage:
+ * ```typescript
+ * const history = createBrowserHistory({ window });
+ *
+ * const unsubscribe = history.subscribe((location) => {
+ *   console.log('URL changed:', location.pathname);
+ * });
+ *
+ * history.push('/new-path');
+ *
+ * // Later:
+ * unsubscribe();
+ * history.destroy();
+ * ```
+ */
+export function createBrowserHistory(options) {
+    const win = options.window;
+    const listeners = new Set();
+    // Save originals
+    const originalPushState = win.history.pushState.bind(win.history);
+    const originalReplaceState = win.history.replaceState.bind(win.history);
+    function getLocation() {
+        return {
+            pathname: win.location.pathname,
+            search: win.location.search,
+            hash: win.location.hash,
+            state: win.history.state,
+        };
+    }
+    function notify() {
+        const location = getLocation();
+        listeners.forEach((listener) => listener(location));
+    }
+    // Patch history methods
+    win.history.pushState = function (state, title, url) {
+        originalPushState(state, title, url);
+        notify();
+    };
+    win.history.replaceState = function (state, title, url) {
+        originalReplaceState(state, title, url);
+        notify();
+    };
+    // Listen to popstate
+    const popstateHandler = () => notify();
+    win.addEventListener("popstate", popstateHandler);
+    return {
+        get location() {
+            return getLocation();
+        },
+        push(path, state) {
+            win.history.pushState(state, "", path);
+        },
+        replace(path, state) {
+            win.history.replaceState(state, "", path);
+        },
+        go(delta) {
+            win.history.go(delta);
+        },
+        back() {
+            win.history.back();
+        },
+        forward() {
+            win.history.forward();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        createHref(path) {
+            return path;
+        },
+        destroy() {
+            // Restore originals
+            win.history.pushState = originalPushState;
+            win.history.replaceState = originalReplaceState;
+            // Remove listener
+            win.removeEventListener("popstate", popstateHandler);
+            // Clear subscribers
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=create-browser-history.js.map

package/dist/create-browser-history.js.map

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

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

@@ -0,0 +1,46 @@
+import type { RouteTree } from "./types.js";
+export interface RouteMap {
+    /**
+     * Resolve a URL path to a state ID and params.
+     *
+     * @param path - URL pathname (e.g., "/settings/account")
+     * @returns Object with `to` (state ID with # prefix) and `params`
+     *
+     * Example:
+     * ```typescript
+     * const { to, params } = routeMap.resolve('/settings/account');
+     * // { to: "#settings", params: { section: "account" } }
+     *
+     * if (to) {
+     *   actor.send({ type: 'play.route', to, params });
+     * }
+     * ```
+     */
+    resolve(path: string): {
+        to: string | null;
+        params: Record<string, string>;
+    };
+}
+/**
+ * Create a RouteMap from a RouteTree for efficient path lookups.
+ *
+ * Architecture:
+ * - Pure function - no side effects
+ * - O(1) lookups for exact matches via Map
+ * - O(n) fallback for pattern matching with URLPattern
+ * - Returns formatted state IDs (with # prefix)
+ * - Extracts params from matched patterns
+ *
+ * Usage:
+ * ```typescript
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMap(routeTree);
+ *
+ * const { to, params } = routeMap.resolve('/settings/account');
+ * if (to) {
+ *   actor.send({ type: 'play.route', to, params });
+ * }
+ * ```
+ */
+export declare function createRouteMap(routeTree: RouteTree): RouteMap;
+//# sourceMappingURL=create-route-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QACtB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC/B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAyD7D"}

package/dist/create-route-map.js

@@ -0,0 +1,73 @@
+import { URLPattern } from "urlpattern-polyfill";
+/**
+ * Create a RouteMap from a RouteTree for efficient path lookups.
+ *
+ * Architecture:
+ * - Pure function - no side effects
+ * - O(1) lookups for exact matches via Map
+ * - O(n) fallback for pattern matching with URLPattern
+ * - Returns formatted state IDs (with # prefix)
+ * - Extracts params from matched patterns
+ *
+ * Usage:
+ * ```typescript
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMap(routeTree);
+ *
+ * const { to, params } = routeMap.resolve('/settings/account');
+ * if (to) {
+ *   actor.send({ type: 'play.route', to, params });
+ * }
+ * ```
+ */
+export function createRouteMap(routeTree) {
+    // Build pattern matchers for routes with dynamic segments
+    const patternRoutes = [];
+    // Collect all routable routes with patterns
+    function collectPatterns(node) {
+        if (node.routable && node.pattern) {
+            try {
+                // URLPattern expects patterns in format: /settings/:section
+                const pattern = new URLPattern({ pathname: node.pattern });
+                patternRoutes.push({ pattern, node });
+            }
+            catch (err) {
+                console.warn("[RouteMap] Invalid pattern:", node.pattern, err);
+            }
+        }
+        for (const child of node.children) {
+            collectPatterns(child);
+        }
+    }
+    collectPatterns(routeTree.root);
+    return {
+        resolve(path) {
+            // Try exact match first (O(1))
+            const exactMatch = routeTree.byPath.get(path);
+            if (exactMatch?.routable) {
+                return {
+                    to: `#${exactMatch.id}`,
+                    params: {},
+                };
+            }
+            // Try pattern matching (O(n))
+            for (const { pattern, node } of patternRoutes) {
+                const match = pattern.exec({ pathname: path });
+                if (match) {
+                    // Extract pathname params (e.g., { section: "account" })
+                    const params = {};
+                    if (match.pathname.groups) {
+                        Object.assign(params, match.pathname.groups);
+                    }
+                    return {
+                        to: `#${node.id}`,
+                        params,
+                    };
+                }
+            }
+            // No match found
+            return { to: null, params: {} };
+        },
+    };
+}
+//# sourceMappingURL=create-route-map.js.map

package/dist/create-route-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAyBjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAAC,SAAoB;IAClD,0DAA0D;IAC1D,MAAM,aAAa,GAGd,EAAE,CAAC;IAER,4CAA4C;IAC5C,SAAS,eAAe,CAAC,IAA2B;QACnD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACnC,IAAI,CAAC;gBACJ,4DAA4D;gBAC5D,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC3D,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAChE,CAAC;QACF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,eAAe,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhC,OAAO;QACN,OAAO,CAAC,IAAY;YACnB,+BAA+B;YAC/B,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,UAAU,EAAE,QAAQ,EAAE,CAAC;gBAC1B,OAAO;oBACN,EAAE,EAAE,IAAI,UAAU,CAAC,EAAE,EAAE;oBACvB,MAAM,EAAE,EAAE;iBACV,CAAC;YACH,CAAC;YAED,8BAA8B;YAC9B,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;gBAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/C,IAAI,KAAK,EAAE,CAAC;oBACX,yDAAyD;oBACzD,MAAM,MAAM,GAA2B,EAAE,CAAC;oBAC1C,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;wBAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBAC9C,CAAC;oBAED,OAAO;wBACN,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE;wBACjB,MAAM;qBACN,CAAC;gBACH,CAAC;YACF,CAAC;YAED,iBAAiB;YACjB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACjC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/create-router.d.ts

@@ -0,0 +1,73 @@
+import type { RouteTree } from "./types.js";
+import type { BrowserHistory } from "./create-browser-history.js";
+export interface VanillaRouter {
+    /**
+     * History instance
+     */
+    readonly history: BrowserHistory;
+    /**
+     * Route tree (for structure reference)
+     */
+    readonly routeTree: RouteTree;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create vanilla router for framework-agnostic routing.
+ *
+ * Architecture:
+ * - Just wraps history and routeTree
+ * - Does NOT embed routeMap (providers need it as prop)
+ * - Framework-agnostic history management only
+ *
+ * Why no routeMap:
+ * - Router doesn't know about state IDs (that's Play-specific)
+ * - RouteMap is the bridge between router and actor
+ * - Provider receives routeMap as prop to do path → state ID resolution
+ *
+ * Usage (parallel to TanStack mode):
+ * ```typescript
+ * // Both modes: identical setup
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMap(routeTree);
+ * const history = createBrowserHistory({ window });
+ *
+ * // Vanilla router
+ * const router = createRouter({ routeTree, history });
+ *
+ * // Provider needs routeMap as prop (router doesn't have it)
+ * <PlayRouterProvider
+ *   actor={actor}
+ *   router={router}
+ *   routeMap={routeMap}  // ← Must pass separately
+ *   renderer={(currentActor, currentRouter) => {
+ *     void currentRouter;
+ *     return <Renderer actor={currentActor} components={components} />;
+ *   }}
+ * />
+ * ```
+ *
+ * Compare to TanStack mode:
+ * ```typescript
+ * // TanStack router (external library)
+ * const router = TanStackCreateRouter({ routeTree, history });
+ *
+ * // Provider needs routeMap as prop (same as vanilla!)
+ * <PlayRouterProvider
+ *   actor={actor}
+ *   router={router}
+ *   routeMap={routeMap}  // ← Must pass separately
+ *   renderer={(currentActor, currentRouter) => {
+ *     void currentRouter;
+ *     return <Renderer actor={currentActor} components={components} />;
+ *   }}
+ * />
+ * ```
+ */
+export declare function createRouter(options: {
+    routeTree: RouteTree;
+    history: BrowserHistory;
+}): VanillaRouter;
+//# sourceMappingURL=create-router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-router.d.ts","sourceRoot":"","sources":["../src/create-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,aAAa;IAC7B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,cAAc,CAAC;CACxB,GAAG,aAAa,CAWhB"}

package/dist/create-router.js

@@ -0,0 +1,63 @@
+/**
+ * Create vanilla router for framework-agnostic routing.
+ *
+ * Architecture:
+ * - Just wraps history and routeTree
+ * - Does NOT embed routeMap (providers need it as prop)
+ * - Framework-agnostic history management only
+ *
+ * Why no routeMap:
+ * - Router doesn't know about state IDs (that's Play-specific)
+ * - RouteMap is the bridge between router and actor
+ * - Provider receives routeMap as prop to do path → state ID resolution
+ *
+ * Usage (parallel to TanStack mode):
+ * ```typescript
+ * // Both modes: identical setup
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMap(routeTree);
+ * const history = createBrowserHistory({ window });
+ *
+ * // Vanilla router
+ * const router = createRouter({ routeTree, history });
+ *
+ * // Provider needs routeMap as prop (router doesn't have it)
+ * <PlayRouterProvider
+ *   actor={actor}
+ *   router={router}
+ *   routeMap={routeMap}  // ← Must pass separately
+ *   renderer={(currentActor, currentRouter) => {
+ *     void currentRouter;
+ *     return <Renderer actor={currentActor} components={components} />;
+ *   }}
+ * />
+ * ```
+ *
+ * Compare to TanStack mode:
+ * ```typescript
+ * // TanStack router (external library)
+ * const router = TanStackCreateRouter({ routeTree, history });
+ *
+ * // Provider needs routeMap as prop (same as vanilla!)
+ * <PlayRouterProvider
+ *   actor={actor}
+ *   router={router}
+ *   routeMap={routeMap}  // ← Must pass separately
+ *   renderer={(currentActor, currentRouter) => {
+ *     void currentRouter;
+ *     return <Renderer actor={currentActor} components={components} />;
+ *   }}
+ * />
+ * ```
+ */
+export function createRouter(options) {
+    const { routeTree, history } = options;
+    return {
+        routeTree,
+        history,
+        destroy() {
+            history.destroy();
+        },
+    };
+}
+//# sourceMappingURL=create-router.js.map

package/dist/create-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-router.js","sourceRoot":"","sources":["../src/create-router.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,UAAU,YAAY,CAAC,OAG5B;IACA,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEvC,OAAO;QACN,SAAS;QACT,OAAO;QAEP,OAAO;YACN,OAAO,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/extract-route.d.ts

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1 @@
+{"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"}