@xmachines/docs 6.1.0 → 8.0.0-next.1

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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L474)
 
 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:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L174)
 
 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:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/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/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L195) |

package/contributing/architecture.md

@@ -4,7 +4,7 @@ XMachines Play implements the **Universal Player Architecture** — a layered, a
 
 ## System Overview
 
-XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes atoms emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through atoms — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v6 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes atoms emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through atoms — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
 
 ## Architectural Invariants
 
@@ -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"]
@@ -86,7 +86,7 @@ The diagram groups the packages by role. The build order is a separate view: eac
 | [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | The atom primitives, isolated in one package            | `packages/play-atom/src/index.ts`                                   |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `PlayActor`, and nothing else                           | `packages/play-actor/src/play-actor.ts`                             |
 | [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `Viewable`, `PlaySpec`, the shared view half            | `packages/play-view/src/view-types.ts`                              |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v5 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v6 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
 | [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md)                             | The route pattern language: one parse, and `buildPath`  | `packages/play-pattern/src/pattern-grammar.ts`                      |
 | [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | The URLPattern API, a base path, framework params       | `packages/play-url/src/url-pattern-utils.ts`                        |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `RouteMap`, `RouterBridgeBase`, the provider lifecycle  | `packages/play-router/src/router-bridge-base.ts`                    |
@@ -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 change of the context 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 */
 }
@@ -259,11 +259,18 @@ Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the m
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 
-Concrete XState v5 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to atoms. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
+Concrete XState v6 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to atoms. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
 
 [`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 */
@@ -327,7 +340,7 @@ Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It
 
 ### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
-Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition targets the matching state, guards on `event.to === "#stateId"`, and assigns `event.params` and `event.query` to context. Returns the same config type `T` — directly usable by `setup().createMachine()`.
+Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition is a config object: it targets the matching state, it selects the event with `matches: { to: "#stateId" }`, and its `context` mapper returns a patch with `event.params` and `event.query`. The `play.route` entry is a list, with the generated transitions first and a transition of the machine last. Returns the same config type `T` — directly usable by `setup().createMachine()`.
 
 ## View Renderer Pattern
 
@@ -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,9 +405,9 @@ 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
+├── play-xstate/                # Layer 4: Concrete XState v6 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
@@ -469,7 +482,7 @@ The **protocol layer** is `play`, `play-atom` and `play-actor`. `play` reads `co
 | URL layer (`play-url`)                | Protocol layer, `play-pattern`, `urlpattern-polyfill`   | Any other `@xmachines/*` package |
 | View half (`play-view`)               | Protocol layer, `@xmachines/json-render-core`           | Router adapters, framework code  |
 | Actor logic (`play-xstate`)           | Protocol layer, `play-pattern`, `xstate`                | View renderers, router adapters  |
-| Router infrastructure (`play-router`) | Protocol layer, `play-url`, `@statelyai/graph`          | View renderers                   |
+| Router infrastructure (`play-router`) | Protocol layer, `play-url`, `xstate`                    | View renderers                   |
 | Router adapters (`play-*-router`)     | `play-router`, protocol layer, framework router lib     | View renderers                   |
 | View renderers (`play-*`)             | Protocol layer, `play-view`, `@xmachines/json-render-*` | Router adapters                  |
 
@@ -526,39 +539,56 @@ import { InvalidEventError } from "@xmachines/play-xstate/errors";
 
 ## Application Bootstrap (React example)
 
-```typescript
-import { setup } from "xstate";
+```tsx
+import { createRootRoute, createRouter } from "@tanstack/react-router";
+import { setup, types } 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";
+import type { ViewMeta } from "@xmachines/play-view";
 
 // 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);
+// XState 6 types the `meta` of each state from `schemas.meta`
+const machine = setup({
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine(machineConfig);
 
 // 2. Build route map from machine definition (done once at startup)
 const routeTree = extractMachineRoutes(machine);
@@ -569,18 +599,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 +626,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 +636,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`