@xmachines/docs 5.0.2 → 6.1.0

package/guides/atoms.md

@@ -1,4 +1,4 @@
-# Understanding Atoms in XMachines
+# Atoms in XMachines
 
 Atoms are the reactive substrate connecting actors to the outside world in XMachines. This page explains what they are, why XMachines uses them instead of observables or callbacks, and how the atom primitives map to distinct roles in the architecture.
 
@@ -121,6 +121,16 @@ const subscription = actor.currentRoute.subscribe((route) => {
 subscription.unsubscribe();
 ```
 
+The subscription is a plain object. To hold it with `using`, publish it with `asDisposable` of [`@xmachines/core/utils`](../api/@xmachines/core/README.md), and name `unsubscribe` as the release:
+
+```typescript
+{
+	const plain = actor.currentRoute.subscribe((route) => render(route));
+	using subscription = asDisposable(plain, () => plain.unsubscribe());
+	render(actor.currentRoute.get());
+}
+```
+
 Two consequences follow from the synchronous delivery, and both matter:
 
 - Several writes in one tick call the observer several times. Nothing coalesces them.
@@ -157,9 +167,8 @@ Use [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) in frame
 
 ## The release, and `using`
 
-`watchAtom()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
-function, and a `Disposable`. One value therefore serves two forms, and the same holds for
-the mount of [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md) and for `history.subscribe()` of
+`watchAtom()` returns a plain function. The same holds for the mount of
+[`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md) and for `history.subscribe()` of
 [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md).
 
 Keep the explicit call where the release outlives the scope that made it — a field that a
@@ -170,12 +179,15 @@ const stop = watchAtom(actor.currentRoute, render);
 onUnmount(() => stop());
 ```
 
-Write `using` where the release belongs to one scope. The scope releases it, an exception
-releases it too, and the code carries no teardown:
+Where the release belongs to one scope, publish it with `asDisposable` of
+[`@xmachines/core/utils`](../api/@xmachines/core/README.md), and write `using`. The scope releases
+it, an exception releases it too, and the code carries no teardown:
 
 ```typescript
+import { asDisposable } from "@xmachines/core/utils";
+
 {
-	using stop = watchAtom(actor.currentRoute, render);
+	using stop = asDisposable(watchAtom(actor.currentRoute, render));
 	render(actor.currentRoute.get());
 	// stop() runs here, and it runs even when render() throws
 }
@@ -184,17 +196,17 @@ releases it too, and the code carries no teardown:
 A scope releases from the last declaration to the first, so a release that depends on an
 earlier one is safe.
 
-Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
+Every release here is synchronous, so `asDisposable` makes a `Disposable` and not an
 `AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
 `await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
-forces every holder into an async function. `asCleanup` therefore refuses a release that
-returns a value, and a promise above all — a promise handed to it would go on the floor,
-released and unawaitable.
+forces every holder into an async function. `asDisposable` therefore refuses a release that
+returns a value, a promise above all: the scope would ignore the promise, and nothing could
+await the work.
 
 `using` needs Node 24 or a browser with Explicit Resource Management. The publishable
 packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
-decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
-`Symbol.dispose` still calls it as a plain function.
+decides how to emit it. A caller that does not write `using` needs neither, and it needs no
+[`@xmachines/core/utils`](../api/@xmachines/core/README.md).
 
 ---
 
@@ -202,7 +214,7 @@ decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
 
 `@xstate/store` holds the active subscriber in a variable of its own module. Two copies in one application build two separate graphs: a computed atom of the first copy and a subscription of the second copy never meet, the subscriber stays silent, and no error reports the fault. Every propagation of state in this architecture goes through an atom, so the second copy stops the whole reactivity of an application.
 
-[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) therefore declares `@xstate/store` as a **peer** dependency. A renderer declares it no more, because it reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) and names the engine in no import. Install one copy, and install it yourself. `tests/singleton-peers.test.ts` holds the rule true inside this workspace.
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) therefore declares `@xstate/store` as a **peer** dependency. A renderer does not declare it, because it reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) and names the engine in no import. Install one copy, and install it yourself. `tests/singleton-peers.test.ts` holds the rule true inside this workspace.
 
 ---
 
@@ -256,8 +268,8 @@ Failing to clean up subscriptions causes memory leaks and stale callbacks firing
 
 ## See also
 
-- [Understanding the Actor Model](actor-model.md) — why the actor owns all atom writes
-- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that atoms derive
+- [The Actor Model](actor-model.md) — why the actor owns all atom writes
+- [State Machines](state-machines.md) — how state nodes produce the metadata that atoms derive
 - [Getting Started](getting-started.md) — hands-on walkthrough using atoms to observe an actor
 - [@xmachines/play-atom](../api/@xmachines/play-atom/README.md) — API reference
 - [Play RFC](../rfc/play.md) — architectural specification

package/guides/getting-started.md

@@ -151,19 +151,21 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 
 #### Step 1: Install the core packages
 
-Every XMachines application needs these four packages plus XState:
+Every XMachines application needs these six packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core
 ```
 
-| Package                                                             | Role                                                                                                                                                                            |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                           |
-| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                           |
-| `@xmachines/json-render-core`                                       | Spec and store types the actor layer builds on — a peer of [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), and of every renderer package                     |
+| Package                                                             | Role                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers                                                                                            |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                                                                                                                      |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                                                                                                                      |
+| [`@xmachines/play`](../api/@xmachines/play/README.md)               | The protocol: `PlayEvent`, and `PlayError` on its `errors` subpath — a peer of every package that reads it                                                                                                                                                                 |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)               | `BaseError`, the release protocol, and the cache — a peer of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) |
+| `@xmachines/json-render-core`                                       | The spec type that `PlaySpec` extends — a peer of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), and of every renderer package                                                                                                                           |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -277,7 +279,7 @@ const stop = watchAtom(actor.state, (snapshot) => {
 
 actor.send({ type: "toggle" }); // the callback runs from a microtask
 
-stop(); // release it, or write `using stop = watchAtom(...)`
+stop(); // release it, or write `using stop = asDisposable(watchAtom(...))`
 ```
 
 Three rules cover every use of them:
@@ -294,7 +296,7 @@ A renderer needs none of this: [`@xmachines/play-react`](../api/@xmachines/play-
 and the other renderers observe `currentView` for you. Reach for `watchAtom` when you
 write infrastructure, or a debug panel beside the UI.
 
-[Understanding Atoms](atoms.md) states the whole model.
+[Atoms](atoms.md) states the whole model.
 
 ---
 
@@ -667,11 +669,6 @@ on: {
 }
 ```
 
-(Older releases threw `MissingQueryContextError` at construction for a
-routing-aware context without a `query` field. That class is gone: the generated
-`play.route` transitions assign `query` on every navigation, so the loss it
-guarded against cannot happen.)
-
 #### Missing `id` on routable states
 
 **Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
@@ -749,6 +746,7 @@ node --version
 
 ## Next Steps
 
+- **[Views](views.md)** — Which state supplies the view, the `/context` projection, and when a renderer keeps the UI
 - **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector to see the machine, its transitions, and its context live
 - **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/guides/inspector.md

@@ -192,6 +192,6 @@ const createPlayer = definePlayer({ machine: appMachine, options });
 
 - **[`PlayerOptions`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
 - **[`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)** — the actor an inspector observes
-- **[Understanding the Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
+- **[The Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
 - **[Getting Started](getting-started.md)** — installing packages and creating your first actor
 - **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options

package/guides/routing.md

@@ -1,8 +1,8 @@
-# Understanding Routing in XMachines
+# Routing in XMachines
 
 A route of XMachines is a fact about a STATE, and not a fact about a component tree. A state node declares `meta.route`, and the library carries that declaration in both directions: a URL becomes a state, and a state becomes a URL.
 
-This guide states the pattern language one time, and it names the three rules that every one of the nine router adapters follows.
+This guide states the pattern language one time, it tells when a navigation re-enters a state, and it names the three rules that every one of the nine router adapters follows.
 
 After you read it, you know which patterns a route can declare, which side resolves a location, and why a bridge comes in a `connect()` and `disconnect()` pair.
 
@@ -19,13 +19,13 @@ The first direction needs a matcher, and every router writes its own. Express us
 
 `URLPattern` is the WHATWG standard for this, its syntax comes from `path-to-regexp`, and it is a superset of it. XMachines takes it as the pattern language, and it reads the whole of it.
 
-This is the same decision that [`@xmachines/play-atom`](atoms.md) makes for reactivity: one primitive, isolated behind one module, present on every runtime. There is no `AtomsUnavailableError`, because one package holds the reactive primitive and every consumer reads it from there, and there is no URLPattern availability error for the same reason.
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) makes the same decision for reactivity: one primitive, isolated behind one module, present on every runtime. The [Atoms](atoms.md) guide describes it.
 
 ### The API is always present
 
-[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
+[`@xmachines/play-url`](../api/@xmachines/play-url/README.md) carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
 
-The native API arrived in Chrome 95, in Firefox 142 and in Safari 26. The browser floor of this workspace is Chrome 110, Firefox 115 and Safari 16.4. Chrome carries the API at that floor, and Firefox and Safari carry it far above it, so a Firefox or a Safari at the floor runs the polyfill. `test/url-pattern-parity.test.ts` measures the two implementations against each other, form by form. They agree on every form of the grammar, and they disagree about one shape that no bridge can produce — see the prefix rule below.
+The native API arrived in Chrome 95, in Firefox 142 and in Safari 26. The browser floor of XMachines is Chrome 110, Firefox 115 and Safari 16.4. Chrome carries the API at that floor, and Firefox and Safari carry it far above it, so a Firefox or a Safari at the floor runs the polyfill. The test suite of [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) measures the two implementations against each other, form by form. They agree on every form of the grammar, and they disagree about one shape that no bridge can produce — see the prefix rule below.
 
 The cost is 18 kB, minified and with no dependency of its own, and a consumer whose runtime has the native API pays it too. A conditional load would save those bytes and it would make the module asynchronous: `RouteMap` compiles in its constructor, and a navigation matches inside an event handler. Neither can await.
 
@@ -116,12 +116,6 @@ The build resolves every escape, so the derived path carries the character and n
 backslash that protects it. `/tags/c\+\+` derives `/tags/c++`, which is the path that the
 route matches.
 
-**An escaped `:` is the one escape that stops at the bridge.** The build derives
-`/time/10:30` for `/time/10\:30`, and the route matches that path — but a bridge refuses
-to push a path that holds a `:`, because a `:` in a CONCRETE path marks a param that
-nothing substituted. `resolveNavigationPath` therefore answers `null`, and the address bar
-follows that state never. Write `%3A` instead, as the section below prescribes.
-
 ### A literal that the grammar would read
 
 `:`, `+`, `?`, `(` and `{` are characters of the grammar, so a route that writes one of them raw does not mean the literal. The two halves fail differently.
@@ -148,25 +142,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.
 
-**This is a change of behaviour, and a route of yours can hold one of these characters today.** An earlier release read a route as a pattern only when the route held a `:` or a `*`. `/tags/c++`, `/docs/rfc(2119)` and `/i18n/{en}` therefore went to the exact-match map, and each one matched the path that its author wrote. The route map reads the whole grammar now. `/tags/c++` throws `InvalidRoutePatternError` in the constructor of `RouteMap`, and the other two compile and match another path in silence. Add the escape to each route that writes one of these characters raw.
-
-A route that carries a QUERY STRING is the same case, and it is the form a machine writes most often. `meta: { route: "/dates?trip=one-way" }` reached the exact-match map before, and the bridge pushed it to the address bar with its query. The grammar reads that `?` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor now 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.
-
-### Upgrading from 3.x: the `reenter` default changed
-
-An earlier release wrote `reenter: true` on every transition that `formatPlayRouteTransitions` generated, so every routed state re-entered its own domain on each navigation and ran its `entry` actions again. The flag now comes from `meta.route`, and the default is `false`, which is the default of XState.
-
-**Nothing throws, and the `entry` action simply stops running.** A state that needs it declares the flag for itself:
-
-```ts
-states: {
-	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
-},
-```
-
-`reenter` spares the DOMAIN of the transition and not every ancestor that stays active. Under the default `handler: "root"` the domain is the root of the machine, so `false` spares the root alone and each ancestor between the root and the target still runs its `exit` and `entry` actions. `handler: "local"` and `handler: "both"` move the domain down to the parent, which is the field that spares those intermediate ancestors.
-
-CAUTION: `"local"` also SCOPES the route. The generated transition then sits on the parent alone, so a `play.route` event that arrives while the parent is inactive matches nothing and the actor does not move — a deep link or a press on BACK therefore leaves the URL and the actor divergent. Choose `"local"` where that scope is the intent, such as a step that a person reaches only inside its wizard. Choose `"both"` where the state must stay reachable from everywhere.
+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.
 
 ### The prefix rule
 
@@ -196,6 +172,28 @@ The cost is that you cannot write URLPattern's own reading of `:cat-id`. Use `:c
 
 ---
 
+## Re-entry on a navigation
+
+`formatPlayRouteTransitions` reads the `reenter` flag of each transition from `meta.route`. The default is `false`, which is the default of XState.
+
+The flag decides one thing: whether the DOMAIN of the transition runs its `exit` and `entry` actions again. Under the default `handler: "root"` the domain is the root of the machine. `"local"` and `"both"` put a transition on the parent, and while the parent is active that transition answers the event, so the domain is the parent.
+
+Each state below the domain on the path to the target runs its `exit` and `entry` actions on each navigation, whatever the flag says. The target itself is one of them, unless the route targets the root of the machine: the root is then the domain, and the flag decides. Under `"root"`, `false` therefore spares the root alone, and each ancestor between the root and the target runs its actions again. `handler` is the field that spares those intermediate ancestors.
+
+CAUTION: a parallel state loses the position of its other regions when it is the domain or a state below the domain. XState exits each active state below the domain, and not only the states on the path to the target. Each other region therefore enters its `initial` state again. A parallel root under `handler: "root"` is such a domain. With `reenter: true`, a `"local"` or `"both"` transition also exits the parent. Where the parent is a region of a parallel state, the other regions of that state enter their `initial` state again too.
+
+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
+states: {
+	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
+},
+```
+
+CAUTION: `"local"` also SCOPES the route. The generated transition then sits on the parent alone, so a `play.route` event that arrives while the parent is inactive matches nothing and the actor does not move — a deep link or a press on BACK therefore leaves the URL and the actor divergent. Choose `"local"` where that scope is the intent, such as a step that a person reaches only inside its wizard. Choose `"both"` where the state must stay reachable from everywhere.
+
+---
+
 ## The routing invariants
 
 ### 1. XMachines resolves the state id. The router never does
@@ -234,31 +232,29 @@ A bridge installs an atom subscription on the actor and a subscription on the ro
 
 ---
 
-## Why not a matcher of our own
-
-The 2.2.0 review asked whether a hand-written segment matcher could drop the `URLPattern` requirement. The answer is no, and the reason is not the size of the code.
+## Why not a smaller matcher
 
-A pattern language has to carry the largest set of features that the nine target routers can express, and not the subset that this repository happens to use today. A count of the patterns HERE — 85 of 88 are a literal plus `:name` — measures our own habits, and it is the wrong basis for the decision. `URLPattern` is the most expressive engine available, and a matcher of our own would carry less.
+A matcher that reads only a literal and `:name` covers most routes. It carries fewer features than the routers that XMachines supports, which is the problem that [the first section](#what-problem-urlpattern-solves) describes.
 
-Two matchers that disagree is also a worse failure than one dependency. The match and the extraction of the params would then read the same pattern differently, and a route would resolve while its params came back empty.
+One engine also keeps the match and the params in agreement. With two matchers, a route could resolve while its params came back empty.
 
 ---
 
 ## Summary
 
-| Question                                  | Answer                                                                              |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- |
-| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names                      |
-| Do I install a polyfill?                  | No. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries one |
-| Which side turns a URL into a state?      | XMachines, in every adapter                                                         |
-| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                                                |
-| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name                     |
-| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component                       |
+| Question                                  | Answer                                                                        |
+| ----------------------------------------- | ----------------------------------------------------------------------------- |
+| What is the pattern language?             | The `URLPattern` pathname grammar, plus hyphenated param names                |
+| Do I install a polyfill?                  | No. [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) carries one |
+| Which side turns a URL into a state?      | XMachines, in every adapter                                                   |
+| Which side turns a state into a URL?      | XMachines, with no URLPattern at all                                          |
+| When does the framework parse the params? | Vue Router and SolidJS Router, when the parse covers every name               |
+| Who releases the bridge?                  | You, through `disconnect()` in the teardown of your component                 |
 
 ## See also
 
-- [Understanding State Machines](state-machines.md) — how `meta.route` reaches the route map
-- [Understanding Atoms](atoms.md) — the same decision, made for reactivity
+- [State Machines](state-machines.md) — how `meta.route` reaches the route map
+- [Atoms](atoms.md) — the same decision, made for reactivity
 - [Multi-router integration](../examples/multi-router-integration.md) — the provider pattern and `basePath`, end to end
 - [Routing patterns](../examples/routing-patterns.md) — worked route maps
 - [@xmachines/play-router](../api/@xmachines/play-router/README.md) — API reference

package/guides/state-machines.md

@@ -1,4 +1,4 @@
-# Understanding State Machines in XMachines
+# 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.
 
@@ -122,12 +122,76 @@ 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 [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/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'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.
 
 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.
 
 **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`
+
+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
+const shell = typedSpec({
+	root: "shell",
+	state: { collapsed: false },
+	elements: {
+		shell: { type: "Shell", props: {}, children: ["title"], slots: { sidebar: [] } },
+		title: { type: "Heading", props: { text: "App" }, children: [] },
+	},
+	outlets: {
+		menu: { element: "shell", slot: "sidebar" }, // the region "menu"
+		"*": { element: "shell" }, //                 every other child
+	},
+});
+
+const appMachine = setup({/* ... */}).createMachine({
+	id: "app",
+	type: "parallel",
+	meta: { view: shell },
+	states: {
+		menu: { initial: "open", states: { open: { meta: { view: menuView } } } },
+		page: {
+			initial: "home",
+			states: {
+				home: { meta: { route: "/", view: homeView } },
+				search: { meta: { route: "/search", view: searchView } },
+			},
+		},
+	},
+});
+```
+
+- **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 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.
+
+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.
+
+**`handler` decides whether the layout survives a navigation.** Under the default `handler: "root"`, a navigation exits and enters every active state below the root, and a parallel state then puts its other regions back in their `initial` state. Declare `handler: "local"` or `"both"` on a routed state inside a region, as [Re-entry on a navigation](routing.md#re-entry-on-a-navigation) describes.
+
+**The URL comes from the routed region.** In a parallel machine, the URL comes from the first region whose active states declare a `meta.route`, so the `menu` region can come before the `page` region. Keep the routes of one layout in one region. The URL shows the route of the first routed region only, so a navigation to a route of a second routed region never shows in the address bar.
+
+CAUTION: a second routed region moves without its URL. Take a `page` region with `/` and `/search`, and a `drawer` region after it with `/drawer` and `/drawer/settings`:
+
+| Step                        | `page`   | `drawer`   | URL       |
+| --------------------------- | -------- | ---------- | --------- |
+| start                       | `home`   | `closed`   | `/`       |
+| a navigation to `#settings` | `home`   | `settings` | `/`       |
+| a navigation to `#search`   | `search` | `closed`   | `/search` |
+
+- The navigation to `#settings` moves the drawer, and the URL stays `/`. The browser adds no history entry, BACK does not close the drawer, and a reload or a shared link loses the drawer.
+- 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.
+
 ---
 
 ## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) — automatic route event wiring
@@ -276,9 +340,10 @@ actor.start();
 
 ## See also
 
-- [Understanding the Actor Model](actor-model.md) — how the machine definition becomes a live actor
-- [Understanding Atoms](atoms.md) — how the actor's state is observed by infrastructure
+- [The Actor Model](actor-model.md) — how the machine definition becomes a live actor
+- [Atoms](atoms.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
+- [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