@xmachines/docs 6.1.0 → 7.1.0

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:407](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L407)
 
 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:378](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L378)
 
 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:514](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L514)
 
 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:467](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L467)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 
@@ -26,9 +26,9 @@ packages this project actually depends on.
 
 ## Parameters
 
-| Parameter | Type       | Default value | Description                                                    |
-| --------- | ---------- | ------------- | -------------------------------------------------------------- |
-| `include` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
+| Parameter  | Type       | Default value | Description                                                    |
+| ---------- | ---------- | ------------- | -------------------------------------------------------------- |
+| `include?` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
 
 ## Returns
 

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:352](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L352)
 
 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:493](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L493)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -33,6 +33,6 @@ one and change the other.
 
 `object`
 
-| 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) |
+| Name                      | Type                                                    | Defined in                                                                                                                       |
+| ------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:494](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L494) |

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/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L25)
 
 Reads the test target from the `XM_TEST_TARGET` environment variable.
 
@@ -19,7 +19,7 @@ the suite against the source and report the result as a run against the build.
 
 | Parameter | Type         | Default value | Description                                            |
 | --------- | ------------ | ------------- | ------------------------------------------------------ |
-| `env`     | `ProcessEnv` | `process.env` | The environment to read. The default is `process.env`. |
+| `env?`    | `ProcessEnv` | `process.env` | The environment to read. The default is `process.env`. |
 
 ## Returns
 

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/docs-v7.1.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:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L230)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 
@@ -33,7 +33,7 @@ Playwright defaults. Plugins stay per-package arguments (`plugins: [vue()]`).
 | --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `importMetaUrl` | `string`                                                            | Pass `import.meta.url` from the calling config file.                                                                                                 |
 | `overrides`     | `UserConfig`                                                        | Package/project-specific Vitest config overrides. `overrides.test.name` is required — it names the project and keys the shared Vite cache directory. |
-| `options`       | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
+| `options?`      | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
 
 ## Returns
 

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/docs-v7.1.0/packages/shared/config/vitest.ts#L76)
 
 Create a Vitest config with XMachines workspace defaults.
 

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

@@ -2,15 +2,15 @@
 
 # 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:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L180)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
 
 ## Properties
 
-| 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) |
+| 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:188](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L188) |
+| <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:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L195) |
+| <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:201](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L201) |

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`