@xmachines/docs 5.0.2 → 6.1.0

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteObject
 
-Defined in: [packages/play-router/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-router/src/types.ts#L33)
+Defined in: [packages/play-router/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-router/src/types.ts#L33)
 
 A route object, with more metadata.
 
@@ -15,20 +15,17 @@ A route object, with more metadata.
 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.
+reads those four names. An unknown `handler` value throws an
+`InvalidRouteHandlerError` from `formatPlayRouteTransitions`, so the machine builds
+never. A `data` value goes to `context.data`, where the `/context` projection of
+every view reads it. A `reenter` value is the FLAG of the generated transition, and
+the literal `true` alone turns the reentry on. Give a field of your own 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/v5.0.2/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/v5.0.2/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/v5.0.2/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/v5.0.2/packages/play-router/src/types.ts#L64)   |
+| 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:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-router/src/types.ts#L134) |
+| <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. The parent then runs its `exit` and its `entry` actions again only where the state declares `reenter: true`. `"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:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-router/src/types.ts#L98)   |
+| <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/v6.1.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, while the parent is active. Use the two fields together where an `entry` action must run one time for each state that the actor really enters. The target itself re-enters under both settings, so a route to the state that the actor already holds runs the `exit` and `entry` actions of that state again. The ROOT of the machine is the one exception: a route to the root has the root as its domain, so the flag decides. Set the field to `true` where the domain must run its `entry` actions again on each route to this state. The flag of a state applies to the routes to that state alone, and not to the routes to its descendants. 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 XState enters the initial child of a compound target under both settings. **See** [Play RFC](../../../../../rfc/play.md)    | [packages/play-router/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-router/src/types.ts#L67)   |

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

@@ -6,7 +6,7 @@
 type RouteData = Record<string, unknown>;
 ```
 
-Defined in: [packages/play-router/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-router/src/types.ts#L15)
+Defined in: [packages/play-router/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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

@@ -6,7 +6,7 @@
 type RouteDataResolver = (args) => RouteData;
 ```
 
-Defined in: [packages/play-router/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-router/src/types.ts#L28)
+Defined in: [packages/play-router/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-router/src/types.ts#L28)
 
 The function form of [RouteObject.data](../interfaces/RouteObject.md#property-data).
 

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

@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L177)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L178)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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:1
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L180)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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:1
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L179)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L179)

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

@@ -6,6 +6,6 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [packages/play-router/src/types.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-router/src/types.ts#L151)
+Defined in: [packages/play-router/src/types.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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/with-routing/type-aliases/RouteStateNode.md

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -64,7 +64,7 @@ generated transition, and that flag defaults to `false`.
 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/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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.
@@ -77,6 +77,6 @@ local `play.route` handler, so that the transitions of the user survive the merg
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L46)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.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/functions/withView.md

@@ -6,15 +6,13 @@
 function withView<TMachine>(Base): PlayerConstructor<TMachine, Viewable>;
 ```
 
-Defined in: [packages/play-xstate/src/with-view.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/with-view.ts#L99)
+Defined in: [packages/play-xstate/src/with-view.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-xstate/src/with-view.ts#L97)
 
 Adds the view capability to an actor class.
 
 The ORDER of the composition does not matter. `currentView` and `currentRoute` are two
 computed atoms over `state`, and neither reads the other, so the engine evaluates both
-from one write in topological order. An earlier release wrote `currentView` from an
-`onSnapshot` override, and the order then decided which capability held its new value
-first.
+from one write in topological order.
 
 ## Type Parameters
 

package/api/@xmachines/shared/vite-aliases/README.md

@@ -2,10 +2,17 @@
 
 # vite-aliases
 
+## Type Aliases
+
+- [XmTestTarget](type-aliases/XmTestTarget.md)
+
 ## Functions
 
 - [xmAliases](functions/xmAliases.md)
+- [xmBuildOutput](functions/xmBuildOutput.md)
+- [xmBuildOutputFile](functions/xmBuildOutputFile.md)
 - [xmCacheDir](functions/xmCacheDir.md)
 - [xmOptimizeDeps](functions/xmOptimizeDeps.md)
 - [xmResolve](functions/xmResolve.md)
 - [xmSvelteRunes](functions/xmSvelteRunes.md)
+- [xmTestTarget](functions/xmTestTarget.md)

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

@@ -3,10 +3,10 @@
 # Function: xmAliases()
 
 ```ts
-function xmAliases(importMetaUrl): Record<string, string>;
+function xmAliases(importMetaUrl, target?): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L238)
+Defined in: [vite-aliases.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L292)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 
@@ -27,11 +27,17 @@ export default defineConfig({
 resolve: { alias: xmAliases(import.meta.url) },
 });
 
+The dist run (`XM_TEST_TARGET=dist`, see [xmTestTarget](xmTestTarget.md)) gets no entry for a
+published package, except `<name>/src`. Each `@xmachines/*` specifier of a published
+package then resolves through its `exports` map to `dist/`, and [xmBuildOutput](xmBuildOutput.md)
+moves each `src/` file that a test imports by path to its counterpart in `dist/`.
+
 ## Parameters
 
-| Parameter       | Type     | Description                                                                                                                    |
-| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. Used to locate the workspace root (the directory containing `packages/`). |
+| Parameter       | Type                                              | Description                                                                                                                    |
+| --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `importMetaUrl` | `string`                                          | Pass `import.meta.url` from the calling config file. Used to locate the workspace root (the directory containing `packages/`). |
+| `target`        | [`XmTestTarget`](../type-aliases/XmTestTarget.md) | The code to resolve to. The default reads `XM_TEST_TARGET`.                                                                    |
 
 ## Returns
 

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

@@ -0,0 +1,37 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmBuildOutput
+
+# Function: xmBuildOutput()
+
+```ts
+function xmBuildOutput(importMetaUrl): Plugin;
+```
+
+Defined in: [vite-aliases.ts:388](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L388)
+
+The Vite plugin of the dist run: it moves each `src/` file of a published package to its
+counterpart in `dist/`.
+
+A specifier of a published package resolves through its `exports` map in the dist run (see
+[xmAliases](xmAliases.md)). A test also imports the module under test by path, as
+`../src/define-player.js`, and that import reaches no exports map. Without this plugin the
+test would exercise the source while every other import reads the build, and a class would
+exist two times, one copy for each tree. The plugin gives both imports the ONE file of
+`dist/`. A `vi.mock` of a `src/` path resolves through the same hook, so the mock replaces
+the module that the build output imports.
+
+A source file with no counterpart in `dist/` is a module that the build does not ship. The
+plugin then fails the import and names both files, because a fallback to the source would
+hide exactly the defect that the dist run exists to find.
+
+The plugin is part of every config of `defineXmVitestConfig` when `XM_TEST_TARGET` is
+`dist`, and of none when it is not.
+
+## Parameters
+
+| Parameter       | Type     | Description                                          |
+| --------------- | -------- | ---------------------------------------------------- |
+| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. |
+
+## Returns
+
+`Plugin`

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

@@ -0,0 +1,28 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmBuildOutputFile
+
+# Function: xmBuildOutputFile()
+
+```ts
+function xmBuildOutputFile(packageDir, sourceFile): string;
+```
+
+Defined in: [vite-aliases.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L359)
+
+The file in `dist/` that the build writes for one source file of a package.
+
+The library build keeps the module structure (`preserveModules`, with `src/` as the root),
+and tsc writes the same layout. So `src/a/b.ts` becomes `dist/a/b.js`. A `.tsx`, `.vue` or
+`.svelte` file becomes `.js` too. A runes module `x.svelte.ts` becomes `x.js`: the build of
+play-svelte drops the infix, because a consumer's Svelte plugin compiles each `*.svelte.js`
+again (see `packages/play-svelte/vite.config.ts`).
+
+## Parameters
+
+| Parameter    | Type     | Description                                 |
+| ------------ | -------- | ------------------------------------------- |
+| `packageDir` | `string` | The package directory.                      |
+| `sourceFile` | `string` | An absolute path under `<packageDir>/src/`. |
+
+## Returns
+
+`string`

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

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L355)
+Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L495)
 
 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:308](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L308)
+Defined in: [vite-aliases.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L448)
 
 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:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L275)
+Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L333)
 
 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:334](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L334)
+Defined in: [vite-aliases.ts:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L474)
 
 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:335](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L335) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L475) |

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

@@ -0,0 +1,26 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmTestTarget
+
+# Function: xmTestTarget()
+
+```ts
+function xmTestTarget(env?): XmTestTarget;
+```
+
+Defined in: [vite-aliases.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L25)
+
+Reads the test target from the `XM_TEST_TARGET` environment variable.
+
+The variable is the one switch of the dist run. The config helpers of this package read
+it, so no package config holds a second copy of the dist setup. An unset or empty variable
+gives `source`. Any other value than `source` or `dist` is an error: a typo must not run
+the suite against the source and report the result as a run against the build.
+
+## Parameters
+
+| Parameter | Type         | Default value | Description                                            |
+| --------- | ------------ | ------------- | ------------------------------------------------------ |
+| `env`     | `ProcessEnv` | `process.env` | The environment to read. The default is `process.env`. |
+
+## Returns
+
+[`XmTestTarget`](../type-aliases/XmTestTarget.md)

package/api/@xmachines/shared/vite-aliases/type-aliases/XmTestTarget.md

@@ -0,0 +1,15 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / XmTestTarget
+
+# Type Alias: XmTestTarget
+
+```ts
+type XmTestTarget = "source" | "dist";
+```
+
+Defined in: [vite-aliases.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L13)
+
+The code that a test run loads for each published `@xmachines/*` package.
+
+- `source` — the TypeScript under `src/`. `pnpm test` runs this way, and it needs no build.
+- `dist` — the build output under `dist/`, through the `exports` map of each package, as
+  a consumer gets it. `pnpm run test:dist` runs this way, after `pnpm run build`.

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

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

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

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L65)
+Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L76)
 
 Create a Vitest config with XMachines workspace defaults.
 
@@ -14,6 +14,10 @@ What this applies automatically:
 
 - `resolve.alias` from `xmAliases(importMetaUrl)` so `@xmachines/*` imports
   resolve to source in local/dev test runs.
+- In the dist run (`XM_TEST_TARGET=dist`), the `xmBuildOutput` plugin, and an
+  alias map with no published package in it: each `@xmachines/*` import then
+  resolves through its `exports` map to `dist/`, and each `src/` file that a
+  test imports by path resolves to its counterpart in `dist/`.
 - `config/vitest.setup.ts` when missing.
 - `config/vitest.node.setup.ts` for non-browser projects when missing.
 - `pool: "vmThreads"` for jsdom projects that declare no pool.

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L159)
+Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L174)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
 | -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L167) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L174) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L180) |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L182) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L189) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L195) |

package/api/README.md

@@ -2,6 +2,7 @@
 
 ## Packages
 
+- [@xmachines/core](@xmachines/core/README.md)
 - [@xmachines/play](@xmachines/play/README.md)
 - [@xmachines/play-actor](@xmachines/play-actor/README.md)
 - [@xmachines/play-atom](@xmachines/play-atom/README.md)

package/api/llms.txt

@@ -46,6 +46,7 @@
 - [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md): SvelteKit router adapter for actor-driven navigation
 - [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md): Svelte SPA router adapter for actor-driven navigation
 - [@xmachines/shared](@xmachines/shared/README.md): Shared TypeScript, oxlint, and formatting configuration
+- [@xmachines/core](@xmachines/core/README.md): BaseError, the release protocol (asDisposable), a key-value cache, and helpers for values and errors
 
 ## Notes For LLMs
 
@@ -63,8 +64,7 @@ import { withRouting } from '@xmachines/play-xstate/routing';
 import { withView } from '@xmachines/play-xstate/view';
 import { createRouteMapFromTree, extractRouteParams } from '@xmachines/play-router';
 import { extractMachineRoutes } from '@xmachines/play-router/xstate';
-import { defineRegistry } from '@xmachines/json-render-react';
-import { PlayRenderer } from '@xmachines/play-react';
+import { PlayUIProvider, PlayRenderer, defineRegistry } from '@xmachines/play-react';
 
 const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
 const actor = createPlayer();
@@ -76,6 +76,11 @@ const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 const stateId = routeMap.getStateIdByPath(currentRoute ?? '/');
 
-const { registry } = defineRegistry(catalog, { components, actions });
-<PlayRenderer actor={actor} registry={registry} actions={{ login: 'auth.login' }} />
+const registryResult = defineRegistry(catalog, {
+  components,
+  actions: { login: async ({ username }) => actor.send({ type: 'auth.login', username }) },
+});
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+  <PlayRenderer />
+</PlayUIProvider>
 ```