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

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 actions via registryResult.handlers() — real async functions dispatching to actor.
+ * - 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,29 @@ import type { PlayRendererProps } from "./types.js";
  * @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} />
+ * import { defineRegistry } from "@json-render/react";
+ *
+ * const registryResult = defineRegistry(catalog, {
+ *   components: { Login, Dashboard },
+ *   actions: {
+ *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+ *     logout: async () => actor.send({ type: 'auth.logout' }),
+ *     route: async ({ to, params }) => actor.send({ type: 'play.route', to, params }),
+ *   },
+ * });
+ *
+ * // Uncontrolled — fresh atom created per view, seeded from spec.state:
+ * <PlayRenderer actor={actor} registryResult={registryResult} />
+ *
+ * // 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} registryResult={registryResult} store={store} />
  * ```
  *
  * @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;AAchD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiDpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAuDpD,CAAC"}

package/dist/PlayRenderer.js

@@ -1,19 +1,54 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment } 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, useStateStore, } 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) });
+}
+/**
+ * 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 renders ActionProvider.
+ */
+function PlayRendererInner({ registryResult, spec, }) {
+    const stateCtx = useStateStore();
+    // 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.
+    const setStateAdapter = (updater) => {
+        const prev = stateCtx.getSnapshot();
+        stateCtx.update(updater(prev));
+    };
+    const handlers = registryResult.handlers(() => setStateAdapter, () => stateCtx.getSnapshot());
+    return (_jsx(ActionProvider, { handlers: handlers, children: _jsx(VisibilityProvider, { children: _jsx(Renderer, { spec: spec, registry: registryResult.registry }) }) }));
+}
 /**
  * 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 actions via registryResult.handlers() — real async functions dispatching to actor.
+ * - 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 +57,65 @@ 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 registryResult = defineRegistry(catalog, {
+ *   components: { Login, Dashboard },
+ *   actions: {
+ *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+ *     logout: async () => actor.send({ type: 'auth.logout' }),
+ *     route: async ({ to, params }) => actor.send({ type: 'play.route', to, params }),
+ *   },
+ * });
  *
- * 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} registryResult={registryResult} />
  *
- * <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} registryResult={registryResult} store={store} />
  * ```
  *
  * @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, registryResult, store: externalStore, fallback = null, onError, }) => {
     // 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) });
+    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, ...(onError && { onError }), children: _jsx(StateProvider, { store: store, children: _jsx(PlayRendererInner, { registryResult: registryResult, spec: view.spec ?? null }) }) }) }));
 };
 //# 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`, `useBoundProp`, `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, 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,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClE,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`, `useBoundProp`, `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, 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,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types.d.ts

@@ -3,22 +3,66 @@
  *
  * @packageDocumentation
  */
+import type { DefineRegistryResult } 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";
 /**
  * Props for PlayRenderer component
  *
+ * @typeParam TLogic - The XState actor logic type. Defaults to `AnyActorLogic` for
+ *   non-generic usage.
+ *
  * @property actor - Actor instance with currentView signal (requires Viewable capability)
- * @property components - Map of component names to React components
+ * @property registryResult - Full result from defineRegistry() in @json-render/react.
+ *   Contains both the component registry and the action handlers factory. Action handlers
+ *   are real async functions dispatching to the actor (not string-mapped event types).
+ * @property store - Optional external StateStore (controlled mode).
  * @property fallback - Optional component shown when currentView is null
+ * @property onError - Optional callback invoked when a catalog component throws during render.
  */
-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;
+    /**
+     * Full result from defineRegistry() — contains component registry and action handlers.
+     * Action handlers are async functions that dispatch to the actor (not string-mapped
+     * event type stubs). Replaces the old `registry` + `actions` prop pair.
+     *
+     * @example
+     * ```tsx
+     * const registryResult = defineRegistry(catalog, {
+     *   components: { Login, Dashboard },
+     *   actions: {
+     *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+     *     logout: async () => actor.send({ type: 'auth.logout' }),
+     *   },
+     * });
+     * <PlayRenderer actor={actor} registryResult={registryResult} />
+     * ```
+     */
+    registryResult: DefineRegistryResult;
+    /**
+     * 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.
+     */
+    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} registryResult={registryResult} onError={Sentry.captureException} />
+     * ```
+     */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
 }
 //# 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,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,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,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IAC9E,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,EAAE,oBAAoB,CAAC;IAErC;;;;;;OAMG;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;CACxD"}

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"}

package/dist/useSignalEffect.d.ts

@@ -51,6 +51,12 @@
  * **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.
+ *
+ * **Memory safety (Phase 29):**
+ * - `disposed` flag prevents post-cleanup callback execution: if cleanup is
+ *   called before a pending microtask fires, the microtask returns early.
+ * - `needsEnqueue` guard dedups rapid synchronous signal changes: only one
+ *   microtask is ever queued per batch of synchronous mutations.
  */
 export declare const useSignalEffect: (callback: () => void | (() => void)) => void;
 //# sourceMappingURL=useSignalEffect.d.ts.map

package/dist/useSignalEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSignalEffect.d.ts","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,KAAG,IAuDrE,CAAC"}
+{"version":3,"file":"useSignalEffect.d.ts","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,KAAG,IA+DrE,CAAC"}