@xmachines/play-router 1.0.0-beta.46 → 1.0.0-beta.48

package/README.md

@@ -1,35 +1,23 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-router
 
-**Route tree extraction from XState v5 state machines with routing patterns**
+Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
 Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
 
-## Overview
-
-`@xmachines/play-router` extracts route trees from XState state machines using `@statelyai/graph` — a typed, JSON-serializable graph library. It converts machines to a directed `Graph` with hierarchy, transition edges, and route metadata, then builds hierarchical `RouteTree` structures with bidirectional state ID ↔ path mapping.
-
-It also exports `RouterBridgeBase`, the shared base class used by framework adapters to implement `RouterBridge` with consistent actor↔router synchronization behavior.
-
-`RouterBridgeBase` is the policy point; framework adapters are thin ports that implement only framework-specific navigate/subscribe/unsubscribe behavior.
-
-The low-level `connectRouter()` from `@xmachines/play-dom-router` uses the same router-to-actor event builder and route-map match helper as `RouterBridgeBase`, so pathname sanitization, state-id normalization, param extraction, and query extraction stay aligned across vanilla and framework adapters.
-
-Per [Play RFC](../docs/rfc/play.md), this package implements:
-
-- **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
-
-**Routing:** Supports `meta.route` detection, `play.route` event routing, and pattern matching for dynamic parameters.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install xstate@^5.0.0
+npm install xstate@^5.30.0
 npm install @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^5.0.0 — State machine runtime
+- `xstate` ^5.30.0 — XState v5 state machine runtime
 
 **URLPattern polyfill (Node.js < 24 / older browsers):**
 
@@ -48,552 +36,324 @@ Install the polyfill:
 npm install urlpattern-polyfill
 ```
 
-`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — consumers must install and load it when their runtime lacks native URLPattern support (Node.js < 24, older browsers).
+`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — consumers must install and load it when their runtime lacks native URLPattern support.
+
+## Usage
 
-## Quick Start
+### Extract routes from a machine
 
 ```typescript
 import { createMachine } from "xstate";
-import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
 
-// Route pattern (recommended)
 const machine = createMachine({
 	id: "app",
 	initial: "home",
 	states: {
 		home: {
 			id: "home",
-			meta: { route: "/", view: { component: "Home" } },
+			meta: { route: "/" },
 		},
 		dashboard: {
 			id: "dashboard",
-			meta: { route: "/dashboard", view: { component: "Dashboard" } },
+			meta: { route: "/dashboard" },
 			initial: "overview",
 			states: {
 				overview: {
 					id: "overview",
-					meta: { route: "/overview", view: { component: "Overview" } },
+					meta: { route: "/overview" },
 				},
 				settings: {
 					id: "settings",
-					meta: { route: "/settings/:section?", view: { component: "Settings" } }, // Optional parameter
+					meta: { route: "/settings/:section?" }, // optional parameter
 				},
 			},
 		},
+		profile: {
+			id: "profile",
+			meta: { route: "/profile/:userId" }, // required parameter
+		},
 	},
 });
 
+// Build hierarchical route tree with bidirectional maps
 const tree = extractMachineRoutes(machine);
 
-// Bidirectional lookup
-console.log(findRouteByPath(tree, "/overview")); // RouteNode
-console.log(tree.byStateId.get("overview")); // RouteNode
+// Path → RouteNode
+const node = tree.byPath.get("/dashboard"); // RouteNode for "dashboard"
 
-// Pattern matching for dynamic routes
-const settingsRoute = findRouteByPath(tree, "/settings/profile");
-console.log(settingsRoute?.id); // "settings"
-```
+// State ID → RouteNode
+const overview = tree.byStateId.get("overview");
+console.log(overview?.fullPath); // "/overview"
 
-## Vanilla Browser Example
-
-See `examples/vanilla-demo/` for a complete example using vanilla TypeScript with the browser History API.
-
-The demo demonstrates:
-
-- **RouteTree extraction** from XState machine meta.route
-- **History API integration** (pushState, popstate)
-- **Bidirectional synchronization** (actor ↔ URL)
-- **Protected route guards** (authentication redirects)
-- **Dynamic route parameters** (/profile/:userId)
-
-**Run the demo:**
-
-```bash
-npm run dev -w @xmachines/play-dom-router-demo
+// Build a RouteMap for framework adapters
+const routeMap = createRouteMap(machine);
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("profile"); // "/profile/:userId"
 ```
 
-Open http://localhost:5174/ and explore:
-
-1. Login with any username
-2. Navigate between home and profile
-3. Use browser back/forward buttons
-4. Try accessing protected routes directly
-
-**Key implementation patterns:**
+### Sending `play.route` events
 
 ```typescript
-// Extract routes from machine
-const routeTree = extractMachineRoutes(authMachine);
-const routeMatcher = createRouteMatcher(routeTree);
-
-// Actor → URL sync
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		watcher.getPending();
-		const route = actor.currentRoute.get();
-		if (route) {
-			window.history.pushState({}, "", route);
-		}
-		watcher.watch(actor.currentRoute);
-	});
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+// Navigate to a state by ID
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#dashboard",
+};
+actor.send(event);
+
+// Navigate with route parameters
+actor.send({
+	type: "play.route",
+	to: "#profile",
+	params: { userId: "123" },
 });
 
-// URL → Actor sync (with pattern matching)
-window.addEventListener("popstate", () => {
-	const path = window.location.pathname;
-	const { to, params } = routeMatcher.match(path);
-	if (to) {
-		actor.send({ type: "play.route", to, params });
-	}
+// Navigate with query parameters
+actor.send({
+	type: "play.route",
+	to: "#settings",
+	params: { section: "billing" },
+	query: { tab: "invoices" },
 });
-
-// Initial URL handling
-const initialPath = window.location.pathname;
-if (initialPath !== "/") {
-	const { to, params } = routeMatcher.match(initialPath);
-	if (to) {
-		actor.send({ type: "play.route", to, params });
-	}
-}
-```
-
-This example shows the core routing concepts without framework dependencies, making it ideal for understanding how @xmachines/play-router integrates with browser History API.
-
-## Canonical Watcher Lifecycle
-
-Bridge implementations should use one watcher flow:
-
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. read actor route and sync infrastructure state
-5. re-arm with `watch(...)` or `watch()`
-
-Watcher notification is one-shot; re-arm is required.
-
-## Bridge Cleanup Contract
-
-Bridge teardown must be explicit and deterministic:
-
-- `disconnect`/`dispose` must unwatch signal subscriptions and unhook router listeners.
-- Do not rely on GC-only cleanup guidance.
-- Infrastructure remains passive: bridges observe and forward intents, actors decide validity.
-- `createBrowserHistory().destroy()` (from `@xmachines/play-dom-router`) is idempotent and restores shared `window.history` patches only after the last wrapper for that window is removed.
-    - **Note**: `createBrowserHistory()` mutates global `window.history` methods (`pushState` and `replaceState`) and coordinates wrappers with shared ref-count state. To reduce leakage, create one history wrapper per browser window at the application boundary and always pair it with `destroy()` during teardown.
-
-## Bridge Sync Ordering
-
-`RouterBridgeBase.connect()` has an intentional ordering contract used by all framework adapters:
-
-- seed `lastSyncedPath` from `actor.currentRoute` in the constructor
-- install the actor route watcher
-- install adapter router subscriptions
-- resolve initial sync using `getInitialRouterPath()` and `actor.initialRoute`
-
-That final step distinguishes:
-
-- **deep-link:** browser URL differs from the machine's initial route, so router wins and the actor receives `play.route`
-- **restore:** browser URL is still at the machine's initial route while the actor was restored elsewhere, so actor wins and the bridge pushes the actor route back into the router
-
-Actor-originated router sync suppresses router echoes via `lastSyncedPath`. `syncRouterFromActor` resolves the concrete path and stores it before calling the adapter's navigation method; when the router callback fires with that same path, `syncActorFromRouter` short-circuits at `sanitized === lastSyncedPath` and sends no event.
-
-## Diagnostics
-
-Router infrastructure reports runtime failures through `PlayDiagnostics` from `@xmachines/play`.
-
-- Default behavior uses `consoleDiagnostics`.
-- Messages follow a stable `[scope:code] message` format.
-- Example: `[RouterBridgeBase:PLAY_ROUTER_SYNC_FAILED] Failed to sync actor state from router location.`
-
-This keeps router errors observable while letting applications swap in their own diagnostics implementation upstream.
-
-## API Reference
-
-### extractMachineRoutes()
-
-Main entry point — crawls state machine, extracts routes, builds tree:
-
-```typescript
-const tree = extractMachineRoutes(machine: AnyStateMachine): RouteTree;
 ```
 
-**Detection:**
+### Implementing a `RouterBridgeBase` adapter
 
-- States with `meta.route` in meta object
-
-**Returns:** `RouteTree` with:
-
-- `byPath: Map<string, RouteNode>` — URL path → route node
-- `byStateId: Map<string, RouteNode>` — State ID → route node
-- `root: RouteNode` — synthetic root node
-- `graph: MachineGraph` — `@statelyai/graph` Graph for hierarchy queries, reachability checks, and transition-aware navigation
-
-**Throws:** Error if routes are invalid (malformed paths, missing state IDs, duplicates)
-
-**Example:**
-
-```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-
-const tree = extractMachineRoutes(authMachine);
-
-// Query routes — use fullPath for URL matching (path is the raw meta.route segment)
-const loginRoute = tree.byStateId.get("login");
-console.log(loginRoute?.fullPath); // "/login"
-console.log(loginRoute?.path); // "/login" (same for absolute routes)
-
-// For nested relative routes the distinction matters:
-// meta.route: "overview" under "/dashboard" → path: "overview", fullPath: "/dashboard/overview"
-const overviewRoute = tree.byStateId.get("overview");
-console.log(overviewRoute?.path); // "overview"  (raw segment — relative)
-console.log(overviewRoute?.fullPath); // "/dashboard/overview"  (resolved — use this)
-
-const dashboardRoute = tree.byPath.get("/dashboard");
-console.log(dashboardRoute?.id); // "dashboard"
-```
-
-### machineToGraph()
-
-Converts an XState v5 machine to a typed `@statelyai/graph` `Graph`:
+Extend `RouterBridgeBase` and implement the three abstract methods for your framework:
 
 ```typescript
-import { machineToGraph } from "@xmachines/play-router";
-import { getChildren, getSuccessors, hasPath } from "@statelyai/graph";
-
-const graph = machineToGraph(machine);
-
-// Hierarchy queries
-const children = getChildren(graph, "myMachine");
-const successors = getSuccessors(graph, "myMachine.home"); // transition-reachable states
-
-// Reachability
-const reachable = hasPath(graph, "myMachine.home", "myMachine.dashboard");
-```
-
-The graph is also available on any `RouteTree` returned by `extractMachineRoutes()`:
-
-```typescript
-const tree = extractMachineRoutes(machine);
-
-// Use @statelyai/graph algorithms directly on the graph
-const successors = getSuccessors(tree.graph!, "myMachine.home");
-```
-
-**Node data** (`MachineNodeData`):
-
-- `stateId: string` — XState state ID (e.g., `"myMachine.dashboard.overview"`)
-- `type` — `"atomic" | "compound" | "parallel" | "final" | "history"`
-- `meta?: Record<string, unknown>` — original state meta object
-- `route?: string` — extracted route path from `meta.route`
+import { RouterBridgeBase } from "@xmachines/play-router";
+import type { AbstractActor, Routable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+
+export class MyRouterBridge extends RouterBridgeBase {
+	private unsubscribe: (() => void) | null = null;
+
+	constructor(
+		private readonly myRouter: MyRouter,
+		actor: AbstractActor<AnyActorLogic> & Routable,
+		routeMap: ReturnType<typeof createRouteMap>,
+	) {
+		super(actor, routeMap);
+	}
 
-**Edge data** (`MachineEdgeData`):
+	// Tell the framework router to navigate to a path
+	protected navigateRouter(path: string): void {
+		this.myRouter.navigate(path);
+	}
 
-- `eventType: string` — event type triggering this transition
-- `guardType?: string` — guard name/description (if transition is guarded)
+	// Subscribe to router location changes, call syncActorFromRouter on each
+	protected watchRouterChanges(): void {
+		this.unsubscribe = this.myRouter.subscribe((location) => {
+			this.syncActorFromRouter(location.pathname, location.search);
+		});
+	}
 
-### createRouteMap() / createRouteMapFromTree()
+	// Unsubscribe from router location changes
+	protected unwatchRouterChanges(): void {
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+	}
 
-Both build a `BaseRouteMap` using `node.fullPath` (absolute resolved paths) for browser URL matching.
+	// Provide the router's current path for initial deep-link sync
+	protected override getInitialRouterPath(): string {
+		return this.myRouter.state.location.pathname;
+	}
+}
 
-```typescript
-// Single-call form — preferred for XState machines:
-import { createRouteMap } from "@xmachines/play-router";
+// Usage
 const routeMap = createRouteMap(machine);
-
-// Two-step form — used by framework adapter packages:
-import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+const bridge = new MyRouterBridge(myRouter, actor, routeMap);
+bridge.connect();
+// ...
+bridge.disconnect();
 ```
 
-Both forms produce identical `RouteMap` results. `createRouteMapFromTree` is exposed for framework adapters (React Router, TanStack Router) that already hold the `RouteTree` separately for other purposes (e.g. graph queries). `createRouteMatcher(routeTree)` is the distinct API for URL-pattern matching that returns a `RouteMatcher`, not a `RouteMap`.
-
-**`node.path` vs `node.fullPath`:** Every `RouteNode` carries both fields. `path` is the raw `meta.route` segment as declared in the machine — it may be relative (e.g. `"overview"`). `fullPath` is the resolved absolute path (e.g. `"/dashboard/overview"`). Route maps always use `fullPath`. Only use `path` if you specifically need the declared segment.
-
-### Query Utilities
+## API Summary
 
-```typescript
-import {
-	getNavigableRoutes,
-	getRoutableRoutes,
-	routeExists,
-	getTransitionReachableRoutes,
-	isRouteReachable,
-} from "@xmachines/play-router";
+### Route Extraction
 
-// Child routes (hierarchical + transition-reachable)
-const navigable = getNavigableRoutes(tree, "dashboard");
+| Export                                   | Description                                                                        |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- |
+| `extractMachineRoutes(machine)`          | Convert an XState machine to a `RouteTree` with bidirectional state ID ↔ path maps |
+| `createRouteMap(machine, options?)`      | Build a `RouteMap` directly from a machine (preferred form for adapters)           |
+| `createRouteMapFromTree(tree, options?)` | Build a `RouteMap` from an already-extracted `RouteTree`                           |
+| `buildRouteTree(routes)`                 | Build a `RouteTree` from an array of `RouteInfo` objects                           |
+| `machineToGraph(machine)`                | Convert a machine to a typed `@statelyai/graph` `Graph` for graph algorithm access |
 
-// All routable routes as flat array
-const allRoutes = getRoutableRoutes(tree);
+### Route Matching
 
-// Check path exists
-const exists = routeExists(tree, "/profile/:userId");
+| Export                        | Description                                                                                |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `createRouteMatcher(tree)`    | Create a `RouteMatcher` that matches URL paths to `#stateId` values and extracts params    |
+| `RouteMap`                    | Bidirectional `stateId ↔ path` lookup class; supports O(1) exact and O(k) pattern matching |
+| `findRouteById(tree, id)`     | Look up a `RouteNode` by state ID                                                          |
+| `findRouteByPath(tree, path)` | Look up a `RouteNode` by URL path (supports dynamic patterns)                              |
 
-// Transition-aware: which state IDs are reachable via transitions?
-const reachableIds = getTransitionReachableRoutes(tree.graph!, "myMachine.home");
-
-// Is there any path from state A to state B via transitions?
-const canReach = isRouteReachable(tree.graph!, "myMachine.home", "myMachine.dashboard");
-```
-
-## Examples
-
-### Route Detection
-
-```typescript
-import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
-import { createMachine } from "xstate";
-
-const machine = createMachine({
-	initial: "home",
-	states: {
-		home: {
-			id: "home",
-			meta: { route: "/", view: { component: "Home" } },
-		},
-		profile: {
-			id: "profile",
-			meta: { route: "/profile/:userId", view: { component: "Profile" } }, // Parameter pattern
-		},
-		settings: {
-			id: "settings",
-			meta: { route: "/settings/:section?", view: { component: "Settings" } }, // Optional parameter
-		},
-	},
-});
-
-const tree = extractMachineRoutes(machine);
-
-// Bidirectional mapping — use fullPath for URLs; path is the raw meta.route segment
-const profileById = tree.byStateId.get("profile");
-console.log(profileById?.fullPath); // "/profile/:userId"
-
-const profileByPath = findRouteByPath(tree, "/profile/user123");
-console.log(profileByPath?.id); // "profile"
-```
-
-### Hierarchical Route Tree
-
-```typescript
-import { extractMachineRoutes, getNavigableRoutes } from "@xmachines/play-router";
-
-const machine = createMachine({
-	initial: "app",
-	states: {
-		app: {
-			id: "app",
-			meta: { route: "/", view: { component: "AppShell" } },
-			initial: "dashboard",
-			states: {
-				dashboard: {
-					id: "dashboard",
-					meta: { route: "/dashboard", view: { component: "Dashboard" } },
-					initial: "overview",
-					states: {
-						overview: {
-							id: "overview",
-							meta: { route: "/overview", view: { component: "Overview" } },
-						},
-						analytics: {
-							id: "analytics",
-							meta: { route: "/analytics", view: { component: "Analytics" } },
-						},
-					},
-				},
-			},
-		},
-	},
-});
-
-const tree = extractMachineRoutes(machine);
-
-// Get child routes
-const dashboardChildren = getNavigableRoutes(tree, "dashboard");
-console.log(dashboardChildren.map((r) => r.id)); // ["overview", "analytics"]
-
-// Route inheritance
-const analyticsRoute = tree.byStateId.get("analytics");
-console.log(analyticsRoute?.fullPath); // "/analytics" (absolute route)
-```
+### Query Utilities
 
-### Pattern Matching
+| Export                                            | Description                                                               |
+| ------------------------------------------------- | ------------------------------------------------------------------------- |
+| `getRoutableRoutes(tree)`                         | All routable `RouteNode`s as a flat array                                 |
+| `getNavigableRoutes(tree, stateId)`               | Child routes reachable from a state (hierarchical + transition-reachable) |
+| `routeExists(tree, path)`                         | Check whether a path is registered in the tree                            |
+| `getTransitionReachableRoutes(graph, stateId)`    | Route paths reachable via XState transitions from a state                 |
+| `isRouteReachable(graph, fromStateId, toStateId)` | Check whether a transition path exists between two states                 |
+
+### Router Bridge
+
+| Export                                  | Description                                                                           |
+| --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `RouterBridgeBase`                      | Abstract base class for framework router adapters; implements `RouterBridge` protocol |
+| `sanitizePathname(path)`                | Normalize a raw pathname; returns `null` for paths > 2048 chars or malformed input    |
+| `buildPlayRouteEvent(options)`          | Build a `PlayRouteEvent` from a pathname + route-map match result                     |
+| `extractRouteParams(pathname, pattern)` | Extract path parameters from a URL using URLPattern                                   |
+| `extractQuery(search)`                  | Extract query parameters from a URL search string                                     |
+
+### Validation
+
+| Export                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `validateRouteFormat(route, stateId)`    | Assert route path is non-empty                    |
+| `validateStateExists(stateId, stateIds)` | Assert a state ID is present in the machine graph |
+| `detectDuplicateRoutes(routes)`          | Throw if any two states share the same URL path   |
+
+### Key Types
+
+| Export                             | Description                                                                            |
+| ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `RouterBridge`                     | Interface for `connect()` / `disconnect()` lifecycle                                   |
+| `RouteTree`                        | Hierarchical tree with `root`, `byStateId`, `byPath`, and optional `graph`             |
+| `RouteNode`                        | Single node in the tree with `id`, `path`, `fullPath`, `stateId`, `children`, `parent` |
+| `RouteInfo`                        | Flat route descriptor extracted from a state node                                      |
+| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                            |
+| `RouteMapping`                     | `{ stateId, path }` pair used to build a `RouteMap`                                    |
+| `RouteMapping as BaseRouteMapping` | Alias for `RouteMapping` (backwards-compat re-export)                                  |
+| `MachineGraph`                     | Typed `@statelyai/graph` Graph with `MachineNodeData` / `MachineEdgeData`              |
+| `WindowLike`                       | Injectable minimal `window` interface for SSR / testing                                |
+| `LocationLike`                     | Injectable minimal `location` interface for SSR / testing                              |
+
+### Errors (subpath `@xmachines/play-router/errors`)
+
+| Class                        | Code                                    | When thrown                                                       |
+| ---------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
+| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to send a `play.route` event        |
+| `DuplicateBridgeError`       | `PLAY_ROUTER_DUPLICATE_BRIDGE`          | A second bridge tries to connect to an actor that already has one |
+| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | URLPattern API is absent and no polyfill is loaded                |
+| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by the URLPattern constructor  |
+| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                 |
+| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route references a state ID not in the machine graph            |
+| `DuplicateRoutePathError`    | `PLAY_ROUTE_DUPLICATE_PATH`             | Two or more states share the same URL path                        |
+| `UnknownStateTypeError`      | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`         | A state node has an unrecognised XState `.type` value             |
 
 ```typescript
-import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
-
-const machine = createMachine({
-	states: {
-		user: {
-			id: "user",
-			meta: { route: "/user/:userId", view: { component: "User" } }, // Required parameter
-		},
-		settings: {
-			id: "settings",
-			meta: { route: "/settings/:section?", view: { component: "Settings" } }, // Optional parameter
-		},
-	},
-});
-
-const tree = extractMachineRoutes(machine);
-
-// Pattern matching for actual URLs
-const userRoute = findRouteByPath(tree, "/user/user123");
-console.log(userRoute?.id); // "user"
-
-const settingsDefault = findRouteByPath(tree, "/settings");
-console.log(settingsDefault?.id); // "settings" (optional param)
+import {
+	RouterSyncError,
+	DuplicateBridgeError,
+	URLPatternUnavailableError,
+} from "@xmachines/play-router/errors";
 
-const settingsProfile = findRouteByPath(tree, "/settings/profile");
-console.log(settingsProfile?.id); // "settings" (with param)
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof DuplicateBridgeError) {
+		// Actor already bridged — call disconnect() first
+	} else if (err instanceof RouterSyncError) {
+		console.error("Router sync failed:", err.message, err.cause);
+	}
+}
 ```
 
 ## Route Configuration
 
-### Route Pattern (Recommended)
+### `meta.route` patterns
 
-```typescript
-states: {
-	dashboard: {
-		id: "dashboard", // Required for bidirectional lookup
-		meta: {
-			route: "/dashboard", // URL path - marks state as routable
-		},
-	},
-}
-```
-
-### Alternative Pattern
+Routes are declared on XState state nodes via the `meta.route` field:
 
 ```typescript
 states: {
-	dashboard: {
-		id: "dashboard",
-		meta: {
-			route: "/dashboard",
-		},
-	},
+  home: {
+    id: "home",
+    meta: { route: "/" },                       // static route
+  },
+  profile: {
+    id: "profile",
+    meta: { route: "/profile/:userId" },        // required parameter
+  },
+  settings: {
+    id: "settings",
+    meta: { route: "/settings/:section?" },     // optional parameter
+  },
+  docs: {
+    id: "docs",
+    meta: { route: { path: "/docs", title: "Documentation" } }, // object form
+  },
 }
 ```
 
-### Route Inheritance
+### Relative vs absolute paths
 
-```typescript
-states: {
-	parent: {
-		id: "parent",
-		meta: { route: "/parent", view: { component: "Parent" } },
-		states: {
-			absolute: {
-				id: "absolute",
-				meta: { route: "/absolute", view: { component: "Absolute" } }, // Starts with / → doesn't inherit
-			},
-			relative: {
-				id: "relative",
-				meta: { route: "relative", view: { component: "Relative" } }, // No leading / → inherits parent path prefix
-				// Final path: "/parent/relative"
-			},
-		},
-	},
-}
-```
-
-### Dynamic Parameters
+Child routes with a leading `/` are absolute (do not inherit the parent path). Without a leading `/`, they resolve relative to their nearest routable ancestor:
 
 ```typescript
-meta: {
-	route: "/profile/:userId", // Required parameter
-	route: "/settings/:section?", // Optional parameter
-	route: "/docs/:category/:page", // Multiple parameters
-	view: { component: "AnyView" },
+states: {
+  dashboard: {
+    id: "dashboard",
+    meta: { route: "/dashboard" },
+    states: {
+      overview: {
+        id: "overview",
+        meta: { route: "/overview" },   // absolute → fullPath: "/overview"
+      },
+      stats: {
+        id: "stats",
+        meta: { route: "stats" },       // relative → fullPath: "/dashboard/stats"
+      },
+    },
+  },
 }
 ```
 
-**Parameter substitution:** Values extracted from context or event params (handled by play-xstate adapter).
-
-## Security Utilities
-
-### `sanitizePathname()`
+Always use `node.fullPath` (never `node.path`) for browser URL matching and route map construction.
 
-Normalize a raw pathname before route-map lookup. Used internally by `RouterBridgeBase.syncActorFromRouter()` and available to adapters that bypass the base class:
+## Testing
 
-```typescript
-import { sanitizePathname } from "@xmachines/play-router";
-
-// In a custom adapter's route-watch callback:
-const clean = sanitizePathname(rawPath);
-if (clean === null) return; // Reject malformed/oversized paths (> 2048 chars)
-// Proceed with clean normalized path
-```
-
-Returns `null` for paths exceeding 2048 characters. Strips query fragments, hash fragments, and collapses duplicate slashes.
-
----
-
-## Error Handling
-
-All runtime errors thrown by this package extend `PlayError` from `@xmachines/play` and
-are exported from the `./errors` subpath:
+```bash
+# Run tests for this package
+npm test -w @xmachines/play-router
 
-```typescript
-import {
-	RouterSyncError,
-	URLPatternUnavailableError,
-	InvalidRoutePatternError,
-} from "@xmachines/play-router/errors";
+# Watch mode
+npm run test:watch -w @xmachines/play-router
 ```
 
-| Class                        | Code                                    | When thrown                                                    |
-| ---------------------------- | --------------------------------------- | -------------------------------------------------------------- |
-| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to send a `play.route` event     |
-| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | `createRouteMap()` called before URLPattern polyfill is loaded |
-| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by URLPattern constructor   |
-
-`InvalidRoutePatternError` carries a `pattern: string` field with the offending pattern.
+The package exports a router bridge contract test suite for adapter authors:
 
 ```typescript
-import { PlayError } from "@xmachines/play";
-import { RouterSyncError } from "@xmachines/play-router/errors";
+import { runBridgeContractTests } from "@xmachines/play-router/test/contract.js";
 
-try {
-	bridge.connect();
-} catch (err) {
-	if (err instanceof RouterSyncError) {
-		// err.cause — the original error that triggered the sync failure
-		monitoringService.record(err);
-	} else if (err instanceof PlayError) {
-		console.error(`[${err.scope}:${err.code}] ${err.message}`);
-	}
-}
+runBridgeContractTests({
+	name: "MyRouterBridge",
+	createHarness(initialPath) {
+		// return ContractHarness with bridge, actor, simulateNavigation, getLastNavigatedPath
+	},
+});
 ```
 
-## Architecture
-
-This package enables **Actor Authority (INV-01)**:
-
-1. **Routes derive from machine:** Business logic defines routes in state machine, not external config
-2. **Graph-based extraction:** `machineToGraph()` converts machines to typed `@statelyai/graph` `Graph` objects with hierarchy, transition edges, and route metadata
-3. **Bidirectional mapping:** Fast lookup by path (browser URL) or by state ID (state machine)
-4. **Transition-aware queries:** `getTransitionReachableRoutes()` and `isRouteReachable()` use graph algorithms for navigation reachability
-5. **Build-time validation:** Invalid routes throw errors during extraction, not runtime
-
-**Enhancements:**
-
-- `meta.route` detection via state metadata — extracted into typed graph node data
-- Pattern matching for dynamic routes (`:param` and `:param?`)
-- State ID ↔ path bidirectional maps for `play.route` events
-- `@statelyai/graph` integration — hierarchy queries, reachability checks, transition traversal
-
 ## Related Packages
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter using route extraction
-- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** - TanStack Router adapter using route trees
-- **[@xmachines/play-react-router](../play-react-router/README.md)** - React Router v7 adapter using RouterBridgeBase
-- **[@xmachines/play](../play/README.md)** - Protocol types
+- **[@xmachines/play](../play/README.md)** — Core protocol types (`PlayEvent`, `PlayError`)
+- **[@xmachines/play-actor](../play-actor/README.md)** — Abstract actor base class (`AbstractActor`, `Routable`)
+- **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
+- **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v5 logic adapter that integrates with route trees
+- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** — TanStack Router adapter (React)
+- **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** — TanStack Router adapter (SolidJS)
+- **[@xmachines/play-react-router](../play-react-router/README.md)** — React Router v7 adapter
+- **[@xmachines/play-vue-router](../play-vue-router/README.md)** — Vue Router adapter
+- **[@xmachines/play-solid-router](../play-solid-router/README.md)** — SolidJS Router adapter
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-router",
-  "version": "1.0.0-beta.46",
+  "version": "1.0.0-beta.48",
   "description": "Route tree extraction from XState v5 state machines. Part of @xmachines/play Universal Player Architecture.",
   "keywords": [
     "routing",
@@ -46,26 +46,26 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@statelyai/graph": "^0.11.0",
-    "@xmachines/play": "1.0.0-beta.46",
-    "@xmachines/play-actor": "1.0.0-beta.46",
-    "@xmachines/play-signals": "1.0.0-beta.46",
+    "@statelyai/graph": "^0.12.0",
+    "@xmachines/play": "1.0.0-beta.48",
+    "@xmachines/play-actor": "1.0.0-beta.48",
+    "@xmachines/play-signals": "1.0.0-beta.48",
     "quick-lru": "^7.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@xmachines/play-xstate": "1.0.0-beta.46",
-    "@xmachines/shared": "1.0.0-beta.46",
-    "oxfmt": "^0.45.0",
-    "oxlint": "^1.60.0",
+    "@xmachines/play-xstate": "1.0.0-beta.48",
+    "@xmachines/shared": "1.0.0-beta.48",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
     "typescript": "^5.9.3 || ^6.0.3",
     "urlpattern-polyfill": "^10.1.0",
-    "vitest": "^4.1.4",
-    "xstate": "^5.30.0"
+    "vitest": "^4.1.5",
+    "xstate": "^5.31.0"
   },
   "peerDependencies": {
     "urlpattern-polyfill": "^10.1.0",
-    "xstate": "^5.30.0"
+    "xstate": "^5.31.0"
   },
   "peerDependenciesMeta": {
     "urlpattern-polyfill": {