@xmachines/docs 2.2.0 → 4.0.0

package/contributing/testing.md

@@ -4,21 +4,45 @@ This document describes the test framework, conventions, and CI integration for
 
 ## Test Framework and Setup
 
-The monorepo uses **[Vitest](https://vitest.dev/) `^4.1.5`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
+The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.1`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
 
 All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
 
 - `@xmachines/*` source aliases so imports resolve to source during test runs
 - `@xmachines/shared/vitest-setup` — extends Vitest matchers with `@testing-library/jest-dom`
-- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 22 on non-browser projects
+- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 24 on non-browser projects
 
 **Auto-injected setup files:**
 
 | File                                          | When injected            | Purpose                                                 |
 | --------------------------------------------- | ------------------------ | ------------------------------------------------------- |
-| `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 22 runtime; throws if wrong runtime |
+| `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 24 runtime; throws if wrong runtime |
 | `packages/shared/config/vitest.setup.ts`      | All projects             | Imports `@testing-library/jest-dom/vitest` matchers     |
 
+`vitest.setup.ts` is also the one file that `@xmachines/shared/tsconfig-test` names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
+
+### The jest-dom patch
+
+`patches/@testing-library__jest-dom@7.0.1.patch` moves the matcher declaration of the library from `Assertion` to `Matchers`. The library declares this:
+
+```ts
+declare module "vitest" {
+	interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
+}
+```
+
+Vitest 5 declares `interface Assertion<R extends void | Promise<void> = void, T = unknown>`. A module augmentation merges only when the type parameters are IDENTICAL, and TypeScript reports nothing when they differ — it simply does not apply. Every matcher therefore left the type of `expect(...)` while the runtime kept working. `Matchers` is the interface that vitest publishes for an extension, and `Assertion` extends it, so the patched declaration reaches every assertion and restates no interface whose shape vitest owns.
+
+Delete the patch, its `patchedDependencies` entry in `pnpm-workspace.yaml`, and `tests/jest-dom-augmentation.test.ts` on the day the library ships a declaration that vitest 5 accepts. See [testing-library/jest-dom#738](https://github.com/testing-library/jest-dom/issues/738).
+
+### The vitest mocker patch
+
+`patches/@vitest__mocker@5.0.1.patch` takes the `configureServer` hook off `vitest:mocks:interceptor` when the caller passes `registerWebSocketEvents: false`, which is how `@vitest/browser` calls it.
+
+Vitest returns that plugin from the `applyToEnvironment` of another plugin, and Vite 8 ignores a `configureServer` that it finds there. Vite reports the fact one time for each environment, so a run of 29 projects wrote 29 lines, in the `test` job and in the `test:browser` job both. The hook returns at once for `registerWebSocketEvents: false`, so the omission changes no behaviour.
+
+Delete the patch and its `patchedDependencies` entry when vitest ships the fix. See [vitest-dev/vitest#11276](https://github.com/vitest-dev/vitest/issues/11276).
+
 Before running any tests, ensure all dependencies are installed:
 
 ```bash
@@ -33,7 +57,7 @@ pnpm install --frozen-lockfile
 pnpm test
 ```
 
-Runs `vitest run` across every project that the root `vitest.config.ts` collects — 36 of them today: one for each package, one for each demo that holds node tests, and `infrastructure` for the repository tests in `tests/`. Uses the `forks` pool (up to 4 workers) with process-level isolation between test files.
+Runs `vitest run` across every project that the root `vitest.config.ts` collects — 38 of them today: one for each package, one for each demo that holds node tests, and `infrastructure` for the repository tests in `tests/`. A node project uses the `forks` pool (up to 4 workers) and reuses a worker across test files — see [Isolation](#isolation). A jsdom project uses the `vmThreads` pool — see [Test environments](#test-environments).
 
 The root config finds those projects by glob, so a new package or demo joins the run with no edit. Each test file must belong to **one** project: a package config that reaches into its own `examples/` collects the demo tests that the demo config collects already, and the run then executes them two times, under two different environments. `tests/project-collection-overlap.test.ts` asks Vitest for the whole collection and fails on any file that two projects claim.
 
@@ -82,7 +106,7 @@ Individual packages may enforce higher per-package thresholds in their own `vite
 pnpm run test:build
 ```
 
-Runs `tsc --build tsconfig.test.json --force`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles `.typecheck.ts` files in `src/` directories.
+Runs `tsc --build tsconfig.test.json --force`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles the `.typecheck.ts` files of the `test/` directories.
 
 This is the command that answers "does this tree type-check?". Use it rather than `pnpm run build` for that question. `tsc --build` skips a project whose dependencies have unchanged `.d.ts` files, so an error inside the source of a library that changes no exported declaration can leave every consumer of that library up to date and never be reported — and consumers here compile library **source**, through the `source` export condition. `--force` costs about a second and takes that decision away from tsc; `tests/typecheck-staleness.test.ts` holds it, and the two other properties the complete check rests on, in place: no project of the gate is `composite`, and the CI job starts with no build state on disk. The job gets that second property by DELETING every `*.tsbuildinfo` before it runs the gate. It does not inherit it: most of the caching of the pipeline arrives through the included node component, and no test in this repository can read that component's cache paths, so a claim about them would be prose that nothing verifies.
 
@@ -133,11 +157,38 @@ packages/<name>/
 | `jsdom`                       | UI renderers: `@xmachines/play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`                 |
 | Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                        |
 
+`defineXmVitestConfig` gives a jsdom project the `vmThreads` pool. The `forks` pool builds one jsdom for each test file, and a jsdom costs about 0.4 s. The `vmThreads` pool gives each file its own VM context in a worker that keeps the environment, so a worker builds one jsdom for all the files that it runs. Each file still gets a fresh module registry and fresh globals. The full `pnpm test` run takes 94 s with `vmThreads` and 160 s with `forks`, and the environment share of the tracked time drops from 42% to 14%.
+
+A project that declares its own `pool` keeps it.
+
+### Isolation
+
+`defineXmVitestConfig` gives a node project `isolate: false`, and it keeps isolation for a jsdom project, for a browser project, and for a project that declares `environmentMatchGlobs`.
+
+Isolation gives each test FILE its own worker: Vitest spawns a process, builds the environment, and evaluates the module graph one more time. That costs about 110 ms for each file, and the full `pnpm test` run takes 90 s with isolation on every project and 62 s with this rule.
+
+A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three `@xmachines/play-react` tests fail under it.
+
+A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. `@xmachines/play-router` showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
+
+**A project whose test files call `vi.mock`, `vi.doMock`, `vi.stubGlobal`, or `vi.stubEnv` declares `isolate: true` in its own `vitest.config.ts`, with the reason.** `tests/isolate-policy.test.ts` holds this rule true: it asks `vitest list` which project collects which file, reads `isolate` from the config module, and names the file and the config when the two disagree. The scan follows the relative imports of each test file and reads the setup files of the project, so a fixture that mocks a module cannot hide, and it reads each `@vitest-environment` docblock, which reaches no config. Two projects declare it today: the `play-sveltekit-router` demo, which mocks `$app/navigation`, and the `play-actor` shared example, which stubs `window`.
+
+Prefer the other answer where you can reach it. A test that builds the real collaborator needs no isolation, and it costs the whole project nothing.
+
+A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. `@xmachines/play-react-router` runs three React files that way.
+
+A spy needs no isolation, and neither do fake timers. Each patches something that the test itself owns and restores, and neither depends on a fresh module registry.
+
+To check a project that you move off isolation, run the suite with a shuffled file order — the same check that `vitest doctor` applies:
+
+```bash
+pnpm exec vitest run --sequence.shuffle.files
+```
+
 ### Test helpers and shared setup
 
 - **`@xmachines/shared/vitest-setup`** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
-- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 22 at runtime. Auto-injected for non-browser configs.
-- **`@xmachines/shared/vitest-urlpattern-setup`** — Polyfills `URLPattern` for packages that need it (e.g. `@xmachines/play-router`). Must be declared explicitly in `setupFiles`.
+- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
 - **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
 - **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
 
@@ -211,7 +262,7 @@ describe("ClassName or functionName()", () => {
 **Import style:** Always use `.js` extensions in imports (ESM requirement):
 
 ```typescript
-import { AbstractActor } from "../src/abstract-actor.js";
+import { PlayActor } from "../src/abstract-actor.js";
 import { Signal } from "@xmachines/play-signals";
 ```
 
@@ -235,16 +286,13 @@ afterEach(() => {
 - **Framework router objects** (TanStack Router, Vue Router, React Router, SolidJS Router) — mock with typed `vi.fn()` interfaces because they are external framework dependencies and carry significant setup complexity:
 
     ```typescript
-    const mocks = vi.hoisted(() => ({
-    	machineToGraph: vi.fn(),
-    	buildRouteTree: vi.fn(),
-    }));
-
-    vi.mock("../src/machine-to-graph.js", () => ({
-    	machineToGraph: mocks.machineToGraph,
-    }));
+    const mocks = vi.hoisted(() => ({ goto: vi.fn() }));
+
+    vi.mock("$app/navigation", () => ({ goto: mocks.goto }));
     ```
 
+    A mock of a module costs the WHOLE project its isolation — see [Isolation](#isolation). Mock the framework module, and not a module of the package under test: a test that builds the real collaborator is both cheaper and stronger.
+
 - **`console.warn` / `console.error`** when testing code that legitimately emits warnings — mock to suppress noise and assert call counts:
 
     ```typescript
@@ -264,22 +312,20 @@ afterEach(() => {
 
 ### Test actor patterns
 
-**Preferred: extend `AbstractActor` for full type safety:**
+**Preferred: extend `PlayActor` for full type safety:**
 
 ```typescript
-import { AbstractActor } from "@xmachines/play-actor";
-import type { Routable } from "@xmachines/play-actor";
+import { PlayActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
-import type { AnyActorLogic } from "xstate";
 
-class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
-	override state = new Signal.State({} as unknown);
+class MockActor implements PlayActor, Routable {
+	readonly state = new Signal.State({} as unknown);
 	private _routeState: Signal.State<string | null>;
 	readonly currentRoute: Signal.Computed<string | null>;
 	readonly initialRoute: string | null;
 
 	constructor(startRoute: string | null = "/") {
-		super({} as AnyActorLogic, {}); // {} as AnyActorLogic is the standard stub
 		this._routeState = new Signal.State<string | null>(startRoute);
 		this.currentRoute = new Signal.Computed(() => this._routeState.get());
 		this.initialRoute = startRoute;
@@ -297,7 +343,7 @@ class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
 import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
-	return stubOf<AbstractActor<AnyActorLogic> & Viewable>({
+	return stubOf<ViewActor>({
 		currentView: new Signal.State<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
@@ -365,10 +411,10 @@ const bad: PlaySpec = typedSpec({
 expect(bad.root).toBe("root");
 ```
 
-For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `src/`:
+For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `test/`:
 
 ```typescript
-// packages/play-xstate/src/define-player.typecheck.ts
+// packages/play-xstate/test/define-player.typecheck.ts
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type AssertFalse<T extends false> = T;
 
@@ -400,6 +446,17 @@ try {
 }
 ```
 
+### An expected report in the log
+
+A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and `@xmachines/play-solid` writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
+
+Claim the report in the test that expects it, and assert it:
+
+- **React.** Take `render` from `test/test-utils.js` of `@xmachines/play-react`, and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
+- **Any framework.** Call `vi.spyOn(console, "error").mockImplementation(() => {})` before the render, and `expect(spy).toHaveBeenCalled()` after it. An `afterEach` with `vi.restoreAllMocks()` returns the console to the next test.
+
+A report that a spy swallows and no assertion reads is worse than the noise, because it hides the day that the renderer stops to report.
+
 ## Contract Tests
 
 The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in `@xmachines/play-router`) because the suite drives a real actor via `@xmachines/play-xstate` and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps `@xmachines/play-router` free of any dependency on the actor runtime:
@@ -448,11 +505,13 @@ Coverage is collected using the **v8** provider. The root `vitest.config.ts` def
 
 Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
 
-| Package tier                                                               | Lines | Functions | Branches | Statements |
-| -------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
-| Core packages (`@xmachines/play`, `@xmachines/play-actor`)                 | 90%   | 90%       | 85%      | 90%        |
-| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)         | 85%   | 85%       | 80%      | 85%        |
-| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`) | 80%   | 80%       | 80%      | 80%        |
+| Package tier                                                                       | Lines | Functions | Branches | Statements |
+| ---------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
+| Core packages (`@xmachines/play`, `@xmachines/play-actor`, `@xmachines/play-view`) | 90%   | 90%       | 85%      | 90%        |
+| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)                 | 85%   | 85%       | 80%      | 85%        |
+| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`)         | 80%   | 80%       | 80%      | 80%        |
+
+`@xmachines/play-router` carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
 
 Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
 

package/examples/README.md

@@ -76,12 +76,14 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 
 ### Core
 
-| Package                                                               | Role                                                        |
-| --------------------------------------------------------------------- | ----------------------------------------------------------- |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | `AbstractActor`, `typedSpec`                                |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill, `watchSignal`                        |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)   | `extractMachineRoutes`, `getRoutableRoutes`                 |
+| Package                                                                    | Role                                                        |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)        | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)          | `PlayActor`                                                 |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `typedSpec`                         |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)      | TC39 Signals polyfill, `watchSignal`                        |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)        | `RouterBridgeBase`, `RouteMap`, `Routable`                  |
+| [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) | `extractMachineRoutes`, `getRoutableRoutes`                 |
 
 ### Renderers
 
@@ -98,7 +100,7 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 | Package                                                                                           | Router                  |
 | ------------------------------------------------------------------------------------------------- | ----------------------- |
 | [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla browser history |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router v7         |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8        |
 | [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack Router (React) |
 | [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router          |
 | [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Router (Solid) |

package/examples/form-validation.md

@@ -15,7 +15,8 @@ This example mirrors the `authMachine` login pattern: a form state with a local
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 // Context shape
 interface LoginContext {
@@ -304,5 +305,5 @@ window.addEventListener("beforeunload", () => {
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
-- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
+- **[`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/examples/multi-router-integration.md

@@ -25,12 +25,13 @@ Used by framework adapters that have a React/Solid/Vue provider context. The `Pl
 import { useEffect, useMemo } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { defineRegistry } from "@xmachines/play-react";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 const { registry } = defineRegistry(authCatalog, {
   components: { /* ...your components */ },
@@ -66,15 +67,16 @@ export function App() {
 }
 ```
 
-### React + React Router v7 (`@xmachines/play-react-router`)
+### React + React Router 7/8 (`@xmachines/play-react-router`)
 
 ```typescript
 import { createBrowserRouter, RouterProvider } from "react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 function createAppRuntime() {
   const actor = createPlayer();
@@ -116,11 +118,13 @@ export default function App() {
 ```typescript
 import { Router, Route } from "@solidjs/router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -164,11 +168,13 @@ export default function App() {
 ```typescript
 import { createRouter, createRootRoute, createRoute, RouterProvider } from "@tanstack/solid-router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -222,7 +228,8 @@ export default function App() {
 <script setup lang="ts">
 	import { h, inject } from "vue";
 	import { createRouter, createWebHistory } from "vue-router";
-	import { PlayRouterProvider, createRouteMap } from "@xmachines/play-vue-router";
+	import { PlayRouterProvider } from "@xmachines/play-vue-router";
+	import { createRouteMap } from "@xmachines/play-router/xstate";
 	import { defineRegistry } from "@xmachines/play-vue";
 	import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
@@ -258,18 +265,20 @@ Used by vanilla DOM and Svelte adapters. Call `connectRouter` directly after cre
 ### Vanilla DOM (`@xmachines/play-dom-router`)
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { createPlayUI, defineRegistry } from "@xmachines/play-dom";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+// The router needs `withRouting`, and the renderer below needs `withView`.
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -306,10 +315,15 @@ window.addEventListener("beforeunload", () => {
 // lib/router.ts
 import { defineRegistry } from "@xmachines/play-svelte";
 import { authCatalog, authMachine } from "@xmachines/play-actor-shared";
-import { definePlayer } from "@xmachines/play-xstate";
-import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
-
-const createDemoPlayer = definePlayer({ machine: authMachine });
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { connectRouter } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 const { registry } = defineRegistry(authCatalog, {
 	components: {/* ...your Svelte components */},
@@ -337,11 +351,17 @@ export const disconnectRouter = connectRouter({ actor, routeMap });
 
 ```typescript
 // lib/router.ts — identical pattern to SvelteKit, different import
-import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter } from "@xmachines/play-svelte-spa-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { authMachine } from "@xmachines/play-actor-shared";
 
-const createDemoPlayer = definePlayer({ machine: authMachine });
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 export const actor = createDemoPlayer();
 actor.start();
@@ -446,7 +466,7 @@ An actor never changes identity, so a segment of the prefix that _identifies_ th
 For a host router that declares real route objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
-import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
 
 const tree = extractMachineRoutes(authMachine);
 
@@ -460,7 +480,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 // [{ stateId: "home", path: "/:machineId/play" }, ...]
 ```
 
-> **Polyfill note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. Both adapters therefore need a `URLPattern` polyfill on an older runtime when they are mounted. With no prefix, both keep the parse of their framework whenever it reports at least one
+> **Param note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. With no prefix, both keep the parse of their framework whenever it reports at least one
 > param the pattern declares, and every required one. A pattern whose params are ALL
 > optional and a framework that reports none — `/settings/:section?` under a catch-all of
 > the host — is settled by the PATH: `/settings` is the bare form of that pattern, so
@@ -468,17 +488,19 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > value, such as `/settings/security`, still reaches the extraction, because only the
 > extraction reads that value.
 >
-> These branches decide the CALLS of a navigation, and not whether the application needs
-> the polyfill. `RouteMap` compiles each parameterized route in its constructor and
-> throws there without `URLPattern`, so one `:param` in the route map makes the polyfill
-> a startup requirement on an older runtime.
+> These branches decide the CALLS of a navigation, and never the availability of the API.
+> `@xmachines/play-router` carries `urlpattern-polyfill` as an ordinary dependency and it
+> uses the native `URLPattern` when the runtime has one, so you install no polyfill and
+> you load none. A BAD pattern is a question of the route map: `RouteMap` compiles each
+> parameterized route in its constructor and throws an `InvalidRoutePatternError` there.
+> The [routing guide](../guides/routing.md) states the pattern language.
 
 ## Adapter Summary
 
 | Package                                 | Framework             | Pattern         | Key Import                                                                |
 | --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
 | `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
-| `@xmachines/play-react-router`          | React Router v7       | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| `@xmachines/play-react-router`          | React Router 7/8      | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
 | `@xmachines/play-tanstack-react-router` | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
 | `@xmachines/play-solid-router`          | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
 | `@xmachines/play-tanstack-solid-router` | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |

package/examples/routing-patterns.md

@@ -64,7 +64,8 @@ Instead of hand-writing `play.route` event handlers for every routable state, wr
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
 interface AuthContext {
@@ -108,14 +109,16 @@ const authMachine = authSetup.createMachine(
 ```typescript
 on: {
   "play.route": [
-    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: true, actions: assign({ params, query }) },
-    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: true, actions: assign({ params, query }) },
-    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: true, actions: assign({ params, query }) },
-    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: true, actions: assign({ params, query }) },
+    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: false, actions: assign({ params, query }) },
+    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: false, actions: assign({ params, query }) },
+    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: false, actions: assign({ params, query }) },
+    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
 
+`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state that must re-enter its own domain.
+
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
@@ -204,7 +207,10 @@ const authMachine = authSetup.createMachine(
 ## Complete Actor Usage
 
 ```typescript
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -237,13 +243,8 @@ actor.stop();
 To sync the browser URL with `actor.currentRoute`, use `@xmachines/play-dom-router`:
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
@@ -268,7 +269,7 @@ For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react
 
 ```tsx
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);

package/examples/traffic-light.md

@@ -17,7 +17,9 @@ Applicable patterns:
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
 // 1. Typed setup
 const trafficSetup = setup({
@@ -70,7 +72,10 @@ const trafficMachine = trafficSetup.createMachine(
 );
 
 // 3. Player factory
-const createPlayer = definePlayer({ machine: trafficMachine });
+const createPlayer = definePlayer({
+	machine: trafficMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 
 // 4. Create and start actor
 const actor = createPlayer();
@@ -105,9 +110,9 @@ actor.stop();
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: true, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: true, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: true, actions: assign({ params, query }) },
+    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: false, actions: assign({ params, query }) },
+    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: false, actions: assign({ params, query }) },
+    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
@@ -116,6 +121,7 @@ on: {
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
 - The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
+- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state that must re-enter its own domain.
 
 ## `actor.currentRoute` Signal
 

package/guides/README.md

@@ -12,6 +12,7 @@ Background reading that explains the _why_ behind XMachines design decisions.
 
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
+- **[Understanding Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
 - **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling