@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-vue-router/index/interfaces/RoutableActor.md

@@ -0,0 +1,72 @@
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / RoutableActor
+
+# Interface: RoutableActor
+
+Defined in: [packages/play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L392)
+
+The minimal actor interface that `RouterBridgeBase` and every framework router
+adapter require.
+
+It names `send` itself, and it therefore gives `RouterBridgeBase.actor.send` a type that
+accepts a `PlayRouteEvent` directly. That removes the unsafe cast
+`(actor.send as (e: PlayRouteEvent) => void)`.
+
+It is [Routable](../../../play-router/index/interfaces/Routable.md) with `send`. The two members of the capability are declared once,
+in `Routable`, and this interface extends it. A copy of them here drifts the day that
+one of the two files changes.
+
+**It names the view NOWHERE. Routing implies no rendering.** No file of this package,
+and no file of any of the eight router adapters, ever reads `currentView`. A provider
+whose renderer callback reads the view binds its own `TActor`, and a constraint keeps
+the concrete type of the actor whole, so that callback still reads the exact spec of
+that actor.
+
+Every `PlayActor` of `@xmachines/play-actor` that also implements `Routable`, and whose
+event union holds `PlayRouteEvent`, satisfies this interface structurally. A machine
+that declares no route event does NOT satisfy it, and that refusal is correct: a bridge
+cannot navigate an actor that receives no route event.
+
+## Example
+
+```typescript
+import type { RoutableActor } from "@xmachines/play-router";
+
+class MyBridge extends RouterBridgeBase {
+	constructor(actor: RoutableActor, routeMap: RouteMap) {
+		super(actor, routeMap);
+	}
+}
+```
+
+## Extends
+
+- [`Routable`](../../../play-router/index/interfaces/Routable.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                            | Inherited from                                                                                                                                            | Defined in                                                                                                                               |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [`Routable`](../../../play-router/index/interfaces/Routable.md).[`currentRoute`](../../../play-router/index/interfaces/Routable.md#property-currentroute) | [packages/play-router/src/types.ts:354](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L354) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                              | [`Routable`](../../../play-router/index/interfaces/Routable.md).[`initialRoute`](../../../play-router/index/interfaces/Routable.md#property-initialroute) | [packages/play-router/src/types.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L355) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [packages/play-router/src/types.ts:394](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L394)
+
+Sends a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`

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

@@ -1,13 +1,13 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMapOptions
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / RouteMapOptions
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [packages/play-router/src/types.ts:567](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L567)
 
 The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L21) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                               |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [packages/play-router/src/types.ts:579](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L579) |

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

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMapping
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / RouteMapping
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L54)
+Defined in: [packages/play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L54)
 
 One entry of the map between a state ID and a path.
 
@@ -22,7 +22,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
-| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L58) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L56) |
+| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                               |
+| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [packages/play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [packages/play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L56) |

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

@@ -1,8 +1,8 @@
-[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:438](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L438)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -46,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - invariant INV-04
+[Play RFC](../../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -56,7 +56,7 @@ 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:455](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L455)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +86,7 @@ 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:471](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L471)
 
 Disconnects the router bridge from the Actor
 

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;
@@ -45,7 +45,7 @@ const PlayRouterProvider: DefineComponent<
 		ExtractPropTypes<{
 			actor: {
 				required: true;
-				type: PropType<PlayActor>;
+				type: PropType<RoutableActor>;
 			};
 			basePath: {
 				default: undefined;
@@ -87,7 +87,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:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-vue-router/src/play-router-provider.ts#L17)
 
 PlayRouterProvider — the Vue wrapper of VueRouterBridge.
 

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

@@ -4,15 +4,13 @@
 
 > 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.
 
-[![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-4.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
 
@@ -20,7 +18,7 @@
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency. Install it with this package.
+`xstate ^5.33.0` is a peer dependency. Install it with this package.
 
 ---
 
@@ -28,7 +26,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,7 +39,7 @@ 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();
@@ -135,16 +134,75 @@ 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 TC39 Signals. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
 
 #### Signals
 
-| 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 |
+| Signal  | Type                                   | Description                                                                  |
+| ------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `state` | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+
+### The capabilities
+
+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.
+
+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` in its own types.
+
+| Capability | Entry point                      | Adds                           | Interface                              |
+| ---------- | -------------------------------- | ------------------------------ | -------------------------------------- |
+| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of `@xmachines/play-router` |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of `@xmachines/play-view`   |
+
+`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 });
+```
+
+**Compose `withView` after `withRouting`.** An override calls `super.onSnapshot()` first, so the composition order decides the derivation order: the route holds its new value before the view derives from the same transition. A router bridge therefore sees a guard redirect before a renderer sees the view of the state that the guard refused.
+
+**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;
+```
+
+| Signal         | Type                              | Capability | Description                                                                                                                              |
+| -------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentRoute` | `Signal.Computed<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`  | `Signal.State<PlaySpec \| null>`  | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
 
 #### Methods
 
@@ -155,7 +213,6 @@ 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
@@ -175,39 +232,26 @@ actor.start();
 
 ---
 
-### Guard utilities
+### Guards
 
-> **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.
-
-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 +259,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 +275,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 +359,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`. `@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 +437,16 @@ 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
 	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`. 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 +454,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,13 @@
+[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)
+- [MissingRouteParamError](classes/MissingRouteParamError.md)
+- [MissingStateIdError](classes/MissingStateIdError.md)