@xmachines/docs 3.0.0 → 4.0.0

package/guides/getting-started.md

@@ -18,11 +18,11 @@ Jump to the section that applies to you:
 
 You need the following installed before cloning the repository:
 
-| Requirement | Version            | Notes                                                                                                                                                   |
-| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Node.js     | `>= 24.0.0`        | The floor to DEVELOP. The suite writes `using`, which needs V8 13.4. A published package declares `>= 22.0.0`, and the emitted JavaScript parses there. |
-| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces.                                   |
-| Git         | any recent version | Conventional commit format is enforced by CI                                                                                                            |
+| Requirement | Version            | Notes                                                                                                                 |
+| ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Node.js     | `>= 24.0.0`        | The floor to develop AND to consume. Every `package.json` `engines` field declares it.                                |
+| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces. |
+| Git         | any recent version | Conventional commit format is enforced by CI                                                                          |
 
 No global TypeScript install is needed — it is installed as a dev dependency via `pnpm install --frozen-lockfile`.
 
@@ -140,7 +140,7 @@ This section covers installing XMachines packages into your own application and
 
 ### Prerequisites
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>= 24.0.0`
 - **pnpm** via corepack (`corepack enable`)
 - **TypeScript** `>= 5.7` (strict mode recommended)
 - **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
@@ -157,13 +157,13 @@ Every XMachines application needs these four packages plus XState:
 pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/json-render-core
 ```
 
-| Package                                                               | Role                                                                                                                                                                |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                              | XState v5 state machine engine (peer dependency)                                                                                                                    |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                 |
-| `@xmachines/json-render-core`                                         | Spec and store types the actor layer builds on — a peer of `@xmachines/play-actor`, and of every renderer package                                                   |
+| Package                                                               | Role                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                              | XState v5 state machine engine (peer dependency)                                                                                                                                |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | The actor contract: `PlayActor`, which names no state machine library                                                                                                           |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                             |
+| `@xmachines/json-render-core`                                         | Spec and store types the actor layer builds on — a peer of `@xmachines/play-actor`, and of every renderer package                                                               |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -171,7 +171,7 @@ pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-sig
 # Provider pattern (framework-integrated routers)
 pnpm add @xmachines/play-tanstack-react-router   # TanStack Router (React)
 pnpm add @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
-pnpm add @xmachines/play-react-router            # React Router v7
+pnpm add @xmachines/play-react-router            # React Router 7/8
 pnpm add @xmachines/play-vue-router              # Vue Router 4.x/5.x
 pnpm add @xmachines/play-solid-router            # SolidJS Router
 
@@ -269,11 +269,13 @@ State machines control navigation through `meta.route` on states and `play.route
 
 #### Define a routable machine with `formatPlayRouteTransitions`
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```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";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
 const appSetup = setup({
@@ -328,7 +330,10 @@ const appMachine = appSetup.createMachine(
 	}),
 );
 
-const createPlayer = definePlayer({ machine: appMachine });
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -353,7 +358,7 @@ actor.stop();
 
 **Routing rules:**
 
-- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
+- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
 - Send `play.route` events with `to: "#stateId"` — always use the `id` field prefixed with `#`, never raw URL paths.
 - The machine context **must** include `params: Record<string, string>` and `query: Record<string, string>`.
 - Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
@@ -372,12 +377,8 @@ Used with framework-integrated routers like TanStack Router. All three props (`a
 // React + TanStack Router example
 import { useMemo, useEffect } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import {
-	PlayRouterProvider,
-	extractMachineRoutes,
-	createRouteMapFromTree,
-} from "@xmachines/play-tanstack-react-router";
-
+import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 // Build OUTSIDE of JSX — must be stable references
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -408,7 +409,8 @@ Used with framework-agnostic or server-rendered routers. `connectRouter` handles
 
 ```typescript
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
-import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
@@ -610,7 +612,7 @@ window.addEventListener("beforeunload", () => disconnect());
 `play.route` event never appears. No error is raised — a context without a
 `query` field builds a query-less URL, exactly like `query: {}`.
 
-**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
+**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 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:
@@ -627,8 +629,9 @@ on: {
 ```
 
 (Older releases threw `MissingQueryContextError` at construction for a
-routing-aware context without a `query` field; the error class remains
-exported for `instanceof` compatibility but is never thrown.)
+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
 
@@ -675,7 +678,7 @@ const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
 
 **Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
 
-**Fix:** Use Node.js `>= 22.0.0`. Check with:
+**Fix:** Use Node.js `>= 24.0.0`. Check with:
 
 ```bash
 node --version
@@ -685,23 +688,23 @@ node --version
 
 ## Key Concepts Reference
 
-| Term                                                                                                  | Description                                                                                                     |
-| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `setup({ types })`                                                                                    | XState v5 entry point — declares TypeScript types for context, events, and input                                |
-| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) instances |
-| `actor.start()`                                                                                       | Activates the machine — always call before sending events                                                       |
-| `actor.send({ type })`                                                                                | Sends an event; machine guards decide whether a transition occurs                                               |
-| `actor.getSnapshot()`                                                                                 | Synchronous read of current state and context                                                                   |
-| `actor.state`                                                                                         | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                           |
-| `actor.currentRoute`                                                                                  | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                               |
-| `actor.currentView`                                                                                   | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                    |
-| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                            |
-| `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                 |
-| `always` guard                                                                                        | Protects states — fires on entry before any event, even on direct URL access                                    |
-| [`extractMachineRoutes`](../api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                      |
-| [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                 |
-| [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                               |
-| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                          |
+| Term                                                                                                               | Description                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `setup({ types })`                                                                                                 | XState v5 entry point — declares TypeScript types for context, events, and input                                      |
+| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md)                       | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) instances |
+| `actor.start()`                                                                                                    | Activates the machine — always call before sending events                                                             |
+| `actor.send({ type })`                                                                                             | Sends an event; machine guards decide whether a transition occurs                                                     |
+| `actor.getSnapshot()`                                                                                              | Synchronous read of current state and context                                                                         |
+| `actor.state`                                                                                                      | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                                 |
+| `actor.currentRoute`                                                                                               | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                                     |
+| `actor.currentView`                                                                                                | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                          |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                                  |
+| `play.route` event                                                                                                 | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                       |
+| `always` guard                                                                                                     | Protects states — fires on entry before any event, even on direct URL access                                          |
+| [`extractMachineRoutes`](../api/@xmachines/play-router/xstate/functions/extractMachineRoutes.md)                   | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                            |
+| [`createRouteMapFromTree`](../api/@xmachines/play-router/index/functions/createRouteMapFromTree.md)                | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                       |
+| [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                                    | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                                     |
+| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)               | React component that connects a `PlayerActor` to TanStack React Router                                                |
 
 ---
 

package/guides/inspector.md

@@ -22,7 +22,7 @@ Install the inspect client alongside your existing XState dependency:
 pnpm add -D @statelyai/inspect
 ```
 
-Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md):
+Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md):
 
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
@@ -42,7 +42,7 @@ actor.start();
 
 `createBrowserInspector()` opens Stately's hosted inspector in a new tab and streams the actor's events to it. From there the machine draws itself, every transition animates, and the context is readable at each step.
 
-That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/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:
+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
 // Function form — the common case
@@ -190,8 +190,8 @@ const createPlayer = definePlayer({ machine: appMachine, options });
 
 ## Related documentation
 
-- **[`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
-- **[`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)** — the actor an inspector observes
+- **[`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
 - **[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

@@ -0,0 +1,245 @@
+# Understanding 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.
+
+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.
+
+---
+
+## What problem URLPattern solves
+
+A route pattern has to say two different things.
+
+- A URL must become a **state id**. `/profile/alice` is the state `profile`, and `alice` is a param of it.
+- A state must become a **URL**. The state `profile` with `{ userId: "alice" }` is the path `/profile/alice`.
+
+The first direction needs a matcher, and every router writes its own. Express uses `path-to-regexp`, svelte-spa-router uses `regexparam`, and Vue Router, React Router, SolidJS Router, TanStack Router and SvelteKit each wrote a parser of their own. A library that spans nine of them cannot adopt one of those parsers, because each one carries a different set of features, and a machine that declares a pattern one router refuses is a machine that runs on eight of the nine.
+
+`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-signals`](signals.md) makes for reactivity: one standard, isolated behind one module, present on every runtime. There is no `SignalsUnavailableError`, because the polyfill makes the question impossible to ask, and there is no URLPattern availability error for the same reason.
+
+### The API is always present
+
+`@xmachines/play-router` 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 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.
+
+---
+
+## The pattern grammar
+
+A `meta.route` path is a URLPattern **pathname** pattern. These are the forms:
+
+| Form         | Name         | Matches                                                    |
+| ------------ | ------------ | ---------------------------------------------------------- |
+| `/users`     | a literal    | that path, and nothing else                                |
+| `:name`      | a param      | one path segment, reported to the machine as `name`        |
+| `:name(\d+)` | a constraint | one segment that the regular expression accepts            |
+| `(\d+)`      | anonymous    | one segment, reported under a NUMBER and not a name        |
+| `*`          | a wildcard   | every remaining character, reported under a number         |
+| `{…}`        | a group      | the forms inside it, as one unit that a modifier can carry |
+| `\:`         | an escape    | the next character, as a literal                           |
+
+A **modifier** follows a param, a wildcard or a group:
+
+| Modifier | Meaning      | A path that fills it not |
+| -------- | ------------ | ------------------------ |
+| none     | exactly one  | does not match           |
+| `?`      | zero or one  | matches                  |
+| `+`      | one or more  | does not match           |
+| `*`      | zero or more | matches                  |
+
+```ts
+const machine = createMachine({
+	id: "app",
+	states: {
+		home: { meta: { route: "/" } },
+		profile: { meta: { route: "/profile/:userId" } },
+		settings: { meta: { route: "/settings/:section?" } },
+	},
+});
+```
+
+### Which forms work in which direction
+
+The table above is what the route map MATCHES. The two directions are not the same size
+today, and a route that uses only the inbound half stops the URL silently.
+
+| Form                          | URL to state | state to URL                                                           |
+| ----------------------------- | ------------ | ---------------------------------------------------------------------- |
+| a literal, `:name`, `:name?`  | yes          | yes                                                                    |
+| `:name*`                      | yes          | **no** — the `*` stops the push, and the URL does not move             |
+| `:name+`                      | yes          | **no** — the `+` reaches the URL, and a value with a `/` is encoded    |
+| `{…}`                         | yes          | **no** — the braces reach the URL                                      |
+| `:name(\d+)`, `(\d+)`         | yes          | **no** — the constraint reaches the URL, or it stops the push          |
+| `*`                           | yes          | **no** — the `*` stops the push, and the URL does not move             |
+| `:cat-id`, a hyphen in a name | yes          | **no** — the substitution throws, and the URL stops                    |
+| an escape, `\+` and `\(`      | yes          | yes — the bridge resolves the escape before it pushes                  |
+| an escape, `\:`               | yes          | **no** — the substitution reads the escaped `:` as a param, and throws |
+
+`buildRouteUrl` of `@xmachines/play-xstate` performs the outbound half, and it reads
+`:name` and `:name?` alone. A state whose route uses another form derives a URL that its
+own route matches never — or no URL at all, because `deriveCurrentRoute` catches the
+`MissingRouteParamError` and answers `null`.
+
+**Declare a route with a literal, `:name`, `:name?` and an escape until the outbound half
+reads the whole grammar.** The remaining forms are safe for a route that the machine never
+navigates TO, such as a catch-all that only receives a deep link. Issue #16 closes the
+difference.
+
+A constraint fails in one of two ways, and which one depends on a single character. The
+derived path carries the constraint whole — `/v/:major(\d+)` with `{ major: "2" }` gives
+`/v/2(\d+)` — and the bridge reads a path that holds a BACKSLASH through the grammar. It
+reads `(\d+)` as a param there, so the route resolves to no one path and the push stops.
+A constraint with no backslash, such as `([0-9]+)`, reaches the address bar as it stands.
+
+`buildRouteUrl` leaves an escape as the template writes it, and the bridge resolves it
+before the push. The actor route carries `/tags/c\+\+`, and the address bar receives
+`/tags/c++`, which is the path that the route matches.
+
+### 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.
+
+URLPattern **refuses** `:`, `+` and `?`: `/tags/c++` reads `+` as a modifier of the literal before it, and a modifier needs a part; `/time/10:30` reads `:` as the start of a param name, and `30` is no name. A route map throws `InvalidRoutePatternError` for each of them, and the error names the pattern.
+
+URLPattern **accepts** `(` and `{`, and it reads them as grammar: `/docs/rfc(2119)` is the literal `/docs/rfc` and an anonymous param that the expression `2119` constrains, so it matches `/docs/rfc2119`; `/i18n/{en}` is a group, so it matches `/i18n/en`. Neither route reports a fault, and neither one matches the path that its author wrote.
+
+Escape the character when you mean it literally. A `:` and a `?` are the two exceptions,
+and the paragraphs below give the form to write for each.
+
+```
+/tags/c\+\+          matches /tags/c++
+/docs/rfc\(2119\)    matches /docs/rfc(2119)
+/time/10%3A30        matches /time/10:30
+/a%3Fb               matches /a?b
+```
+
+**An escaped `:` matches, and it derives no URL.** `substituteParams` of `buildRouteUrl` reads `:30` of `/time/10\:30` as a param placeholder, finds no value for the name `30`, and throws `MissingRouteParamError` — which `deriveCurrentRoute` answers with `null`, so the address bar follows that state never. `\+` and `\(` carry no such risk, because neither character starts a param name. Write `%3A` instead: `/time/10%3A30` is an ordinary literal path, and both halves read it. Issue #16 closes the difference.
+
+A `?` has no literal form, and the escape does not give it one. A URL pathname ends at its first `?`, so `getStateIdByPath` cuts every location there. The route `/a\?b` compiles with no fault, and no location reaches it. Write `%3F` instead: `/a%3Fb` is an ordinary literal path, and it resolves.
+
+This rule is about the PATTERN that a state declares. A param VALUE needs no escape, because `buildRouteUrl` percent-encodes each value: `/search/:q` with `{ q: "a+b" }` becomes the location `/search/a%2Bb`, and `extractRouteParams` reads `a+b` back from it.
+
+`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.
+
+### The prefix rule
+
+A `/` directly before a **param** belongs TO that param. A `/` directly before a **group** does not.
+
+```
+/settings/:section?    matches /settings          — the modifier removed the separator too
+/a/:b?/c               matches /a/c
+/a/{b}?/c              matches /a//c, and NOT /a/c
+/books{/:id}?          matches /books
+/books/{:id}?          matches /books/, and NOT /books
+```
+
+This one rule decides every optional route in this library. Write `{/:id}?` and not `/{:id}?` when you want the bare path to work.
+
+**A bare path of a doubled slash is unreachable.** `sanitizePathname` joins every run of separators into one, and every bridge calls it before the match, so the location `/a//c` arrives as `/a/c` — which `/a/{b}?/c` matches never. Put the separator INSIDE the group, and the bare path is an ordinary one.
+
+The two URLPattern implementations also disagree about a path of a doubled slash, and about nothing else: the native API matches `/{/v2}` against `//v2`, and `urlpattern-polyfill` does not. The collapse above is what keeps that difference away from your routes.
+
+### The one divergence from URLPattern
+
+A param name of URLPattern is a JavaScript identifier, and it carries no hyphen: `/docs/:cat-id` is the param `cat` followed by the literal `-id` for the standard.
+
+**XMachines reads `cat-id` as one name.** It compiles the pattern as `:cat_id` and it maps the group back, so the machine receives `{ "cat-id": "intro" }`. A route names its params the way the application does.
+
+The cost is that you cannot write URLPattern's own reading of `:cat-id`. Use `:cat` followed by a separate literal segment when you need it.
+
+---
+
+## The routing invariants
+
+### 1. XMachines resolves the state id. The router never does
+
+The router is a **source of locations** and a **sink for navigations**. It resolves a state id never, because a state id is a concept of the machine that the router knows nothing about.
+
+| Direction         | Who does the work                                                                       |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| URL → state id    | XMachines. `RouteMap.getStateIdByPath` runs the URLPattern match, in all nine adapters  |
+| actor route → URL | XMachines, and it touches URLPattern never: a map lookup, then a substitution of params |
+| params            | the URLPattern extraction, except where the framework already parsed them               |
+
+That follows from the architecture: a host registers ONE catch-all route — `/:pathMatch(.*)*` in the Vue demo — so the framework matches nothing that belongs to the machine.
+
+Vue Router and SolidJS Router parse their own params, and their bridges keep that parse when it covers every **required** name of the pattern. That is an optimization, and never a second source of truth: a bridge under a mount ignores the framework entirely, because the framework matched a route of the HOST there and a name that collides carries the value of the host.
+
+### 2. A `basePath` divides the two sides
+
+A machine can own the whole router, or it can sit under a mount. `basePath` is the prefix that belongs to the host, and the machine owns the suffix alone. Every path that reaches the machine has the prefix removed already, and every path that the machine pushes gets it back.
+
+### 3. `connect()` and `disconnect()` come in a pair, and one actor takes one bridge
+
+A bridge installs a signal watcher on the actor and a subscription on the router. Neither releases itself.
+
+- Call `disconnect()` from the teardown of your component: `useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid.
+- A second `connect()` on an actor that already has a bridge throws `DuplicateBridgeError`. The actor takes one bridge, so that two bridges cannot drive it in opposite directions.
+- `connect()` gives all or nothing. It installs the watcher and the subscription BEFORE the first synchronization, because that synchronization drives both directions — and when the synchronization throws, `connect()` removes everything it installed and frees the actor again.
+
+---
+
+## Which patterns cost what
+
+- A **static** route costs nothing. `RouteMap` splits at construction: a literal path goes into an exact-match `Map`, and only a pattern compiles a `URLPattern`. A route map of literal paths alone reaches the API never.
+- A **parameterized** route pays one compilation in the constructor, and one match for each distinct path, behind an LRU cache.
+- A route that a **framework** already parsed pays neither, for as long as its parse covers every required name.
+
+---
+
+## 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.
+
+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.
+
+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.
+
+---
+
+## 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` 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 TC39 Signals](signals.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
+- [URLPattern on MDN](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) — the standard

package/guides/state-machines.md

@@ -77,7 +77,7 @@ Key patterns:
 XMachines extends XState's `meta` field on each state node. This is where routing intent and view structure live:
 
 ```typescript
-import { typedSpec } from "@xmachines/play-actor";
+import { typedSpec } from "@xmachines/play-view";
 
 const appMachine = setup({/* ... */}).createMachine({
 	id: "app",
@@ -122,7 +122,7 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
 
 The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
@@ -130,7 +130,7 @@ The machine's whole context is available to every view through the **`/context`
 
 ---
 
-## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) — automatic route event wiring
+## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) — automatic route event wiring
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
@@ -150,10 +150,10 @@ states: {
 }
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
 
 ```typescript
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const appMachine = setup({/* ... */}).createMachine(
 	formatPlayRouteTransitions({
@@ -168,7 +168,7 @@ const appMachine = setup({/* ... */}).createMachine(
 );
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
 types: {
@@ -200,16 +200,15 @@ Guards are evaluated by XState before a transition fires. If the guard returns `
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
+Compose a condition with the combinators of XState:
 
-| Function                                                                                            | What it does                            |
-| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| [`composeGuards(...guards)`](../api/@xmachines/play-xstate/functions/composeGuards.md)              | AND — all guards must pass              |
-| [`composeGuardsOr(...guards)`](../api/@xmachines/play-xstate/functions/composeGuardsOr.md)          | OR — any guard must pass                |
-| [`negateGuard(guard)`](../api/@xmachines/play-xstate/functions/negateGuard.md)                      | NOT — inverts the guard result          |
-| [`hasContext(key)`](../api/@xmachines/play-xstate/functions/hasContext.md)                          | Checks that a context field is non-null |
-| [`contextFieldMatches(key, value)`](../api/@xmachines/play-xstate/functions/contextFieldMatches.md) | Checks a context field against a value  |
-| [`eventMatches(type)`](../api/@xmachines/play-xstate/functions/eventMatches.md)                     | Checks the event type                   |
+| Function        | What it does                |
+| --------------- | --------------------------- |
+| `and([g1, g2])` | AND — every guard must pass |
+| `or([g1, g2])`  | OR — one guard must pass    |
+| `not(g)`        | NOT — it inverts the guard  |
+
+Each combinator resolves a guard NAME against the `guards` of `setup()`, so a name that the map does not hold fails to compile.
 
 ---
 
@@ -259,7 +258,7 @@ actor.start();
 // Actor resumes from where it left off
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---
 
@@ -281,6 +280,6 @@ actor.start();
 - [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), and the routing utilities
 - [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -45,6 +45,7 @@
   },
   "scripts": {
     "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
@@ -53,16 +54,16 @@
     "clean": "rm -rf coverage node_modules/.vite*"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
-    "typedoc": "^0.28.19",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "vitest": "^4.1.11"
+    "typedoc-plugin-markdown": "^4.13.0",
+    "vitest": "^5.0.1"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   }
 }