@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -1,25 +1,27 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / useSignalEffect
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / useSignalEffect
 
 # Function: useSignalEffect()
 
 ```ts
-function useSignalEffect(callback): void;
+function useSignalEffect(callback, deps?): void;
 ```
 
-Defined in: [packages/play-react/src/useSignalEffect.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/useSignalEffect.ts#L65)
+Defined in: [packages/play-react/src/useSignalEffect.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/useSignalEffect.ts#L80)
 
 React hook that subscribes to signal changes and runs effect callback
 
-Wraps Signal.subtle.Watcher to automatically track signal dependencies
-accessed in the callback. When any tracked signal changes, the callback
-re-runs and React component re-renders.
+Wraps the callback in a Signal.Computed to automatically track signal
+dependencies accessed inside it, then delegates the watcher lifecycle
+(microtask batching, re-arming, disposal) to `watchSignal` from
+`@xmachines/play-signals` — the single canonical implementation shared
+across framework renderers.
 
-Architecture (per RESEARCH.md Pattern 3):
+Architecture:
 
 - Uses Signal.Computed to wrap callback for automatic dependency tracking
-- Signal.subtle.Watcher monitors the Computed for changes
+- watchSignal owns the Signal.subtle.Watcher lifecycle (Phase 29 memory safety)
 - Microtask batching coalesces rapid signal updates
-- Forces React re-render via useReducer when signals change
+- Re-rendering is driven by the callback's own setState (see remarks)
 - Handles cleanup on unmount to prevent memory leaks
 
 Invariant: Signal-Only Reactivity - Signals accessed in callback are watched.
@@ -27,9 +29,10 @@ Invariant: Passive Infrastructure - React observes signals and does not control
 
 ## Parameters
 
-| Parameter  | Type                           | Description                                                         |
-| ---------- | ------------------------------ | ------------------------------------------------------------------- |
-| `callback` | () => `void` \| (() => `void`) | Effect function that accesses signals. Can return cleanup function. |
+| Parameter  | Type                           | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------- | ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `callback` | () => `void` \| (() => `void`) | `undefined`   | Effect function that accesses signals. Can return cleanup function.                                                                                                                                                                                                                                                                                                                                                    |
+| `deps`     | `DependencyList`               | `[]`          | Optional dependency list (like useEffect). When any dependency changes, the watcher and Computed are torn down and recreated, re-tracking signals from scratch. Defaults to `[]` (subscribe once per mount). Pass this when the identity of the object whose signals you read can change over the component's lifetime (e.g. an `actor` prop) — otherwise the watcher keeps tracking the OLD object's signals forever. |
 
 ## Returns
 
@@ -41,11 +44,11 @@ Invariant: Passive Infrastructure - React observes signals and does not control
 const MyComponent = ({ actor }) => {
   const [view, setView] = useState(null);
 
-  // Subscribe to actor.currentView signal
+  // Subscribe to actor.currentView signal; re-subscribe if the actor swaps
   useSignalEffect(() => {
     const currentView = actor.currentView.get();
     setView(currentView);
-  });
+  }, [actor]);
 
   return <div>{view?.component}</div>;
 };
@@ -56,13 +59,19 @@ const MyComponent = ({ actor }) => {
 **CRITICAL:** Signals must be accessed unconditionally (no if statements).
 Conditional signal access breaks automatic dependency tracking.
 
-**Performance:** Microtask batching (queueMicrotask) prevents React thrashing
-when multiple signals update rapidly. Per signal-polyfill README pattern.
+**Performance:** Microtask batching (queueMicrotask, inside watchSignal)
+prevents React thrashing when multiple signals update rapidly.
 
-**Why forceUpdate:** React needs useState/useReducer to trigger re-render cycle.
-Signal changes won't automatically re-render React components without forcing
-update via state change.
+**Re-rendering:** the hook itself does NOT force a React render on signal
+change — the callback drives re-rendering by calling setState with the new
+signal value (as in the example above). This lets React's setState bailout
+skip renders when the derived value is unchanged; an unconditional
+force-update here previously caused a wasted render per notification even
+when the callback's setState bailed. If you need to re-render on every
+notification while reading signals during render, mirror the signal value
+into React state inside the callback.
 
 **Implementation note:** We wrap the callback in Signal.Computed because
 Signal.subtle.Watcher cannot automatically track arbitrary function calls.
-The Computed handles dependency tracking, and the Watcher monitors it.
+The Computed handles dependency tracking; watchSignal evaluates it (which
+runs the callback) whenever any tracked signal changes.

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

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ActionProviderProps
+
+# Interface: ActionProviderProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for ActionProvider
+
+## Properties
+
+| Property                                   | Type                                  | Description             | Defined in |
+| ------------------------------------------ | ------------------------------------- | ----------------------- | ---------- |
+| <a id="property-children"></a> `children`  | `ReactNode`                           | -                       | -          |
+| <a id="property-handlers"></a> `handlers?` | `Record`\<`string`, `ActionHandler`\> | Initial action handlers | -          |
+| <a id="property-navigate"></a> `navigate?` | (`path`) => `void`                    | Navigation function     | -          |

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

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ActorProviderProps
+
+# Interface: ActorProviderProps
+
+Defined in: [packages/play-react/src/ActorProvider.tsx:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L41)
+
+Props for the ActorProvider component.
+
+## Extends
+
+- [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md)\<`DefineRegistryResult`\>
+
+## Extended by
+
+- [`PlayUIProviderProps`](PlayUIProviderProps.md)
+
+## Properties
+
+| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                               |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L159) |
+| <a id="property-children"></a> `children`             | `ReactNode`                                                                                                                                                                                                                                                      | Child components to render inside the provider tree                                                                                                                                                                         | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L47)   |
+| <a id="property-fallback"></a> `fallback?`            | `ReactNode`                                                                                                                                                                                                                                                      | Optional component shown when currentView is null or a catalog component throws                                                                                                                                             | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L43)   |
+| <a id="property-onerror"></a> `onError?`              | (`error`, `info`) => `void`                                                                                                                                                                                                                                      | Optional error handler callback invoked when a catalog component throws during render                                                                                                                                       | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L45)   |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L172) |
+| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L161) |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L167) |

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

@@ -0,0 +1,37 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+Defined in: `@xmachines/json-render-react`
+
+Context passed to component render functions
+
+## Example
+
+```ts
+const Button: ComponentFn<typeof catalog, 'Button'> = (ctx) => {
+  return <button onClick={() => ctx.emit("press")}>{ctx.props.label}</button>
+}
+```
+
+## Extends
+
+- `BaseComponentProps`\<`InferComponentProps`\<`C`, `K`\>\>
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Properties
+
+| Property                                   | Type                           | Description                                                                                                                      | Inherited from                | Defined in |
+| ------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings?` | `Record`\<`string`, `string`\> | Two-way binding paths resolved from `$bindState` / `$bindItem` expressions. Maps prop name → absolute state path for write-back. | `BaseComponentProps.bindings` | -          |
+| <a id="property-children"></a> `children?` | `ReactNode`                    | -                                                                                                                                | `BaseComponentProps.children` | -          |
+| <a id="property-emit"></a> `emit`          | (`event`) => `void`            | Simple event emitter (shorthand). Fires the event and returns void.                                                              | `BaseComponentProps.emit`     | -          |
+| <a id="property-loading"></a> `loading?`   | `boolean`                      | -                                                                                                                                | `BaseComponentProps.loading`  | -          |
+| <a id="property-on"></a> `on`              | (`event`) => `EventHandle`     | Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks.                                       | `BaseComponentProps.on`       | -          |
+| <a id="property-props"></a> `props`        | `InferComponentProps`          | -                                                                                                                                | `BaseComponentProps.props`    | -          |

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

@@ -0,0 +1,22 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / JSONUIProviderProps
+
+# Interface: JSONUIProviderProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for JSONUIProvider
+
+## Properties
+
+| Property                                                         | Type                                                                                                      | Description                                                                                      | Defined in |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| <a id="property-children"></a> `children`                        | `ReactNode`                                                                                               | -                                                                                                | -          |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives for user-defined `$`-prefixed dynamic values                                   | -          |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named functions for `$computed` expressions in props                                             | -          |
+| <a id="property-handlers"></a> `handlers?`                       | `Record`\<`string`, (`params`) => `unknown`\>                                                             | Action handlers                                                                                  | -          |
+| <a id="property-initialstate"></a> `initialState?`               | `Record`\<`string`, `unknown`\>                                                                           | Initial state model (uncontrolled mode)                                                          | -          |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Navigation function                                                                              | -          |
+| <a id="property-onstatechange"></a> `onStateChange?`             | (`changes`) => `void`                                                                                     | Callback when state changes (uncontrolled mode)                                                  | -          |
+| <a id="property-registry"></a> `registry`                        | `ComponentRegistry`                                                                                       | Component registry                                                                               | -          |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | External store (controlled mode). When provided, `initialState` and `onStateChange` are ignored. | -          |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions                                                                      | -          |

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

@@ -1,15 +1,15 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / PlayErrorBoundaryProps
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / PlayErrorBoundaryProps
 
 # Interface: PlayErrorBoundaryProps
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L14)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L14)
 
 Props for PlayErrorBoundary
 
 ## Properties
 
-| Property                                   | Type                        | Description                                                                             | Defined in                                                                                                                                                                                       |
-| ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
-| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
-| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
+| Property                                   | Type                        | Description                                                                             | Defined in                                                                                                                                                     |
+| ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
+| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
+| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L20) |

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

@@ -1,14 +1,14 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / PlayErrorBoundaryState
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / PlayErrorBoundaryState
 
 # Interface: PlayErrorBoundaryState
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L28)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L28)
 
 Internal state shape for PlayErrorBoundary
 
 ## Properties
 
-| Property                                  | Type              | Defined in                                                                                                                                                                                       |
-| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
-| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayErrorBoundary.tsx#L29) |
+| Property                                  | Type              | Defined in                                                                                                                                                     |
+| ----------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
+| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayErrorBoundary.tsx#L29) |

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

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / PlayUIProviderProps
+
+# Interface: PlayUIProviderProps
+
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayUIProvider.tsx#L34)
+
+Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own props.
+
+## Extends
+
+- [`ActorProviderProps`](ActorProviderProps.md).`Partial`\<`JSONUIForwardedProps`\>
+
+## Properties
+
+| Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                               | Defined in                                                                                                                                               |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                                | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L159) |
+| <a id="property-children"></a> `children`                        | `ReactNode`                                                                                                                                                                                                                                                      | Child components to render inside the provider tree                                                                                                                                                                         | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-react/src/ActorProvider.tsx:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L47)   |
+| <a id="property-fallback"></a> `fallback?`                       | `ReactNode`                                                                                                                                                                                                                                                      | Optional component shown when currentView is null or a catalog component throws                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-react/src/ActorProvider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L43)   |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                                                                                                                                                                         | Named functions for `$computed` expressions in props                                                                                                                                                                        | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`functions`](JSONUIProviderProps.md#property-functions)                     | -                                                                                                                                                        |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigation function                                                                                                                                                                                                         | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`navigate`](JSONUIProviderProps.md#property-navigate)                       | -                                                                                                                                                        |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `info`) => `void`                                                                                                                                                                                                                                      | Optional error handler callback invoked when a catalog component throws during render                                                                                                                                       | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-react/src/ActorProvider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L45)   |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)                | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L172) |
+| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult)              | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L161) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                                | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L167) |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | Custom validation functions                                                                                                                                                                                                 | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`validationFunctions`](JSONUIProviderProps.md#property-validationfunctions) | -                                                                                                                                                        |

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

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / RendererProps
+
+# Interface: RendererProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for the Renderer component
+
+## Properties
+
+| Property                                             | Type                                                          | Description                                                     | Defined in |
+| ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- | ---------- |
+| <a id="property-fallback"></a> `fallback?`           | `ComponentRenderer`\<`Record`\<`string`, `unknown`\>\>        | Fallback component for unknown types                            | -          |
+| <a id="property-loading"></a> `loading?`             | `boolean`                                                     | Whether the spec is currently loading/streaming                 | -          |
+| <a id="property-onrendererror"></a> `onRenderError?` | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Callback for element render errors caught by the inner boundary | -          |
+| <a id="property-registry"></a> `registry`            | `ComponentRegistry`                                           | Component registry                                              | -          |
+| <a id="property-spec"></a> `spec`                    | `Spec` \| `null`                                              | The UI spec to render                                           | -          |

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

@@ -0,0 +1,16 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / StateProviderProps
+
+# Interface: StateProviderProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for StateProvider
+
+## Properties
+
+| Property                                             | Type                  | Description                                                                                                                                                                                   | Defined in |
+| ---------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-children"></a> `children`            | `ReactNode`           | -                                                                                                                                                                                             | -          |
+| <a id="property-initialstate"></a> `initialState?`   | `StateModel`          | Initial state model (used only in uncontrolled mode)                                                                                                                                          | -          |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`changes`) => `void` | Callback when state changes (used only in uncontrolled mode). Called once per `set` or `update` with all changed entries.                                                                     | -          |
+| <a id="property-store"></a> `store?`                 | `StateStore`          | External store that owns the state. When provided, the provider operates in **controlled mode** — `initialState` and `onStateChange` are ignored and the store is the single source of truth. | -          |

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

@@ -0,0 +1,14 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ValidationProviderProps
+
+# Interface: ValidationProviderProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for ValidationProvider
+
+## Properties
+
+| Property                                                 | Type                                       | Description                              | Defined in |
+| -------------------------------------------------------- | ------------------------------------------ | ---------------------------------------- | ---------- |
+| <a id="property-children"></a> `children`                | `ReactNode`                                | -                                        | -          |
+| <a id="property-customfunctions"></a> `customFunctions?` | `Record`\<`string`, `ValidationFunction`\> | Custom validation functions from catalog | -          |

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

@@ -0,0 +1,20 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ViewContextValue
+
+# Interface: ViewContextValue
+
+Defined in: [packages/play-react/src/ActorProvider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L55)
+
+Value provided by ViewContext (accessible via usePlayView()).
+
+## Extends
+
+- [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md)\<`ComponentRegistry`\>
+
+## Properties
+
+| Property                                  | Type                                                  | Description                                                                                               | Inherited from                                                                                                                                                    | Defined in                                                                                                                                               |
+| ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                                           | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L129) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L131) |

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / VisibilityProviderProps
+
+# Interface: VisibilityProviderProps
+
+Defined in: `@xmachines/json-render-react`
+
+Props for VisibilityProvider
+
+## Properties
+
+| Property                                  | Type        | Defined in |
+| ----------------------------------------- | ----------- | ---------- |
+| <a id="property-children"></a> `children` | `ReactNode` | -          |

package/api/@xmachines/play-react/type-aliases/AnyPlayActor.md

@@ -0,0 +1,11 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / AnyPlayActor
+
+# Type Alias: AnyPlayActor
+
+```ts
+type AnyPlayActor = AbstractActor<AnyActorLogic>;
+```
+
+Defined in: [packages/play-react/src/useActor.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/useActor.ts#L28)
+
+Bare actor type accepted by React context providers. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`.

package/api/@xmachines/play-react/type-aliases/ComponentFn.md

@@ -0,0 +1,36 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ComponentFn
+
+# Type Alias: ComponentFn\<C, K\>
+
+```ts
+type ComponentFn<C, K> = (ctx) => ReactNode;
+```
+
+Defined in: `@xmachines/json-render-react`
+
+Component render function type for React
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Parameters
+
+| Parameter | Type                                                                |
+| --------- | ------------------------------------------------------------------- |
+| `ctx`     | [`ComponentContext`](../interfaces/ComponentContext.md)\<`C`, `K`\> |
+
+## Returns
+
+`ReactNode`
+
+## Example
+
+```ts
+const Button: ComponentFn<typeof catalog, 'Button'> = ({ props, emit }) => (
+  <button onClick={() => emit("press")}>{props.label}</button>
+);
+```

package/api/@xmachines/play-react/type-aliases/RenderErrorHandler.md

@@ -0,0 +1,23 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / RenderErrorHandler
+
+# Type Alias: RenderErrorHandler
+
+```ts
+type RenderErrorHandler = (error, elementType) => void;
+```
+
+Defined in: `@xmachines/json-render-core`
+
+Callback invoked when an individual catalog component throws during render.
+Implemented by each framework renderer's error boundary / error capture mechanism.
+
+## Parameters
+
+| Parameter     | Type      |
+| ------------- | --------- |
+| `error`       | `unknown` |
+| `elementType` | `string`  |
+
+## Returns
+
+`void`

package/api/@xmachines/play-react/variables/ActorProvider.md

@@ -0,0 +1,33 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / ActorProvider
+
+# Variable: ActorProvider
+
+```ts
+const ActorProvider: React.FC<ActorProviderProps>;
+```
+
+Defined in: [packages/play-react/src/ActorProvider.tsx:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/ActorProvider.tsx#L184)
+
+ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+
+Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+into the component registry.
+
+Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+
+## Example
+
+```tsx
+// Custom composition (escape hatch):
+<ActorProvider actor={actor} registryResult={registryResult}>
+  <JSONUIProvider registry={registryResult.registry}>
+    <PlayRenderer />
+  </JSONUIProvider>
+</ActorProvider>
+
+// Standard usage: prefer PlayUIProvider
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+  <PlayRenderer />
+</PlayUIProvider>
+```

package/api/@xmachines/play-react/variables/PlayRenderer.md

@@ -1,64 +1,14 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / PlayRenderer
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / PlayRenderer
 
 # Variable: PlayRenderer
 
 ```ts
-const PlayRenderer: React.FC<PlayRendererProps>;
+const PlayRenderer: React.FC<Record<string, never>>;
 ```
 
-Defined in: [packages/play-react/src/PlayRenderer.tsx:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/PlayRenderer.tsx#L61)
+Defined in: [packages/play-react/src/PlayRenderer.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-react/src/PlayRenderer.tsx#L39)
 
-Main renderer component that subscribes to actor signals and renders UI
+Zero-prop leaf component that renders the current actor view.
 
-Architecture (per RESEARCH.md Pattern 1):
-
-- Subscribes to actor.currentView signal via useSignalEffect
-- Dynamically renders catalog components based on view.component string
-- Forwards user events to actor via actor.send()
-- React state only for triggering renders, NOT business logic
-
-Invariant: Actor Authority - Actor decides all state transitions via guards.
-Invariant: Passive Infrastructure - Component observes signals and sends events.
-Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
-
-## Example
-
-```typescript
-import { PlayRenderer } from "@xmachines/play-react";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const actor = definePlayer({ machine, catalog })();
-actor.start();
-
-const components = {
-  Dashboard: ({ userId, send }) => <div>User: {userId}</div>,
-  LoginForm: ({ error, send }) => <form onSubmit={(e) => {
-    e.preventDefault();
-    send({ type: "intent", name: "login.submit", payload: {...} });
-  }}>...</form>
-};
-
-<PlayRenderer actor={actor} components={components} />
-```
-
-## Param
-
-Component props
-
-## Returns
-
-React element rendering current view from actor
-
-## Remarks
-
-**Component lookup:** Dynamically looks up component from `components` map
-using `view.component` string from actor.currentView signal.
-
-**Event forwarding:** Injects `send` function as prop to components. Components
-call `send(event)` to forward intents to actor. Actor guards decide validity.
-
-**Error handling:** If component not found in catalog, logs error and shows
-fallback. This indicates missing component registration, not runtime error.
-
-**CRITICAL:** Never call actor.send() during render - only in event handlers.
-Calling send during render causes infinite render loops.
+Reads the current PlaySpec, handlers, and registry from the ActorProvider
+context via usePlayView(), then renders via @xmachines/json-render-react Renderer.