@xmachines/docs 4.0.0 → 5.0.0

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

@@ -2,9 +2,9 @@
 
 # @xmachines/play-react
 
-React renderer for XMachines Play architecture with signal-driven rendering.
+React renderer for XMachines Play architecture with atom-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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-react)
 
 ## Installation
 
@@ -15,15 +15,20 @@ pnpm add @xmachines/play-react
 **Peer dependencies.** Install them separately:
 
 ```bash
-pnpm add react react-dom @xstate/store @xmachines/json-render-react @xmachines/json-render-core @xmachines/json-render-xstate
+pnpm add react react-dom @xmachines/play @xmachines/play-atom @xstate/store @xmachines/json-render-react @xmachines/json-render-core @xmachines/json-render-xstate
 ```
 
 Supported versions:
 
 - `react` / `react-dom`: `^18.0.0 || ^19.0.0`
-- `@xstate/store`: `^3.17.0`
+- [`@xmachines/play`](../play/README.md) and [`@xmachines/play-atom`](../play-atom/README.md): the version of this release
+- `@xstate/store`: `^4.2.3`
 - `@xmachines/json-render-*`: `^0.20.0-xm.4`
 
+`@xstate/store` is the peer of [`@xmachines/play-atom`](../play-atom/README.md), and not of this
+package: this package reads the atom through [`@xmachines/play-atom`](../play-atom/README.md) and
+imports the engine in no source file. Install ONE copy of it.
+
 ## Usage
 
 ### Standard usage — `PlayUIProvider` + `PlayRenderer`
@@ -51,7 +56,7 @@ const registryResult = defineRegistry(myCatalog, {
 	},
 });
 
-// 3. Render — signals drive view transitions automatically
+// 3. Render — atoms drive view transitions automatically
 function App() {
 	return (
 		<PlayUIProvider actor={actor} registryResult={registryResult}>
@@ -116,18 +121,23 @@ function SubmitButton() {
 }
 ```
 
-### Subscribing to signals directly
+### Subscribing to atoms directly
 
 ```tsx
 import { useState } from "react";
-import { useSignalEffect } from "@xmachines/play-react";
+import { useAtomEffect } from "@xmachines/play-react";
 
 function MyComponent({ actor }) {
 	const [view, setView] = useState(null);
 
-	useSignalEffect(() => {
-		setView(actor.currentView.get());
-	}, [actor]); // deps: re-subscribe when the actor prop swaps
+	// The first argument names every atom that runs the effect.
+	useAtomEffect(
+		[actor.currentView],
+		() => {
+			setView(actor.currentView.get());
+		},
+		[actor], // deps: re-subscribe when the actor prop swaps
+	);
 
 	return <div>{view?.root}</div>;
 }
@@ -141,16 +151,16 @@ function MyComponent({ actor }) {
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `<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>`     | The low-level provider. It owns the actor bridge, the signal subscription, and the `StateStore` lifecycle of each view.                 |
+| `<ActorProvider>`     | The low-level provider. It owns the actor bridge, the atom 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 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.                                                                                                                                                                       |
+| Export                                    | Description                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useAtomEffect(sources, callback, deps?)` | Subscribes to the atoms of `sources`. It runs the callback again when one of them changes, and the callback triggers the re-render with its own setState. A read inside the callback tracks nothing, so name every dependency in `sources`. 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
 
@@ -183,7 +193,7 @@ import {
 
 ## Key Principle
 
-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.
+React state is **never** the place for the business logic. It only triggers the render cycle of React. The atoms ([`@xmachines/play-atom`](../play-atom/README.md)) are the source of truth. `PlayUIProvider` observes the actor atoms with `useAtomEffect`, and it renders again when the current view changes. It groups rapid atom updates into microtasks, so React does not render more often than necessary.
 
 ## License
 
@@ -192,13 +202,13 @@ MIT — see [LICENSE](./LICENSE).
 @xmachines/play-react - React renderer for the XMachines Play architecture
 
 This package is the React rendering layer, and it works through providers. It
-observes the actor signals and renders the UI components with
+observes the actor atoms 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
+framework, because React is only a render target that subscribes to the atom
 changes.
 
 **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.
+triggers the render cycle of React. The atoms are the source of truth.
 
 **Standard use:**
 
@@ -254,9 +264,9 @@ composition. Read its source for the reference bridge.
 - [Renderer](functions/Renderer.md)
 - [StateProvider](functions/StateProvider.md)
 - [useActor](functions/useActor.md)
+- [useAtomEffect](functions/useAtomEffect.md)
 - [useBoundProp](functions/useBoundProp.md)
 - [useFieldValidation](functions/useFieldValidation.md)
 - [usePlayView](functions/usePlayView.md)
-- [useSignalEffect](functions/useSignalEffect.md)
 - [ValidationProvider](functions/ValidationProvider.md)
 - [VisibilityProvider](functions/VisibilityProvider.md)

package/api/@xmachines/play-react/classes/PlayErrorBoundary.md

@@ -2,7 +2,7 @@
 
 # Class: PlayErrorBoundary
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L99)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L99)
 
 The React class component that catches a render error of a catalog component.
 
@@ -37,7 +37,7 @@ CONS-14: the class component pattern works with every React version, 18 and 19.
 new PlayErrorBoundary(props): PlayErrorBoundary;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L103)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L103)
 
 #### Parameters
 
@@ -76,7 +76,7 @@ React.Component<
 componentDidCatch(error, info): void;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L135)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L135)
 
 Catches exceptions generated in descendant components. Unhandled exceptions will cause
 the entire component tree to unmount.
@@ -378,7 +378,7 @@ React.Component.getSnapshotBeforeUpdate;
 render(): ReactNode;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L139)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L139)
 
 #### Returns
 
@@ -609,7 +609,7 @@ React.Component.UNSAFE_componentWillUpdate;
 static getDerivedStateFromError(error): Pick<PlayErrorBoundaryState, "hasError" | "error">;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:108](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L108)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:108](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L108)
 
 #### Parameters
 
@@ -631,7 +631,7 @@ static getDerivedStateFromProps(props, state):
   | null;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L126)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L126)
 
 Clears the error state after a change of `resetKey`.
 

package/api/@xmachines/play-react/functions/useActor.md

@@ -6,7 +6,7 @@
 function useActor(): AnyPlayActor;
 ```
 
-Defined in: [packages/play-react/src/useActor.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/useActor.ts#L41)
+Defined in: [packages/play-react/src/useActor.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/useActor.ts#L41)
 
 ## Returns
 

package/api/@xmachines/play-react/functions/useAtomEffect.md

@@ -0,0 +1,103 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / useAtomEffect
+
+# Function: useAtomEffect()
+
+```ts
+function useAtomEffect(sources, callback, deps?): void;
+```
+
+Defined in: [packages/play-react/src/useAtomEffect.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/useAtomEffect.ts#L105)
+
+The React hook that subscribes to the named atoms and runs an effect callback
+
+The hook puts the SOURCES in a computed atom, and it gives the subscription lifecycle
+to `watchAtom` from `@xmachines/play-atom`. That function owns the coalescing and the
+disposal. It is the one canonical implementation, and every framework renderer uses
+it.
+
+Architecture:
+
+- The `sources` array names every atom that runs the effect
+- The callback runs OUTSIDE the tracking scope, so a read inside it adds no dependency
+- watchAtom owns the subscription lifecycle
+- The callback triggers each new render with its own setState (see the remarks)
+- The hook cleans up on unmount, so that nothing stays in memory
+
+Invariant: Atom-Only Reactivity. The hook watches each atom of `sources`.
+Invariant: Passive Infrastructure. React observes the atoms, and it does not control them.
+
+## Parameters
+
+| Parameter  | Type                                                                         | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------- | ---------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sources`  | readonly [`Readable`](../../play-atom/interfaces/Readable.md)\<`unknown`\>[] | `undefined`   | The atoms that run the effect. The list names every dependency, and the reads of the callback name none: a callback that reads a view store therefore depends on that store not, and a write of the store runs the effect never.                                                                                                                                                                                                                                                      |
+| `callback` | () => `void` \| (() => `void`)                                               | `undefined`   | The effect function. It can return a cleanup function. It runs one time on the mount, and one time for each write of a source.                                                                                                                                                                                                                                                                                                                                                        |
+| `deps`     | `DependencyList`                                                             | `[]`          | The optional dependency list, as in useEffect. On a change of one dependency, the hook removes the watcher and the computed atom, then makes them again and reads the sources from the start. The default is `[]`, which subscribes one time for each mount. Give this list when the identity of the object whose atoms you read can change during the life of the component, for example an `actor` prop. Without the list, the watcher tracks the atoms of the OLD object for ever. |
+
+## Returns
+
+`void`
+
+## Example
+
+```typescript
+const MyComponent = ({ actor }) => {
+  const [view, setView] = useState(null);
+
+  // Subscribe to the actor.currentView atom, and subscribe again on a new actor
+  useAtomEffect(
+    [actor.currentView],
+    () => {
+      const currentView = actor.currentView.get();
+      setView(currentView);
+    },
+    [actor],
+  );
+
+  return <div>{view?.root}</div>;
+};
+```
+
+## Remarks
+
+**CRITICAL:** name every atom that must run the effect in `sources`. A read inside
+the callback tracks nothing, so an atom that the list leaves out runs the effect
+never.
+
+**How often the callback runs:** one time for each MICROTASK, and not one time for
+each write. `watchAtom` owns that rule: it keeps the synchronous notification of
+`@xstate/store` and it defers the callback, so one batch of synchronous writes reaches
+the callback one time, with the last value. Three writes in one tick therefore run the
+callback ONE time.
+
+The DERIVATION is the part that runs for each write: `@xstate/store` evaluates a
+computed atom synchronously inside the `set` of a dependency, and that evaluation IS
+the dependency tracking. Keep each source atom cheap to derive.
+
+**Re-rendering:** the hook itself does NOT force a React render on an atom
+change. The callback triggers each new render, because it calls setState with the
+new atom value, as in the example above. The setState bailout of React can skip a
+render when the derived value is the same.
+
+**A callback that throws:** the FIRST run happens while the hook mounts, so a throw
+there reaches the caller and React reports it. A later run happens in the microtask of
+`watchAtom`, and a throw there reaches no caller. The hook catches it and throws it
+again from a microtask of its own, which reaches the global handler of the runtime.
+
+**A SOURCE that throws:** a source derives its value inside the `set` of the atom that
+it reads, and `@xstate/store` evaluates it there for every watcher. A throw from that
+derivation therefore leaves the `set` of the WRITER: the write fails, and every other
+observer of that write is skipped. The hook can catch none of it, because the engine
+runs the derivation before it reaches this hook — a watched computed atom that throws
+does the same with no hook anywhere.
+
+Therefore a source derivation must return a value and throw nothing. `currentView` and
+`currentRoute` of `@xmachines/play-xstate` follow that rule: each one catches its own
+failure, reports it through `onError` of the actor from a microtask, and keeps the last
+value. Write a source of your own the same way.
+
+**Implementation note:** the hook puts the SOURCES in a computed atom, because a
+subscription needs one atom to watch. That computed atom reads each source and holds
+the dependency edges, `watchAtom` owns the subscription that keeps it live, and the
+callback runs from the observer, which `@xstate/store` calls with no active
+subscriber.

package/api/@xmachines/play-react/functions/usePlayView.md

@@ -6,7 +6,7 @@
 function usePlayView(): ViewContextValue;
 ```
 
-Defined in: [packages/play-react/src/ActorProvider.tsx:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/ActorProvider.tsx#L150)
+Defined in: [packages/play-react/src/ActorProvider.tsx:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/ActorProvider.tsx#L150)
 
 The hook that gives the current view spec, the handlers, and the registry.
 

package/api/@xmachines/play-react/interfaces/ActorProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: ActorProviderProps
 
-Defined in: [packages/play-react/src/ActorProvider.tsx:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/ActorProvider.tsx#L59)
+Defined in: [packages/play-react/src/ActorProvider.tsx:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/ActorProvider.tsx#L59)
 
 The props of the ActorProvider component.
 
@@ -18,10 +18,10 @@ The props of the ActorProvider component.
 
 | Property                                              | Type                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Inherited from                                                                                                                                                                                | Defined in                                                                                                                                             |
 | ----------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`                   | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor instance with the currentView signal. It requires the Viewable capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`actor`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-view/src/view-types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-view/src/view-types.ts#L169)         |
-| <a id="property-children"></a> `children`             | `ReactNode`                                                    | The child components to render inside the provider tree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/ActorProvider.tsx#L98) |
-| <a id="property-fallback"></a> `fallback?`            | `ReactNode`                                                    | The component to show when currentView is null, or when a catalog component throws. This prop is optional                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/ActorProvider.tsx#L61) |
-| <a id="property-onerror"></a> `onError?`              | (`error`, `info`, `reset`) => `void`                           | The optional error handler. The provider calls it when a descendant throws during a render. While the error is active, the provider renders the `fallback` instead of its children. The provider clears the error on the next view emission (when `currentView` changes), so a view transition retries the render. Element-level catalog component throws are caught upstream by the per-element boundary of @json-render, and reported through `onRenderError`. This boundary is the outer net for everything else. The THIRD parameter is the reset, for a retry that the host starts — a "Retry" button of its own. It sits after `info`, and not in the second place that the four other renderers use, because `React.ErrorInfo` holds that place already and a move would break every handler that reads `info.componentStack`. The reset clears the contained error and renders again. It renders the view that the actor holds at the MOMENT OF THE CALL, so a host that keeps the callback cannot rewind the screen to the view that failed. A reset that the host calls from inside this handler does nothing, because no input changed between the two attempts, and a reset after the provider is unmounted does nothing. The five renderers hold the same three rules. **A handler that THROWS reaches no caller.** The provider contains that throw, and it writes the throw to `console.error`. This handler runs inside `componentDidCatch`, so a throw that left it would reach the boundary ABOVE this provider, and React can then unmount the complete root — which is the failure that this boundary contained. Report a failure from this handler. To ESCALATE one, raise it from a task of your own — `queueMicrotask(() => { throw error; })` — which reaches the global handler of the page and leaves the containment whole. The five renderers hold this one rule. | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/ActorProvider.tsx#L96) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)  | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-view/src/view-types.ts:183](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-view/src/view-types.ts#L183)         |
-| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                         | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-view/src/view-types.ts:171](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-view/src/view-types.ts#L171)         |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                   | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`store`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-view/src/view-types.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-view/src/view-types.ts#L178)         |
+| <a id="property-actor"></a> `actor`                   | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor instance with the currentView atom. It requires the Viewable capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`actor`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-view/src/view-types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-view/src/view-types.ts#L169)         |
+| <a id="property-children"></a> `children`             | `ReactNode`                                                    | The child components to render inside the provider tree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/ActorProvider.tsx#L98) |
+| <a id="property-fallback"></a> `fallback?`            | `ReactNode`                                                    | The component to show when currentView is null, or when a catalog component throws. This prop is optional                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/ActorProvider.tsx#L61) |
+| <a id="property-onerror"></a> `onError?`              | (`error`, `info`, `reset`) => `void`                           | The optional error handler. The provider calls it when a descendant throws during a render. While the error is active, the provider renders the `fallback` instead of its children. The provider clears the error on the next view emission (when `currentView` changes), so a view transition retries the render. Element-level catalog component throws are caught upstream by the per-element boundary of @json-render, and reported through `onRenderError`. This boundary is the outer net for everything else. The THIRD parameter is the reset, for a retry that the host starts — a "Retry" button of its own. It sits after `info`, and not in the second place that the four other renderers use, because `React.ErrorInfo` holds that place already and a move would break every handler that reads `info.componentStack`. The reset clears the contained error and renders again. It renders the view that the actor holds at the MOMENT OF THE CALL, so a host that keeps the callback cannot rewind the screen to the view that failed. A reset that the host calls from inside this handler does nothing, because no input changed between the two attempts, and a reset after the provider is unmounted does nothing. The five renderers hold the same three rules. **A handler that THROWS reaches no caller.** The provider contains that throw, and it writes the throw to `console.error`. This handler runs inside `componentDidCatch`, so a throw that left it would reach the boundary ABOVE this provider, and React can then unmount the complete root — which is the failure that this boundary contained. Report a failure from this handler. To ESCALATE one, raise it from a task of your own — `queueMicrotask(() => { throw error; })` — which reaches the global handler of the page and leaves the containment whole. The five renderers hold this one rule. | -                                                                                                                                                                                             | [packages/play-react/src/ActorProvider.tsx:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/ActorProvider.tsx#L96) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)  | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-view/src/view-types.ts:183](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-view/src/view-types.ts#L183)         |
+| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                         | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-view/src/view-types.ts:171](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-view/src/view-types.ts#L171)         |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                   | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [`BaseActorProviderProps`](../../play-view/index/interfaces/BaseActorProviderProps.md).[`store`](../../play-view/index/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-view/src/view-types.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-view/src/view-types.ts#L178)         |

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryProps
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L14)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L14)
 
 The props of PlayErrorBoundary
 
@@ -10,8 +10,8 @@ The props of PlayErrorBoundary
 
 | Property                                               | Type                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                                     |
 | ------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children`              | `ReactNode`                       | The child components to render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
-| <a id="property-fallback"></a> `fallback?`             | `ReactNode`                       | The fallback UI to render when a child component throws. The default is null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
-| <a id="property-onerror"></a> `onError?`               | (`error`, `info`) => `void`       | The optional error handler. It sends each error to an observability tool, such as Sentry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
-| <a id="property-resetkey"></a> `resetKey?`             | `unknown`                         | The reset key. The boundary clears its error state when this value changes, and it renders the children again. ActorProvider gives it the current view. A view transition therefore retries the render. Without the key the boundary holds the fallback for the complete life of the provider: the user sends a recovery event, the actor moves to a healthy view, and the screen keeps the fallback. **The boundary compares the value by IDENTITY (`Object.is`) by default.** Give a stable reference. An inline object literal — `resetKey={{ view }}` — is a new value on every render, so the boundary clears its caught error before each one, renders the children that threw, catches again, and calls `onError` again. Hold the value where it survives a render, and build a new one only when an input moves. [PlayErrorBoundaryProps.resetKeyEquals](#property-resetkeyequals) takes the identity rule away, and a caller that gives one needs no stable reference at all. | [packages/play-react/src/PlayErrorBoundary.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L39) |
-| <a id="property-resetkeyequals"></a> `resetKeyEquals?` | (`previous`, `next`) => `boolean` | The comparison of two reset keys. The default is `Object.is`. The boundary clears its error where this function answers `false`. A caller that builds a key of several inputs therefore compares those INPUTS, and it owes the boundary no stable reference for the key that carries them. That is what `ActorProvider` gives. A key of the three view inputs and the retry nonce holds no identity of its own across renders — React makes no promise to keep a `useMemo`, and a ref that the render writes survives a render that React throws away, which the documentation of React forbids for that reason. With a comparison of the fields, a key that carries the same inputs is the same key, whichever render built it. The state of this class is the key of the last COMMIT: React commits the state of a class with the commit, so a render that React discards writes none. The comparison therefore reads the committed key on one side every time.                      | [packages/play-react/src/PlayErrorBoundary.tsx:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L63) |
+| <a id="property-children"></a> `children`              | `ReactNode`                       | The child components to render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
+| <a id="property-fallback"></a> `fallback?`             | `ReactNode`                       | The fallback UI to render when a child component throws. The default is null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
+| <a id="property-onerror"></a> `onError?`               | (`error`, `info`) => `void`       | The optional error handler. It sends each error to an observability tool, such as Sentry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
+| <a id="property-resetkey"></a> `resetKey?`             | `unknown`                         | The reset key. The boundary clears its error state when this value changes, and it renders the children again. ActorProvider gives it the current view. A view transition therefore retries the render. Without the key the boundary holds the fallback for the complete life of the provider: the user sends a recovery event, the actor moves to a healthy view, and the screen keeps the fallback. **The boundary compares the value by IDENTITY (`Object.is`) by default.** Give a stable reference. An inline object literal — `resetKey={{ view }}` — is a new value on every render, so the boundary clears its caught error before each one, renders the children that threw, catches again, and calls `onError` again. Hold the value where it survives a render, and build a new one only when an input moves. [PlayErrorBoundaryProps.resetKeyEquals](#property-resetkeyequals) takes the identity rule away, and a caller that gives one needs no stable reference at all. | [packages/play-react/src/PlayErrorBoundary.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L39) |
+| <a id="property-resetkeyequals"></a> `resetKeyEquals?` | (`previous`, `next`) => `boolean` | The comparison of two reset keys. The default is `Object.is`. The boundary clears its error where this function answers `false`. A caller that builds a key of several inputs therefore compares those INPUTS, and it owes the boundary no stable reference for the key that carries them. That is what `ActorProvider` gives. A key of the three view inputs and the retry nonce holds no identity of its own across renders — React makes no promise to keep a `useMemo`, and a ref that the render writes survives a render that React throws away, which the documentation of React forbids for that reason. With a comparison of the fields, a key that carries the same inputs is the same key, whichever render built it. The state of this class is the key of the last COMMIT: React commits the state of a class with the commit, so a render that React discards writes none. The comparison therefore reads the committed key on one side every time.                      | [packages/play-react/src/PlayErrorBoundary.tsx:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L63) |

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryState.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryState
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L71)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L71)
 
 The internal state shape of PlayErrorBoundary
 
@@ -10,6 +10,6 @@ The internal state shape of PlayErrorBoundary
 
 | Property                                  | Type              | Description                                                               | Defined in                                                                                                                                                     |
 | ----------------------------------------- | ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-error"></a> `error`       | `Error` \| `null` | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L73) |
-| <a id="property-haserror"></a> `hasError` | `boolean`         | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L72) |
-| <a id="property-resetkey"></a> `resetKey` | `unknown`         | The resetKey of the last render. A different prop clears the error state. | [packages/play-react/src/PlayErrorBoundary.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L75) |
+| <a id="property-error"></a> `error`       | `Error` \| `null` | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L73) |
+| <a id="property-haserror"></a> `hasError` | `boolean`         | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L72) |
+| <a id="property-resetkey"></a> `resetKey` | `unknown`         | The resetKey of the last render. A different prop clears the error state. | [packages/play-react/src/PlayErrorBoundary.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L75) |