@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/api/@xmachines/play-router/README.md

@@ -1,35 +1,25 @@
-[Documentation](../../README.md) / @xmachines/play-router
+[API](../../README.md) / @xmachines/play-router
 
-# @xmachines/play-router
-
-**Route tree extraction from XState v5 state machines with routing patterns**
-
-BFS graph crawling and bidirectional route lookup enabling Actor Authority over navigation.
-
-## Overview
-
-`@xmachines/play-router` extracts route trees from XState state machines by crawling the state graph using breadth-first traversal. It extracts `meta.route` paths from state machines and builds hierarchical route trees with bidirectional state ID ↔ path mapping.
+<!-- generated-by: gsd-doc-writer -->
 
-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.
+# @xmachines/play-router
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+Route tree extraction from XState v6 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-- **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
+Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
 
-**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 @xmachines/play-router
+pnpm add xstate@^6.0.0-alpha.19
+pnpm add @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^5.0.0 — State machine runtime
+- `xstate` ^6.0.0-alpha.19 — XState v6 state machine runtime
 
 **URLPattern polyfill (Node.js < 24 / older browsers):**
 
@@ -45,458 +35,398 @@ import "urlpattern-polyfill";
 Install the polyfill:
 
 ```bash
-npm install urlpattern-polyfill
+pnpm add urlpattern-polyfill
 ```
 
-`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — it is the consumer's responsibility to load it when needed.
+`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.
 
-## Quick Start
+## Usage
 
-```typescript
-import { createMachine } from "xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
+### Extract routes from a machine
 
-// Route pattern (recommended)
-const machine = createMachine({
+```typescript
+import { setup, types } from "xstate";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+
+// meta.route on state nodes needs a declared meta schema —
+// without it, XState v6 types `meta` as `never`.
+const machine = setup({
+	schemas: {
+		meta: types<{ route?: string }>(),
+	},
+}).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(tree.byPath.get("/dashboard/overview")); // RouteNode
-console.log(tree.byId.get("overview")); // RouteNode
-
-// Pattern matching for dynamic routes
-const settingsRoute = tree.byPath.get("/settings/profile");
-console.log(settingsRoute?.id); // "settings"
-```
-
-## Vanilla Browser Example
-
-See `examples/vanilla-demo/` for a complete example using vanilla TypeScript with the browser History API.
-
-The demo demonstrates:
+// Path → RouteNode
+const node = tree.byPath.get("/dashboard"); // RouteNode for "dashboard"
 
-- **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)
+// State ID → RouteNode
+const overview = tree.byStateId.get("overview");
+console.log(overview?.fullPath); // "/overview"
 
-**Run the demo:**
-
-```bash
-cd packages/play-router/examples/demo
-npm install
-npm run dev
+// 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 routeMap = createRouteMap(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 } = routeMap.resolve(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 } = routeMap.resolve(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.
-
-## API Reference
-
-### extractMachineRoutes()
+### Implementing a `RouterBridgeBase` adapter
 
-Main entry point — crawls state machine, extracts routes, builds tree:
+Extend `RouterBridgeBase` and implement the three abstract methods for your framework:
 
 ```typescript
-const tree = extractMachineRoutes(machine: AnyStateMachine): RouteTree;
-```
-
-**Detection:**
-
-- States with `meta.route` in meta object
-
-**Returns:** `RouteTree` with:
-
-- `routes: RouteNode[]` - Array of route nodes
-- `byPath: Map<string, RouteNode>` - URL path → route node
-- `byId: Map<string, RouteNode>` - State ID → route node
-
-**Throws:** Error if routes are invalid (malformed paths, missing state IDs, duplicates)
+import { RouterBridgeBase } from "@xmachines/play-router";
+import type { RoutableActor } from "@xmachines/play-router";
+
+export class MyRouterBridge extends RouterBridgeBase {
+	private unsubscribe: (() => void) | null = null;
+
+	constructor(
+		private readonly myRouter: MyRouter,
+		actor: RoutableActor,
+		routeMap: ReturnType<typeof createRouteMap>,
+	) {
+		super(actor, routeMap);
+	}
 
-**Example:**
+	// Tell the framework router to navigate to a path
+	protected navigateRouter(path: string): void {
+		this.myRouter.navigate(path);
+	}
 
-```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
+	// Subscribe to router location changes, call syncActorFromRouter on each
+	protected watchRouterChanges(): void {
+		this.unsubscribe = this.myRouter.subscribe((location) => {
+			this.syncActorFromRouter(location.pathname, location.search);
+		});
+	}
 
-const tree = extractMachineRoutes(authMachine);
+	// Unsubscribe from router location changes
+	protected unwatchRouterChanges(): void {
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+	}
 
-// Query routes
-const loginRoute = tree.byId.get("login");
-console.log(loginRoute?.path); // "/login"
+	// Provide the router's current path for initial deep-link sync
+	protected override getInitialRouterPath(): string {
+		return this.myRouter.state.location.pathname;
+	}
+}
 
-const dashboardRoute = tree.byPath.get("/dashboard");
-console.log(dashboardRoute?.id); // "dashboard"
+// Usage
+const routeMap = createRouteMap(machine);
+const bridge = new MyRouterBridge(myRouter, actor, routeMap);
+bridge.connect();
+// ...
+bridge.disconnect();
 ```
 
-### crawlMachine()
-
-Low-level BFS traversal of state machine graph:
-
-```typescript
-const visits = crawlMachine(machine: AnyStateMachine): StateVisit[];
-```
+## API Summary
 
-**Returns:** Array of state visits in breadth-first order with:
+### Route Extraction
 
-- `path: string[]` - State path (e.g., ["dashboard", "settings"])
-- `parent: StateNode | null` - Parent state node
-- `node: StateNode` - Current state node
+| 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 |
 
-**Example:**
+> **Graph shape under XState v6:** machines wired by `formatPlayRouteTransitions` expose their route navigation as statically-targeted `xstate.route` edges (one per routed state) plus a single dynamic `play.route` forwarder edge — tooling that previously filtered for per-route `play.route` edges should query `xstate.route` instead. Edge data marks guard presence with `guarded: true`; guard _names_ are unrecoverable under v6 (`guardType` is never populated).
 
-```typescript
-import { crawlMachine } from "@xmachines/play-router";
+### Route Matching
 
-const visits = crawlMachine(machine);
-visits.forEach((visit) => {
-	console.log("State:", visit.path.join("."));
-	console.log("Parent:", visit.parent?.id ?? "root");
-});
-```
+| Export                        | Description                                                                                |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `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)                              |
 
 ### Query Utilities
 
-```typescript
-// Get child routes from state
-const children = getNavigableRoutes(tree, "dashboard");
-
-// Check if route exists
-const exists = routeExists(tree, "/profile/:userId");
-```
-
-## Examples
-
-### Route Detection
+| 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 resolve to the same full 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? }`                                                            |
+| `RoutableActor`                    | Minimal actor interface required by `RouterBridgeBase` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`    |
+| `PlayActor`                        | Full actor interface used by `PlayRouterProvider` — extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
+| `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 } 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
-const profileById = tree.byId.get("profile");
-console.log(profileById?.path); // "/profile/:userId"
-
-const profileByPath = tree.byPath.get("/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.byId.get("analytics");
-console.log(analyticsRoute?.path); // "/dashboard/analytics" (inherited parent path)
-```
-
-### Pattern Matching
-
-```typescript
-import { extractMachineRoutes } 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 = tree.byPath.get("/user/user123");
-console.log(userRoute?.id); // "user"
-
-const settingsDefault = tree.byPath.get("/settings");
-console.log(settingsDefault?.id); // "settings" (optional param)
-
-const settingsProfile = tree.byPath.get("/settings/profile");
-console.log(settingsProfile?.id); // "settings" (with param)
+import {
+	RouterSyncError,
+	DuplicateBridgeError,
+	URLPatternUnavailableError,
+} from "@xmachines/play-router/errors";
+
+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. The machine's `setup({ schemas })` must declare a matching `meta` schema (e.g. `meta: types<{ route?: string | { path: string; title?: string } }>()`) — without one, XState v6 types state `meta` as `never`:
 
 ```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
+
+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
 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
-				// Final path: "/parent/relative"
-			},
-		},
-	},
+  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"
+      },
+    },
+  },
 }
 ```
 
-### Dynamic Parameters
+Always use `node.fullPath` (never `node.path`) for browser URL matching and route map construction.
 
-```typescript
-meta: {
-	route: "/profile/:userId", // Required parameter
-	route: "/settings/:section?", // Optional parameter
-	route: "/docs/:category/:page", // Multiple parameters
-	view: { component: "AnyView" },
-}
-```
-
-**Parameter substitution:** Values extracted from context or event params (handled by play-xstate adapter).
+## Testing
 
-## Architecture
+```bash
+# Run tests for this package
+pnpm --filter @xmachines/play-router test
 
-This package enables **Actor Authority (INV-01)**:
+# Watch mode
+pnpm --filter @xmachines/play-router run test:watch
+```
 
-1. **Routes derive from machine:** Business logic defines routes in state machine, not external config
-2. **BFS traversal:** Systematic state discovery ensures all nested states visited
-3. **Bidirectional mapping:** Fast lookup by path (browser URL) or by ID (state machine)
-4. **Build-time validation:** Invalid routes throw errors during extraction, not runtime
+A router bridge contract test suite for adapter authors lives in
+`@xmachines/play-router-shared` (it drives a real actor, so it sits one layer
+above this package to keep `@xmachines/play-router` free of an actor-runtime
+dependency):
 
-**Enhancements:**
+```typescript
+import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
 
-- `meta.route` detection via state metadata
-- Pattern matching for dynamic routes (`:param` and `:param?`)
-- State ID ↔ path bidirectional maps for `play.route` events
+runBridgeContractTests({
+	name: "MyRouterBridge",
+	createHarness(initialPath) {
+		// return ContractHarness with bridge, actor, simulateNavigation, getLastNavigatedPath
+	},
+});
+```
 
 ## 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`); all `AbstractActor` subclasses satisfy `RoutableActor` structurally
+- **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
+- **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v6 logic adapter that integrates with route trees
+- **[@xmachines/play-tanstack-router](../play-tanstack-router/README.md)** — Shared TanStack Router bridge base (framework-agnostic)
+- **[@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).
 
 ## Classes
 
-- [BaseRouteMap](classes/BaseRouteMap.md)
+- [RouteMap](classes/RouteMap.md)
 - [RouterBridgeBase](classes/RouterBridgeBase.md)
 
 ## Interfaces
 
-- [BaseRouteMapping](interfaces/BaseRouteMapping.md)
-- [BrowserHistory](interfaces/BrowserHistory.md)
-- [BrowserWindow](interfaces/BrowserWindow.md)
-- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [BuildPlayRouteEventOptions](interfaces/BuildPlayRouteEventOptions.md)
+- [LocationLike](interfaces/LocationLike.md)
+- [MachineEdgeData](interfaces/MachineEdgeData.md)
+- [MachineNodeData](interfaces/MachineNodeData.md)
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [ResolvedRoutePath](interfaces/ResolvedRoutePath.md)
+- [RoutableActor](interfaces/RoutableActor.md)
 - [RouteInfo](interfaces/RouteInfo.md)
-- [RouteMap](interfaces/RouteMap.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouteMatch](interfaces/RouteMatch.md)
 - [RouteNode](interfaces/RouteNode.md)
 - [RouteObject](interfaces/RouteObject.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouteTree](interfaces/RouteTree.md)
-- [StateVisit](interfaces/StateVisit.md)
-- [VanillaRouter](interfaces/VanillaRouter.md)
+- [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
+- [WindowLike](interfaces/WindowLike.md)
 
 ## Type Aliases
 
+- [MachineGraph](type-aliases/MachineGraph.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 
 ## Functions
 
+- [buildPlayRouteEvent](functions/buildPlayRouteEvent.md)
 - [buildRouteTree](functions/buildRouteTree.md)
-- [connectRouter](functions/connectRouter.md)
-- [crawlMachine](functions/crawlMachine.md)
-- [createBrowserHistory](functions/createBrowserHistory.md)
 - [createRouteMap](functions/createRouteMap.md)
-- [createRouter](functions/createRouter.md)
+- [createRouteMapFromTree](functions/createRouteMapFromTree.md)
 - [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
-- [extractRoute](functions/extractRoute.md)
+- [extractQuery](functions/extractQuery.md)
+- [extractRouteParams](functions/extractRouteParams.md)
 - [findRouteById](functions/findRouteById.md)
 - [findRouteByPath](functions/findRouteByPath.md)
 - [getNavigableRoutes](functions/getNavigableRoutes.md)
 - [getRoutableRoutes](functions/getRoutableRoutes.md)
+- [getTransitionReachableRoutes](functions/getTransitionReachableRoutes.md)
+- [isRouteReachable](functions/isRouteReachable.md)
+- [machineToGraph](functions/machineToGraph.md)
 - [routeExists](functions/routeExists.md)
+- [sanitizePathname](functions/sanitizePathname.md)
 - [validateRouteFormat](functions/validateRouteFormat.md)
 - [validateStateExists](functions/validateStateExists.md)
+
+## References
+
+### BaseRouteMapping
+
+Renames and re-exports [RouteMapping](interfaces/RouteMapping.md)