@xmachines/docs 2.2.0 → 4.0.0

package/guides/actor-model.md

@@ -19,7 +19,7 @@ The boundary between them is enforced by the signal protocol: the actor exposes
 ```
 Actor (business logic)
   │
-  │  emits signals: state, currentRoute, currentView
+  │  emits signals: state, and currentRoute / currentView from its capabilities
   ▼
 Infrastructure (runtime adapters)
   ├── Router Bridge — reflects currentRoute into the URL bar
@@ -33,20 +33,20 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md). It implements three reactive properties:
+An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It implements three reactive properties:
 
-| Property             | Type                              | What it is                                                                                                                     |
-| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                 |
-| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`.                                                                             |
-| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) that drives renderers. |
+| Property             | Type                              | What it is                                                                                                                                                     |
+| -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                                                 |
+| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`. Needs the routing capability.                                                                               |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) that drives renderers. Needs the view capability. |
 
 All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
 
 The actor also owns:
 
 - **Guards** — it decides whether a transition is valid. If a router sends a `play.route` event for a path the actor's guards reject, the actor does not transition. It then emits its current valid route back through `currentRoute`, and the router bridge overwrites the URL to match.
-- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
+- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
 - **Initial route** — `actor.initialRoute` is the route the actor starts in. Router adapters use this for initial navigation, not the browser's current URL.
 
 ---
@@ -87,17 +87,19 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 ---
 
-## [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — the enforced contract
+## [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) — the enforced contract
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the contract that all actor implementations satisfy. It is an INTERFACE, and it names no state machine library.
+
+An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) extends `Actor` of XState, which means:
 
 - XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) adds one abstract requirement: a reactive `state` property of type `Signal.State<unknown>`. This is the single point where XState's pull-based snapshot API is bridged to TC39's push-based signal system.
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Signal.State<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based signal system of TC39.
 
-The two optional capability interfaces — [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md) — are deliberately separate:
+The two optional capability interfaces — [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) — are deliberately separate:
 
 - Not every actor needs routing (e.g., a background data-sync actor).
 - Not every actor drives a view (e.g., a sub-actor composed inside a parent).
@@ -105,26 +107,33 @@ The two optional capability interfaces — [`Routable`](../api/@xmachines/play-a
 An actor implements only the capabilities it actually uses:
 
 ```typescript
-// Minimal actor: just reactive state
-class MinimalActor extends AbstractActor<SomeLogic> {
-	state = new Signal.State(this.getSnapshot());
+// Minimal actor: the contract alone, which is reactive state and send
+class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
+	readonly state = new Signal.State<SomeSnapshot>(initial);
+	send(event: SomeEvent): void {
+		/* dispatch */
+	}
 }
 
-// Full actor: state + routing + view
-class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewable {
-	state = new Signal.State(this.getSnapshot());
-	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-	currentView = new Signal.State<PlaySpec | null>(null);
+// Full actor: the contract, the routing and the view. It extends the actor class of
+// its own engine, and `PlayActor` stays out of the inheritance.
+class PlayerActor
+	extends Actor<SomeMachine>
+	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
+{
+	readonly state = new Signal.State(this.getSnapshot());
+	readonly currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+	readonly currentView = new Signal.State<PlaySpec | null>(null);
 }
 ```
 
-In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
 
 ---
 
-## [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) — the factory builder
+## [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) — the factory builder
 
-[`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md) is the primary entry point for creating actors:
+[`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) is the primary entry point for creating actors:
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -137,7 +146,7 @@ const actor = createPlayer();
 actor.start();
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
+[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
 
 The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
 
@@ -175,6 +184,6 @@ The Play RFC captures the actor/infrastructure split in a single statement:
 - [Understanding TC39 Signals](signals.md) — how the actor communicates with infrastructure
 - [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
 - [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
-- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md)
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/getting-started.md

@@ -20,13 +20,13 @@ You need the following installed before cloning the repository:
 
 | Requirement | Version            | Notes                                                                                                                 |
 | ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| Node.js     | `>= 22.0.0`        | Specified in all `package.json` `engines` fields                                                                      |
+| 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`.
 
-> **Node.js version manager tip:** If you manage multiple Node versions with `nvm` or `fnm`, install and activate Node 22 before proceeding.
+> **Node.js version manager tip:** If you manage multiple Node versions with `nvm` or `fnm`, install and activate Node 24 before proceeding.
 
 ### Installation Steps
 
@@ -68,7 +68,7 @@ All tests should pass on a freshly cloned and built repository. If they do, your
 
 ### Dev Container (Optional)
 
-A fully configured dev container is provided at `.devcontainer/`. It uses Docker Compose with a Node 22 Bookworm base image and includes Docker-outside-of-Docker, Claude Code, and OpenCode pre-installed.
+A fully configured dev container is provided at `.devcontainer/`. It uses Docker Compose with a Node 24 Bookworm base image and includes Docker-outside-of-Docker, Claude Code, and OpenCode pre-installed.
 
 **VS Code:** Open the repository and choose **Reopen in Container** when prompted.
 
@@ -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