@xmachines/docs 6.1.0 → 8.0.0-next.1

package/guides/routing.md

@@ -55,8 +55,13 @@ A **modifier** follows a param, a wildcard or a group:
 | `*`      | zero or more | matches                  |
 
 ```ts
+import { createMachine, types } from "xstate";
+
 const machine = createMachine({
 	id: "app",
+	// XState 6 types the `meta` of each state from this schema
+	schemas: { meta: types<{ route?: string }>() },
+	initial: "home",
 	states: {
 		home: { meta: { route: "/" } },
 		profile: { meta: { route: "/profile/:userId" } },
@@ -142,7 +147,7 @@ This rule is about the PATTERN that a state declares. A param VALUE needs no esc
 
 `encodeURIComponent` leaves `*` as it stands, and that is the one exception. A bridge refuses a path that still holds a `:` or a `*`, because such a character marks a param that nothing substituted. A value of `a*b` therefore stops the push, and the URL stays where it is.
 
-A route that carries a QUERY STRING is the same case as a raw `?`, and it is the form a machine writes most often. The grammar reads the `?` of `meta: { route: "/dates?trip=one-way" }` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition assigns and `buildRouteUrl` writes to the URL.
+A route that carries a QUERY STRING is the same case as a raw `?`, and it is the form a machine writes most often. The grammar reads the `?` of `meta: { route: "/dates?trip=one-way" }` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition writes and `buildRouteUrl` writes to the URL.
 
 ### The prefix rule
 
@@ -184,7 +189,7 @@ CAUTION: a parallel state loses the position of its other regions when it is the
 
 A state whose navigation must re-enter the domain too declares the flag for itself. Here the root runs its `exit` and `entry` actions on each navigation to `dashboard`:
 
-```ts
+```ts fragment
 states: {
 	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
 },

package/guides/state-machines.md

@@ -1,6 +1,6 @@
 # State Machines in XMachines
 
-XMachines uses XState v5 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
+XMachines uses XState v6 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
 
 After reading this, you will understand what a machine definition actually encodes — and why state machines are a better unit of business logic than component-level state or ad-hoc if/else trees.
 
@@ -22,18 +22,20 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ---
 
-## How XMachines uses XState v5
+## How XMachines uses XState v6
 
-XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
+XMachines wraps XState v6 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 
 const authSetup = setup({
-	types: {
-		context: {} as { username: string | null },
-		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
+	schemas: {
+		context: types<{ username: string | null }>(),
+		events: {
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": types<void>(),
+		},
 	},
 });
 
@@ -44,20 +46,18 @@ const authMachine = authSetup.createMachine({
 	states: {
 		unauthenticated: {
 			on: {
-				"auth.login": {
+				"auth.login": ({ event }) => ({
 					target: "authenticated",
-					actions: authSetup.assign({
-						username: ({ event }) => event.username,
-					}),
-				},
+					context: { username: event.username },
+				}),
 			},
 		},
 		authenticated: {
 			on: {
-				"auth.logout": {
+				"auth.logout": () => ({
 					target: "unauthenticated",
-					actions: authSetup.assign({ username: null }),
-				},
+					context: { username: null },
+				}),
 			},
 		},
 	},
@@ -66,8 +66,8 @@ const authMachine = authSetup.createMachine({
 
 Key patterns:
 
-- **Always use `setup({ types })`** before `createMachine`. The type declarations let TypeScript check that your events, context fields, and actions are consistent throughout the machine.
-- **Use `setup.assign()`**, not the bare `assign` from xstate. This keeps the type checker aware of which context fields the action touches.
+- **Always use `setup({ schemas })`** before `createMachine`. `types<T>()` declares a schema for the type alone. The schemas let TypeScript check that your events, context fields, and transitions are consistent throughout the machine. `events` is a map from the type of each event to its payload.
+- **Return a context patch** from a transition function: `{ context: { username: null } }`. XState 6 merges the patch into the context at the top level, and it has no `assign` action.
 - **Event names use lowercase dot-separated namespaces**: `"auth.login"`, `"play.route"`, `"form.submit"`. This convention makes the event log readable and avoids collisions.
 
 ---
@@ -77,9 +77,13 @@ Key patterns:
 XMachines extends XState's `meta` field on each state node. This is where routing intent and view structure live:
 
 ```typescript
-import { typedSpec } from "@xmachines/play-view";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+import { setup, types } from "xstate";
 
-const appMachine = setup({/* ... */}).createMachine({
+const appMachine = setup({
+	// XState 6 types the `meta` of each state from this schema.
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -122,10 +126,12 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `ReadonlyAtom`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md) — a `@xmachines/json-render-core` spec object describing what to render. The actor derives a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) from it, and that derived spec is what a renderer receives. Use `typedSpec(...)` from [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md) — a `@xmachines/json-render-core` spec object describing what to render. The actor derives a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) from it, and that derived spec is what a renderer receives. Use `typedSpec(...)` from [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) to type-check the spec literal at the definition site. XState 6 types `meta` from `schemas.meta` of the machine, and a state cannot declare a `meta` that the schema does not name. When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
 
 The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
+**Give each state its own id, and do not use an array index as an id.** XState 6 throws when two states declare the same explicit id, because a repeated id makes a `#id` target name two states. XMachines keys the route, the view and its store on the id of a state, so two states that share an id share one route entry, one store, and one key. An array index is a whole number from 0 to 2³² − 2 with no leading zero, such as `"42"`. JavaScript lists such a key first in every object that is keyed on ids, so the route of its state loses its place in the branch. [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) writes one warning for each machine that breaks these rules.
+
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 
 ### A layout and its pages: `outlets`
@@ -133,6 +139,11 @@ The machine's whole context is available to every view through the **`/context`
 Without outlets, the deepest active state that declares a view wins, and a view on a parent state stays off the screen. Declare `outlets` in the view of the parent to show the parent view AND the view of its active child. Each outlet names an element of the parent view, and the view of the child goes into that element:
 
 ```typescript
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+import { setup, types } from "xstate";
+
+declare const menuView: ViewMeta, homeView: ViewMeta, searchView: ViewMeta; // your views
+
 const shell = typedSpec({
 	root: "shell",
 	state: { collapsed: false },
@@ -146,7 +157,9 @@ const shell = typedSpec({
 	},
 });
 
-const appMachine = setup({/* ... */}).createMachine({
+const appMachine = setup({
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	type: "parallel",
 	meta: { view: shell },
@@ -166,11 +179,11 @@ const appMachine = setup({/* ... */}).createMachine({
 - **The key of an outlet** is the key of a child state in `states`, or `"*"` for each active child that has no outlet of its own. A child with neither stays off the screen.
 - **A compound state** fills one outlet with its active child. **A parallel state** fills one outlet for each region, in the order of `states`.
 - **`slot`** names a named slot of the element. Omit it to append the child view to the `children` of the element. The component of the element renders the slot, as the renderer of your framework describes.
-- **The view of a child** is the deepest view in its active subtree, and a child view can declare `outlets` of its own for a nested layout. A parallel state without outlets shows the region of the URL when that region has a view, and its first region that has a view otherwise.
+- **The view of a child** is the deepest view in its active subtree, and a child view can declare `outlets` of its own for a nested layout. A parallel state without outlets shows the region of the routes when that region has a view, and its first region that has a view otherwise. The region of the routes keeps the screen while it sits in a state without a route of its own.
 
 The derived spec holds the elements of every composed view. The keys of the outer view stay as you wrote them, and each key of a child view gets the id of its state as a prefix, for example `app.page.search/root`, so two views never collide.
 
-The `viewKey` of a composed view is the id of the outermost state that declares `outlets`. A change of the page therefore keeps the store of the layout: the `collapsed` value in the example above does not change. The first time that a page shows, the provider writes the keys of its authored `state` that the store does not hold. A page that comes back finds the values that it left. All the pages of one layout share one store, so two pages that declare the same key share one value: give each page its own keys. When two composed views declare the same state key, the outer view wins, and the library writes a warning.
+The `viewKey` of a composed view is the id of the outermost state that declares `outlets`. A change of the page therefore keeps the store of the layout: the `collapsed` value in the example above does not change. The first time that a page shows, the provider writes the keys of its authored `state` that the store does not hold. A page that comes back finds the values that it left. All the pages of one layout share one store, so two pages that declare the same key share one value: give each page its own keys. When two composed views declare the same state key, the outer view wins. The library writes one warning for each layout that names every key that two of its views declare, also for two pages that are never on the screen together.
 
 An outlet that names an element that its view does not hold throws `InvalidViewOutletError`. The actor reports it through its `onError` option, and it keeps the last good view.
 
@@ -190,7 +203,7 @@ CAUTION: a second routed region moves without its URL. Take a `page` region with
 - A deep link to `/drawer/settings` moves the drawer too, but the actor derives the URL `/` from the `page` region, so the address bar does not keep the path of the drawer.
 - The navigation to `#search` puts the drawer back to `closed`, because the default `handler: "root"` exits and enters every region. `handler: "local"` keeps it.
 
-A URL path has one hierarchy, and it cannot hold the branches of two regions. Keep the other regions unrouted. When the position of such a region must survive a reload or a shared link, write it as a query value of the routed region, for example `/search?drawer=settings`. The generated `play.route` transition assigns the query to `context.query`, the URL carries `context.query`, and your machine moves the region to match the value.
+A URL path has one hierarchy, and it cannot hold the branches of two regions. Keep the other regions unrouted. When the position of such a region must survive a reload or a shared link, write it as a query value of the routed region, for example `/search?drawer=settings`. The generated `play.route` transition writes the query to `context.query`, the URL carries `context.query`, and your machine moves the region to match the value.
 
 ---
 
@@ -198,15 +211,15 @@ A URL path has one hierarchy, and it cannot hold the branches of two regions. Ke
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
-```typescript
+```typescript fragment
 // Without formatPlayRouteTransitions — verbose and repetitive
 states: {
   home: {
     on: {
-      "play.route": [
-        { guard: ({ event }) => event.to === "#login", target: "login" },
-        { guard: ({ event }) => event.to === "#dashboard", target: "dashboard" },
-      ],
+      "play.route": ({ event }) => {
+        if (event.to === "#login") return { target: "login" };
+        if (event.to === "#dashboard") return { target: "dashboard" };
+      },
     },
     meta: { route: "/" },
   },
@@ -218,8 +231,11 @@ states: {
 
 ```typescript
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { setup, types } from "xstate";
 
-const appMachine = setup({/* ... */}).createMachine(
+const appMachine = setup({
+	schemas: { meta: types<{ route?: string }>() },
+}).createMachine(
 	formatPlayRouteTransitions({
 		id: "app",
 		initial: "home",
@@ -232,16 +248,19 @@ const appMachine = setup({/* ... */}).createMachine(
 );
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` transitions. Each one is a config object: `matches: { to: "#<id>" }` selects the event, and a `context` mapper returns the patch with the `params` and the `query` of the event. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present), and the event map must declare `play.route`:
 
-```typescript
-types: {
-  context: {} as {
+```typescript fragment
+schemas: {
+  context: types<{
     params: Record<string, string>;
     query:  Record<string, string>;
     // ... other context fields
+  }>(),
+  events: {
+    "play.route": types<Omit<PlayRouteEvent, "type">>(),
+    // ... other events
   },
-  events: {} as PlayRouteEvent | OtherEvents,
 }
 ```
 
@@ -249,56 +268,67 @@ types: {
 
 ## Guards — the actor's authority
 
-Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
+Guards are the mechanism by which the actor controls whether a transition occurs. In XState 6 the transition function is the guard: it returns nothing to refuse the event. A named guard of `setup()` is a pure predicate, and a transition function calls it through its `guards` argument:
 
 ```typescript
-const authSetup = setup({
+import { setup, types } from "xstate";
+
+const authMachine = setup({
+	schemas: {
+		context: types<{ isAuthenticated: boolean; role: "user" | "admin" }>(),
+		events: { "admin.open": types<void>() },
+	},
 	guards: {
-		isAuthenticated: ({ context }) => context.isAuthenticated,
-		isAdmin: ({ context }) => context.role === "admin",
+		isAdmin: (role: "user" | "admin") => role === "admin",
+	},
+}).createMachine({
+	context: { isAuthenticated: false, role: "user" },
+	initial: "home",
+	states: {
+		home: {
+			on: {
+				"admin.open": ({ context, guards }) =>
+					context.isAuthenticated && guards.isAdmin(context.role)
+						? { target: "admin" }
+						: undefined,
+			},
+		},
+		admin: {},
 	},
 });
 ```
 
-Guards are evaluated by XState before a transition fires. If the guard returns `false`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
+XState evaluates the transition function before a transition fires. If the function returns nothing, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-Compose a condition with the combinators of XState:
-
-| Function        | What it does                |
-| --------------- | --------------------------- |
-| `and([g1, g2])` | AND — every guard must pass |
-| `or([g1, g2])`  | OR — one guard must pass    |
-| `not(g)`        | NOT — it inverts the guard  |
-
-Each combinator resolves a guard NAME against the `guards` of `setup()`, so a name that the map does not hold fails to compile.
+XState 6 has no guard combinators. Combine conditions with `&&`, `||` and `!` inside the transition function. A guard name that the `guards` map does not hold fails to compile.
 
 ---
 
 ## Context — persistent state across transitions
 
-Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
+Context is the machine's persistent data store. It survives transitions. A transition function and an entry or exit function read it, and they change it with a returned patch:
 
-```typescript
-// Context is defined in setup({ types })
-types: {
-  context: {} as {
+```typescript fragment
+// Context is declared in setup({ schemas })
+schemas: {
+  context: types<{
     isAuthenticated: boolean;
     username: string | null;
     loginAttempts: number;
-  },
+  }>(),
 },
 
-// Actions mutate context via assign
-actions: {
-  recordLoginFailure: assign({
-    loginAttempts: ({ context }) => context.loginAttempts + 1,
+// A transition function changes the context with a patch
+on: {
+  "auth.failed": ({ context }) => ({
+    context: { loginAttempts: context.loginAttempts + 1 },
   }),
 },
 ```
 
-Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via atoms — only the derived atoms (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a computed atom to the actor that derives from `actor.state`.
+Context is accessed in transition functions, and when computing routes or views. It is not directly observable from outside the actor via atoms — only the derived atoms (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a computed atom to the actor that derives from `actor.state`.
 
 ---
 
@@ -307,22 +337,30 @@ Context is accessed in guards, actions, and when computing routes or views. It i
 A snapshot is a point-in-time serialisation of the machine's current state and context. XState produces snapshots in a JSON-compatible format:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
 const snapshot = actor.getSnapshot();
 // snapshot.value → current state node name, e.g. "dashboard"
 // snapshot.context → current context object
 
-// Stop and serialize
+// Serialize and stop
+const saved = JSON.stringify(actor.getPersistedSnapshot());
 actor.stop();
-const saved = JSON.stringify(snapshot);
 
 // Restore
-const restored = JSON.parse(saved);
-const actor = createPlayer(undefined, { snapshot: restored });
-actor.start();
+const restored = createPlayer(undefined, { snapshot: JSON.parse(saved) });
+restored.start();
 // Actor resumes from where it left off
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+The factory that [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns accepts an optional second argument, `{ snapshot }`, for this purpose. Serialize the result of `getPersistedSnapshot()`, and not of `getSnapshot()`: XState restores from the persisted form. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---
 
@@ -346,5 +384,5 @@ actor.start();
 - [Views](views.md) — which state supplies the view, how a layout holds its pages, and when a renderer keeps the UI
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), and the routing utilities
-- [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [XState documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation. The migration guide of XState 6 ships in the `docs` folder of the `xstate` package
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/views.md

@@ -37,10 +37,12 @@ A machine and its specs therefore change never when you change the framework. Yo
 A `meta.view` is a [`ViewMeta`](../api/@xmachines/play-view/index/interfaces/ViewMeta.md). `root` names the first element, and `elements` holds every element by its key:
 
 ```ts
-import { setup } from "xstate";
-import { typedSpec } from "@xmachines/play-view";
+import { setup, types } from "xstate";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
 
-const machine = setup({}).createMachine({
+const machine = setup({
+	schemas: { meta: types<{ view?: ViewMeta }>() },
+}).createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -59,7 +61,7 @@ const machine = setup({}).createMachine({
 });
 ```
 
-XState types `meta` as `Record<string, unknown>`, so TypeScript checks nothing that you write there. `typedSpec` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) gives the literal the type `ViewMeta` where you write it, and it does nothing at run time. The check of an excess property works on an inline literal only. For a spec in a variable, write `satisfies ViewMeta` at the literal.
+XState 6 types `meta` from `schemas.meta` of the machine, and a state cannot declare a `meta` that the schema does not name. Declare `view?: ViewMeta` there. `typedSpec` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) gives the literal the type `ViewMeta` where you write it, and it does nothing at run time. The check of an excess property works on an inline literal only. For a spec in a variable, write `satisfies ViewMeta` at the literal.
 
 A `ViewMeta` is what you WRITE. A [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) is what the actor DERIVES from it, and what a renderer receives. The derivation consumes `outlets`, it adds the machine context, and it stamps `viewKey` and `viewParts`.
 
@@ -68,6 +70,9 @@ The view is an OPTIONAL capability of the actor. Compose it with `withView` of [
 ```ts
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withView } from "@xmachines/play-xstate/view";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
 
 const actor = definePlayer({ machine, actor: compose(PlayerActor, withView) })();
 actor.start();
@@ -81,7 +86,7 @@ The actor then holds `currentView`, a `ReadonlyAtom<PlaySpec | null>`. An applic
 
 **The deepest active state that declares a view supplies it**, unless a parent composes it. A state that declares no view shows the view of its nearest ancestor that declares one. An ancestor view without `outlets` does not show, because the view of its descendant replaces it:
 
-```ts
+```ts fragment
 states: {
 	dashboard: {
 		meta: { view: dashboardView },   // shows in dashboard.overview
@@ -96,13 +101,13 @@ states: {
 
 When no active state declares a view, `currentView` holds `null`, and the renderer shows its `fallback` content.
 
-A **parallel** state follows the same region as the route derivation: the first region whose active states declare a `meta.route`, or the first region when no region does. The view on the screen therefore belongs to the region of the URL. When that region holds no view, the view comes from another active region, so one region can own the URL and another region can own the view. Keep the routes in one region: the [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows what a second routed region does to the URL.
+A **parallel** state follows the same region as the route derivation: the first region whose active states declare a `meta.route`, else the first region that declares a route in any state, else the first region. A region that owns the routes therefore keeps the screen while it sits in a state without a route, such as a load. The view on the screen therefore belongs to the region of the URL. When that region holds no view, the view comes from another active region, so one region can own the URL and another region can own the view. Keep the routes in one region: the [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows what a second routed region does to the URL.
 
 ### A layout and its pages: `outlets`
 
 A parent view that declares `outlets` shows itself AND the view of its active child. Each outlet names an element of the parent view, and the view of the child goes into that element:
 
-```ts
+```ts fragment
 const shell = typedSpec({
 	root: "shell",
 	state: { collapsed: false },
@@ -130,6 +135,7 @@ states: {
 - `slot` names a named slot of the element. Omit it, and the renderer appends the child view to the `children` of the element.
 - The view of a child is the deepest view below it. A child view can declare `outlets` of its own, for a nested layout.
 - An outlet that names an element that its view does not hold throws `InvalidViewOutletError`. The actor reports it through `onError`, and it keeps the last valid view.
+- The keys of the outer view carry no prefix, and each key of a child view gets the id of its state and a `/` as a prefix. A key of the outer view such as `"page/root"` equals the key of the element `root` of the child state `page`, and the composition throws `ViewElementKeyCollisionError`. Do not start a key of the outer view with the id of a state and a `/`.
 
 The derived spec is ONE flat spec. The keys of the outer view stay as you wrote them. Each key of a child view gets the id of its state as a prefix: the `root` element of the view of the state `app.search` becomes `app.search/root`. Two views therefore never collide. The [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows a parallel layout with a named slot.
 
@@ -149,7 +155,7 @@ derived state = { ...meta.view.state, context: <the machine context> }
 
 A spec reads the context through the ordinary state grammar of json-render. The same path works in a prop, in a `visible` condition, and in `repeat.statePath`:
 
-```ts
+```ts fragment
 elements: {
 	greeting: { type: "Text", props: { text: { $state: "/context/username" } }, children: [] },
 	tasks: {
@@ -189,7 +195,7 @@ Domain state is the state of the application. Each change of it is an event, so
 
 This login form uses both. The field binds to `/username`, and the submit sends the value to the machine:
 
-```ts
+```ts fragment
 view: typedSpec({
 	root: "form",
 	state: { username: "" },
@@ -215,10 +221,26 @@ Keep high-frequency data in the ephemeral state or in a child actor, and not in
 A component emits a named event of json-render, such as `submit` or `press`. The `on` field of its element maps that name to an ACTION, with params that the renderer resolves from the store. The registry holds the handler of each action, and a handler of a domain action sends a machine event:
 
 ```ts
+import { defineCatalog } from "@xmachines/json-render-core";
+import { defineRegistry, schema, type ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+import { z } from "zod";
+
+declare const actor: ViewActor<unknown, { type: "auth.login"; username: string }>;
+
+const catalog = defineCatalog(schema, {
+	components: { Login: { props: z.object({ username: z.string() }) } },
+	actions: { login: { params: z.object({ username: z.string() }) } },
+});
+
+declare const Login: ComponentFn<typeof catalog, "Login">; // your component
+
 const registryResult = defineRegistry(catalog, {
 	components: { Login },
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 	},
 });
 ```
@@ -227,7 +249,7 @@ The guards of the machine then decide. The renderer changes no state of the mach
 
 The renderer implements four built-in actions over the ephemeral state: `setState`, `pushState`, `removeState` and `validateForm`. They need no handler in the registry. An `on` entry can hold an array of bindings, and the renderer runs them in order. For example, it sends the event, and then it clears the draft:
 
-```ts
+```ts fragment
 on: {
 	press: [
 		{ action: "addTask", params: { title: { $state: "/newTaskTitle" } } },
@@ -255,18 +277,18 @@ A renderer holds one view store for each view, and the `viewKey` decides its lif
 
 With the same `viewKey`, every renderer keeps the DOM nodes, the focus and the ephemeral state. A context change therefore updates a list under a field that has the focus, and the draft in the field stays.
 
-With a new `viewKey`, the ephemeral state starts again from `spec.state`. Two sibling states that each declare a view therefore reset a draft on each transition between them, also when their two specs are equal.
+With a new `viewKey`, the ephemeral state starts again from `spec.state`, and every renderer builds the view again. The state that a component keeps for itself, such as the text of an unbound input, goes with the old view. Two sibling states that each declare a view therefore reset a draft on each transition between them, also when their two specs are equal.
 
 A parent keeps the ephemeral state across a move between its children in one of two ways:
 
 - **Declare the view on the parent**, and no view on the children. The `viewKey` stays the id of the parent.
 - **Declare `outlets` on the parent.** The `viewKey` stays the id of the parent, and each child still shows its own view. A change of the page keeps the store of the layout, so the `collapsed` value of the [layout above](#a-layout-and-its-pages-outlets) does not change.
 
-In a composed view, all the views of one layout share ONE store. The first time that a page shows, the renderer writes each key of its authored `state` that the store does not hold. A page that comes back finds the values that it left. Two pages that declare the same key therefore share one value: give each page its own keys. When two composed views declare the same key, the outer view wins, and a warning names the key.
+In a composed view, all the views of one layout share ONE store. The first time that a page shows, the renderer writes each key of its authored `state` that the store does not hold. A page that comes back finds the values that it left. Two pages that declare the same key therefore share one value: give each page its own keys. When two composed views declare the same key, the outer view wins. play-xstate reads the states of the machine one time, and it writes one warning for each layout that names every key that two of its views declare.
 
 `currentView` also emits only on a real change of the view on the screen. An event that changes no context field and moves to no other view keeps the previous reference, and no subscriber runs. The gate compares the top-level fields of the context. It does not enter a value, so a new object in a field emits again, also when its contents are equal.
 
-In the **controlled mode**, you give the provider a `store`. The provider then ignores `spec.state`, and you own the seed and the lifetime of that store. The renderer still owns `/context`, and it refreshes the subtree in your store on each emission.
+In the **controlled mode**, you give the provider a `store`. The provider then ignores `spec.state`, and you own the seed and the lifetime of that store. The renderer still owns `/context`, and it refreshes the subtree in your store on each emission. The tree lives as long as its store, so a new `viewKey` keeps the tree in the controlled mode, and a new store builds it again.
 
 ---
 
@@ -274,16 +296,16 @@ In the **controlled mode**, you give the provider a `store`. The provider then i
 
 A failure of the DERIVATION stays inside the actor. `currentView` catches it, it keeps the last valid view, and it reports the error to the `onError` hook of the actor in a microtask. The transition continues for every other observer.
 
-A failure of the RENDER stays inside the provider. When a component throws, or the store does not resolve, the provider shows its `fallback` and it calls its own `onError` prop:
+A failure of the RENDER stays inside the provider. When a component throws, when the store does not resolve, or when the root of the view fails, the provider shows its `fallback` and it calls its own `onError` prop:
 
 | Renderer                                                          | The `onError` prop of the provider |
 | ----------------------------------------------------------------- | ---------------------------------- |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | `(error, info, reset) => void`     |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | `(error, reset, info) => void`     |
 | the four other renderers                                          | `(error, reset) => void`           |
 
 The provider reports one failure one time for one set of inputs — the actor, the view and the store — and not one time for each render. A new emission, or a call of `reset`, makes the next failure report again. Without `onError`, the provider writes the failure to `console.error`, so that no failure is silent. A handler that throws does not break the containment: the provider writes that failure to `console.error` too.
 
-`onRenderError` receives the failure of one catalog component, with the name of the component, and it replaces every handler of `defineRegistry`.
+`onRenderError` receives each failure that json-render reports, with `(error, name, info)`, and it replaces every handler of `defineRegistry`. `info.kind` names the failure: a catalog component that throws (`"element"`), a prop or a `visible` condition of a child (`"props"`, `"visible"`), an action chain or a watch chain (`"action"`, `"watch"`), or the root (`"root"`). A failure of the ROOT — its component, a prop, or its `visible` condition — leaves no view on the screen. json-render gives it to no error boundary of the host, so each of the five providers contains it as a failure of the view: it shows its `fallback`, it calls `onError` one time, and the next view renders again. `onRenderError` also receives it, with the kind `"root"`. A failure below the root reaches `onRenderError` alone, and the rest of the view stays. Without a handler of the host, the provider writes one console line for a failure of the root, and not two.
 
 ---
 
@@ -319,7 +341,7 @@ A provider takes a `ViewActor`: the actor contract and the `Viewable` capability
 
 Each one exports `schema` for `defineCatalog`, and `defineRegistry` for its own components. `PlayUIProvider` takes the `actor`, the `registryResult`, and the optional `store`, `fallback`, `onError` and `onRenderError`. The [Getting Started](getting-started.md#connecting-a-view-renderer) guide shows a complete mount for each framework.
 
-[`@xmachines/play-view`](../api/@xmachines/play-view/README.md) holds the part that the five share: the store lifecycle, the `/context` guard and the report rules. A shared contract suite runs the same scenarios against each renderer, so the five agree on what a viewer sees.
+[`@xmachines/play-view`](../api/@xmachines/play-view/README.md) holds the part that the five share: the view session, which resolves the store of each view outside a render, the `/context` guard and the report guard. A shared contract suite runs the same scenarios against each renderer, so the five agree on what a viewer sees.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "6.1.0",
+  "version": "8.0.0-next.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -56,13 +56,13 @@
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^7.0.1",
-    "@types/node": "^26.6.2",
-    "oxfmt": "^0.70.0",
-    "oxlint": "^1.85.0",
+    "@types/node": "^26.6.4",
+    "oxfmt": "^0.71.0",
+    "oxlint": "^1.86.0",
     "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.13.0",
-    "vitest": "^5.0.1"
+    "typedoc-plugin-markdown": "^4.13.1",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=24.0.0"

package/rfc/git.md

@@ -25,10 +25,10 @@ Git is optional.
 
 ## 2. Model
 
-- machines = orphan branches
-- runs = forks
-- events = commits
-- snapshots = commits
+- machines = orphan branches (the definition is `machine.json`)
+- runs = forks (the fork commit adds `run.json`)
+- event batches = commits (one commit per appended batch, as `events.ndjson`)
+- snapshots = commits (`snapshot.json`)
 
 History is append-only.
 
@@ -37,7 +37,15 @@ History is append-only.
 ## 3. Identity
 
 - commit hashes are canonical IDs
-- same algorithm used with or without Git
+- IDs are Git object IDs in the **SHA-1** object format; SHA-256 repositories are
+  out of scope
+- IDs hash the **exact bytes** of each file: JSON is written as
+  `JSON.stringify(value, null, 2)` and a final newline, and `events.ndjson` has one
+  `JSON.stringify(event)` line per event
+- key order is kept: it is part of a machine definition (the order of `states` is
+  XState's document order), so a definition with reordered keys is another machine
+  with another ID
+- same algorithm used with or without Git: the same value gives the same ID
 
 ---