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

package/dist/url-pattern-utils.js

@@ -0,0 +1,176 @@
+/**
+ * Shared URLPattern utilities — internal module, NOT exported from index.ts
+ *
+ * Provides the common URLPattern plumbing shared by:
+ * - `create-route-map.ts`
+ * - `base-route-map.ts`
+ * - `find-route.ts`
+ * - `router-bridge-base.ts`
+ *
+ * URLPattern is accessed via globalThis — consumers must load a polyfill on
+ * environments without native support (Node < 24, older browsers).
+ *
+ * @internal
+ */
+/**
+ * Retrieve the URLPattern constructor from `globalThis`, or `undefined` if
+ * it is not available (Node < 24, older browsers without a polyfill).
+ */
+export function getURLPatternCtor() {
+    return globalThis["URLPattern"];
+}
+/**
+ * Check whether a route path is a parameterized pattern rather than a concrete URL.
+ *
+ * A pattern contains `:param` segments (required or optional) and/or the `*`
+ * wildcard — both require URLPattern matching and carry no concrete values, so
+ * they can never be pushed to a browser URL verbatim.
+ *
+ * This is THE single source of truth for "is this path a pattern?" — used by
+ * `RouteMap` to decide static-map vs pattern-bucket indexing and by
+ * `RouterBridgeBase.resolveNavigationPath` to skip non-navigable routes, so the
+ * two checks can never drift apart.
+ *
+ * @param path - URL path or route pattern string (e.g. `/profile/:userId`, `/docs/*`)
+ * @returns `true` if the path contains `:param` or `*` pattern syntax
+ */
+export function isParameterizedPattern(path) {
+    return path.includes(":") || path.includes("*");
+}
+/**
+ * Matches hyphenated `:param` names (e.g. `:cat-id`, `:page-num?`).
+ * URLPattern requires parameter names to be valid JS identifiers, so hyphenated
+ * names must be rewritten before compilation.
+ */
+const HYPHENATED_PARAM_RE = /:([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+)(\??)/g;
+/**
+ * Normalize a route path so its parameter names are valid URLPattern identifiers.
+ *
+ * URLPattern requires parameter names to be valid JS identifiers (no hyphens).
+ * Hyphenated names like `:cat-id` are replaced with underscored equivalents
+ * (`:cat_id`) for the URLPattern compilation step. Callers that need the captured
+ * group values (not just a match test) must map the normalized group names back to
+ * the original param names via {@link getNormalizedParamNameMap}.
+ *
+ * @example
+ * normalizeParamNames("/docs/:cat-id/:page-num?")
+ * // → "/docs/:cat_id/:page_num?"
+ */
+export function normalizeParamNames(path) {
+    return path.replace(HYPHENATED_PARAM_RE, (_m, name, optional) => {
+        return `:${name.replace(/-/g, "_")}${optional}`;
+    });
+}
+/**
+ * Build a map from normalized URLPattern group names back to the original
+ * (hyphenated) param names for a route pattern.
+ *
+ * Only params rewritten by {@link normalizeParamNames} appear in the map —
+ * params that are already valid identifiers keep their own name and need no entry.
+ *
+ * @example
+ * getNormalizedParamNameMap("/docs/:cat-id/:plain")
+ * // → Map { "cat_id" → "cat-id" }
+ */
+export function getNormalizedParamNameMap(path) {
+    const nameMap = new Map();
+    for (const match of path.matchAll(HYPHENATED_PARAM_RE)) {
+        const original = match[1];
+        nameMap.set(original.replace(/-/g, "_"), original);
+    }
+    return nameMap;
+}
+/**
+ * Module-level cache of compiled URLPattern instances keyed by pattern string.
+ *
+ * Route patterns are compiled on every navigation-time lookup path
+ * (`extractRouteParams`, `findRouteByPath`) and once per `RouteMap`
+ * construction; compiling the same route pattern each time is wasted work.
+ * Growth is bounded by the number of distinct route patterns in the
+ * application's route maps. The cache is invalidated when the URLPattern
+ * constructor changes (tests swap `globalThis.URLPattern`).
+ */
+const compiledPatternCache = new Map();
+let compiledPatternCtor;
+/**
+ * Compile a route pattern to a `URLPattern`, reusing the module-level cache.
+ *
+ * The pattern is normalized with {@link normalizeParamNames} before compilation
+ * so hyphenated param names (`:cat-id`) become valid URLPattern identifiers
+ * (`:cat_id`). Callers that extract group values must map the normalized names
+ * back via {@link getNormalizedParamNameMap}.
+ *
+ * Compilation errors from the URLPattern constructor propagate as-is — callers
+ * that need a typed error wrap this in `InvalidRoutePatternError`.
+ *
+ * @param pattern - Route pattern string (e.g. `/profile/:userId`)
+ * @param Ctor - URLPattern constructor retrieved via {@link getURLPatternCtor}
+ */
+export function getCompiledPattern(pattern, Ctor) {
+    if (Ctor !== compiledPatternCtor) {
+        compiledPatternCache.clear();
+        compiledPatternCtor = Ctor;
+    }
+    let compiled = compiledPatternCache.get(pattern);
+    if (compiled === undefined) {
+        compiled = new Ctor({ pathname: normalizeParamNames(pattern) });
+        compiledPatternCache.set(pattern, compiled);
+    }
+    return compiled;
+}
+/**
+ * Compute the bucket index key for a given path or pattern.
+ *
+ * The key is the first path segment (e.g. `"settings"` for `"/settings/:id"`).
+ * Parameterised first segments (`:lang`) fall into the `"*"` wildcard bucket.
+ * The root path `"/"` maps to the key `"/"`.
+ *
+ * @param path - URL path or route pattern string
+ */
+export function getIndexKey(path) {
+    const trimmed = path.startsWith("/") ? path.slice(1) : path;
+    if (trimmed.length === 0)
+        return "/";
+    const segment = trimmed.split("/")[0];
+    if (segment === undefined || segment.startsWith(":"))
+        return "*";
+    return segment;
+}
+/**
+ * Merge the named-segment bucket and the wildcard bucket for a given index key,
+ * preserving insertion order (by `order` field).
+ *
+ * @param patternBuckets - Map of bucket key → ordered pattern entries
+ * @param indexKey - First-segment key computed by `getIndexKey`
+ */
+export function getCandidates(patternBuckets, indexKey) {
+    const bucket = patternBuckets.get(indexKey) ?? [];
+    const wildcardBucket = patternBuckets.get("*") ?? [];
+    if (bucket.length === 0)
+        return wildcardBucket;
+    if (wildcardBucket.length === 0)
+        return bucket;
+    const merged = [];
+    let b = 0;
+    let w = 0;
+    while (b < bucket.length && w < wildcardBucket.length) {
+        if (bucket[b].order < wildcardBucket[w].order) {
+            merged.push(bucket[b]);
+            b += 1;
+        }
+        else {
+            merged.push(wildcardBucket[w]);
+            w += 1;
+        }
+    }
+    while (b < bucket.length) {
+        merged.push(bucket[b]);
+        b += 1;
+    }
+    while (w < wildcardBucket.length) {
+        merged.push(wildcardBucket[w]);
+        w += 1;
+    }
+    return merged;
+}
+//# sourceMappingURL=url-pattern-utils.js.map

package/dist/url-pattern-utils.js.map

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

package/dist/validate-routes.d.ts

@@ -1,39 +1,57 @@
-import type { StateNode } from "xstate";
-import type { RouteInfo } from "./types.js";
+/**
+ * A route entry with its RESOLVED full path — the path after relative routes have
+ * been prefixed with their parent's full path during tree construction.
+ *
+ * `RouteNode` satisfies this shape structurally.
+ */
+export interface ResolvedRoutePath {
+    /** State identifier owning the route (e.g. `"app.dashboard.settings"`). */
+    stateId: string;
+    /** Resolved absolute route path (e.g. `"/dashboard/settings"`). */
+    fullPath: string;
+}
 /**
  * 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 {EmptyRoutePathError} 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 {InvalidStateIdError} 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
  *
- * THROWS ERROR when multiple states share the same route path.
+ * THROWS ERROR when multiple states share the same RESOLVED full path.
+ *
+ * Detection operates on resolved full paths (after relative routes have been
+ * prefixed with their parent's path in `buildRouteTree`), not on raw route
+ * strings: two relative `"settings"` routes under different parents resolve to
+ * distinct full paths and are valid, while a relative route and an absolute
+ * route resolving to the same URL genuinely collide and must be rejected.
+ * Called from `buildRouteTree` once full paths are known.
  *
  * Rationale: URL-based routing requires one-to-one mapping between URLs and states.
  * Multiple states at the same path creates ambiguity for browser navigation (back button,
  * direct URL access). Use different paths for different states, or single state with
  * conditional rendering.
  *
- * @param routes - Array of extracted RouteInfo objects
- * @throws {Error} If duplicate route paths are detected
+ * @param routes - Array of route entries with resolved full paths (e.g. `RouteNode`s)
+ * @throws {DuplicateRoutePathError} If duplicate resolved route paths are detected
  */
-export declare const detectDuplicateRoutes: (routes: RouteInfo[]) => void;
+export declare const detectDuplicateRoutes: (routes: ResolvedRoutePath[]) => void;
 //# sourceMappingURL=validate-routes.d.ts.map

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":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,MAAM,EAAE,SAAS,MAAM,KAAG,IAIxE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,UAAU,GAAG,CAAC,MAAM,CAAC,KAAG,IAI5E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,iBAAiB,EAAE,KAAG,IAqBnE,CAAC"}

package/dist/validate-routes.js

@@ -1,53 +1,62 @@
+import { EmptyRoutePathError, InvalidStateIdError, DuplicateRoutePathError } from "./errors.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 {EmptyRoutePathError} 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 EmptyRoutePathError(stateId);
     }
 };
 /**
- * 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 {InvalidStateIdError} If state ID doesn't exist in set
  */
-export const validateStateExists = (stateId, stateMap) => {
-    if (!stateMap.has(stateId)) {
-        throw new Error(`Route references non-existent state ID: ${stateId}`);
+export const validateStateExists = (stateId, stateIds) => {
+    if (!stateIds.has(stateId)) {
+        throw new InvalidStateIdError(stateId);
     }
 };
 /**
  * Detect duplicate route paths
  *
- * THROWS ERROR when multiple states share the same route path.
+ * THROWS ERROR when multiple states share the same RESOLVED full path.
+ *
+ * Detection operates on resolved full paths (after relative routes have been
+ * prefixed with their parent's path in `buildRouteTree`), not on raw route
+ * strings: two relative `"settings"` routes under different parents resolve to
+ * distinct full paths and are valid, while a relative route and an absolute
+ * route resolving to the same URL genuinely collide and must be rejected.
+ * Called from `buildRouteTree` once full paths are known.
  *
  * Rationale: URL-based routing requires one-to-one mapping between URLs and states.
  * Multiple states at the same path creates ambiguity for browser navigation (back button,
  * direct URL access). Use different paths for different states, or single state with
  * conditional rendering.
  *
- * @param routes - Array of extracted RouteInfo objects
- * @throws {Error} If duplicate route paths are detected
+ * @param routes - Array of route entries with resolved full paths (e.g. `RouteNode`s)
+ * @throws {DuplicateRoutePathError} If duplicate resolved route paths are detected
  */
 export const detectDuplicateRoutes = (routes) => {
     const routeMap = new Map();
-    // Build map of route paths to state IDs
+    // Build map of resolved full paths to state IDs
     for (const route of routes) {
-        const stateIds = routeMap.get(route.routePath) || [];
+        const stateIds = routeMap.get(route.fullPath) || [];
         stateIds.push(route.stateId);
-        routeMap.set(route.routePath, stateIds);
+        routeMap.set(route.fullPath, stateIds);
     }
     // Check for duplicates and throw error
     const duplicates = [];
@@ -57,9 +66,7 @@ export const detectDuplicateRoutes = (routes) => {
         }
     }
     if (duplicates.length > 0) {
-        throw new Error(`Duplicate route paths detected:\n${duplicates.join("\n")}\n\n` +
-            `Each route path must map to exactly one state.\n` +
-            `Use different paths (e.g., /dashboard vs /) or conditional rendering within a single state.`);
+        throw new DuplicateRoutePathError(duplicates);
     }
 };
 //# sourceMappingURL=validate-routes.js.map

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":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAehG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAE,OAAe,EAAQ,EAAE;IAC/E,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACxC,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,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAA2B,EAAQ,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,gDAAgD;IAChD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxC,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,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;AACF,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-router",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Route tree extraction from XState v5 state machines. Part of @xmachines/play Universal Player Architecture.",
   "keywords": [
     "routing",
@@ -11,6 +11,11 @@
   ],
   "license": "MIT",
   "author": "XMachines",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "directory": "packages/play-router"
+  },
   "files": [
     "dist",
     "README.md",
@@ -19,8 +24,14 @@
   "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": {
@@ -28,25 +39,42 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
-    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__ node_modules/.svelte2tsx-* node_modules/.vite*",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
     "test": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.8",
-    "@xmachines/play-actor": "1.0.0-beta.8",
-    "@xmachines/play-signals": "1.0.0-beta.8",
-    "urlpattern-polyfill": "^10.1.0"
+    "@statelyai/graph": "^2.1.0",
+    "@xmachines/play": "1.0.0",
+    "@xmachines/play-actor": "1.0.0",
+    "@xmachines/play-signals": "1.0.0",
+    "quick-lru": "^7.3.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.8",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0",
-    "xstate": "^5.28.0"
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/node": "^26.1.1",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@xmachines/shared": "1.0.0",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "typescript": "^5.9.3 || ^6.0.3",
+    "urlpattern-polyfill": "^10.1.0",
+    "vitest": "^4.1.10",
+    "xstate": "^5.31.0"
   },
   "peerDependencies": {
-    "xstate": "^5.28.0"
-  }
+    "urlpattern-polyfill": "^10.1.0",
+    "xstate": "^5.31.0"
+  },
+  "peerDependenciesMeta": {
+    "urlpattern-polyfill": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "_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/connect-router.d.ts

@@ -1,56 +0,0 @@
-import type { AbstractActor, Routable } from "@xmachines/play-actor";
-import type { AnyActorLogic } from "xstate";
-import type { VanillaRouter } from "./create-router.js";
-import type { RouteMap } from "./create-route-map.js";
-export interface ConnectRouterOptions {
-    actor: AbstractActor<AnyActorLogic> & Routable;
-    router: VanillaRouter;
-    routeMap: RouteMap;
-}
-/**
- * Connect vanilla router to actor (pure browser integration).
- *
- * This is the LOW-LEVEL API for maximum control. No JSX, no rendering,
- * just actor ↔ router synchronization.
- *
- * Use this when:
- * - You want manual control over rendering
- * - Using non-JSX framework (jQuery, Alpine, HTMX, etc.)
- * - Building custom integration
- *
- * For JSX frameworks, use framework adapters instead:
- * - @xmachines/play-react (React components)
- * - Future: @xmachines/play-preact, @xmachines/play-solid, @xmachines/play-vue
- *
- * Architecture:
- * - Subscribes to history changes → sends play.route to actor
- * - Watches actor.currentRoute signal → updates browser URL
- * - Prevents circular updates (history change triggers actor, actor triggers history)
- * - Returns cleanup function
- *
- * Usage:
- * ```typescript
- * import { createBrowserHistory, createRouter, connectRouter } from '@xmachines/play-router';
- *
- * const history = createBrowserHistory({ window });
- * const router = createRouter({ routeTree, history });
- *
- * // Connect router to actor
- * const disconnect = connectRouter({ actor, router, routeMap });
- *
- * // User handles rendering (vanilla JS)
- * const watcher = new Signal.subtle.Watcher(() => {
- *   queueMicrotask(() => {
- *     const view = actor.currentView.get();
- *     document.getElementById('app').innerHTML = render(view);
- *   });
- * });
- * watcher.watch(actor.currentView);
- *
- * // Later: cleanup
- * disconnect();
- * watcher.unwatch(actor.currentView);
- * ```
- */
-export declare function connectRouter(options: ConnectRouterOptions): () => void;
-//# sourceMappingURL=connect-router.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"connect-router.d.ts","sourceRoot":"","sources":["../src/connect-router.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAmFvE"}

package/dist/connect-router.js

@@ -1,119 +0,0 @@
-import { Signal } from "@xmachines/play-signals";
-/**
- * Connect vanilla router to actor (pure browser integration).
- *
- * This is the LOW-LEVEL API for maximum control. No JSX, no rendering,
- * just actor ↔ router synchronization.
- *
- * Use this when:
- * - You want manual control over rendering
- * - Using non-JSX framework (jQuery, Alpine, HTMX, etc.)
- * - Building custom integration
- *
- * For JSX frameworks, use framework adapters instead:
- * - @xmachines/play-react (React components)
- * - Future: @xmachines/play-preact, @xmachines/play-solid, @xmachines/play-vue
- *
- * Architecture:
- * - Subscribes to history changes → sends play.route to actor
- * - Watches actor.currentRoute signal → updates browser URL
- * - Prevents circular updates (history change triggers actor, actor triggers history)
- * - Returns cleanup function
- *
- * Usage:
- * ```typescript
- * import { createBrowserHistory, createRouter, connectRouter } from '@xmachines/play-router';
- *
- * const history = createBrowserHistory({ window });
- * const router = createRouter({ routeTree, history });
- *
- * // Connect router to actor
- * const disconnect = connectRouter({ actor, router, routeMap });
- *
- * // User handles rendering (vanilla JS)
- * const watcher = new Signal.subtle.Watcher(() => {
- *   queueMicrotask(() => {
- *     const view = actor.currentView.get();
- *     document.getElementById('app').innerHTML = render(view);
- *   });
- * });
- * watcher.watch(actor.currentView);
- *
- * // Later: cleanup
- * disconnect();
- * watcher.unwatch(actor.currentView);
- * ```
- */
-export function connectRouter(options) {
-    const { actor, router, routeMap } = options;
-    const { history } = router;
-    // Prevent circular updates
-    let isProcessingHistoryChange = false;
-    let isProcessingActorChange = false;
-    let isProcessingPopstate = false;
-    // Subscribe to history changes (browser navigation)
-    const unsubscribeHistory = history.subscribe((location) => {
-        if (isProcessingActorChange)
-            return;
-        const { to, params } = routeMap.resolve(location.pathname);
-        if (to) {
-            isProcessingHistoryChange = true;
-            isProcessingPopstate = true;
-            actor.send({ type: "play.route", to, params });
-            // Check immediately if actor redirected (always-guard)
-            // XState processes events synchronously, so snapshot is already updated
-            const newActorRoute = actor.currentRoute.get();
-            if (newActorRoute && newActorRoute !== location.pathname) {
-                // Actor redirected - update URL
-                isProcessingActorChange = true;
-                history.replace(newActorRoute);
-                isProcessingActorChange = false;
-            }
-            // Clear flags synchronously to prevent race conditions
-            isProcessingHistoryChange = false;
-            isProcessingPopstate = false;
-        }
-    });
-    // Watch actor's currentRoute signal (actor-driven navigation)
-    const watcher = new Signal.subtle.Watcher(() => {
-        queueMicrotask(() => {
-            if (isProcessingHistoryChange)
-                return;
-            // Skip if we're processing popstate - let the history subscriber handle URL updates
-            if (isProcessingPopstate)
-                return;
-            for (const signal of watcher.getPending()) {
-                signal.get();
-            }
-            watcher.watch(actor.currentRoute);
-            // Sync URL from actor
-            const route = actor.currentRoute.get();
-            const currentPath = history.location.pathname;
-            // Find path from route (reverse lookup)
-            // Note: This assumes route tree has path metadata
-            // For now, simple implementation - can enhance later
-            if (route && route !== currentPath) {
-                isProcessingActorChange = true;
-                history.push(route);
-                isProcessingActorChange = false;
-            }
-        });
-    });
-    watcher.watch(actor.currentRoute);
-    // Sync initial URL to actor
-    // ONLY send route event if URL doesn't match actor's initial state
-    const initialPath = history.location.pathname;
-    const initialActorRoute = actor.currentRoute.get();
-    if (initialPath !== initialActorRoute) {
-        const { to, params } = routeMap.resolve(initialPath);
-        if (to) {
-            actor.send({ type: "play.route", to, params });
-        }
-    }
-    // Return cleanup
-    return () => {
-        unsubscribeHistory();
-        watcher.unwatch(actor.currentRoute);
-    };
-}
-//# sourceMappingURL=connect-router.js.map

package/dist/connect-router.js.map

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