@xmachines/docs 6.1.0 → 7.0.0

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/v6.1.0/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/v7.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
 
 The minimal structural shape of one XState state node, as
 `formatPlayRouteTransitions` reads it during its walk over the machine config.
@@ -29,7 +29,7 @@ signature without a change.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/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/v7.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
 
 The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
@@ -41,7 +41,7 @@ The optional explicit state ID, for example `"home"` or `"settings"`. It is the
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/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/v7.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -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/v6.1.0/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/v7.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
 
 The event handlers of this state. The function reads them where a child asks for a
 local `play.route` handler, so that the transitions of the user survive the merge.
@@ -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/v6.1.0/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/v7.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L46)
 
 The nested child states. The function walks them for each further route declaration.

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

@@ -6,7 +6,7 @@
 function withView<TMachine>(Base): PlayerConstructor<TMachine, Viewable>;
 ```
 
-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)
+Defined in: [packages/play-xstate/src/with-view.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-xstate/src/with-view.ts#L61)
 
 Adds the view capability to an actor class.
 

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

@@ -126,6 +126,7 @@ Use `xmAliases` for the aliases alone. Use `xmResolve` for a resolve config that
 In a browser test project, use `xmOptimizeDeps` to bundle the packages in advance. The optimizer then does not restart during a run. Use `xmCacheDir` to share one Vite dependency cache across the workspace:
 
 ```typescript
+import { defineConfig } from "vite";
 import { xmResolve, xmOptimizeDeps, xmCacheDir } from "@xmachines/shared/vite-aliases";
 
 export default defineConfig({

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

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl, target?): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L292)
+Defined in: [vite-aliases.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L292)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 

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

@@ -6,7 +6,7 @@
 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)
+Defined in: [vite-aliases.ts:388](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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/`.

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

@@ -6,7 +6,7 @@
 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)
+Defined in: [vite-aliases.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L359)
 
 The file in `dist/` that the build writes for one source file of a package.
 

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

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L495)
+Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L448)
+Defined in: [vite-aliases.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L333)
+Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.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:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L474)
+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:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vite-aliases.ts#L475) |
+| `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

@@ -6,7 +6,7 @@
 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)
+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.
 

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

@@ -6,7 +6,7 @@
 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)
+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.
 

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

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L224)
+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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L76)
+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.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/shared/config/vitest.ts#L174)
+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: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) |
+| <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/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,13 +175,13 @@ 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 derivation
@@ -189,24 +189,22 @@ flowchart TD
 ```mermaid
 flowchart TD
     A["XState snapshot"]
-    O{"a state node of the machine\ndeclares meta.view.outlets?\n(cached for each machine)"}
-    T["resolveViewTree(root, snapshot.value)\na view with outlets composes its active children;\nany other node keeps its deepest view"]
-    G["composeViews(tree) in play-view\ncached for each tree: elements, authored state, viewParts\nviewKey = the id of the outermost composing state"]
-    B["resolveViewMeta(active branch: the routed region first)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
+    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 --> O
-    O -->|"yes"| T
-    T -->|"an active view composes"| G --> C
-    T -->|"no active view composes:\nthe view that the walk resolved"| C
-    O -->|"no"| B --> C
+    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. `composeViews` caches the result for each tree of view objects. A context assign therefore emits the same `elements` and `viewParts` references, and the emit gate of `withView` walks no element. 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.
+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:**
 
@@ -236,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 */
 }
@@ -264,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) });
 ```
 
@@ -278,7 +285,11 @@ A capability that must run an EFFECT on a transition overrides `onSnapshot`, and
 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 })
@@ -290,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 */
@@ -356,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;
 
@@ -392,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/
@@ -526,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);
@@ -569,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>
+			)}
+		/>
+	);
 }
 ```
 
@@ -588,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";
 
@@ -598,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`

package/contributing/configuration.md

@@ -104,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
@@ -126,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
@@ -165,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: [
@@ -229,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: [
@@ -362,7 +369,7 @@ 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`. The dist run (`XM_TEST_TARGET=dist`) writes `test-results-dist.xml`, and it prefixes each class name with `dist:`, so the two runs stay apart in the merge request widget.
+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`, 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`).
@@ -459,10 +466,11 @@ Renovate updates the npm dependencies of every package of the workspace, the dem
 
 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 11. The `@xmachines/*` packages have no cooldown, as in `pnpm-workspace.yaml`.
+- **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 audit floor.** An override with a major in its key, for example `brace-expansion@2`, gets no update to the next major.
-- **Approval for a patched package.** `pnpm-workspace.yaml` patches `@testing-library/jest-dom` and `@vitest/mocker` at one version. An update of these packages, or of vitest, needs a new patch. Approve it in the Dependency Dashboard, then move the patch on its branch.
+- **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.

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