@xmachines/play-router 1.0.0-beta.1

package/.oxfmtrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@xmachines/shared/oxfmt"]
+}

package/.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@xmachines/shared/oxlint"]
+}

package/README.md

@@ -0,0 +1,436 @@
+# @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.
+
+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.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.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.
+
+## Installation
+
+```bash
+npm install xstate@^5.0.0
+npm install @xmachines/play-router
+```
+
+**Peer dependencies:**
+
+- `xstate` ^5.0.0 - State machine runtime
+
+## Quick Start
+
+```typescript
+import { createMachine } from "xstate";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+// Route pattern (recommended)
+const machine = createMachine({
+	id: "app",
+	initial: "home",
+	states: {
+		home: {
+			id: "home",
+			meta: { route: "/", view: { component: "Home" } },
+		},
+		dashboard: {
+			id: "dashboard",
+			meta: { route: "/dashboard", view: { component: "Dashboard" } },
+			initial: "overview",
+			states: {
+				overview: {
+					id: "overview",
+					meta: { route: "/overview", view: { component: "Overview" } },
+				},
+				settings: {
+					id: "settings",
+					meta: { route: "/settings/:section?", view: { component: "Settings" } }, // Optional parameter
+				},
+			},
+		},
+	},
+});
+
+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:
+
+- **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
+cd packages/play-router/examples/demo
+npm install
+npm run dev
+```
+
+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:**
+
+```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);
+	});
+});
+
+// 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 });
+	}
+});
+
+// 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()
+
+Main entry point — crawls state machine, extracts routes, builds tree:
+
+```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)
+
+**Example:**
+
+```typescript
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+const tree = extractMachineRoutes(authMachine);
+
+// Query routes
+const loginRoute = tree.byId.get("login");
+console.log(loginRoute?.path); // "/login"
+
+const dashboardRoute = tree.byPath.get("/dashboard");
+console.log(dashboardRoute?.id); // "dashboard"
+```
+
+### crawlMachine()
+
+Low-level BFS traversal of state machine graph:
+
+```typescript
+const visits = crawlMachine(machine: AnyStateMachine): StateVisit[];
+```
+
+**Returns:** Array of state visits in breadth-first order with:
+
+- `path: string[]` - State path (e.g., ["dashboard", "settings"])
+- `parent: StateNode | null` - Parent state node
+- `node: StateNode` - Current state node
+
+**Example:**
+
+```typescript
+import { crawlMachine } from "@xmachines/play-router";
+
+const visits = crawlMachine(machine);
+visits.forEach((visit) => {
+	console.log("State:", visit.path.join("."));
+	console.log("Parent:", visit.parent?.id ?? "root");
+});
+```
+
+### Query Utilities
+
+```typescript
+// Get child routes from state
+const children = getNavigableRoutes(tree, "dashboard");
+
+// Check if route exists
+const exists = routeExists(tree, "/profile/:userId");
+```
+
+**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-router)
+
+## Examples
+
+### Route Detection
+
+```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)
+```
+
+## Route Configuration
+
+### Route Pattern (Recommended)
+
+```typescript
+states: {
+	dashboard: {
+		id: "dashboard", // Required for bidirectional lookup
+		meta: {
+			route: "/dashboard", // URL path - marks state as routable
+		},
+	},
+}
+```
+
+### Alternative Pattern
+
+```typescript
+states: {
+	dashboard: {
+		id: "dashboard",
+		meta: {
+			route: "/dashboard",
+		},
+	},
+}
+```
+
+### Route Inheritance
+
+```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"
+			},
+		},
+	},
+}
+```
+
+### Dynamic Parameters
+
+```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).
+
+## Architecture
+
+This package enables **Actor Authority (INV-01)**:
+
+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
+
+**Enhancements:**
+
+- `meta.route` detection via state metadata
+- Pattern matching for dynamic routes (`:param` and `:param?`)
+- State ID ↔ path bidirectional maps for `play.route` events
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate)** - XState adapter using route extraction
+- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router)** - TanStack Router adapter using route trees
+- **[@xmachines/play-react-router](../play-react-router)** - React Router v7 adapter using RouterBridgeBase
+- **[@xmachines/play](../play)** - Protocol types
+
+## License
+
+MIT

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}