@xmachines/docs 6.0.0 → 7.0.0

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/v6.0.0/packages/shared/config/vite-aliases.ts#L334)
+Defined in: [vite-aliases.ts:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/v6.0.0/packages/shared/config/vite-aliases.ts#L335) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/v7.0.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/v7.0.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/v6.0.0/packages/shared/config/vitest.ts#L209)
+Defined in: [vitest.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/v6.0.0/packages/shared/config/vitest.ts#L65)
+Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/v6.0.0/packages/shared/config/vitest.ts#L159)
+Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/v6.0.0/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/v6.0.0/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/v6.0.0/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/v7.0.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/v7.0.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/v7.0.0/packages/shared/config/vitest.ts#L195) |

package/api/llms.txt

@@ -64,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();
@@ -77,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>
 ```

package/contributing/architecture.md

@@ -35,7 +35,7 @@ graph TD
     end
 
     subgraph ViewHalf["The View Half"]
-        view["@xmachines/play-view\n(Viewable, PlaySpec, the view store lifecycle)"]
+        view["@xmachines/play-view\n(Viewable, PlaySpec, the view session)"]
     end
 
     subgraph Concrete["Concrete Implementations"]
@@ -175,29 +175,37 @@ flowchart TD
     C["watchRouterChanges() subscribed"]
     D["getInitialRouterPath() reads current browser URL"]
     E["resolves sanitized URL path → stateId via routeMap"]
-    F{"Compare stateId vs actor.initialRoute"}
+    F{"Compare the URL, path and query, vs actor.initialRoute"}
     G["syncActorFromRouter()\nrouter wins — deep-link"]
     H["navigateRouter()\nactor wins — restore"]
 
     A --> B --> C --> D --> E --> F
-    F -->|"URL ≠ machine initial state"| G
-    F -->|"URL = machine initial state"| H
+    F -->|"URL ≠ initial URL (path or query)"| G
+    F -->|"URL = initial URL"| H
 ```
 
-### View Prop Enrichment
+### View derivation
 
 ```mermaid
 flowchart TD
-    A["XState snapshot.getMeta()"]
-    B["resolveViewMeta(meta)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
+    A["XState snapshot"]
+    T["resolveViewTree(root, snapshot.value)\na view with outlets composes the active children that an outlet shows;\nany other node takes its deepest view, the routed region first\nviewKey = the id of the state of the selected view"]
+    G["composeViews(tree) in play-view\nkept for each tree of each machine: elements, authored state, viewParts\nviewKey = the id of the outermost composing state"]
     C["snapshot.context\nprojected wholesale as the /context slice"]
     D["composePlayState(spec.state, slice)\nstate: { ...authored, context: slice }"]
-    E["reuseComposedState (in the currentView atom)\ncarry previous state reference when the slice is value-unchanged"]
+    E["reuseComposedState (the emit gate of the currentView atom)\nthe previous spec when nothing changed,\nits state reference when the slice is value-unchanged"]
     F["Derived PlaySpec (with viewKey) is the value of the currentView atom"]
 
-    A --> B --> C --> D --> E --> F
+    A --> T
+    T -->|"the selected view composes"| G --> C
+    T -->|"a view without outlets"| C
+    C --> D --> E --> F
 ```
 
+The composition keeps each element of the outer view by reference, except an element that receives a child view. It prefixes each key of a child view with the id of its state. play-xstate keeps one result of `composeViews` for each tree of views of each machine. A context assign therefore emits the same `elements` and `viewParts` references, and the emit gate of `withView` compares the top-level fields alone. One walk derives every view: a machine without `outlets` is its simple case, in which the deepest view wins. When the `viewKey` stays and the `viewParts` value changes, `createViewStoreLifecycle` writes the authored keys that the store does not hold. play-dom then gives the new spec to `setSpec` of the incremental renderer, which keeps each node whose element did not change.
+
+Each provider reads the view through `createViewSession` of play-view. The session resolves the store when the actor emits, when the host hands over a new actor or controlled store, and for a retry — never in a render. A provider binds the snapshot of the session to its framework: `useState` and a layout effect in play-react, a `shallowRef` in play-vue, a signal in play-solid, `$state.raw` in play-svelte, and a listener in play-dom. The subtree of the view is keyed on the `generation` of the store, and the error boundary resets on a new snapshot.
+
 **State atoms on the actor:**
 
 | Atom                 | Type                             | Description                                                                                                                                                                                                      |
@@ -226,6 +234,8 @@ Base class for the typed runtime errors of every Play package. It extends [`Base
 import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 
+declare const err: unknown;
+
 if (err instanceof RouterSyncError) {
 	/* err.scope, err.code, err.cause */
 }
@@ -245,7 +255,7 @@ Optional capability interface. Exposes `currentView: ReadonlyAtom<PlaySpec | nul
 
 ### [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)
 
-Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
+Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. An authored `outlets` field composes the views of the active substates into the view of their parent, and the composed spec also carries `viewParts`. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 
@@ -254,6 +264,13 @@ Concrete XState v5 actor. It extends XState's own `Actor` directly, and it imple
 [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) are OPTIONAL capabilities, and the class implements neither. Each one is a mixin behind its own entry point — [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) and [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) — and `compose` builds the class that an application needs:
 
 ```typescript
+import type { AnyStateMachine } from "xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+declare const machine: AnyStateMachine;
+
 definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
 ```
 
@@ -261,14 +278,18 @@ The core imports neither capability, so an application that declares no route lo
 
 **The composition order decides nothing.** `PlayerActor` writes ONE atom for each transition — `state` — and every capability that publishes a value DERIVES it with a computed atom over that one. The engine evaluates `currentRoute` and `currentView` from a single write, in topological order, so a router bridge sees a guard redirect and a renderer sees the view of the same snapshot whatever order `compose` applied.
 
-An earlier release wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there: two writes flushed two times, and an observer of `state` and `currentView` read the new state beside the old view in between. `onSnapshot` remains for a capability that must run an EFFECT on a transition, and an override still calls `super.onSnapshot()` first.
+A capability that must run an EFFECT on a transition overrides `onSnapshot`, and the override calls `super.onSnapshot()` first.
 
 ### [`definePlayer(config)`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/index/type-aliases/PlayerFactory.md)
 
 Factory creator. Each call constructs one `PlayerActor`, which is itself the XState actor and derives its own `initialRoute` from its pre-start snapshot. Restoring a snapshot is the exception: the default initial route can only come from XState's pure `initialTransition` helper, whose inert actor scope constructs a throwaway actor and evaluates the initial transition twice. Returns `(input?, restore?) => PlayerActor<TMachine>`.
 
 ```typescript
-import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+import { definePlayer, type PlayerOptions } from "@xmachines/play-xstate";
+
+declare const machine: AnyStateMachine;
+declare const options: PlayerOptions<AnyStateMachine>;
 
 const createPlayer = definePlayer({ machine, options });
 const actor = createPlayer(); // or createPlayer(input) or createPlayer(undefined, { snapshot })
@@ -280,6 +301,8 @@ actor.start();
 Abstract base class capturing all common router bridge logic. Template Method pattern — subclasses implement exactly three abstract methods: `navigateRouter(path)`, `watchRouterChanges()`, `unwatchRouterChanges()`. Manages `isConnected`, `lastSyncedPath` (echo suppression), `isProcessingNavigation` (re-entrant guard redirect prevention), and `routeWatcher` lifecycle. Enforces one-bridge-per-actor via a module-level `WeakMap`.
 
 ```typescript
+import { RouterBridgeBase } from "@xmachines/play-router";
+
 class MyRouterBridge extends RouterBridgeBase {
 	protected navigateRouter(path: string): void {
 		/* push URL */
@@ -346,7 +369,7 @@ Per-view component state is managed by `@xstate/store`: a fresh store atom is cr
 
 All eight router adapter packages follow the Template Method pattern via [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md). Each adapter implements exactly three abstract methods:
 
-```typescript
+```typescript fragment
 // How to tell the framework router to change URL
 protected abstract navigateRouter(path: string): void;
 
@@ -382,7 +405,7 @@ packages/
 ├── play-actor/                 # Layer 1: the PlayActor contract — state and send, and nothing else
 ├── play-pattern/               # Layer 1: the route pattern language — one parse, and the path it builds back
 ├── play-url/                   # Layer 2: the URL layer — the URLPattern API, a base path, framework params
-├── play-view/                  # Layer 2: Viewable, PlaySpec, the view store lifecycle, the context projection
+├── play-view/                  # Layer 2: Viewable, PlaySpec, the view session, the context projection
 │
 ├── play-xstate/                # Layer 4: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
@@ -436,7 +459,7 @@ packages/<name>/
 
 The monorepo uses **TypeScript composite project references** (`"composite": true` per package) for a correct, incremental, dependency-ordered build. The root `tsconfig.json` lists every package in layer order — leaves first, dependents last — and it is the ONLY build order of the workspace. `tsc --build` at the root reads that array and resolves the graph.
 
-**The layer table and the diagram live in [development.md](development.md#build-layers).** They stood here too, and the copy drifted: it kept the numbers of an earlier release, so a reader who added a package placed it in the wrong block of the root array. One home for the question, as for the `references` arrays that the root file replaced.
+**The layer table and the diagram live in [development.md](development.md#build-layers).**
 
 Two facts about the graph belong to this document, because they are architecture and not build order:
 
@@ -516,36 +539,49 @@ import { InvalidEventError } from "@xmachines/play-xstate/errors";
 
 ## Application Bootstrap (React example)
 
-```typescript
+```tsx
+import { createRootRoute, createRouter } from "@tanstack/react-router";
 import { setup } from "xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { createRouteMapFromTree, PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
-import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { PlayUIProvider, PlayRenderer, type PlayUIProviderProps } from "@xmachines/play-react";
 
 // 1. Define machine — meta.route declares virtual routes; meta.view declares UI specs
 const machineConfig = formatPlayRouteTransitions({
-  id: "app",
-  initial: "home",
-  context: { params: {}, query: {} },
-  states: {
-    home: {
-      id: "home",
-      meta: {
-        route: "/",
-        view: { root: "home", elements: { home: { type: "HomePage", props: {}, children: [] } } }
-      }
-    },
-    profile: {
-      id: "profile",
-      meta: {
-        route: "/profile/:userId",
-        view: { root: "profile", elements: { profile: { type: "ProfilePage", props: { userId: undefined }, children: [] } } }
-      }
-    },
-  },
+	id: "app",
+	initial: "home",
+	context: { params: {}, query: {} },
+	states: {
+		home: {
+			id: "home",
+			meta: {
+				route: "/",
+				view: {
+					root: "home",
+					elements: { home: { type: "HomePage", props: {}, children: [] } },
+				},
+			},
+		},
+		profile: {
+			id: "profile",
+			meta: {
+				route: "/profile/:userId",
+				view: {
+					root: "profile",
+					elements: {
+						profile: {
+							type: "ProfilePage",
+							props: { userId: undefined },
+							children: [],
+						},
+					},
+				},
+			},
+		},
+	},
 });
 
 const machine = setup({}).createMachine(machineConfig);
@@ -559,18 +595,26 @@ const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRou
 const actor = createPlayer();
 actor.start();
 
-// 4. Define component registry for json-render
-const registryResult = defineRegistry({ /* components */ });
+// 4. Create the framework router. The machine owns the routes, so the route tree is one root route
+const router = createRouter({ routeTree: createRootRoute() });
 
-// 5. Render — framework providers wire actor → router → view
+// 5. Define component registry for json-render: defineRegistry(catalog, { components })
+declare const registryResult: PlayUIProviderProps["registryResult"];
+
+// 6. Render — the router provider wires actor → router, and its renderer callback renders the view
 function App() {
-  return (
-    <PlayRouterProvider actor={actor} router={router} routeMap={routeMap}>
-      <PlayUIProvider actor={actor} registryResult={registryResult}>
-        <PlayRenderer />
-      </PlayUIProvider>
-    </PlayRouterProvider>
-  );
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor) => (
+				<PlayUIProvider actor={currentActor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			)}
+		/>
+	);
 }
 ```
 
@@ -578,7 +622,7 @@ function App() {
 
 ### Importing `@xstate/store` directly
 
-```typescript
+```typescript fragment
 // ❌ Wrong — bypasses the atom isolation layer, and names the engine in your own .d.ts
 import { createAtom } from "@xstate/store";
 
@@ -588,12 +632,13 @@ import { createAtom } from "@xmachines/play-atom";
 
 ### Using framework state for business logic
 
-```typescript
+```typescript fragment
 // ❌ Wrong — violates INV-03 (Atom-Only Reactivity) and INV-04 (Passive Infrastructure)
 const [currentUser, setCurrentUser] = useState(null);
 
-// ✅ Correct — observe the actor atom directly
-const currentUser = useActorSelector(actor, (s) => s.context.currentUser);
+// ✅ Correct — observe the actor atom directly; React state only triggers the render
+const [currentUser, setCurrentUser] = useState(actor.state.get().context.currentUser);
+useAtomEffect([actor.state], () => setCurrentUser(actor.state.get().context.currentUser));
 ```
 
 ### Calling `navigateRouter` inside `watchRouterChanges`
@@ -614,7 +659,7 @@ Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()
 
 Five paths reach that case. The host gives no `onError` prop. The handler of the host throws, or the producer of the `fallback` throws, or a release of the caller throws — each of those reports the failure of the HOST, which no handler of the host receives. `ActorProvider` of play-vue stops a second report of one error, and `onError` stays silent there on purpose, because the four other renderers see such an error never.
 
-Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) names a `/context` projection that it cannot derive, one time for each spec; [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
+Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) names a `/context` projection that it cannot derive, one time for each spec; [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) names a `meta.view.contextProps` field, which the view does not read, one time for each spec; and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
 
 **Authentication:** Not in scope. Enforced via XState guards on `play.route` transitions. The guard evaluates machine `context` (e.g., `isLoggedIn`) before permitting navigation. No library-level auth primitives — the machine defines all access control.
 

package/contributing/configuration.md

@@ -6,12 +6,20 @@ This document describes every configuration file, environment variable, and per-
 
 ## Environment Variables
 
-The monorepo itself has no application runtime that reads environment variables. The only variables are for the **dev container** tooling and the **CI/CD release pipeline**.
+The monorepo itself has no application runtime that reads environment variables. The only variables are for the **dev container** tooling, the **test runs**, and the **CI/CD release pipeline**.
 
 ### Dev Container Variables
 
 The dev container currently defines no workspace-specific environment variables; `.devcontainer/.env` (loaded via `env_file` in `.devcontainer/compose.yaml`) is available for local overrides if a future tool needs one. Copy `.devcontainer/.env.sample` to `.devcontainer/.env` to get started.
 
+### Test Run Variable
+
+| Variable         | Required | Default  | Description                                                                                                                                                      |
+| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `XM_TEST_TARGET` | Optional | `source` | The code that a test run loads for each published package: `source` (the `src/` tree) or `dist` (the build output). Any other value stops the run with an error. |
+
+**Defined in:** the `test:dist` and `test:browser:dist` scripts of the root `package.json`. **Read by:** `xmTestTarget` of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md), which every config helper of that package calls. Do not set it by hand: run `pnpm run test:dist`. See [testing.md](testing.md#tests-on-the-build-output).
+
 ### CI / Release Pipeline Variable
 
 | Variable            | Required | Default                      | Description                                                                                                                                                                         |
@@ -96,19 +104,20 @@ All packages extend this base. Key compiler settings:
 | `exactOptionalPropertyTypes` | `true`       |                                                          |
 | `declaration`                | `true`       | Emits `.d.ts` files                                      |
 | `declarationMap`             | `true`       | Emits `.d.ts.map` for IDE go-to-source                   |
+| `emitDeclarationOnly`        | `true`       | tsc emits no JavaScript: the Vite pass ships it          |
 | `sourceMap`                  | `true`       |                                                          |
 | `verbatimModuleSyntax`       | `true`       | Preserves `import type`                                  |
 | `isolatedModules`            | `true`       |                                                          |
 | `removeComments`             | `false`      | Preserves JSDoc in output                                |
 
-**Two passes emit, and `emitDeclarationOnly` decides which one ships.** `build` is
-`vite build && tsc --build`, so tsc runs last.
+**Vite writes the JavaScript, and tsc writes the declarations.** `build` is
+`vite build && tsc --build`. The shared tsconfig sets `emitDeclarationOnly`, so tsc emits
+only `.d.ts` and `.d.ts.map`, and the Vite pass is the published `dist/*.js` of every
+package. `build.target` governs it.
 
-- **Fourteen publishable packages** let tsc emit JavaScript. tsc overwrites the Vite pass,
-  and `compilerOptions.target` above is what governs the published `dist/*.js`.
-- **Five** — play-vue, play-svelte, play-solid, play-solid-router,
-  play-tanstack-solid-router — set `emitDeclarationOnly`, so tsc emits only `.d.ts` and the
-  Vite pass is the published JavaScript. `build.target` governs theirs.
+Vite emits a module that holds only types as no file. Its `.d.ts` still ships. A test that
+imports such a module by path, or an internal re-export module that no entry reaches, fails
+in the dist run: import the module that holds the code.
 
 Vite inherits no target from the tsconfig. It reads `compilerOptions.target` for one
 purpose: to pick the `useDefineForClassFields` default that it gives the transform. The
@@ -118,7 +127,7 @@ explicit browser list for a demo app.
 
 Leave both stated, and keep both at ESNext for a library. A package that inherits the Vite
 default builds against a browser baseline, which is a second and lower ceiling than the one
-this table declares — and it is the ceiling that ships for those five.
+this table declares — and it is the ceiling that ships.
 
 **A demo states an explicit browser list, and not `baseline-widely-available`.** A target
 controls syntax and adds no method. `baseline-widely-available` of Vite 8 names
@@ -157,6 +166,9 @@ The root config extends the shared base ([`@xmachines/shared/oxlint`](../api/@xm
 
 ```typescript
 // /oxlint.config.ts
+import sharedConfig from "@xmachines/shared/oxlint";
+import { defineConfig } from "oxlint";
+
 export default defineConfig({
 	extends: [sharedConfig],
 	ignorePatterns: [
@@ -221,6 +233,9 @@ The root config extends the shared base and adds workspace-level ignore patterns
 
 ```typescript
 // /oxfmt.config.ts
+import sharedConfig from "@xmachines/shared/oxfmt";
+import { defineConfig } from "oxfmt";
+
 export default defineConfig({
 	...sharedConfig,
 	ignorePatterns: [
@@ -329,7 +344,7 @@ stays.
 
 **Location:** `/vitest.config.ts`
 **Tool:** [Vitest](https://vitest.dev/) `^4.1.5`
-**Run:** `pnpm test` / `pnpm run test:coverage`
+**Run:** `pnpm test` / `pnpm run test:coverage` / `pnpm run test:dist`
 
 Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
 
@@ -354,8 +369,10 @@ Root Vitest config is a **workspace coordinator** that lists all per-package con
 
 Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
 
+The JUnit file is `test-results.xml`. CI runs the suites on the build output alone (`XM_TEST_TARGET=dist`), so each test counts one time in the merge request widget. In the dist run, `coverage.include` also names `packages/*/dist/**/*.js`, and `excludeAfterRemap` filters again after the source maps name the files of `src/`. The dist run leaves out the `doc-examples` project: `pnpm run test:docs:examples` runs it.
+
 **Browser test config:** `/vitest.browser.config.ts`
-Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
+Run with `pnpm run test:browser`, or with `pnpm run test:browser:dist` against the build output. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
 
 ### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
@@ -365,6 +382,8 @@ Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mo
 Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
 
 - `resolve.alias` via `xmAliases()` so `@xmachines/*` imports resolve to TypeScript source without a prior build.
+- In the dist run, the `xmBuildOutput` plugin. The alias map then holds no published package, so each `@xmachines/*` import resolves through its `exports` map to `dist/`. The plugin moves each `src/` file that a test imports by path to its counterpart in `dist/`.
+- `test.provide.xmTestTarget`, which a test reads with `inject("xmTestTarget")`.
 - `vitest.node.setup.ts` for non-browser projects (if not already present).
 - `vitest.setup.ts` for all projects (if not already present).
 
@@ -387,10 +406,12 @@ export default defineXmVitestConfig(import.meta.url, {
 **Location:** `packages/shared/config/vite-aliases.ts`
 **Exported as:** [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md)
 
-Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
+Provides the helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
-- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
-- **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
+- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`. In the dist run, the map holds no entry for a published package except `<name>/src`.
+- **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: false`. It sets no `conditions`: the aliases do the work that the `source` condition does for TypeScript.
+- **`xmTestTarget()`** — reads `XM_TEST_TARGET`, and returns `source` or `dist`.
+- **`xmBuildOutput(import.meta.url)`** — the Vite plugin of the dist run. It moves each `src/` file of a published package to its counterpart in `dist/`, and it fails the import when the build output holds no such file. It also fails the run when anything loads a `src/` file of a published package.
 - **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
 - **`xmOptimizeDeps(include?)`** — returns an `optimizeDeps.include` list holding exactly the specifiers passed in. Nothing is pre-bundled by default, and every entry has to be a package the calling project declares: pnpm gives each package its own `node_modules`, so Vite cannot resolve an undeclared specifier — it warns on stderr and carries on, which reads as a failure in a passing job.
 
@@ -436,6 +457,26 @@ Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which th
 
 ---
 
+### Dependency Updates — `renovate.json5`
+
+**Location:** `/renovate.json5`
+**Tool:** [Renovate](https://docs.renovatebot.com/), from the `xmachin-es/renovate` project
+
+Renovate updates the npm dependencies of every package of the workspace, the demos under `packages/*/examples/*` too. It also updates the to-be-continuous components that `.gitlab-ci.yml` includes. The bot runs one time each week. For each new version, it opens a merge request, and the pipeline of that merge request tests the new version. The Dependency Dashboard issue lists every update that Renovate knows.
+
+The rules of the file:
+
+- **Three days of cooldown.** The renovate component waits 3 days for a new version, which also covers the cooldown of one day in pnpm. The `@xmachines/*` packages have no cooldown, as in `pnpm-workspace.yaml`.
+- **One merge request for json-render.** The `@xmachines/json-render-*` packages move together. The merge request moves every range, the `peerDependencies` too, as a `feat(deps):` commit. Renovate proposes the prereleases of the fork (`0.22.0-xm.1`), which it skips by default. Update the ranges that the README files name on the branch of that merge request.
+- **No new major for an override of one major.** An override with a major in its key, for example `zod@4`, gets no update to the next major.
+- **Approval for a patched package.** `pnpm-workspace.yaml` patches `@testing-library/jest-dom` at one version. An update of that package needs a new patch. Approve it in the Dependency Dashboard, then move the patch on its branch.
+- **Approval for a TypeScript major.** A new major of `typescript` waits in the Dependency Dashboard. typedoc reads the TypeScript API, and it declares the majors that it supports. The `docs` job is manual in a merge request, so a green pipeline does not show the fault. Approve the update when typedoc supports the new major.
+- **Commit types.** A component update is a `ci:` commit, so semantic-release makes no release from it. An npm update is a `fix(deps):` commit for a `dependencies` entry, and a `chore(deps):` commit for any other type.
+
+A new version of a component can rename an input and not say so. A pipeline that fails with no job is then an error in the inputs. Compare the inputs in `.gitlab-ci.yml` with the `spec` of the new version before you merge.
+
+---
+
 ## Per-Environment Overrides
 
 This monorepo has no application-level config with per-environment overrides (no `.env.development` / `.env.production` files). All configuration is tool-level (TypeScript, linter, formatter, test runner) and is environment-agnostic.

package/contributing/deployment.md

@@ -76,15 +76,15 @@ The `node-build` job runs one command:
 pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
 ```
 
-It runs no test. The `test` job owns the unit suite, so `node-build` skips its own with `NODE_TEST_ARGS`. It also builds no documentation: the `docs` job below does that.
+It runs no test. The `test:dist` job owns the unit suite, so `node-build` skips its own with `NODE_TEST_ARGS`. It also builds no documentation: the `docs` job below does that.
 
-Coverage comes from the `test` job, through the regex:
+Coverage comes from the `test:dist` job, through the regex:
 
 ```
 /All files[^|]*\|[^|]*\s+([\d\.]+)/
 ```
 
-That job publishes the JUnit results as `reports/test-results.xml` and the Cobertura coverage as `reports/cobertura-coverage.xml`. `vitest.config.ts` names both paths, and `COVERAGE_REPORTS_DIR` points them at `reports/`.
+That job runs the suites on the `dist/` of `node-build`, and it maps the coverage back to `src/` through the source maps. It publishes the JUnit results as `reports/test-results.xml` and the Cobertura coverage as `reports/cobertura-coverage.xml`. `vitest.config.ts` names both paths, and `COVERAGE_REPORTS_DIR` points them at `reports/`.
 
 ### Docs Job