@xmachines/docs 6.0.0 → 7.0.0

package/guides/getting-started.md

@@ -102,13 +102,13 @@ The test suite relies on TypeScript path aliases that resolve to source files. I
 
 #### TypeScript errors about missing types after adding a dependency
 
-Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
+Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, declare it in the `package.json` of the package with a `workspace:*` range. The root `tsconfig.json` holds the build order, and `tests/tsconfig-reference-graph.test.ts` fails when that order misses the new edge.
 
 #### Lint errors about import extensions
 
 All TypeScript imports must end with `.js`, even for `.ts` source files:
 
-```typescript
+```typescript fragment
 // ✅ Correct
 import { PlayError } from "./errors.js";
 
@@ -154,9 +154,11 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 Every XMachines application needs these six packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core@0.21.0-xm.6
 ```
 
+The json-render packages are exact peers: install the version that this release names, `0.21.0-xm.6`.
+
 | Package                                                             | Role                                                                                                                                                                                                                                                                       |
 | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
@@ -208,7 +210,6 @@ const appSetup = setup({
 	types: {
 		context: {} as { count: number },
 		events: {} as { type: "toggle" },
-		input: {} as undefined,
 	},
 });
 
@@ -272,6 +273,10 @@ release:
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine>; // the actor of the example above
 
 const stop = watchAtom(actor.state, (snapshot) => {
 	console.log("the machine is now:", snapshot.value);
@@ -296,7 +301,7 @@ A renderer needs none of this: [`@xmachines/play-react`](../api/@xmachines/play-
 and the other renderers observe `currentView` for you. Reach for `watchAtom` when you
 write infrastructure, or a debug panel beside the UI.
 
-[Understanding Atoms](atoms.md) states the whole model.
+[Atoms](atoms.md) states the whole model.
 
 ---
 
@@ -325,7 +330,6 @@ const appSetup = setup({
 		},
 		events: {} as
 			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
 	},
 });
 
@@ -412,16 +416,27 @@ Used with framework-integrated routers like TanStack Router. All three props (`a
 
 ```tsx
 // React + TanStack Router example
-import { useMemo, useEffect } from "react";
+import { useMemo, useEffect, type ReactNode } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
+declare function Shell(props: { actor: typeof actor }): ReactNode; // your layout
+
 // Build OUTSIDE of JSX — must be stable references
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const router = createRouter({ routeTree: createRootRoute() });
 
 // Actor also created outside the component (or memoized inside)
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -448,12 +463,21 @@ Used with framework-agnostic or server-rendered routers. `connectRouter` handles
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
 import { createRouteMapFromTree } from "@xmachines/play-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
 
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -483,6 +507,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-re
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-react";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -501,7 +529,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -548,7 +578,9 @@ function App() {
 			Login: { template: `<button @click="on('submit').emit()">Log in</button>` },
 		},
 		actions: {
-			login: async ({ username }) => actor.send({ type: "auth.login", username }),
+			login: async (params) => {
+				if (params) actor.send({ type: "auth.login", username: params.username });
+			},
 			logout: async () => actor.send({ type: "auth.logout" }),
 		},
 	});
@@ -562,6 +594,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-so
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-solid";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -580,7 +616,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -601,6 +639,10 @@ import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -631,7 +673,9 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ on }) => {
 const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -658,7 +702,7 @@ nothing is needed — the generated transitions assign `event.query` to context
 on every navigation. A machine that handles `play.route` by hand must do that
 assignment itself:
 
-```typescript
+```typescript fragment
 on: {
   "play.route": {
     actions: assign({
@@ -669,18 +713,13 @@ on: {
 }
 ```
 
-(Older releases threw `MissingQueryContextError` at construction for a
-routing-aware context without a `query` field. That class is gone: the generated
-`play.route` transitions assign `query` on every navigation, so the loss it
-guarded against cannot happen.)
-
 #### Missing `id` on routable states
 
 **Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
 
 **Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-```typescript
+```typescript fragment
 // ❌ Missing id
 home: { meta: { route: "/" } }
 
@@ -695,6 +734,12 @@ home: { id: "home", meta: { route: "/" } }
 **Fix:** Always call `actor.start()` before `actor.send()`:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start(); // required before any send()
 actor.send({ type: "toggle" });
@@ -706,7 +751,7 @@ actor.send({ type: "toggle" });
 
 **Fix:** Construct stable references outside JSX or memoize them:
 
-```typescript
+```typescript fragment
 // ✅ Built outside the component
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -751,6 +796,7 @@ node --version
 
 ## Next Steps
 
+- **[Views](views.md)** — Which state supplies the view, the `/context` projection, and when a renderer keeps the UI
 - **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector to see the machine, its transitions, and its context live
 - **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/guides/inspector.md

@@ -27,7 +27,9 @@ Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import { appMachine } from "./machine.js";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
 
 const { inspect } = createBrowserInspector();
 
@@ -45,6 +47,12 @@ actor.start();
 That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+declare const sink: { write(event: InspectionEvent): void }; // your log
+
 // Function form — the common case
 definePlayer({ machine, options: { inspect: (event) => console.log(event.type) } });
 
@@ -61,6 +69,13 @@ Two properties of the attachment point matter in practice.
 **It is configured on the factory, not on the instance.** `definePlayer({ machine, options })` returns a factory; `options.inspect` belongs to that configuration, and every actor the factory creates reports to the same observer. The factory's per-call options bag carries `snapshot` for restoring persisted state and nothing else — there is no per-instance `inspect` override. When one factory produces several live actors (multi-user scenarios, SSR, tests), demultiplex the stream by root instead:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const inspect = (event: InspectionEvent) => console.log(event.type);
+
 const createPlayer = definePlayer({ machine, options: { inspect } });
 
 const alice = createPlayer({ userId: "alice" });
@@ -87,7 +102,7 @@ The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.
 
 `@xstate.actor` fires from _inside_ the actor's constructor. The `actorRef` it carries is a real `PlayerActor`, but a mid-construction one: `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet, and reading them there throws — XState itself refuses to read a snapshot in that window.
 
-```typescript
+```typescript fragment
 const inspect = (event: InspectionEvent) => {
 	if (event.type === "@xstate.actor") {
 		// ❌ throws — the atoms are not assigned yet
@@ -109,11 +124,17 @@ Capture the reference during construction if you need it, and read the atoms fro
 An inspector that is only created when the user asks for it — a dev-tools toggle, a keyboard shortcut, a debug panel button — cannot be passed to `definePlayer`, which ran at module scope long before the click. Pass a forwarding function instead, so the attachment point is fixed at factory time while the destination stays swappable:
 
 ```typescript
-let current: ((event: InspectionEvent) => void) | undefined;
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent, Observer } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+let current: Observer<InspectionEvent> | undefined;
 
 const createPlayer = definePlayer({
 	machine: appMachine,
-	options: { inspect: (event) => current?.(event) },
+	options: { inspect: (event) => current?.next?.(event) },
 });
 
 // Later, from a click handler
@@ -135,6 +156,10 @@ There is a catch worth knowing before you ship it: events that arrive while `cur
 
 ```typescript
 import { createWebSocketInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
 
 const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
 
@@ -155,22 +180,49 @@ pnpm --filter @xmachines/play-react-demo run dev
 
 Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you log in, navigate, and log out.
 
-The demos share one controller, `createDemoInspector()` from `@xmachines/play-actor-shared`, which each demo passes straight through to `definePlayer`:
+The demos share one controller, `createDemoInspector()`, which each demo passes straight through to `definePlayer`. The controller lives in a private package of this repository, so you cannot install it. The block below shows the same wiring with the public API. It keeps each event from the creation of the actor, and it replays the events when the user opens the inspector:
 
 ```typescript
-const inspector = createDemoInspector();
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent, Observer } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+const buffer: InspectionEvent[] = [];
+let current: Observer<InspectionEvent> | undefined;
 
 const actor = definePlayer({
-	machine: authMachine,
-	options: { inspect: inspector.inspect },
+	machine: appMachine,
+	options: {
+		inspect: (event) => {
+			if (current) {
+				current.next?.(event);
+				return;
+			}
+			// Keep the last 500 events while nobody opens the inspector. A long session drops
+			// its oldest events, also the registration of the root actor, and the inspector
+			// then has no machine to draw. The demo controller pins each registration for
+			// that reason, and it costs more code.
+			buffer.push(event);
+			if (buffer.length > 500) buffer.shift();
+		},
+	},
 })();
 actor.start();
 
-// The debug panel's button
-<button onClick={() => inspector.show()}>Show Inspector</button>;
+// The click handler of the "Show Inspector" button of the debug panel
+export function showInspector() {
+	if (current) return;
+	// The inspector holds these events until its window connects, and it drops the oldest
+	// past `maxDeferredEvents`. The limit leaves room for the events of the handshake, so
+	// the inspector keeps every event of the replay.
+	current = createBrowserInspector({ maxDeferredEvents: 1000 }).inspect;
+	for (const event of buffer.splice(0)) current.next?.(event);
+}
 ```
 
-The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the registration of every live root so it can never roll out of the bounded buffer, and flushes those buffers when the inspector window completes its handshake. Several machines can be alive together — one for each document a host has open — and the handshake replays each of them. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
+The demo controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the registration of every live root so it can never roll out of the bounded buffer, and flushes those buffers when the inspector window completes its handshake. Several machines can be alive together — one for each document a host has open — and the handshake replays each of them. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
 
 ---
 
@@ -179,6 +231,14 @@ The controller answers the late-opening problem from the previous section: it bu
 **Cost.** Inspection serializes events. A `console.log` observer is cheap; a browser inspector posting every transition, and any buffering scheme layered on top, is not. Gate the inspector behind a development-only branch, and prefer letting the bundler drop it entirely:
 
 ```typescript
+/// <reference types="vite/client" />
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+// `import.meta.env.DEV` is the development flag of Vite
 const options = import.meta.env.DEV ? { inspect: createBrowserInspector().inspect } : {};
 
 const createPlayer = definePlayer({ machine: appMachine, options });
@@ -192,6 +252,6 @@ const createPlayer = definePlayer({ machine: appMachine, options });
 
 - **[`PlayerOptions`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
 - **[`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)** — the actor an inspector observes
-- **[Understanding the Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
+- **[The Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
 - **[Getting Started](getting-started.md)** — installing packages and creating your first actor
 - **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options

package/guides/routing.md

@@ -1,8 +1,8 @@
-# Understanding Routing in XMachines
+# Routing in XMachines
 
 A route of XMachines is a fact about a STATE, and not a fact about a component tree. A state node declares `meta.route`, and the library carries that declaration in both directions: a URL becomes a state, and a state becomes a URL.
 
-This guide states the pattern language one time, and it names the three rules that every one of the nine router adapters follows.
+This guide states the pattern language one time, it tells when a navigation re-enters a state, and it names the three rules that every one of the nine router adapters follows.
 
 After you read it, you know which patterns a route can declare, which side resolves a location, and why a bridge comes in a `connect()` and `disconnect()` pair.
 
@@ -19,13 +19,13 @@ The first direction needs a matcher, and every router writes its own. Express us
 
 `URLPattern` is the WHATWG standard for this, its syntax comes from `path-to-regexp`, and it is a superset of it. XMachines takes it as the pattern language, and it reads the whole of it.
 
-This is the same decision that [`@xmachines/play-atom`](atoms.md) makes for reactivity: one primitive, isolated behind one module, present on every runtime. There is no `AtomsUnavailableError`, because one package holds the reactive primitive and every consumer reads it from there, and there is no URLPattern availability error for the same reason.
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) makes the same decision for reactivity: one primitive, isolated behind one module, present on every runtime. The [Atoms](atoms.md) guide describes it.
 
 ### The API is always present
 
-[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
+[`@xmachines/play-url`](../api/@xmachines/play-url/README.md) carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
 
-The native API arrived in Chrome 95, in Firefox 142 and in Safari 26. The browser floor of this workspace is Chrome 110, Firefox 115 and Safari 16.4. Chrome carries the API at that floor, and Firefox and Safari carry it far above it, so a Firefox or a Safari at the floor runs the polyfill. `test/url-pattern-parity.test.ts` measures the two implementations against each other, form by form. They agree on every form of the grammar, and they disagree about one shape that no bridge can produce — see the prefix rule below.
+The native API arrived in Chrome 95, in Firefox 142 and in Safari 26. The browser floor of XMachines is Chrome 110, Firefox 115 and Safari 16.4. Chrome carries the API at that floor, and Firefox and Safari carry it far above it, so a Firefox or a Safari at the floor runs the polyfill. The test suite of [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) measures the two implementations against each other, form by form. They agree on every form of the grammar, and they disagree about one shape that no bridge can produce — see the prefix rule below.
 
 The cost is 18 kB, minified and with no dependency of its own, and a consumer whose runtime has the native API pays it too. A conditional load would save those bytes and it would make the module asynchronous: `RouteMap` compiles in its constructor, and a navigation matches inside an event handler. Neither can await.
 
@@ -55,8 +55,11 @@ A **modifier** follows a param, a wildcard or a group:
 | `*`      | zero or more | matches                  |
 
 ```ts
+import { createMachine } from "xstate";
+
 const machine = createMachine({
 	id: "app",
+	initial: "home",
 	states: {
 		home: { meta: { route: "/" } },
 		profile: { meta: { route: "/profile/:userId" } },
@@ -116,12 +119,6 @@ The build resolves every escape, so the derived path carries the character and n
 backslash that protects it. `/tags/c\+\+` derives `/tags/c++`, which is the path that the
 route matches.
 
-**An escaped `:` is the one escape that stops at the bridge.** The build derives
-`/time/10:30` for `/time/10\:30`, and the route matches that path — but a bridge refuses
-to push a path that holds a `:`, because a `:` in a CONCRETE path marks a param that
-nothing substituted. `resolveNavigationPath` therefore answers `null`, and the address bar
-follows that state never. Write `%3A` instead, as the section below prescribes.
-
 ### A literal that the grammar would read
 
 `:`, `+`, `?`, `(` and `{` are characters of the grammar, so a route that writes one of them raw does not mean the literal. The two halves fail differently.
@@ -148,25 +145,7 @@ This rule is about the PATTERN that a state declares. A param VALUE needs no esc
 
 `encodeURIComponent` leaves `*` as it stands, and that is the one exception. A bridge refuses a path that still holds a `:` or a `*`, because such a character marks a param that nothing substituted. A value of `a*b` therefore stops the push, and the URL stays where it is.
 
-**This is a change of behaviour, and a route of yours can hold one of these characters today.** An earlier release read a route as a pattern only when the route held a `:` or a `*`. `/tags/c++`, `/docs/rfc(2119)` and `/i18n/{en}` therefore went to the exact-match map, and each one matched the path that its author wrote. The route map reads the whole grammar now. `/tags/c++` throws `InvalidRoutePatternError` in the constructor of `RouteMap`, and the other two compile and match another path in silence. Add the escape to each route that writes one of these characters raw.
-
-A route that carries a QUERY STRING is the same case, and it is the form a machine writes most often. `meta: { route: "/dates?trip=one-way" }` reached the exact-match map before, and the bridge pushed it to the address bar with its query. The grammar reads that `?` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor now and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition assigns and `buildRouteUrl` writes to the URL.
-
-### Upgrading from 3.x: the `reenter` default changed
-
-An earlier release wrote `reenter: true` on every transition that `formatPlayRouteTransitions` generated, so every routed state re-entered its own domain on each navigation and ran its `entry` actions again. The flag now comes from `meta.route`, and the default is `false`, which is the default of XState.
-
-**Nothing throws, and the `entry` action simply stops running.** A state that needs it declares the flag for itself:
-
-```ts
-states: {
-	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
-},
-```
-
-`reenter` spares the DOMAIN of the transition and not every ancestor that stays active. Under the default `handler: "root"` the domain is the root of the machine, so `false` spares the root alone and each ancestor between the root and the target still runs its `exit` and `entry` actions. `handler: "local"` and `handler: "both"` move the domain down to the parent, which is the field that spares those intermediate ancestors.
-
-CAUTION: `"local"` also SCOPES the route. The generated transition then sits on the parent alone, so a `play.route` event that arrives while the parent is inactive matches nothing and the actor does not move — a deep link or a press on BACK therefore leaves the URL and the actor divergent. Choose `"local"` where that scope is the intent, such as a step that a person reaches only inside its wizard. Choose `"both"` where the state must stay reachable from everywhere.
+A route that carries a QUERY STRING is the same case as a raw `?`, and it is the form a machine writes most often. The grammar reads the `?` of `meta: { route: "/dates?trip=one-way" }` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition assigns and `buildRouteUrl` writes to the URL.
 
 ### The prefix rule
 
@@ -196,6 +175,28 @@ The cost is that you cannot write URLPattern's own reading of `:cat-id`. Use `:c
 
 ---
 
+## Re-entry on a navigation
+
+`formatPlayRouteTransitions` reads the `reenter` flag of each transition from `meta.route`. The default is `false`, which is the default of XState.
+
+The flag decides one thing: whether the DOMAIN of the transition runs its `exit` and `entry` actions again. Under the default `handler: "root"` the domain is the root of the machine. `"local"` and `"both"` put a transition on the parent, and while the parent is active that transition answers the event, so the domain is the parent.
+
+Each state below the domain on the path to the target runs its `exit` and `entry` actions on each navigation, whatever the flag says. The target itself is one of them, unless the route targets the root of the machine: the root is then the domain, and the flag decides. Under `"root"`, `false` therefore spares the root alone, and each ancestor between the root and the target runs its actions again. `handler` is the field that spares those intermediate ancestors.
+
+CAUTION: a parallel state loses the position of its other regions when it is the domain or a state below the domain. XState exits each active state below the domain, and not only the states on the path to the target. Each other region therefore enters its `initial` state again. A parallel root under `handler: "root"` is such a domain. With `reenter: true`, a `"local"` or `"both"` transition also exits the parent. Where the parent is a region of a parallel state, the other regions of that state enter their `initial` state again too.
+
+A state whose navigation must re-enter the domain too declares the flag for itself. Here the root runs its `exit` and `entry` actions on each navigation to `dashboard`:
+
+```ts fragment
+states: {
+	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
+},
+```
+
+CAUTION: `"local"` also SCOPES the route. The generated transition then sits on the parent alone, so a `play.route` event that arrives while the parent is inactive matches nothing and the actor does not move — a deep link or a press on BACK therefore leaves the URL and the actor divergent. Choose `"local"` where that scope is the intent, such as a step that a person reaches only inside its wizard. Choose `"both"` where the state must stay reachable from everywhere.
+
+---
+
 ## The routing invariants
 
 ### 1. XMachines resolves the state id. The router never does
@@ -234,31 +235,29 @@ A bridge installs an atom subscription on the actor and a subscription on the ro
 
 ---
 
-## Why not a matcher of our own
-
-The 2.2.0 review asked whether a hand-written segment matcher could drop the `URLPattern` requirement. The answer is no, and the reason is not the size of the code.
+## Why not a smaller matcher
 
-A pattern language has to carry the largest set of features that the nine target routers can express, and not the subset that this repository happens to use today. A count of the patterns HERE — 85 of 88 are a literal plus `:name` — measures our own habits, and it is the wrong basis for the decision. `URLPattern` is the most expressive engine available, and a matcher of our own would carry less.
+A matcher that reads only a literal and `:name` covers most routes. It carries fewer features than the routers that XMachines supports, which is the problem that [the first section](#what-problem-urlpattern-solves) describes.
 
-Two matchers that disagree is also a worse failure than one dependency. The match and the extraction of the params would then read the same pattern differently, and a route would resolve while its params came back empty.
+One engine also keeps the match and the params in agreement. With two matchers, a route could resolve while its params came back empty.
 
 ---
 
 ## Summary
 
-| Question                                  | Answer                                                                              |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- |
-| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names                      |
-| Do I install a polyfill?                  | No. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries one |
-| Which side turns a URL into a state?      | XMachines, in every adapter                                                         |
-| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                                                |
-| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name                     |
-| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component                       |
+| Question                                  | Answer                                                                        |
+| ----------------------------------------- | ----------------------------------------------------------------------------- |
+| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names                |
+| Do I install a polyfill?                  | No. [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) carries one |
+| Which side turns a URL into a state?      | XMachines, in every adapter                                                   |
+| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                                          |
+| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name               |
+| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component                 |
 
 ## See also
 
-- [Understanding State Machines](state-machines.md) — how `meta.route` reaches the route map
-- [Understanding Atoms](atoms.md) — the same decision, made for reactivity
+- [State Machines](state-machines.md) — how `meta.route` reaches the route map
+- [Atoms](atoms.md) — the same decision, made for reactivity
 - [Multi-router integration](../examples/multi-router-integration.md) — the provider pattern and `basePath`, end to end
 - [Routing patterns](../examples/routing-patterns.md) — worked route maps
 - [@xmachines/play-router](../api/@xmachines/play-router/README.md) — API reference