@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play-dom-router/interfaces/RouteMap.md

@@ -2,32 +2,33 @@
 
 # Interface: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L105)
 
-Shared bidirectional route map base class.
+The shared base class of the route map for both directions.
 
-All framework adapters use this class as their route map — they add no logic of their
-own and inherit the full public API from here.
+Every framework adapter uses this class as its route map. An adapter adds no logic
+of its own, and it inherits the complete public API from here.
 
-**Lookup strategy:**
+**The strategy of a lookup:**
 
-- Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
-  of routes sharing the same first path segment
-- Results are cached after the first match in an LRU cache (default 500 entries,
-  configurable via the `cacheSize` constructor option)
+- A static path, without a `:param` → a `Map` lookup in O(1)
+- A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
+  `k` is the number of the routes with the same first path segment
+- The class keeps each result of a first match in an LRU cache. The default size
+  is 500 entries, and the `cacheSize` constructor option changes it
 
-**Pattern syntax** (`:param` / `:param?` / `*`):
+**The syntax of a pattern** (`:param`, `:param?`, and `*`):
 
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-- `*` — wildcard, matches any number of segments (URLPattern semantics)
+- `:param` — a necessary segment. It matches exactly one segment without a `/`
+- `:param?` — an optional segment. It matches zero segments or one segment without a `/`
+- `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
-**StateId forms:** stateIds may be registered and looked up in either
-`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
-`getStateIdByPath` returns the stateId exactly as registered;
-`getPathByStateId` accepts both forms. Registering the same stateId in both
-forms refers to one entry (the later registration wins for reverse lookup).
+**The forms of a stateId:** you can register a stateId, and you can look one up,
+in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
+canonical form itself. `getStateIdByPath` returns the stateId exactly as you
+registered it, and `getPathByStateId` accepts both forms. A registration of the
+same stateId in both forms gives one entry, and the later registration wins for
+the lookup in the other direction.
 
 ## Example
 
@@ -57,31 +58,31 @@ map.getPathByStateId("missing"); // null
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [play-router/src/base-route-map.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L225)
 
-Look up the path pattern registered for a state ID.
+Returns the path pattern of a state ID.
 
-Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
-which form was used at registration — lookups are canonicalized internally,
-so consumers never need to try both forms.
+The method accepts the stateId in the form `"#stateId"` and in the form
+`"stateId"`, and the form of the registration has no effect. The method makes the
+canonical form itself. Therefore a consumer tries never both forms.
 
 #### Parameters
 
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+| Parameter | Type     | Description                                                                 |
+| --------- | -------- | --------------------------------------------------------------------------- |
+| `stateId` | `string` | The state ID of the state machine, for example `"profile"` or `"#settings"` |
 
 #### Returns
 
 `string` \| `null`
 
-The registered path pattern, or `null` if the state ID is unknown
+The registered path pattern, or `null` when the state ID is unknown
 
 #### Example
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("#profile"); // "/profile/:userId" — the same entry
 map.getPathByStateId("missing"); // null
 ```
 
@@ -93,25 +94,25 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [play-router/src/base-route-map.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L185)
 
-Resolve a URL path to its mapped state ID.
+Resolves a URL path to its state ID.
 
-Strips query strings and hash fragments before matching. Tries an O(1) exact
-lookup first, then falls back to bucket-indexed pattern matching. Results are
-cached after the first pattern match.
+The method removes the query string and the hash fragment before the match. It
+tries an exact lookup in O(1) first, then it uses the pattern match on the bucket
+index. It keeps each result of a first pattern match in the cache.
 
 #### Parameters
 
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+| Parameter | Type     | Description                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------- |
+| `path`    | `string` | The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"` |
 
 #### Returns
 
 `string` \| `null`
 
-The mapped state ID, or `null` if no route matches
+The state ID of the path, or `null` when no route matches
 
 #### Example
 

package/api/@xmachines/play-dom-router/interfaces/RouteMapOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L9)
 
-Options for `createRouteMap` and `createRouteMapFromTree`.
+The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                          |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L20) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L21) |

package/api/@xmachines/play-dom-router/interfaces/RouteMapping.md

@@ -2,14 +2,15 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L54)
 
-A single state ID ↔ path mapping entry.
+One entry of the map between a state ID and a path.
 
-Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
-Adapter packages re-export a structurally compatible `RouteMapping` type under
-their own name. This type is published from `@xmachines/play-router` as
-`RouteMapping` to avoid name collisions with those adapter-local types.
+Both fields are `readonly`, because a mapping is immutable after the caller gives
+it to `RouteMap`. An adapter package re-exports a structurally compatible
+`RouteMapping` type under its own name. `@xmachines/play-router` publishes this
+type as `RouteMapping`, and its name therefore does not collide with such a local
+type of an adapter.
 
 ## Example
 
@@ -21,7 +22,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                      |
-| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L53) |
+| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L56) |

package/api/@xmachines/play-dom-router/interfaces/RouterBridge.md

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L358)
 
-RouterBridge interface for runtime infrastructure adapters
+The RouterBridge interface of a runtime infrastructure adapter
 
-Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
-the Actor. Infrastructure "bridges" to the Actor by observing its signals and
-managing its own lifecycle accordingly.
+The interface defines the connection of the lifecycle between the infrastructure,
+for example a framework router, and the Actor. The infrastructure builds a "bridge"
+to the Actor: it observes the signals of the Actor, and it manages its own
+lifecycle accordingly.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
-a unidirectional observation pattern. Infrastructure connects to observe Actor signals
-(currentRoute, currentView, state) and reflects changes without making state decisions.
+**Architectural context:** the interface implements **Passive Infrastructure
+(INV-04)**, because it gives an observation in one direction. The infrastructure
+connects to observe the signals of the Actor (currentRoute, currentView, and
+state), and it reflects each change. It makes no decision about the state.
 
 ## Example
 
-Framework router bridge implementation
+The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
@@ -26,7 +28,7 @@ class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
-		// Start observing actor.currentRoute signal
+		// Start the observation of the actor.currentRoute signal
 		this.watcher = new Signal.subtle.Watcher(() => {
 			const route = actor.currentRoute.get();
 			if (route) router.navigate(route);
@@ -35,7 +37,7 @@ class MyRouterBridge implements RouterBridge {
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop observing, cleanup watchers
+		// Stop the observation, and clean the watchers up
 		this.watcher?.unwatch(actor.currentRoute);
 		this.watcher = null;
 	}
@@ -44,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -54,25 +56,26 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L375)
 
-Connect the router bridge to the Actor
+Connects the router bridge to the Actor
 
-Called when Infrastructure should begin observing Actor signals and
-synchronizing its state (e.g., browser URL) with Actor state.
+The infrastructure calls it when it must start the observation of the Actor
+signals, and when it must bring its own state, for example the browser URL, in line
+with the Actor state.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when connection is established, or void for synchronous connection
+The promise that resolves after the connection, or void for a synchronous connection
 
 #### Example
 
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// Bridge now observing actor.currentRoute signal
+// The bridge observes the actor.currentRoute signal now
 ```
 
 ---
@@ -83,22 +86,22 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L391)
 
-Disconnect the router bridge from the Actor
+Disconnects the router bridge from the Actor
 
-Called when Infrastructure should stop observing and clean up resources
-(e.g., signal watchers, event listeners).
+The infrastructure calls it when it must stop the observation and free its
+resources, for example a signal watcher and an event listener.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when disconnection is complete, or void for synchronous disconnection
+The promise that resolves after the disconnection, or void for a synchronous disconnection
 
 #### Example
 
 ```typescript
 await bridge.disconnect();
-// Bridge stopped observing, resources cleaned up
+// The bridge stopped its observation, and it freed its resources
 ```

package/api/@xmachines/play-dom-router/interfaces/VanillaRouter.md

@@ -2,14 +2,14 @@
 
 # Interface: VanillaRouter
 
-Defined in: [play-dom-router/src/create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-router.ts#L4)
+Defined in: [play-dom-router/src/create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-router.ts#L4)
 
 ## Properties
 
-| Property                                    | Modifier   | Type                                                     | Description                          | Defined in                                                                                                                                            |
-| ------------------------------------------- | ---------- | -------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md)                    | History instance                     | [play-dom-router/src/create-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-router.ts#L8)   |
-| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | Route tree (for structure reference) | [play-dom-router/src/create-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-router.ts#L13) |
+| Property                                    | Modifier   | Type                                                     | Description                                     | Defined in                                                                                                                                            |
+| ------------------------------------------- | ---------- | -------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md)                    | The history instance                            | [play-dom-router/src/create-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-router.ts#L8)   |
+| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | The route tree, as a reference to the structure | [play-dom-router/src/create-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-router.ts#L13) |
 
 ## Methods
 
@@ -19,9 +19,9 @@ Defined in: [play-dom-router/src/create-router.ts:4](https://gitlab.com/xmachin-
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-router.ts#L18)
+Defined in: [play-dom-router/src/create-router.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-router.ts#L18)
 
-Cleanup
+Cleans up
 
 #### Returns
 

package/api/@xmachines/play-react/README.md

@@ -4,9 +4,7 @@
 
 React renderer for XMachines Play architecture with signal-driven rendering.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-react)
-
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-react)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-react
 ```
 
-**Peer dependencies** (must be installed separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add react react-dom xstate @xstate/store @xmachines/json-render-react @xmachines/json-render-core @xmachines/json-render-xstate
@@ -25,7 +23,7 @@ Supported versions:
 - `react` / `react-dom`: `^18.0.0 || ^19.0.0`
 - `xstate`: `^5.31.0`
 - `@xstate/store`: `^3.17.0`
-- `@xmachines/json-render-*`: `^0.18.0`
+- `@xmachines/json-render-*`: `^0.20.0-xm.2`
 
 ## Usage
 
@@ -36,6 +34,9 @@ The recommended pattern for actor-driven React rendering:
 ```tsx
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js"; // your xstate machine (states carry meta.view specs)
+import { myCatalog } from "./catalog.js"; // defineCatalog(schema, ...) result, using the schema from "@xmachines/json-render-react/schema"
+import { Login, Dashboard } from "./components.js"; // your React components
 
 // 1. Create and start the actor
 const actor = definePlayer({ machine: myMachine })();
@@ -65,27 +66,42 @@ function App() {
 Pass navigation and validation helpers through `PlayUIProvider`:
 
 ```tsx
+// actor, registryResult from the Quick Start above
 <PlayUIProvider
 	actor={actor}
 	registryResult={registryResult}
-	navigate={(path) => router.push(path)}
+	navigate={(path) => history.pushState(null, "", path)}
 	validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
 >
 	<PlayRenderer />
 </PlayUIProvider>
 ```
 
-### Escape hatch — custom provider composition
+### Custom provider composition
 
 Use `ActorProvider` directly when you need to compose providers manually:
 
 ```tsx
-import { ActorProvider, JSONUIProvider, PlayRenderer } from "@xmachines/play-react";
+import type { ReactNode } from "react";
+import { ActorProvider, JSONUIProvider, PlayRenderer, usePlayView } from "@xmachines/play-react";
+
+// Handlers and store live in ViewContext, so an inner bridge component must
+// read them via usePlayView() and forward all three to JSONUIProvider —
+// passing only `registry` would drop the action handlers and create a fresh store.
+function Bridge({ children }: { children: ReactNode }) {
+	const view = usePlayView();
+	return (
+		<JSONUIProvider registry={view.registry} handlers={view.handlers} store={view.store}>
+			{children}
+		</JSONUIProvider>
+	);
+}
 
+// actor, registryResult from the Quick Start above
 <ActorProvider actor={actor} registryResult={registryResult}>
-	<JSONUIProvider registry={registryResult.registry}>
+	<Bridge>
 		<PlayRenderer />
-	</JSONUIProvider>
+	</Bridge>
 </ActorProvider>;
 ```
 
@@ -103,6 +119,7 @@ function SubmitButton() {
 ### Subscribing to signals directly
 
 ```tsx
+import { useState } from "react";
 import { useSignalEffect } from "@xmachines/play-react";
 
 function MyComponent({ actor }) {
@@ -112,7 +129,7 @@ function MyComponent({ actor }) {
 		setView(actor.currentView.get());
 	}, [actor]); // deps: re-subscribe when the actor prop swaps
 
-	return <div>{view?.component}</div>;
+	return <div>{view?.root}</div>;
 }
 ```
 
@@ -122,34 +139,34 @@ function MyComponent({ actor }) {
 
 | Export                | Description                                                                                                                             |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `<PlayUIProvider>`    | Batteries-included provider: wraps `ActorProvider` + `JSONUIProvider`. Standard entry point.                                            |
+| `<PlayUIProvider>`    | Composite provider. It wraps `ActorProvider` and `JSONUIProvider`. Use it as the standard entry point.                                  |
 | `<PlayRenderer>`      | Zero-prop leaf component. Reads the current actor view from context and renders it. Must be inside `PlayUIProvider` or `ActorProvider`. |
-| `<ActorProvider>`     | Escape-hatch primitive. Owns actor bridging, signal subscription, and per-view `StateStore` lifecycle.                                  |
-| `<PlayErrorBoundary>` | React class error boundary for catching catalog component render errors.                                                                |
+| `<ActorProvider>`     | The low-level provider. It owns the actor bridge, the signal subscription, and the `StateStore` lifecycle of each view.                 |
+| `<PlayErrorBoundary>` | The React class error boundary that catches a render error of a catalog component.                                                      |
 
 ### Hooks
 
-| Export                             | Description                                                                                                                                                                                                                          |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `useSignalEffect(callback, deps?)` | Subscribes to TC39 signal changes; re-runs the callback when any accessed signal changes (re-render via the callback's own setState). Optional `deps` recreates the subscription, like `useEffect`. Cleanup is automatic on unmount. |
-| `useActor()`                       | Returns the raw actor instance. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                                                      |
-| `usePlayView()`                    | Returns `{ spec, handlers, registry, store }` for the current view. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                  |
+| Export                             | Description                                                                                                                                                                                                                                                                                               |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useSignalEffect(callback, deps?)` | Subscribes to the TC39 signal changes. It runs the callback again when a signal that the callback reads changes, and the callback triggers the re-render with its own setState. The optional `deps` array creates the subscription again, like `useEffect`. The hook removes the subscription on unmount. |
+| `useActor()`                       | Returns the raw actor instance. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                                                                                                                           |
+| `usePlayView()`                    | Returns `{ spec, handlers, registry, store }` for the current view. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                                                                                       |
 
 ### Types
 
-| Export                   | Description                                                                                    |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
-| `PlayUIProviderProps`    | Props for `<PlayUIProvider>`                                                                   |
-| `ActorProviderProps`     | Props for `<ActorProvider>` (also exported as `PlayRendererProps` for migration compatibility) |
-| `PlayErrorBoundaryProps` | Props for `<PlayErrorBoundary>`                                                                |
-| `PlayErrorBoundaryState` | State shape for `<PlayErrorBoundary>`                                                          |
-| `AnyPlayActor`           | Type alias for `AbstractActor<AnyActorLogic>` — the bare actor type used by context providers  |
-| `ViewContextValue`       | Value shape returned by `usePlayView()`                                                        |
-| `RenderErrorHandler`     | Error handler callback type for render errors                                                  |
+| Export                   | Description                                                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `PlayUIProviderProps`    | Props for `<PlayUIProvider>`                                                                       |
+| `ActorProviderProps`     | Props for `<ActorProvider>` (also exported as `PlayRendererProps` for migration compatibility)     |
+| `PlayErrorBoundaryProps` | Props for `<PlayErrorBoundary>`                                                                    |
+| `PlayErrorBoundaryState` | State shape for `<PlayErrorBoundary>`                                                              |
+| `AnyPlayActor`           | Type alias for `AbstractActor<AnyActorLogic>` — the bare actor type that the context providers use |
+| `ViewContextValue`       | The value shape that `usePlayView()` returns                                                       |
+| `RenderErrorHandler`     | Error handler callback type for render errors                                                      |
 
 ### Re-exports from `@xmachines/json-render-react`
 
-`@xmachines/play-react` re-exports the full `@xmachines/json-render-react` surface so consumers only need one import:
+`@xmachines/play-react` re-exports the complete `@xmachines/json-render-react` surface, so a consumer needs one import only:
 
 ```ts
 import {
@@ -166,7 +183,7 @@ import {
 
 ## Key Principle
 
-React state is **never** used for business logic — only for triggering React's render cycle. Signals (`@xmachines/play-signals`) are the source of truth. `PlayUIProvider` passively observes actor signals via `useSignalEffect` and re-renders when the current view changes. Rapid signal updates are batched via microtasks to prevent unnecessary React renders.
+React state is **never** the place for the business logic. It only triggers the render cycle of React. The signals (`@xmachines/play-signals`) are the source of truth. `PlayUIProvider` observes the actor signals with `useSignalEffect`, and it renders again when the current view changes. It groups rapid signal updates into microtasks, so React does not render more often than necessary.
 
 ## Testing
 
@@ -182,7 +199,7 @@ Run tests with coverage:
 pnpm --filter @xmachines/play-react run test:coverage
 ```
 
-Run browser integration tests (requires Chromium):
+Run the browser integration tests. They require Chromium:
 
 ```bash
 pnpm --filter @xmachines/play-react run test:browser
@@ -194,17 +211,18 @@ Coverage thresholds: 80% lines, functions, branches, and statements.
 
 MIT — see [LICENSE](./LICENSE).
 
-@xmachines/play-react - React renderer for XMachines Play architecture
+@xmachines/play-react - React renderer for the XMachines Play architecture
 
-Provides a provider-based React rendering layer that passively observes actor signals
-and renders UI components via @xmachines/json-render-react. This package enables
-framework-swappable architecture where React is just a rendering target
-that subscribes to signal changes.
+This package is the React rendering layer, and it works through providers. It
+observes the actor signals and renders the UI components with
+@xmachines/json-render-react. The architecture can therefore change the
+framework, because React is only a render target that subscribes to the signal
+changes.
 
-**Key principle:** React state is NEVER used for business logic—only for
-triggering React's render cycle. Signals are the source of truth.
+**Key principle:** React state is NEVER the place for the business logic. It only
+triggers the render cycle of React. The signals are the source of truth.
 
-**Standard usage:**
+**Standard use:**
 
 ```tsx
 <PlayUIProvider actor={actor} registryResult={registryResult}>
@@ -212,15 +230,11 @@ triggering React's render cycle. Signals are the source of truth.
 </PlayUIProvider>
 ```
 
-**Escape hatch (custom composition):**
-
-```tsx
-<ActorProvider actor={actor} registryResult={registryResult}>
-	<JSONUIProvider registry={registryResult.registry}>
-		<PlayRenderer />
-	</JSONUIProvider>
-</ActorProvider>
-```
+**The escape hatch (a custom composition):** use `<ActorProvider>` directly, and give
+the ViewContext values (`registry`, `handlers`, `store` from `usePlayView()`) to
+`<JSONUIProvider>` through an inner bridge component. If you give only `registry`, you
+lose the action handlers and you make a new store. `PlayUIProvider` is this exact
+composition. Read its source for the reference bridge.
 
 ## Classes
 
@@ -245,6 +259,7 @@ triggering React's render cycle. Signals are the source of truth.
 
 - [AnyPlayActor](type-aliases/AnyPlayActor.md)
 - [ComponentFn](type-aliases/ComponentFn.md)
+- [~~PlayRendererProps~~](type-aliases/PlayRendererProps.md)
 - [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
 
 ## Variables
@@ -267,9 +282,3 @@ triggering React's render cycle. Signals are the source of truth.
 - [useSignalEffect](functions/useSignalEffect.md)
 - [ValidationProvider](functions/ValidationProvider.md)
 - [VisibilityProvider](functions/VisibilityProvider.md)
-
-## References
-
-### PlayRendererProps
-
-Renames and re-exports [ActorProviderProps](interfaces/ActorProviderProps.md)