@xmachines/play-react 2.0.0 → 2.1.0

package/README.md

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

package/dist/ActorProvider.d.ts

@@ -1,11 +1,14 @@
 /**
- * ActorProvider — escape hatch primitive for actor lifecycle management.
+ * ActorProvider — the low-level provider for the actor lifecycle.
  *
- * Owns: actor bridging, signal subscription (useSignalEffect), per-view StateStore
- * lifecycle (controlled/uncontrolled), handler resolution via inner component pattern
- * (uses useStateStore()), StateProvider wrap, PlayErrorBoundary wrap, onRenderError injection.
+ * It owns the actor bridge, the signal subscription (useSignalEffect), the
+ * StateStore lifecycle of each view (controlled and uncontrolled), the handler
+ * resolution through the inner component pattern (it uses useStateStore()), the
+ * StateProvider wrapper, the PlayErrorBoundary wrapper, and the injection of
+ * onRenderError.
  *
- * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ * Standard use: prefer <PlayUIProvider>, and use this component only when you
+ * compose the providers yourself.
  *
  * @packageDocumentation
  */
@@ -13,31 +16,31 @@ import React from "react";
 import type { DefineRegistryResult, ComponentRegistry } from "@xmachines/json-render-react";
 import { type BaseActorProviderProps, type BaseViewContextValue } from "@xmachines/play-actor";
 /**
- * Props for the ActorProvider component.
+ * The props of the ActorProvider component.
  *
  * @public
  */
 export interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
-    /** Optional component shown when currentView is null or a catalog component throws */
+    /** The component to show when currentView is null, or when a catalog component throws. This prop is optional */
     fallback?: React.ReactNode;
-    /** Optional error handler callback invoked when a catalog component throws during render */
+    /** The optional error handler. The provider calls it when a catalog component throws during a render */
     onError?: (error: Error, info: React.ErrorInfo) => void;
-    /** Child components to render inside the provider tree */
+    /** The child components to render inside the provider tree */
     children: React.ReactNode;
 }
 /**
- * Value provided by ViewContext (accessible via usePlayView()).
+ * The value that ViewContext provides. usePlayView() reads it.
  *
  * @public
  */
 export interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {
 }
 /**
- * Hook to access the current view spec, handlers, and registry.
+ * The hook that gives the current view spec, the handlers, and the registry.
  *
- * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ * Call it inside <ActorProvider> or <PlayUIProvider>.
  *
- * @throws {Error} If called outside an ActorProvider/PlayUIProvider tree
+ * @throws {Error} When the caller is outside an ActorProvider or PlayUIProvider tree
  *
  * @example
  * ```typescript
@@ -53,24 +56,25 @@ export interface ViewContextValue extends BaseViewContextValue<ComponentRegistry
  */
 export declare function usePlayView(): ViewContextValue;
 /**
- * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ * ActorProvider — the low-level provider that composes the actor lifecycle with your own 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.
+ * It subscribes to the actor.currentView signal. It manages the StateStore
+ * lifecycle of each view. It wraps the children in StateProvider and in
+ * PlayErrorBoundary. It also puts onRenderError into the component registry.
  *
- * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ * Standard use: prefer <PlayUIProvider>, and use this component only when you
+ * compose the providers yourself.
  *
  * @example
  * ```tsx
- * // Custom composition (escape hatch):
+ * // A custom composition:
  * <ActorProvider actor={actor} registryResult={registryResult}>
  *   <JSONUIProvider registry={registryResult.registry}>
  *     <PlayRenderer />
  *   </JSONUIProvider>
  * </ActorProvider>
  *
- * // Standard usage: prefer PlayUIProvider
+ * // Standard use: prefer PlayUIProvider
  * <PlayUIProvider actor={actor} registryResult={registryResult}>
  *   <PlayRenderer />
  * </PlayUIProvider>

package/dist/ActorProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActorProvider.d.ts","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACX,oBAAoB,EAEpB,iBAAiB,EACjB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAMN,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,MAAM,uBAAuB,CAAC;AAI/B;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;IACvF,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;CAAG;AAQpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAgHtD,CAAC"}
+{"version":3,"file":"ActorProvider.d.ts","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACX,oBAAoB,EAEpB,iBAAiB,EACjB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAMN,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,MAAM,uBAAuB,CAAC;AAI/B;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;IACvF,gHAAgH;IAChH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,wGAAwG;IACxG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IACxD,8DAA8D;IAC9D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;CAAG;AAQpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AA+ED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAqHtD,CAAC"}

package/dist/ActorProvider.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 /**
- * ActorProvider — escape hatch primitive for actor lifecycle management.
+ * ActorProvider — the low-level provider for the actor lifecycle.
  *
- * Owns: actor bridging, signal subscription (useSignalEffect), per-view StateStore
- * lifecycle (controlled/uncontrolled), handler resolution via inner component pattern
- * (uses useStateStore()), StateProvider wrap, PlayErrorBoundary wrap, onRenderError injection.
+ * It owns the actor bridge, the signal subscription (useSignalEffect), the
+ * StateStore lifecycle of each view (controlled and uncontrolled), the handler
+ * resolution through the inner component pattern (it uses useStateStore()), the
+ * StateProvider wrapper, the PlayErrorBoundary wrapper, and the injection of
+ * onRenderError.
  *
- * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ * Standard use: prefer <PlayUIProvider>, and use this component only when you
+ * compose the providers yourself.
  *
  * @packageDocumentation
  */
@@ -20,16 +23,16 @@ import { assertNonNullable } from "@xmachines/play";
 import { attachRenderErrorHandler, createViewStoreLifecycle, refreshContextSubtree, } from "@xmachines/play-actor";
 import { ActorContext } from "./useActor.js";
 /**
- * Internal React context for ViewContextValue.
- * Accessed via usePlayView() hook.
+ * The internal React context of ViewContextValue.
+ * The usePlayView() hook reads it.
  */
 const ViewContext = createContext(null);
 /**
- * Hook to access the current view spec, handlers, and registry.
+ * The hook that gives the current view spec, the handlers, and the registry.
  *
- * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ * Call it inside <ActorProvider> or <PlayUIProvider>.
  *
- * @throws {Error} If called outside an ActorProvider/PlayUIProvider tree
+ * @throws {Error} When the caller is outside an ActorProvider or PlayUIProvider tree
  *
  * @example
  * ```typescript
@@ -47,42 +50,47 @@ export function usePlayView() {
     return assertNonNullable(useContext(ViewContext), "ViewContext");
 }
 /**
- * Create a StateStore backed by a fresh @xstate/store atom seeded from the given state.
- * Called internally per view transition when no external store prop is provided.
+ * Creates a StateStore on a new @xstate/store atom, with the given state as its
+ * first value. The provider calls this function for each view transition, when no
+ * external store prop is present.
  */
 function createViewStore(initialState) {
     return xstateStoreStateStore({ atom: createAtom(initialState) });
 }
 /**
- * Inner component that runs inside StateProvider so it can access StateStore context
- * via useStateStore(). Resolves action handlers from registryResult.handlers() using
- * the live StateProvider set/getSnapshot functions, then exposes them via ViewContext.
+ * The inner component runs inside StateProvider, so that it can read the StateStore
+ * context with useStateStore(). It resolves each action handler from
+ * registryResult.handlers(), with the live set and getSnapshot functions of
+ * StateProvider. It then puts the handlers in ViewContext.
  */
 function ActorProviderInner({ registryResult, spec, store, children, }) {
     const stateCtx = useStateStore();
-    // Stable refs for stateCtx methods so the useMemo below doesn't need to depend
-    // on stateCtx identity (useStateStore() may return a new object each render even
-    // when the underlying store hasn't changed). The handlers factory passes these as
-    // getter functions and calls them at action-execution time, not at creation time,
-    // so reading from a ref is always correct.
+    // Stable refs of the stateCtx methods. The useMemo below therefore needs no
+    // dependency on the identity of stateCtx, because useStateStore() can return a new
+    // object on each render, also when the store below it did not change. The factory of
+    // the handlers gives these refs as getter functions, and it calls them at the moment
+    // of an action, and not at the moment of the creation. A read from a ref is therefore
+    // always correct.
     const stateCtxRef = useRef(stateCtx);
     stateCtxRef.current = stateCtx;
-    // Build a SetState adapter: the handlers factory expects an updater-function pattern
-    // ((prev) => next), while stateCtx provides path-based set/update. This adapter
-    // bridges the two so action functions can use setState if needed.
-    // Stable function reference — reads stateCtxRef.current at invocation time.
+    // Build a SetState adapter: the factory of the handlers expects the pattern of an
+    // updater function, `(prev) => next`, and stateCtx gives a set function and an update
+    // function on a path. This adapter joins the two. An action function can therefore
+    // use setState.
+    // The function reference is stable, and the function reads stateCtxRef.current at the
+    // moment of the call.
     const setStateAdapterRef = useRef((updater) => {
         const prev = stateCtxRef.current.getSnapshot();
         stateCtxRef.current.update(updater(prev));
     });
-    // Memoize handlers keyed to registryResult identity. The getter functions are
-    // stable refs so they do not contribute to invalidation. Handlers are only
-    // recreated when the registry definition itself changes (e.g. a new defineRegistry
-    // call), not on every render cycle.
+    // Keep the handlers, with the identity of registryResult as the key. The getter
+    // functions are stable refs, and they therefore cause no new computation. The code
+    // makes the handlers again only after a change of the definition of the registry, for
+    // example after a new defineRegistry call, and not on each render.
     const handlers = useMemo(() => registryResult.handlers(() => setStateAdapterRef.current, () => stateCtxRef.current.getSnapshot()), [registryResult]);
-    // Memoize the context value on its actual inputs — a fresh object every
-    // render would re-render every usePlayView() consumer even when nothing
-    // changed (wasted renders).
+    // Keep the value of the context on its real inputs. A new object on each render
+    // renders every usePlayView() consumer again, also when nothing changed, and those
+    // renders are lost work.
     const viewValue = useMemo(() => ({
         spec,
         handlers,
@@ -92,24 +100,25 @@ function ActorProviderInner({ registryResult, spec, store, children, }) {
     return _jsx(ViewContext.Provider, { value: viewValue, children: children });
 }
 /**
- * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ * ActorProvider — the low-level provider that composes the actor lifecycle with your own 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.
+ * It subscribes to the actor.currentView signal. It manages the StateStore
+ * lifecycle of each view. It wraps the children in StateProvider and in
+ * PlayErrorBoundary. It also puts onRenderError into the component registry.
  *
- * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ * Standard use: prefer <PlayUIProvider>, and use this component only when you
+ * compose the providers yourself.
  *
  * @example
  * ```tsx
- * // Custom composition (escape hatch):
+ * // A custom composition:
  * <ActorProvider actor={actor} registryResult={registryResult}>
  *   <JSONUIProvider registry={registryResult.registry}>
  *     <PlayRenderer />
  *   </JSONUIProvider>
  * </ActorProvider>
  *
- * // Standard usage: prefer PlayUIProvider
+ * // Standard use: prefer PlayUIProvider
  * <PlayUIProvider actor={actor} registryResult={registryResult}>
  *   <PlayRenderer />
  * </PlayUIProvider>
@@ -118,45 +127,47 @@ function ActorProviderInner({ registryResult, spec, store, children, }) {
  * @public
  */
 export const ActorProvider = ({ actor, registryResult, store: externalStore, fallback = null, onError, onRenderError, children, }) => {
-    // React state for triggering re-renders (NOT business logic state)
-    // Signal is source of truth, useState is just React's render trigger
+    // React state, for the trigger of a new render. It is NOT the state of the business
+    // logic. The signal is the source of truth, and useState is the render trigger of
+    // React only.
     const [view, setView] = useState(() => actor.currentView.get());
-    // Store lifecycle (reseed on viewKey change, refresh /context in place
-    // otherwise, actor-swap reset, guard identity cache) — the shared
-    // coordinator from @xmachines/play-actor; only the reactivity wiring
-    // (render path + effects below) is React's.
+    // The store lifecycle: it seeds the store again on a change of the viewKey, it
+    // refreshes /context in place in every other case, it resets the store on a change of
+    // the actor, and it guards the identity cache. The shared coordinator comes from
+    // @xmachines/play-actor. Only the wiring of the reactivity, which is the render path
+    // and the effects below, belongs to React.
     const storeLifecycleRef = useRef(null);
     storeLifecycleRef.current ??= createViewStoreLifecycle(createViewStore);
     const storeLifecycle = storeLifecycleRef.current;
-    // Latest external store for the signal effect below — the effect's deps are
-    // [actor], so it must not close over a possibly-stale prop.
+    // The newest external store, for the signal effect below. The deps of that effect are
+    // [actor]. Therefore the effect must hold no prop that can be old.
     const externalStoreRef = useRef(externalStore);
     externalStoreRef.current = externalStore;
-    // Subscribe to signal changes. The [actor] dep re-creates the watcher when
-    // the actor prop swaps — without it the watcher keeps tracking the OLD
-    // actor's currentView signal and the rendered view freezes on the old actor
-    // while events flow to the new one.
+    // Subscribe to the signal changes. The [actor] dependency makes the watcher again
+    // when the actor prop changes. Without it, the watcher tracks the currentView signal
+    // of the OLD actor, and the view on the screen freezes on the old actor while the
+    // events go to the new one.
     //
-    // Store sync happens HERE, before setView triggers the re-render, so the
-    // store and the spec the children see are always a consistent pair — and so
-    // store subscribers are never notified during a render pass.
+    // The store update happens HERE, before setView starts the new render. Therefore the
+    // store and the spec of the children are always a consistent pair, and the store
+    // notifies its subscribers never during a render pass.
     useSignalEffect(() => {
         const currentView = actor.currentView.get();
         if (currentView) {
-            // Controlled mode included: /context is machinery-owned in both
-            // modes, and refreshing the external store is allowed here (the
-            // effect runs post-commit, never during a render pass).
+            // The controlled mode is here too: the machinery owns /context in both modes, and a
+            // refresh of the external store is permitted here, because the effect runs after the
+            // commit, and never during a render pass.
             storeLifecycle.resolve(actor, currentView, externalStoreRef.current);
         }
         setView(currentView);
     }, [actor]);
-    // Controlled mode: refresh the external store's /context BEFORE paint. The
-    // render path hands children the external store untouched (the machinery
-    // must not notify store subscribers mid-render), and the passive signal
-    // effect above runs after paint — this layout effect closes the first-paint
-    // gap. Keyed on the store identity too, so swapping the controlled store
-    // prop mid-session brings the NEW store in line immediately instead of
-    // waiting for the next view emission.
+    // The controlled mode: refresh the /context of the external store BEFORE the paint.
+    // The render path gives the children the external store without a change, because the
+    // machinery must notify no store subscriber during a render, and the passive signal
+    // effect above runs after the paint. This layout effect closes the gap of the first
+    // paint. Its key also holds the identity of the store. Therefore a new controlled
+    // store prop during a session brings the NEW store in line at once, and it waits not
+    // for the next emission of a view.
     useLayoutEffect(() => {
         if (!externalStore)
             return;
@@ -164,11 +175,13 @@ export const ActorProvider = ({ actor, registryResult, store: externalStore, fal
         if (currentView)
             refreshContextSubtree(externalStore, currentView);
     }, [externalStore, actor]);
-    // Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)
-    // Centralised here per D-19 — one location for all framework renderers.
-    // Memoized on its actual inputs: rebuilding the injected registry every render
-    // would churn registry identity and invalidate ActorProviderInner's handlers
-    // useMemo on every render (wasted work + wasted consumer re-renders).
+    // Put the onRenderError prop into the registry. The property is not enumerable, and
+    // it replaces the handler of the defineRegistry level.
+    // D-19 puts this work here: one place for every framework renderer.
+    // The code keeps the result on its real inputs. A new injected registry on each render
+    // churns the identity of the registry, and it therefore invalidates the handlers
+    // useMemo of ActorProviderInner on each render. That is lost work, and each consumer
+    // also renders again for nothing.
     const activeRegistryResult = useMemo(() => {
         if (!onRenderError)
             return registryResult;
@@ -177,25 +190,26 @@ export const ActorProvider = ({ actor, registryResult, store: externalStore, fal
             registry: attachRenderErrorHandler(registryResult.registry, onRenderError),
         };
     }, [registryResult, onRenderError]);
-    // Resolve the store for StateProvider on the render path too — it covers
-    // the first render (the useState initializer seeded `view` before any
-    // effect ran) and is a no-op afterwards: reseeding branches on viewKey, and
-    // the /context refresh compares before writing, so no subscriber is
-    // notified mid-render. The EXTERNAL store's refresh is deferred here for
-    // the same mid-render reason — the layout effect above handles it.
-    // Children get the guarded store: /context is read-only to the spec
-    // ($bindState, setState, chained set) — machine context changes only
-    // through events; the identity is cached per underlying store inside the
-    // coordinator, so consumers stay referentially stable.
+    // Resolve the store of StateProvider on the render path too. This covers the first
+    // render, where the initializer of useState seeded `view` before an effect ran, and it
+    // does nothing after that: a new seed branches on the viewKey, and the /context
+    // refresh compares the values before a write. Therefore the store notifies no
+    // subscriber during a render. The refresh of the EXTERNAL store waits here, for the
+    // same reason of the render, and the layout effect above does it.
+    // The children receive the store with the guard: /context is read-only to the spec,
+    // which includes $bindState, setState, and a chained set, because the machine context
+    // changes through an event only. The coordinator keeps the identity of the guard for
+    // each store below it. Therefore each consumer stays stable by its reference.
     const guardedStore = view
         ? storeLifecycle.resolve(actor, view, externalStore, { refreshExternalStore: false })
             .guardedStore
         : null;
-    // No view in current state — render fallback INSIDE ActorContext so a
-    // fallback component can call useActor() (e.g. to send a retry event).
-    // Parity with the error-boundary fallback below and with the Solid/Svelte/Vue
-    // renderers, which all provide context to their null-view fallbacks.
-    // ViewContext is intentionally NOT provided: there is no view spec to expose.
+    // The current state has no view: render the fallback INSIDE ActorContext, so that a
+    // fallback component can call useActor(), for example to send an event of a retry.
+    // The fallback of the error boundary below does the same, and so do the renderers of
+    // Solid, of Svelte, and of Vue: each of them gives the context to its fallback of a
+    // null view.
+    // The code gives ViewContext deliberately NOT: there is no view spec to give.
     if (!view || !guardedStore) {
         return (_jsx(ActorContext.Provider, { value: actor, children: fallback }));
     }

package/dist/ActorProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"ActorProvider.js","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ActorProvider.js","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"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"}