@xmachines/play-react 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/PlayErrorBoundary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PlayErrorBoundary - React error boundary for catching catalog component render errors
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+/**
+ * Props for PlayErrorBoundary
+ *
+ * @public
+ */
+export interface PlayErrorBoundaryProps {
+    /** Fallback UI to render when a child component throws. Defaults to null. */
+    fallback?: React.ReactNode;
+    /** Child components to render */
+    children: React.ReactNode;
+    /** Optional error handler callback — forwards errors to observability tools (Sentry, etc.) */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+/**
+ * Internal state shape for PlayErrorBoundary
+ *
+ * @public
+ */
+export interface PlayErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * React class component error boundary for catching catalog component render errors.
+ *
+ * Wraps catalog component renders so failures are caught and forwarded to standard
+ * React error boundary protocol. Consumers can attach the `onError` prop to forward
+ * errors to production observability tools (Sentry, Datadog, etc.).
+ *
+ * **React 19 safety (Phase 29):** `componentDidCatch` calls `onError` for observability
+ * but does NOT re-throw. `getDerivedStateFromError` already sets the fallback state —
+ * re-throwing from `componentDidCatch` can unmount the entire React 19 root.
+ *
+ * Per CONS-14: Class component pattern works with all React versions (18 and 19).
+ *
+ * @example
+ * ```tsx
+ * <PlayErrorBoundary fallback={<div>Something went wrong</div>} onError={Sentry.captureException}>
+ *   <CatalogComponent {...props} />
+ * </PlayErrorBoundary>
+ * ```
+ */
+export declare class PlayErrorBoundary extends React.Component<PlayErrorBoundaryProps, PlayErrorBoundaryState> {
+    constructor(props: PlayErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): PlayErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+//# sourceMappingURL=PlayErrorBoundary.d.ts.map

package/dist/PlayErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayErrorBoundary.d.ts","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK,CAAC,SAAS,CACrD,sBAAsB,EACtB,sBAAsB,CACtB;gBACY,KAAK,EAAE,sBAAsB;IAKzC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,sBAAsB;IAI5D,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;IAI5D,MAAM,IAAI,KAAK,CAAC,SAAS;CAMlC"}

package/dist/PlayErrorBoundary.js

@@ -0,0 +1,45 @@
+/**
+ * PlayErrorBoundary - React error boundary for catching catalog component render errors
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+/**
+ * React class component error boundary for catching catalog component render errors.
+ *
+ * Wraps catalog component renders so failures are caught and forwarded to standard
+ * React error boundary protocol. Consumers can attach the `onError` prop to forward
+ * errors to production observability tools (Sentry, Datadog, etc.).
+ *
+ * **React 19 safety (Phase 29):** `componentDidCatch` calls `onError` for observability
+ * but does NOT re-throw. `getDerivedStateFromError` already sets the fallback state —
+ * re-throwing from `componentDidCatch` can unmount the entire React 19 root.
+ *
+ * Per CONS-14: Class component pattern works with all React versions (18 and 19).
+ *
+ * @example
+ * ```tsx
+ * <PlayErrorBoundary fallback={<div>Something went wrong</div>} onError={Sentry.captureException}>
+ *   <CatalogComponent {...props} />
+ * </PlayErrorBoundary>
+ * ```
+ */
+export class PlayErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, info) {
+        this.props.onError?.(error, info);
+    }
+    render() {
+        if (this.state.hasError) {
+            return this.props.fallback ?? null;
+        }
+        return this.props.children;
+    }
+}
+//# sourceMappingURL=PlayErrorBoundary.js.map

package/dist/PlayErrorBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayErrorBoundary.js","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AA0B1B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK,CAAC,SAG5C;IACA,YAAY,KAA6B;QACxC,KAAK,CAAC,KAAK,CAAC,CAAC;QACb,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC3C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAqB;QAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAEQ,MAAM;QACd,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC5B,CAAC;CACD"}

package/dist/PlayRenderer.d.ts

@@ -1,18 +1,24 @@
 /**
  * PlayRenderer - Main React renderer component for XMachines Play architecture
  *
+ * Backed by @json-render/react for spec-driven UI rendering.
+ *
  * @packageDocumentation
  */
 import React from "react";
 import type { PlayRendererProps } from "./types.js";
 /**
  * Main renderer component that subscribes to actor signals and renders UI
+ * via @json-render/react Renderer.
  *
- * Architecture (per RESEARCH.md Pattern 1):
+ * Architecture:
  * - 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
+ * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
+ * - Routes action names to actor.send() via the `actions` prop mapping
+ * - State store: uses external `store` prop if provided (controlled mode); otherwise
+ *   creates a fresh @xstate/store atom per view transition seeded from spec.state.
+ *   The atom resets automatically when the actor transitions to a new view, mirroring
+ *   the actor's currentView lifecycle.
  *
  * Invariant: Actor Authority - Actor decides all state transitions via guards.
  * Invariant: Passive Infrastructure - Component observes signals and sends events.
@@ -21,37 +27,22 @@ import type { PlayRendererProps } from "./types.js";
  * @example
  * ```typescript
  * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
+ * import { defineRegistry } from "@json-render/react";
  *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * const { registry } = defineRegistry(catalog, { components: { ... } });
  *
- * 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>
- * };
+ * // Uncontrolled — fresh atom created per view, seeded from spec.state:
+ * <PlayRenderer actor={actor} registry={registry} actions={{ login: "auth.login" }} />
  *
- * <PlayRenderer actor={actor} components={components} />
+ * // Controlled — caller provides and owns the store:
+ * import { createAtom } from "@xstate/store";
+ * import { xstateStoreStateStore } from "@json-render/xstate";
+ * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
+ * <PlayRenderer actor={actor} registry={registry} store={store} actions={{ login: "auth.login" }} />
  * ```
  *
  * @param props - 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.
  */
 export declare const PlayRenderer: React.FC<PlayRendererProps>;
 //# sourceMappingURL=PlayRenderer.d.ts.map

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AAExC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA2CpD,CAAC"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAOhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAYpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAqEpD,CAAC"}

package/dist/PlayRenderer.js

@@ -2,18 +2,36 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 /**
  * PlayRenderer - Main React renderer component for XMachines Play architecture
  *
+ * Backed by @json-render/react for spec-driven UI rendering.
+ *
  * @packageDocumentation
  */
-import React, { useState } from "react";
+import React, { useState, useRef } from "react";
+import { Renderer, StateProvider, ActionProvider, VisibilityProvider } from "@json-render/react";
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
 import { useSignalEffect } from "./useSignalEffect.js";
+import { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+import { ActorContext } from "./useActor.js";
+/**
+ * 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.
+ */
+function createViewStore(initialState) {
+    return xstateStoreStateStore({ atom: createAtom(initialState) });
+}
 /**
  * Main renderer component that subscribes to actor signals and renders UI
+ * via @json-render/react Renderer.
  *
- * Architecture (per RESEARCH.md Pattern 1):
+ * Architecture:
  * - 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
+ * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
+ * - Routes action names to actor.send() via the `actions` prop mapping
+ * - State store: uses external `store` prop if provided (controlled mode); otherwise
+ *   creates a fresh @xstate/store atom per view transition seeded from spec.state.
+ *   The atom resets automatically when the actor transitions to a new view, mirroring
+ *   the actor's currentView lifecycle.
  *
  * Invariant: Actor Authority - Actor decides all state transitions via guards.
  * Invariant: Passive Infrastructure - Component observes signals and sends events.
@@ -22,66 +40,64 @@ import { useSignalEffect } from "./useSignalEffect.js";
  * @example
  * ```typescript
  * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
+ * import { defineRegistry } from "@json-render/react";
  *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * const { registry } = defineRegistry(catalog, { components: { ... } });
  *
- * 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>
- * };
+ * // Uncontrolled — fresh atom created per view, seeded from spec.state:
+ * <PlayRenderer actor={actor} registry={registry} actions={{ login: "auth.login" }} />
  *
- * <PlayRenderer actor={actor} components={components} />
+ * // Controlled — caller provides and owns the store:
+ * import { createAtom } from "@xstate/store";
+ * import { xstateStoreStateStore } from "@json-render/xstate";
+ * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
+ * <PlayRenderer actor={actor} registry={registry} store={store} actions={{ login: "auth.login" }} />
  * ```
  *
  * @param props - 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.
  */
-export const PlayRenderer = ({ actor, components, fallback = null, }) => {
+export const PlayRenderer = ({ actor, registry, store: externalStore, fallback = null, onError, actions = {}, }) => {
     // React state for triggering re-renders (NOT business logic state)
     // Signal is source of truth, useState is just React's render trigger
     const [view, setView] = useState(() => actor.currentView.get());
+    // Internal store ref — tracks the current per-view atom store.
+    // Keyed to view identity: recreated whenever the view changes (new spec.state seed).
+    // Ignored when externalStore is provided.
+    const internalStoreRef = useRef(null);
+    const lastViewRef = useRef(null);
     // Subscribe to signal changes
     useSignalEffect(() => {
         const currentView = actor.currentView.get();
         setView(currentView);
     });
-    // No view in current state
+    // No view in current state — render fallback
     if (!view) {
         return _jsx(_Fragment, { children: fallback });
     }
-    // Handle null/undefined components catalog gracefully
-    if (!components) {
-        console.error(`Components catalog is ${components === null ? "null" : "undefined"}. ` +
-            `Cannot render component "${view.component}".`);
-        return _jsx(_Fragment, { children: fallback });
+    // Resolve the store to use for StateProvider:
+    // - External (controlled): use as-is, caller manages lifecycle
+    // - Internal: create a fresh atom when the view changes (new route/state)
+    let store;
+    if (externalStore) {
+        store = externalStore;
     }
-    // Look up component from catalog
-    const Component = components[view.component];
-    if (!Component) {
-        console.error(`Component "${view.component}" not found in catalog. ` +
-            `Available components: ${Object.keys(components).join(", ")}`);
-        return _jsx(_Fragment, { children: fallback });
+    else {
+        // Recreate the internal store when the view identity changes
+        // (view is a new object on every transition per deriveCurrentView)
+        if (internalStoreRef.current === null || lastViewRef.current !== view) {
+            const initialState = view.spec?.state ?? {};
+            internalStoreRef.current = createViewStore(initialState);
+            lastViewRef.current = view;
+        }
+        store = internalStoreRef.current;
     }
-    // Render with props from actor + send function
-    // bind(actor) ensures 'this' context is correct when components call send()
-    return _jsx(Component, { ...view.props, send: actor.send.bind(actor) });
+    // Build ActionProvider handlers from actions mapping
+    // Each handler calls actor.send() with the configured event type + params
+    const handlers = Object.fromEntries(Object.entries(actions).map(([actionName, eventType]) => [
+        actionName,
+        async (params = {}) => actor.send({ type: eventType, ...params }),
+    ]));
+    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, ...(onError && { onError }), children: _jsx(StateProvider, { store: store, children: _jsx(ActionProvider, { handlers: handlers, children: _jsx(VisibilityProvider, { children: _jsx(Renderer, { spec: view.spec ?? null, registry: registry }) }) }) }) }) }));
 };
 //# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgC,CAAC,EACzD,KAAK,EACL,UAAU,EACV,QAAQ,GAAG,IAAI,GACf,EAAE,EAAE;IACJ,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAEhE,8BAA8B;IAC9B,eAAe,CAAC,GAAG,EAAE;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAC5C,OAAO,CAAC,WAAW,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,UAAU,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CACZ,yBAAyB,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI;YACtE,4BAA4B,IAAI,CAAC,SAAS,IAAI,CAC/C,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE7C,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACZ,cAAc,IAAI,CAAC,SAAS,0BAA0B;YACrD,yBAAyB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9D,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,+CAA+C;IAC/C,4EAA4E;IAC5E,OAAO,KAAC,SAAS,OAAK,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAI,CAAC;AACpE,CAAC,CAAC"}
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Error class for renderer-level errors in the Play architecture.
+ *
+ * **Note (Phase 29):** `PlayErrorBoundary.componentDidCatch()` no longer throws
+ * this error. Re-throwing from `componentDidCatch` can unmount the entire React 19
+ * root. `RendererError` is retained for programmatic use in custom error handlers
+ * and parent boundaries — it is no longer emitted by the built-in boundary itself.
+ *
+ * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
+ *
+ * @example
+ * ```typescript
+ * import { RendererError } from "@xmachines/play-react/errors";
+ *
+ * // Create a RendererError programmatically in a custom boundary:
+ * throw new RendererError("Custom render failure", { cause: originalError });
+ * ```
+ */
+export declare class RendererError extends PlayError {
+    constructor(message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Error class for renderer-level errors in the Play architecture.
+ *
+ * **Note (Phase 29):** `PlayErrorBoundary.componentDidCatch()` no longer throws
+ * this error. Re-throwing from `componentDidCatch` can unmount the entire React 19
+ * root. `RendererError` is retained for programmatic use in custom error handlers
+ * and parent boundaries — it is no longer emitted by the built-in boundary itself.
+ *
+ * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
+ *
+ * @example
+ * ```typescript
+ * import { RendererError } from "@xmachines/play-react/errors";
+ *
+ * // Create a RendererError programmatically in a custom boundary:
+ * throw new RendererError("Custom render failure", { cause: originalError });
+ * ```
+ */
+export class RendererError extends PlayError {
+    constructor(message, options) {
+        super("PlayRenderer", "PLAY_RENDERER_RENDER_ERROR", message, options);
+        this.name = "RendererError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CAAC,cAAc,EAAE,4BAA4B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC7B,CAAC;CACD"}

package/dist/index.d.ts

@@ -2,17 +2,27 @@
  * @xmachines/play-react - React renderer for XMachines Play architecture
  *
  * Provides a thin React rendering layer that passively observes actor signals
- * and renders UI components from catalog definitions. This package enables
+ * and renders UI components via @json-render/react. This package enables
  * framework-swappable architecture where React is just a rendering target
  * that subscribes to signal changes.
  *
  * **Key principle:** React state is NEVER used for business logic—only for
  * triggering React's render cycle. Signals are the source of truth.
  *
+ * Re-exports `defineRegistry`, `useStateBinding`, `ComponentFn`, and
+ * `ComponentContext` from `@json-render/react` so consumers import everything
+ * from `@xmachines/play-react` rather than `@json-render/react` directly.
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 export { PlayRenderer } from "./PlayRenderer.js";
 export { useSignalEffect } from "./useSignalEffect.js";
+export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+export { useActor } from "./useActor.js";
+export { defineRegistry, useStateBinding, useBoundProp } from "@json-render/react";
+export type { ComponentFn, ComponentContext } from "@json-render/react";
 export type { PlayRendererProps } from "./types.js";
+export type { PlayErrorBoundaryProps, PlayErrorBoundaryState } from "./PlayErrorBoundary.js";
+export type { PlayActor } from "./useActor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -2,17 +2,26 @@
  * @xmachines/play-react - React renderer for XMachines Play architecture
  *
  * Provides a thin React rendering layer that passively observes actor signals
- * and renders UI components from catalog definitions. This package enables
+ * and renders UI components via @json-render/react. This package enables
  * framework-swappable architecture where React is just a rendering target
  * that subscribes to signal changes.
  *
  * **Key principle:** React state is NEVER used for business logic—only for
  * triggering React's render cycle. Signals are the source of truth.
  *
+ * Re-exports `defineRegistry`, `useStateBinding`, `ComponentFn`, and
+ * `ComponentContext` from `@json-render/react` so consumers import everything
+ * from `@xmachines/play-react` rather than `@json-render/react` directly.
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 // Main exports
 export { PlayRenderer } from "./PlayRenderer.js";
 export { useSignalEffect } from "./useSignalEffect.js";
+export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+export { useActor } from "./useActor.js";
+// Re-export from @json-render/react so consumers import everything from @xmachines/play-react.
+// React's useContext works anywhere in the call tree — no wrapper needed.
+export { defineRegistry, useStateBinding, useBoundProp } from "@json-render/react";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types.d.ts

@@ -3,22 +3,65 @@
  *
  * @packageDocumentation
  */
+import type { ComponentRegistry } from "@json-render/react";
+import type { StateStore } from "@json-render/core";
 import type { AbstractActor, Viewable } from "@xmachines/play-actor";
 import type React from "react";
-import type { AnyActorLogic } from "xstate";
+import type { AnyActorLogic, EventFromLogic } from "xstate";
 /**
  * Props for PlayRenderer component
  *
+ * @typeParam TLogic - The XState actor logic type. Defaults to `AnyActorLogic` for
+ *   non-generic usage. When a specific machine type is provided, the `actions` values
+ *   are constrained to the event type strings that the machine actually accepts.
+ *
  * @property actor - Actor instance with currentView signal (requires Viewable capability)
- * @property components - Map of component names to React components
+ * @property registry - ComponentRegistry from defineRegistry() in @json-render/react
+ * @property store - Optional external StateStore (e.g. from @json-render/xstate). When
+ *   provided, PlayRenderer operates in controlled mode — spec.state is ignored and the
+ *   store is the single source of truth for UI state. When omitted, a fresh
+ *   @xstate/store atom is created internally per view transition, seeded from spec.state.
  * @property fallback - Optional component shown when currentView is null
+ * @property onError - Optional callback invoked when a catalog component throws during render.
+ *   Receives the error and React ErrorInfo — use to forward to Sentry, Datadog, etc.
+ * @property actions - Maps json-render action names to XState event type strings.
+ *   Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent
+ *   event type string is a compile error when TLogic is specified.
  */
-export interface PlayRendererProps {
+export interface PlayRendererProps<TLogic extends AnyActorLogic = AnyActorLogic> {
     /** Actor instance with currentView signal (requires Viewable capability) */
-    actor: AbstractActor<AnyActorLogic> & Viewable;
-    /** Map of component names to React components */
-    components: Record<string, React.ElementType>;
-    /** Optional component shown when currentView is null */
+    actor: AbstractActor<TLogic> & Viewable;
+    /** ComponentRegistry from defineRegistry() in @json-render/react */
+    registry: ComponentRegistry;
+    /**
+     * Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate).
+     * When provided, PlayRenderer operates in controlled mode — spec.state is ignored and
+     * this store is the single source of truth for UI state (form values, etc.).
+     * When omitted, a fresh @xstate/store atom is created internally per view transition,
+     * seeded from spec.state. The atom resets automatically when the actor transitions to a
+     * new view, mirroring the actor's currentView lifecycle.
+     */
+    store?: StateStore;
+    /** Optional component shown when currentView is null or a catalog component throws */
     fallback?: React.ReactNode;
+    /**
+     * Optional error handler callback invoked when a catalog component throws during render.
+     * Forwarded directly to the internal `PlayErrorBoundary` — use to integrate with
+     * production observability tools (Sentry, Datadog, etc.).
+     *
+     * @example
+     * ```tsx
+     * <PlayRenderer actor={actor} registry={registry} onError={Sentry.captureException} />
+     * ```
+     */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    /**
+     * Maps json-render action names to XState event type strings.
+     * Values are constrained to valid event types for TLogic — wrong event type strings
+     * are caught at compile time when TLogic is specified.
+     */
+    actions?: {
+        [actionName: string]: EventFromLogic<TLogic>["type"];
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAE/C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAE9C,wDAAwD;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IAC9E,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IAExC,oEAAoE;IACpE,QAAQ,EAAE,iBAAiB,CAAC;IAE5B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IAExD;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACnE"}

package/dist/useActor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * useActor — React hook for accessing the raw actor inside a PlayRenderer tree.
+ *
+ * Components rendered inside PlayRenderer can call useActor() to get direct
+ * access to the actor instance without prop drilling.
+ *
+ * @throws {Error} If called outside a PlayRenderer tree
+ *
+ * @example
+ * ```typescript
+ * import { useActor } from "@xmachines/play-react";
+ *
+ * function MyComponent() {
+ *   const actor = useActor();
+ *   return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AbstractActor } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+export type PlayActor = AbstractActor<AnyActorLogic>;
+export declare const ActorContext: import("react").Context<PlayActor | null>;
+export declare function useActor(): PlayActor;
+//# sourceMappingURL=useActor.d.ts.map

package/dist/useActor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActor.d.ts","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAErD,eAAO,MAAM,YAAY,2CAAwC,CAAC;AAElE,wBAAgB,QAAQ,IAAI,SAAS,CAIpC"}

package/dist/useActor.js

@@ -0,0 +1,29 @@
+/**
+ * useActor — React hook for accessing the raw actor inside a PlayRenderer tree.
+ *
+ * Components rendered inside PlayRenderer can call useActor() to get direct
+ * access to the actor instance without prop drilling.
+ *
+ * @throws {Error} If called outside a PlayRenderer tree
+ *
+ * @example
+ * ```typescript
+ * import { useActor } from "@xmachines/play-react";
+ *
+ * function MyComponent() {
+ *   const actor = useActor();
+ *   return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { createContext, useContext } from "react";
+export const ActorContext = createContext(null);
+export function useActor() {
+    const actor = useContext(ActorContext);
+    if (!actor)
+        throw new Error("useActor() must be called inside <PlayRenderer>");
+    return actor;
+}
+//# sourceMappingURL=useActor.js.map

package/dist/useActor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActor.js","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAMlD,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAmB,IAAI,CAAC,CAAC;AAElE,MAAM,UAAU,QAAQ;IACvB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC/E,OAAO,KAAK,CAAC;AACd,CAAC"}