@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-vue-router/{interfaces → index/interfaces}/RouterBridge.md

@@ -1,19 +1,19 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouterBridge
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / RouterBridge
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L359)
+Defined in: [packages/play-router/src/types.ts:436](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L436)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
 The interface defines the connection of the lifecycle between the infrastructure,
 for example a framework router, and the Actor. The infrastructure builds a "bridge"
-to the Actor: it observes the signals of the Actor, and it manages its own
+to the Actor: it observes the atoms of the Actor, and it manages its own
 lifecycle accordingly.
 
 **Architectural context:** the interface implements **Passive Infrastructure
 (INV-04)**, because it gives an observation in one direction. The infrastructure
-connects to observe the signals of the Actor (currentRoute, currentView, and
+connects to observe the atoms of the Actor (currentRoute, currentView, and
 state), and it reflects each change. It makes no decision about the state.
 
 ## Example
@@ -22,31 +22,29 @@ The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
-import { Signal } from "@xmachines/play-signals";
+import { watchAtom, type Cleanup } from "@xmachines/play-atom";
 
 class MyRouterBridge implements RouterBridge {
-	private watcher: Signal.Watcher | null = null;
+	private stop: Cleanup | null = null;
 
 	async connect(): Promise<void> {
-		// Start the observation of the actor.currentRoute signal
-		this.watcher = new Signal.subtle.Watcher(() => {
-			const route = actor.currentRoute.get();
+		// Start the observation of the actor.currentRoute atom
+		this.stop = watchAtom(actor.currentRoute, (route) => {
 			if (route) router.navigate(route);
 		});
-		this.watcher.watch(actor.currentRoute);
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop the observation, and clean the watchers up
-		this.watcher?.unwatch(actor.currentRoute);
-		this.watcher = null;
+		// Stop the observation, and release the subscription
+		this.stop?.();
+		this.stop = null;
 	}
 }
 ```
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - invariant INV-04
+[Play RFC](../../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -56,12 +54,12 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
+Defined in: [packages/play-router/src/types.ts:453](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L453)
 
 Connects the router bridge to the Actor
 
 The infrastructure calls it when it must start the observation of the Actor
-signals, and when it must bring its own state, for example the browser URL, in line
+atoms, and when it must bring its own state, for example the browser URL, in line
 with the Actor state.
 
 #### Returns
@@ -75,7 +73,7 @@ The promise that resolves after the connection, or void for a synchronous connec
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// The bridge observes the actor.currentRoute signal now
+// The bridge observes the actor.currentRoute atom now
 ```
 
 ---
@@ -86,12 +84,12 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
+Defined in: [packages/play-router/src/types.ts:469](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L469)
 
 Disconnects the router bridge from the Actor
 
 The infrastructure calls it when it must stop the observation and free its
-resources, for example a signal watcher and an event listener.
+resources, for example an atom watcher and an event listener.
 
 #### Returns
 

package/api/@xmachines/play-vue-router/{variables → index/variables}/PlayRouterProvider.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouterProvider
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / PlayRouterProvider
 
 # Variable: PlayRouterProvider
 
@@ -7,7 +7,7 @@ const PlayRouterProvider: DefineComponent<
 	ExtractPropTypes<{
 		actor: {
 			required: true;
-			type: PropType<PlayActor>;
+			type: PropType<RoutableActor>;
 		};
 		basePath: {
 			default: undefined;
@@ -19,6 +19,16 @@ const PlayRouterProvider: DefineComponent<
 			required: false;
 			type: PropType<Record<string, string | number>>;
 		};
+		compiledCache: {
+			default: undefined;
+			required: false;
+			type: PropType<PatternCache<URLPatternLike>>;
+		};
+		patternCache: {
+			default: undefined;
+			required: false;
+			type: PropType<PatternCache<ParsedPattern>>;
+		};
 		renderer: {
 			required: true;
 			type: PropType<(actor, router) => VNodeChild>;
@@ -45,7 +55,7 @@ const PlayRouterProvider: DefineComponent<
 		ExtractPropTypes<{
 			actor: {
 				required: true;
-				type: PropType<PlayActor>;
+				type: PropType<RoutableActor>;
 			};
 			basePath: {
 				default: undefined;
@@ -57,6 +67,16 @@ const PlayRouterProvider: DefineComponent<
 				required: false;
 				type: PropType<Record<string, string | number>>;
 			};
+			compiledCache: {
+				default: undefined;
+				required: false;
+				type: PropType<PatternCache<URLPatternLike>>;
+			};
+			patternCache: {
+				default: undefined;
+				required: false;
+				type: PropType<PatternCache<ParsedPattern>>;
+			};
 			renderer: {
 				required: true;
 				type: PropType<(actor, router) => VNodeChild>;
@@ -75,6 +95,8 @@ const PlayRouterProvider: DefineComponent<
 	{
 		basePath: string;
 		basePathParams: Record<string, string | number>;
+		compiledCache: PatternCache<URLPatternLike>;
+		patternCache: PatternCache<ParsedPattern>;
 	},
 	{},
 	{},
@@ -87,7 +109,7 @@ const PlayRouterProvider: DefineComponent<
 >;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-vue-router/src/play-router-provider.ts#L20)
+Defined in: [packages/play-vue-router/src/play-router-provider.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-vue-router/src/play-router-provider.ts#L18)
 
 PlayRouterProvider — the Vue wrapper of VueRouterBridge.
 

package/api/@xmachines/play-xstate/README.md

@@ -2,25 +2,37 @@
 
 # @xmachines/play-xstate
 
-> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with signal-driven reactivity and a router integration.
+> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with atom-driven reactivity and a router integration.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
 > **Browser floor: Chrome 110, Firefox 115, Safari 16.4.** This package calls the ES2023
 > change-by-copy array methods, so a browser below that floor throws
-> `TypeError: ... is not a function`. Vite 8 resolves its default
-> `baseline-widely-available` target to Firefox 114, which is below it — raise
-> `build.target` when you bundle for the browser. The root README carries the table.
+> `TypeError: ... is not a function`. The root README carries the table.
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-xstate xstate
+pnpm add @xmachines/play-xstate @xmachines/play @xmachines/play-atom xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency. Install it with this package.
+**Peer dependencies.** Install them with the package:
+
+- [`@xmachines/play`](../play/README.md) — the core protocol. This package reads `shallowEqualExcept` and `DISPOSE` from it.
+- [`@xmachines/play-atom`](../play-atom/README.md) — the atom primitives. `PlayerActor` holds `currentView` and `currentRoute` as atoms.
+- `xstate` ^5.33.0 — the XState v5 runtime.
+
+**Optional peers.** Each capability subpath carries one. Install it when you read that subpath, and not before:
+
+```bash
+pnpm add @xmachines/play-router   # @xmachines/play-xstate/routing
+pnpm add @xmachines/play-view     # @xmachines/play-xstate/view
+```
+
+- [`@xmachines/play-router`](../play-router/README.md) — the routing capability reads `Routable`, `PlayRouteEvent` and `RouteData` from it.
+- [`@xmachines/play-view`](../play-view/README.md) — the view capability reads `composePlayState`, `PlaySpec` and `Viewable` from it.
 
 ---
 
@@ -28,7 +40,8 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
 // 1. Define your XState v5 machine
 const machine = setup({}).createMachine({
@@ -40,13 +53,13 @@ const machine = setup({}).createMachine({
 });
 
 // 2. Create a player factory
-const createPlayer = definePlayer({ machine });
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
 
 // 3. Instantiate and start an actor
 const actor = createPlayer();
 actor.start();
 
-// 4. Observe TC39 Signal-based reactive state
+// 4. Observe atom-based reactive state
 console.log(actor.currentRoute.get()); // "/"
 console.log(actor.state.get().value); // "idle"
 
@@ -135,16 +148,91 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-This concrete actor class is an XState v5 actor that also exposes reactive TC39 Signals. It implements both the `Routable` interface and the `Viewable` interface from `@xmachines/play-actor`.
+This concrete actor class is an XState v5 actor that exposes reactive atoms. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
+
+#### Atoms
+
+| Atom    | Type                           | Description                                                                  |
+| ------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `state` | `Atom<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+
+### The capabilities
 
-#### Signals
+Routing and the view are OPTIONAL, and each one is a mixin behind its own entry point. An application that declares no route loads no routing code, and an application that renders no view loads no view code and installs no json-render.
 
-| Signal         | Type                                   | Description                                                                                                                             |
-| -------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition                                                            |
-| `currentRoute` | `Signal.Computed<string \| null>`      | The URL that comes from the `meta.route` template of the active state and from the context                                              |
-| `currentView`  | `Signal.State<PlaySpec \| null>`       | The view spec from the `meta.view` metadata of the active state, with the context params added                                          |
-| `initialRoute` | `readonly string \| null`              | The route of the initial state of the machine. The constructor fixes it, and a router bridge uses it to detect a deep link or a restore |
+Each capability package is an OPTIONAL peer dependency. Install the one that you compose:
+
+```bash
+pnpm add @xmachines/play-router   # for @xmachines/play-xstate/routing
+pnpm add @xmachines/play-view     # for @xmachines/play-xstate/view
+```
+
+The main entry point of this package names neither. `@xmachines/play-xstate/routing` also
+carries the route utilities — `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
+`formatPlayRouteTransitions` and the route types — because each one names
+[`@xmachines/play-router`](../play-router/README.md) in its own types.
+
+| Capability | Entry point                      | Adds                           | Interface                                                          |
+| ---------- | -------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of [`@xmachines/play-router`](../play-router/README.md) |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of [`@xmachines/play-view`](../play-view/README.md)     |
+
+`compose` applies each capability from left to right:
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+// Both capabilities
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+
+// Routing alone: `currentView` is a compile error on this actor
+const createRouted = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+
+// Neither: `state` and `send`
+const createBare = definePlayer({ machine });
+```
+
+**The composition ORDER decides nothing.** `currentRoute` and `currentView` are computed atoms over `state`, and neither reads the other, so one write for each transition reaches both and the engine evaluates them in topological order. A router bridge therefore sees a guard redirect and a renderer sees the view of the same snapshot, whatever order `compose` applied. A release before this one wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there.
+
+**A lifecycle hook receives the bare actor.** `PlayerOptions` is typed before the class is composed, so it cannot name the capabilities, and a narrower hook parameter is refused under `strictFunctionTypes`. A hook that reads `currentRoute` or `currentView` reads them through a binding of the composed type:
+
+```typescript
+let composed: PlayerActor<typeof machine> & Routable & Viewable;
+
+const actor = definePlayer({
+	machine,
+	options: { onStateChange: () => console.log(composed.currentRoute.get()) },
+	actor: compose(PlayerActor, withRouting, withView),
+})();
+composed = actor;
+```
+
+| Atom           | Type                             | Capability | Description                                                                                                                              |
+| -------------- | -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentRoute` | `ReadonlyAtom<string \| null>`   | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
+| `initialRoute` | `readonly string \| null`        | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
+| `currentView`  | `ReadonlyAtom<PlaySpec \| null>` | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
+
+`state` is the ONE atom that the actor writes. `currentRoute` and `currentView` are
+COMPUTED over it, so one write for each transition reaches both in one propagation and no
+observer reads the new state beside an old derivation. Each derivation reports a failure
+through the `onError` option and keeps its last good value; it throws never, because it
+runs inside the write.
+
+**`currentRoute` notifies on every transition, and `currentView` notifies on a change of
+the view alone.** The two atoms answer two different questions. A router bridge needs the
+answer of the actor to each event that it proposed, and a guard that refuses an inbound
+location and holds the machine where it was derives the SAME path — so `currentRoute`
+compares "different" always, and the bridge learns that the address bar must go back.
+`currentView` gates its emission on the value, and a snapshot that changes no view on the
+screen keeps the previous reference, so a provider below it mounts the UI again not on
+every event. Debounce your own `watchAtom(actor.currentRoute, ...)` callback, or compare
+the path yourself, when you run work that belongs to a change of the route alone.
 
 #### Methods
 
@@ -155,59 +243,45 @@ This concrete actor class is an XState v5 actor that also exposes reactive TC39
 | `send(event)`   | Sends a typed event to the machine and calls the `onTransition` hook      |
 | `can(event)`    | Returns `true` when the current state accepts the given event             |
 | `getSnapshot()` | Returns the current XState snapshot                                       |
-| `dispose()`     | The alias of `stop()`. Deprecated — call `stop()`, or write `using`       |
 | `[DISPOSE]()`   | Stops the actor at the end of a `using` scope. The release is `stop()`    |
 
-#### Signal usage example
+#### Atom usage example
 
 ```typescript
-import { Signal } from "@xmachines/play-signals";
+import { watchAtom } from "@xmachines/play-atom";
 
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		console.log("Route changed:", actor.currentRoute.get());
-	});
+const stop = watchAtom(actor.currentRoute, (route) => {
+	console.log("Route changed:", route);
 });
 
-watcher.watch(actor.currentRoute);
 actor.start();
+
+// Later, on teardown
+stop();
 ```
 
 ---
 
-### Guard utilities
-
-> **Deprecated:** these guard helpers wrap the `and()`, `or()`, and `not()`
-> combinators of XState, but they do not compose with a guard slot that
-> `setup()` types. Use the combinators of XState directly. The next major
-> version removes this module.
+### Guards
 
-These composable guard helpers wrap the `and()`, `or()`, and `not()` functions of XState. Use them in a machine `setup({ guards })` definition.
+This package gives no guard utility. Compose a guard with the `and()`, `or()` and `not()` combinators of XState:
 
 ```typescript
-import { setup } from "xstate";
-import {
-	composeGuards, // AND logic: all guards must pass
-	composeGuardsOr, // OR logic:  at least one guard must pass
-	negateGuard, // NOT logic: inverts a guard
-	hasContext, // guard: context field is present and non-null
-	eventMatches, // guard: event type matches a string
-	contextFieldMatches, // guard: context field equals a value
-} from "@xmachines/play-xstate";
+import { and, not, setup } from "xstate";
 
 const machine = setup({
 	guards: {
-		isLoggedIn: ({ context }) => !!context.userId,
+		isLoggedIn: ({ context }) => context.userId !== "",
 		hasAdminRole: ({ context }) => context.role === "admin",
 	},
 }).createMachine({
 	on: {
 		accessAdmin: {
-			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
+			guard: and(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
 		accessLogin: {
-			guard: negateGuard("isLoggedIn"),
+			guard: not("isLoggedIn"),
 			target: "login",
 		},
 	},
@@ -215,6 +289,10 @@ const machine = setup({
 });
 ```
 
+A combinator resolves each name against the `guards` of `setup()`. A name that the map does not hold therefore fails to compile, and it names the fault: `Type '"typoGuardName"' is not assignable to type '"isLoggedIn"'`.
+
+`composeGuards`, `composeGuardsOr`, `negateGuard`, `hasContext`, `eventMatches` and `contextFieldMatches` stood here before. They closed two gaps of the types of XState 5.28. The peer floor of this package is `^5.33.0`, and 5.33 holds neither gap. The helpers also fitted a guard slot that `setup()` types never: the example of this package reached them through an `as never` cast. Write the combinator instead, and write a plain predicate in place of each helper.
+
 ---
 
 ### Routing utilities
@@ -227,7 +305,7 @@ This function reads each machine state that has a `meta.route` field. It then ge
 
 ```typescript
 import { setup } from "xstate";
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
@@ -311,17 +389,75 @@ import type {
 	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // deprecated with the guard utilities — removed in the next major
-	GuardArray, // deprecated with the guard utilities — removed in the next major
-	ComposedGuard, // deprecated with the guard utilities — removed in the next major
+} from "@xmachines/play-xstate";
+
+import type {
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
-	RouteObject, // Route metadata object shape: { path: string }
+	RouteObject, // Route metadata object shape: { path, reenter?, handler?, data? }
 	RouteMetadata, // Union: string | RouteObject
-} from "@xmachines/play-xstate";
+	RouteData, // The resolved extra data of a route: Record<string, unknown>
+	RouteDataResolver, // The function form of RouteObject.data
+} from "@xmachines/play-xstate/routing";
 ```
 
+`RouteObject`, `RouteMetadata`, `RouteData`, and `RouteDataResolver` have one
+definition, and it lives in [`@xmachines/play-router`](../play-router/README.md). `@xmachines/play-xstate/routing`
+re-exports them, so either import path gives you the same type. The MAIN entry point of
+this package re-exports them no longer: it would name an optional peer in the types of
+every consumer, including one that composes no routing.
+
+### The object form of `meta.route`
+
+The string form declares the path only. The object form declares the path and the
+behaviour of the generated `play.route` transition:
+
+```typescript
+meta: {
+	route: {
+		path: "/doc/:docId",
+		// Where the generated transition sits. The default is "root", which is what
+		// XState does: every route transition sits on the root of the machine.
+		//   "root"  — one transition on the root. A route from any state arrives.
+		//   "local" — one transition on the PARENT. The parent keeps its entry action,
+		//             and a route from outside the parent arrives NOWHERE.
+		//   "both"  — one in each place. The parent keeps its entry action, and a route
+		//             from outside the parent still arrives.
+		handler: "both",
+		// Whether the transition re-enters its OWN DOMAIN. The default is false, which
+		// is the default of XState. Under `handler: "root"` the domain is the root of
+		// the machine, so `false` spares the root alone: each ancestor between the root
+		// and the target still runs its exit and its entry actions. `handler` is the
+		// field that spares those intermediate ancestors.
+		reenter: false,
+		// The extra data of the route. The generated transition assigns it to
+		// `context.data`. A literal value, or a function of { context, event }.
+		data: { titleKey: "doc.view" },
+	},
+}
+```
+
+An unknown `handler` value throws `InvalidRouteHandlerError` at the format time.
+
+> **Upgrading from 3.x: the `reenter` default changed, and a machine that relies on it
+> goes quiet.** An earlier release wrote `reenter: true` on EVERY generated transition,
+> so every routed state re-entered its own domain on each navigation and ran its `entry`
+> actions again. The flag is now what `meta.route` declares, and the default is `false` —
+> which is the default of XState. A state whose `entry` action must run on each
+> navigation has to declare `reenter: true` for itself. Nothing throws, and the action
+> simply stops running.
+
+The `data` field follows the `WithDynamicParams` shape of XState, so the function form
+reads the context and the event:
+
+```typescript
+data: ({ context, event }) => ({ title: `Document ${event.params?.docId}` });
+```
+
+A function does not survive `JSON.stringify`. Use the literal form for a machine that
+Stately Studio reads, or that a process sends over a wire.
+
 ---
 
 ## Error Classes
@@ -331,31 +467,17 @@ The `@xmachines/play-xstate/errors` subpath exports the error classes. The main
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // deprecated: no longer thrown
+	InvalidRouteParamError, // A :param carries a dot segment, which a URL resolves away
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
 	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
-	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
+	InvalidRouteHandlerError, // meta.route.handler is not "root", "local", or "both"
 } from "@xmachines/play-xstate/errors";
 ```
 
-Every error class extends `PlayError` from `@xmachines/play`. Each class also carries typed detail fields, such as `param`, `template`, and `combinator`. Your code therefore reads the details of an error, and it does not parse the message.
-
----
-
-## Testing
-
-```bash
-# Run tests for this package in isolation
-pnpm --filter @xmachines/play-xstate test
-
-# Watch mode
-pnpm --filter @xmachines/play-xstate run test:watch
-```
-
-The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/test/`.
+Every error class extends `PlayError` from [`@xmachines/play/errors`](../play/README.md). Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
 
 ---
 
@@ -363,52 +485,9 @@ The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/t
 
 MIT — see [LICENSE](LICENSE) for details.
 
-@xmachines/play-xstate - the XState v5 adapter of the Play Architecture
-
-This package gives you the definePlayer() API. That function binds an XState state
-machine to the actor base, with the signal lifecycle and the DevTools
-integration.
-
-The Play RFC gives this package as the adapter of the logic layer. It converts a
-declarative machine definition into a live actor with a signal-driven
-reactivity.
-
-## Classes
-
-- [PlayerActor](classes/PlayerActor.md)
-
-## Interfaces
-
-- [PlayerConfig](interfaces/PlayerConfig.md)
-- [PlayerFactoryResumeOptions](interfaces/PlayerFactoryResumeOptions.md)
-- [PlayerOptions](interfaces/PlayerOptions.md)
-- [RouteContext](interfaces/RouteContext.md)
-- [RouteObject](interfaces/RouteObject.md)
-
-## Type Aliases
-
-- [~~ComposedGuard~~](type-aliases/ComposedGuard.md)
-- [~~Guard~~](type-aliases/Guard.md)
-- [~~GuardArray~~](type-aliases/GuardArray.md)
-- [PlayerFactory](type-aliases/PlayerFactory.md)
-- [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
-- [RouteMetadata](type-aliases/RouteMetadata.md)
-- [RouteStateNode](type-aliases/RouteStateNode.md)
-
-## Variables
-
-- [DISPOSE](variables/DISPOSE.md)
-
-## Functions
+## Modules
 
-- [buildRouteUrl](functions/buildRouteUrl.md)
-- [~~composeGuards~~](functions/composeGuards.md)
-- [~~composeGuardsOr~~](functions/composeGuardsOr.md)
-- [~~contextFieldMatches~~](functions/contextFieldMatches.md)
-- [definePlayer](functions/definePlayer.md)
-- [deriveRoute](functions/deriveRoute.md)
-- [~~eventMatches~~](functions/eventMatches.md)
-- [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
-- [~~hasContext~~](functions/hasContext.md)
-- [isAbsoluteRoute](functions/isAbsoluteRoute.md)
-- [~~negateGuard~~](functions/negateGuard.md)
+- [errors](errors/README.md)
+- [index](index/README.md)
+- [with-routing](with-routing/README.md)
+- [with-view](with-view/README.md)

package/api/@xmachines/play-xstate/errors/README.md

@@ -0,0 +1,14 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / errors
+
+# errors
+
+## Classes
+
+- [ActorThrewNonErrorError](classes/ActorThrewNonErrorError.md)
+- [InvalidEventError](classes/InvalidEventError.md)
+- [InvalidMachineError](classes/InvalidMachineError.md)
+- [InvalidRouteHandlerError](classes/InvalidRouteHandlerError.md)
+- [InvalidRouteMetadataError](classes/InvalidRouteMetadataError.md)
+- [InvalidRouteParamError](classes/InvalidRouteParamError.md)
+- [MissingRouteParamError](classes/MissingRouteParamError.md)
+- [MissingStateIdError](classes/MissingStateIdError.md)