@xmachines/docs 3.0.0 → 4.0.0

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

@@ -0,0 +1,46 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / with-routing
+
+# with-routing
+
+The routing capability of an XState actor, as a mixin.
+
+`PlayerActor` holds `state` and `send`, and nothing about a route. This module adds
+`currentRoute` and `initialRoute`, which is what `Routable` of `@xmachines/play-router`
+asks for and what every router bridge reads.
+
+It is a SEPARATE entry point, `@xmachines/play-xstate/routing`, and the core imports it
+never. `@xmachines/play-router` is an OPTIONAL peer of this package for the same reason:
+an application that declares no route installs neither that package nor the route map
+and the bridge that it carries.
+
+## Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+const actor = createPlayer();
+actor.currentRoute.get(); // "/profile/alice"
+```
+
+## Interfaces
+
+- [RouteContext](interfaces/RouteContext.md)
+- [RouteObject](interfaces/RouteObject.md)
+
+## Type Aliases
+
+- [RouteData](type-aliases/RouteData.md)
+- [RouteDataResolver](type-aliases/RouteDataResolver.md)
+- [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
+- [RouteMetadata](type-aliases/RouteMetadata.md)
+- [RouteStateNode](type-aliases/RouteStateNode.md)
+
+## Functions
+
+- [buildRouteUrl](functions/buildRouteUrl.md)
+- [deriveRoute](functions/deriveRoute.md)
+- [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
+- [isAbsoluteRoute](functions/isAbsoluteRoute.md)
+- [withRouting](functions/withRouting.md)

package/api/@xmachines/play-xstate/{functions → with-routing/functions}/buildRouteUrl.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / buildRouteUrl
 
 # Function: buildRouteUrl()
 
@@ -6,7 +6,7 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/build-url.ts#L38)
+Defined in: [packages/play-xstate/src/routing/build-url.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/build-url.ts#L38)
 
 Builds a complete URL from a route template and the context of the actor.
 

package/api/@xmachines/play-xstate/{functions → with-routing/functions}/deriveRoute.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / deriveRoute
 
 # Function: deriveRoute()
 
@@ -6,7 +6,7 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/derive-route.ts#L92)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/derive-route.ts#L93)
 
 Derives the route from the metadata of an XState state
 
@@ -37,7 +37,7 @@ The template of the route path, which can hold a :param, or null when the functi
 The basic read of a route
 
 ```typescript
-import { deriveRoute } from "@xmachines/play-xstate";
+import { deriveRoute } from "@xmachines/play-xstate/routing";
 import { setup } from "xstate";
 
 const machine = setup({}).createMachine({
@@ -95,7 +95,7 @@ console.log(route); // "/dashboard"
 
 ## See
 
-- [Play RFC](../../../../rfc/play.md)
+- [Play RFC](../../../../../rfc/play.md)
 - [buildRouteUrl](buildRouteUrl.md) for the construction of a URL, with the substitution of each parameter
 - [isAbsoluteRoute](isAbsoluteRoute.md) for the test of an absolute path
 

package/api/@xmachines/play-xstate/{functions → with-routing/functions}/formatPlayRouteTransitions.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / formatPlayRouteTransitions
 
 # Function: formatPlayRouteTransitions()
 
@@ -6,7 +6,7 @@
 function formatPlayRouteTransitions<T>(machineConfig): T;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L112)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L216)
 
 Makes the play.route transitions from the declarative route configs
 

package/api/@xmachines/play-xstate/{functions → with-routing/functions}/isAbsoluteRoute.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / isAbsoluteRoute
 
 # Function: isAbsoluteRoute()
 
@@ -6,7 +6,7 @@
 function isAbsoluteRoute(path): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/derive-route.ts#L163)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/derive-route.ts#L269)
 
 Tells you if the route path is absolute
 
@@ -29,7 +29,7 @@ true when the path starts with '/'. In every other case, false
 ## Example
 
 ```typescript
-import { isAbsoluteRoute } from "@xmachines/play-xstate";
+import { isAbsoluteRoute } from "@xmachines/play-xstate/routing";
 
 console.log(isAbsoluteRoute("/dashboard")); // true
 console.log(isAbsoluteRoute("settings")); // false

package/api/@xmachines/play-xstate/with-routing/functions/withRouting.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / withRouting
+
+# Function: withRouting()
+
+```ts
+function withRouting<TMachine>(Base): PlayerConstructor<TMachine, Routable>;
+```
+
+Defined in: [packages/play-xstate/src/with-routing.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/with-routing.ts#L46)
+
+Adds the routing capability to an actor class.
+
+The result satisfies `Routable`, so a router bridge accepts it. A class without this
+mixin exposes no `currentRoute`, and a bridge therefore refuses it when it compiles,
+rather than at the first navigation.
+
+The mixin declares NO constructor, and that is deliberate: TypeScript demands the
+signature `...args: any[]` from a mixin over a generic base (TS2545), and this
+workspace writes no `any`. A field initializer of a subclass runs after `super()`
+instead, and it reads the inputs that `PlayerActor` keeps for a capability.
+
+## Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+
+## Parameters
+
+| Parameter | Type                                                                               | Description                                        |
+| --------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../../index/type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to extend, normally `PlayerActor`. |
+
+## Returns
+
+[`PlayerConstructor`](../../index/type-aliases/PlayerConstructor.md)\<`TMachine`, [`Routable`](../../../play-router/index/interfaces/Routable.md)\>

package/api/@xmachines/play-xstate/{interfaces → with-routing/interfaces}/RouteContext.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteContext
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteContext
 
 # Interface: RouteContext
 
-Defined in: [packages/play-xstate/src/routing/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L20)
+Defined in: [packages/play-xstate/src/routing/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/types.ts#L28)
 
 The context of the route construction, from the machine context.
 
@@ -19,7 +19,7 @@ machine that calls `buildRouteUrl` itself must fill `params` itself.
 
 | Property                                   | Type                            | Description                                                                           | Defined in                                                                                                                                             |
 | ------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-basepath"></a> `basePath?` | `string`                        | The base path of a relative route                                                     | [packages/play-xstate/src/routing/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L22) |
-| <a id="property-hash"></a> `hash?`         | `string`                        | The hash fragment                                                                     | [packages/play-xstate/src/routing/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L28) |
-| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | The parameters of the path to substitute, for example `:userId` of `/profile/:userId` | [packages/play-xstate/src/routing/types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L24) |
-| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | The query parameters                                                                  | [packages/play-xstate/src/routing/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L26) |
+| <a id="property-basepath"></a> `basePath?` | `string`                        | The base path of a relative route                                                     | [packages/play-xstate/src/routing/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/types.ts#L30) |
+| <a id="property-hash"></a> `hash?`         | `string`                        | The hash fragment                                                                     | [packages/play-xstate/src/routing/types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/types.ts#L36) |
+| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | The parameters of the path to substitute, for example `:userId` of `/profile/:userId` | [packages/play-xstate/src/routing/types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/types.ts#L32) |
+| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | The query parameters                                                                  | [packages/play-xstate/src/routing/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/types.ts#L34) |

package/api/@xmachines/play-xstate/with-routing/interfaces/RouteObject.md

@@ -0,0 +1,34 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteObject
+
+# Interface: RouteObject
+
+Defined in: [packages/play-router/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L33)
+
+A route object, with more metadata.
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+The additional metadata of the route: a title, a breadcrumb, and so on.
+
+CAUTION: `path`, `handler`, `reenter` and `data` are RESERVED. The routing layer
+reads those four names, and a release before this one read `path` alone. A state
+that carries its own `handler` value now throws an `InvalidRouteHandlerError` from
+`formatPlayRouteTransitions`, so the machine builds never; a state that carries its
+own `data` value now writes that value to `context.data`, where the `/context`
+projection of every view reads it. A `reenter` value is read as the FLAG of the
+generated transition, and the literal `true` alone turns the reentry on: the
+default is `false`, and a release before this one generated every transition with
+`reenter: true`. Give such a field another name.
+
+## Properties
+
+| Property                                 | Type                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Defined in                                                                                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-data"></a> `data?`       | \| [`RouteData`](../type-aliases/RouteData.md) \| [`RouteDataResolver`](../type-aliases/RouteDataResolver.md) | The extra data that the state threads into its `play.route` event. The shape follows `WithDynamicParams` of XState, which is how XState itself parameterizes an action and a guard: the field holds a literal value, OR a function of `{ context, event }` that returns one. `// The literal form. It survives a serialization of the machine. meta: { route: { path: "/doc/:docId", data: { titleKey: "doc.view" } } } // The function form, for a value that depends on the route. meta: { route: { path: "/doc/:docId", data: ({ event }) => ({ title: `Document ${event.params?.docId}` }), }, }` The generated transition resolves the value and assigns it to the `data` field of the context, beside `params` and `query`. The data of a state does NOT merge with the data of its ancestors: each state declares the whole value that its own route carries. This field and [PlayRouteEvent.data](../../../play-dom-router/interfaces/PlayRouteEvent.md#property-data) are two different things, and they meet in the resolver. This field is what the STATE declares, in its machine. `PlayRouteEvent.data` is what the SENDER of the event supplies, such as a router bridge or the code of an application. A resolver reads `event.data` and returns whatever mix of the two the state needs. CAUTION: the function form holds a function inside `meta`, and a function does not survive `JSON.stringify`. A machine that Stately Studio reads, or that a process sends over a wire, must use the literal form.                                                                                                                                                                                                                     | [packages/play-router/src/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L131) |
+| <a id="property-handler"></a> `handler?` | `"root"` \| `"local"` \| `"both"`                                                                             | Where the generated `play.route` transition sits. `"root"` is the default, and it is what XState does: `formatRouteTransitions` installs every route transition on the ROOT of the machine, and each one targets its state by the ID. A route from any state therefore reaches this state. The cost is that the root is the domain of the transition, so XState re-enters each ancestor on the path to the target, and those ancestors run their `entry` actions again although they stay active. `"local"` installs the transition on the PARENT of this state instead, and it targets this state relatively. XState offers the transitions of the deepest active state node first, so the parent answers the event itself and runs its `exit` and its `entry` actions NOT again. `"both"` installs one transition in each place. The local one answers while the parent is active, and the root one answers a route that arrives from outside the parent. Use `"both"` where an ancestor holds an `entry` action that must run one time for each real entry, such as an analytics event or an audit record. CAUTION: `"local"` makes this state reachable by a route ONLY while its parent is active. A `play.route` event that arrives from anywhere else matches no transition and the actor does not move. A browser URL for this state therefore leaves the URL and the actor divergent. Choose `"local"` to SCOPE a route on purpose, for example a step that a person reaches only inside its wizard. Choose `"both"` where the state must stay reachable from everywhere. The field has no effect on a state whose parent IS the root: the root transition of such a state is already local to its parent, so all three values agree. | [packages/play-router/src/types.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L95)   |
+| <a id="property-path"></a> `path`        | `string`                                                                                                      | The template of the route path, for example `"/user/:id"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-router/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L35)   |
+| <a id="property-reenter"></a> `reenter?` | `boolean`                                                                                                     | The `reenter` flag of the generated `play.route` transition. The default is `false`, which is also the default of XState. The flag spares the DOMAIN of the transition, and not every ancestor that stays active. Under the default placement `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, because XState re-enters every descendant of the domain that lies on the path to the target. A move between two siblings therefore still runs the `entry` action of their shared parent. [RouteObject.handler](#property-handler) is the field that spares those intermediate ancestors: `"local"` and `"both"` move the domain down to the parent of the state. Use the two fields together where an `entry` action must run one time for each state that the actor really enters. Set the field to `true` where the domain must run its `entry` actions again on every route to a descendant. The flag does not decide the destination. The value of the machine after a route is identical under both settings. A route to a state that has children still enters the `initial` child of that state, because the generated transition targets the state by its id, and XState enters the initial child of an id target under both settings. **See** [Play RFC](../../../../../rfc/play.md)                                                                                                                                                                                                                                                                                                            | [packages/play-router/src/types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L64)   |

package/api/@xmachines/play-xstate/with-routing/type-aliases/RouteData.md

@@ -0,0 +1,12 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteData
+
+# Type Alias: RouteData
+
+```ts
+type RouteData = Record<string, unknown>;
+```
+
+Defined in: [packages/play-router/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L15)
+
+The resolved extra data of a route. It reaches the consumer on the `data` field of a
+`play.route` event.

package/api/@xmachines/play-xstate/with-routing/type-aliases/RouteDataResolver.md

@@ -0,0 +1,31 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteDataResolver
+
+# Type Alias: RouteDataResolver
+
+```ts
+type RouteDataResolver = (args) => RouteData;
+```
+
+Defined in: [packages/play-router/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L28)
+
+The function form of [RouteObject.data](../interfaces/RouteObject.md#property-data).
+
+The signature mirrors `WithDynamicParams` of XState: the resolver reads the context
+of the machine and the event that asks for the route, and it returns the data.
+
+The resolver reads every field of the event, and `event.data` among them: that field
+carries what the SENDER of the event supplied, and the resolver decides how it
+combines with what the state declares. The `data` that the resolver RETURNS goes to
+`context.data`, and it does not go back onto the event.
+
+## Parameters
+
+| Parameter      | Type                                                                                                            |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| `args`         | \{ `context`: `unknown`; `event`: [`PlayRouteEvent`](../../../play-dom-router/interfaces/PlayRouteEvent.md); \} |
+| `args.context` | `unknown`                                                                                                       |
+| `args.event`   | [`PlayRouteEvent`](../../../play-dom-router/interfaces/PlayRouteEvent.md)                                       |
+
+## Returns
+
+[`RouteData`](RouteData.md)

package/api/@xmachines/play-xstate/{type-aliases → with-routing/type-aliases}/RouteMachineConfig.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteMachineConfig
 
 # Type Alias: RouteMachineConfig
 
@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L177)
 
 The minimal structural constraint of a machine config that
 `formatPlayRouteTransitions` accepts.
@@ -32,7 +32,7 @@ original concrete type through the transform. Therefore
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L74)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L178)
 
 ---
 
@@ -42,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L180)
 
 ---
 
@@ -52,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L75)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L179)

package/api/@xmachines/play-xstate/with-routing/type-aliases/RouteMetadata.md

@@ -0,0 +1,11 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteMetadata
+
+# Type Alias: RouteMetadata
+
+```ts
+type RouteMetadata = string | RouteObject;
+```
+
+Defined in: [packages/play-router/src/types.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L151)
+
+The route metadata of the `meta.route` field of a state machine.

package/api/@xmachines/play-xstate/{type-aliases → with-routing/type-aliases}/RouteStateNode.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-routing](../README.md) / RouteStateNode
 
 # Type Alias: RouteStateNode
 
@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
 
 The minimal structural shape of one XState state node, as
 `formatPlayRouteTransitions` reads it during its walk over the machine config.
@@ -29,7 +29,7 @@ signature without a change.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
 
 The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
@@ -41,7 +41,7 @@ The optional explicit state ID, for example `"home"` or `"settings"`. It is the
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -52,8 +52,22 @@ optional route?: RouteMetadata;
 ```
 
 The template of the URL path: the string form, for example
-`"/profile/:username"`, or the object form (`{ path, title }`). Both match
-[RouteMetadata](RouteMetadata.md).
+`"/profile/:username"`, or the object form (`{ path, reenter, title }`). Both
+match [RouteMetadata](RouteMetadata.md). The object form declares the `reenter` flag of the
+generated transition, and that flag defaults to `false`.
+
+---
+
+### on?
+
+```ts
+optional on?: Record<string, unknown>;
+```
+
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
+
+The event handlers of this state. The function reads them where a child asks for a
+local `play.route` handler, so that the transitions of the user survive the merge.
 
 ---
 
@@ -63,6 +77,6 @@ The template of the URL path: the string form, for example
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L46)
 
 The nested child states. The function walks them for each further route declaration.

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

@@ -0,0 +1,31 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / with-view
+
+# with-view
+
+The view capability of an XState actor, as a mixin.
+
+`PlayerActor` holds `state` and `send`, and nothing about a view. This module adds
+`currentView`, which is what `Viewable` of `@xmachines/play-view` asks for and what
+every renderer reads.
+
+It is a SEPARATE entry point, `@xmachines/play-xstate/view`, and the core imports it
+never. `@xmachines/play-view` is an OPTIONAL peer of this package for the same reason:
+an application that renders no view installs neither that package nor the json-render
+types that it names.
+
+## Example
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+```
+
+## Functions
+
+- [withView](functions/withView.md)

package/api/@xmachines/play-xstate/with-view/functions/withView.md

@@ -0,0 +1,32 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [with-view](../README.md) / withView
+
+# Function: withView()
+
+```ts
+function withView<TMachine>(Base): PlayerConstructor<TMachine, Viewable>;
+```
+
+Defined in: [packages/play-xstate/src/with-view.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/with-view.ts#L98)
+
+Adds the view capability to an actor class.
+
+Compose it AFTER the routing capability. An override calls `super.onSnapshot()` first,
+so `compose(PlayerActor, withRouting, withView)` gives the route 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.
+
+## Type Parameters
+
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+
+## Parameters
+
+| Parameter | Type                                                                               | Description                                                                            |
+| --------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `Base`    | [`PlayerConstructor`](../../index/type-aliases/PlayerConstructor.md)\<`TMachine`\> | The actor class to extend, normally `PlayerActor` or the result of another capability. |
+
+## Returns
+
+[`PlayerConstructor`](../../index/type-aliases/PlayerConstructor.md)\<`TMachine`, [`Viewable`](../../../play-view/index/interfaces/Viewable.md)\>

package/api/@xmachines/shared/README.md

@@ -22,17 +22,16 @@ In the monorepo, each package refers to it by name:
 
 ## Exports
 
-| Export                                      | File                                | Description                                                                                     |
-| ------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `@xmachines/shared/tsconfig`                | `config/tsconfig.json`              | Base TypeScript configuration for all packages                                                  |
-| `@xmachines/shared/tsconfig-test`           | `config/tsconfig.test.json`         | TypeScript configuration for test files (no emit, `allowImportingTsExtensions`, Vitest globals) |
-| `@xmachines/shared/oxlint`                  | `config/oxlint.config.ts`           | Shared oxlint configuration                                                                     |
-| `@xmachines/shared/oxfmt`                   | `config/oxfmt.config.ts`            | Shared oxfmt formatter configuration                                                            |
-| `@xmachines/shared/vite-aliases`            | `config/vite-aliases.ts`            | Vite resolve aliases for all `@xmachines/*` workspace packages                                  |
-| `@xmachines/shared/vitest`                  | `config/vitest.ts`                  | `defineXmVitestConfig` helper for per-package Vitest configs                                    |
-| `@xmachines/shared/vitest-setup`            | `config/vitest.setup.ts`            | Shared Vitest setup — extends matchers with `@testing-library/jest-dom`                         |
-| `@xmachines/shared/vitest-node-setup`       | `config/vitest.node.setup.ts`       | Node.js runtime guard — asserts `Node.js >= 24`                                                 |
-| `@xmachines/shared/vitest-urlpattern-setup` | `config/vitest.urlpattern.setup.ts` | Optional URLPattern polyfill setup for route-matching tests                                     |
+| Export                                | File                          | Description                                                                                     |
+| ------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------- |
+| `@xmachines/shared/tsconfig`          | `config/tsconfig.json`        | Base TypeScript configuration for all packages                                                  |
+| `@xmachines/shared/tsconfig-test`     | `config/tsconfig.test.json`   | TypeScript configuration for test files (no emit, `allowImportingTsExtensions`, Vitest globals) |
+| `@xmachines/shared/oxlint`            | `config/oxlint.config.ts`     | Shared oxlint configuration                                                                     |
+| `@xmachines/shared/oxfmt`             | `config/oxfmt.config.ts`      | Shared oxfmt formatter configuration                                                            |
+| `@xmachines/shared/vite-aliases`      | `config/vite-aliases.ts`      | Vite resolve aliases for all `@xmachines/*` workspace packages                                  |
+| `@xmachines/shared/vitest`            | `config/vitest.ts`            | `defineXmVitestConfig` helper for per-package Vitest configs                                    |
+| `@xmachines/shared/vitest-setup`      | `config/vitest.setup.ts`      | Shared Vitest setup — extends matchers with `@testing-library/jest-dom`                         |
+| `@xmachines/shared/vitest-node-setup` | `config/vitest.node.setup.ts` | Node.js runtime guard — asserts `Node.js >= 24`                                                 |
 
 ## Usage
 
@@ -108,17 +107,6 @@ export default defineXmVitestConfig(import.meta.url, {
 - `config/vitest.node.setup.ts` — the Node.js runtime guard (the browser mode skips it)
 - `config/vitest.setup.ts` — `@testing-library/jest-dom` matcher extensions
 
-For packages that test URL routing, add the URLPattern polyfill setup:
-
-```typescript
-export default defineXmVitestConfig(import.meta.url, {
-	test: {
-		globals: true,
-		setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"],
-	},
-});
-```
-
 ### Vite Aliases
 
 In a Vite demo package or app package, resolve every `@xmachines/*` package to its TypeScript source. A build first is not necessary:
@@ -157,16 +145,6 @@ The base `config/tsconfig.json` configures:
 - **Interop:** `verbatimModuleSyntax`, `isolatedModules`
 - **Custom condition:** `"source"` — `xmAliases` uses it to resolve a package to its TypeScript source in development and in a test
 
-## Testing
-
-```bash
-# Run tests for this package
-pnpm --filter @xmachines/shared test
-
-# Or from the package directory
-pnpm test
-```
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/api/@xmachines/shared/vite-aliases/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L238)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L338)
+Defined in: [vite-aliases.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L355)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L291)
+Defined in: [vite-aliases.ts:308](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L308)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L275)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L317)
+Defined in: [vite-aliases.ts:334](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L334)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -35,4 +35,4 @@ one and change the other.
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L318) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:335](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vite-aliases.ts#L335) |

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L209)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.