@xmachines/play-react 1.0.0-beta.4 → 1.0.0-beta.40

package/dist/ActorProvider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ActorProvider — escape hatch primitive for actor lifecycle management.
+ *
+ * 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.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import type { DefineRegistryResult, ComponentRegistry } from "@json-render/react";
+import type { BaseActorProviderProps, BaseViewContextValue } from "@xmachines/play-actor";
+/**
+ * Props for the ActorProvider component.
+ *
+ * @public
+ */
+export interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+    /** 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 */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    /** Child components to render inside the provider tree */
+    children: React.ReactNode;
+}
+/**
+ * Value provided by ViewContext (accessible via usePlayView()).
+ *
+ * @public
+ */
+export interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {
+}
+/**
+ * Hook to access the current view spec, handlers, and registry.
+ *
+ * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ *
+ * @throws {Error} If called outside an ActorProvider/PlayUIProvider tree
+ *
+ * @example
+ * ```typescript
+ * import { usePlayView } from "@xmachines/play-react";
+ *
+ * function MyRenderer() {
+ *   const view = usePlayView();
+ *   return <Renderer spec={view.spec} registry={view.registry} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function usePlayView(): ViewContextValue;
+/**
+ * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ *
+ * Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+ * wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+ * into the component registry.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @example
+ * ```tsx
+ * // Custom composition (escape hatch):
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ *
+ * // Standard usage: prefer PlayUIProvider
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export declare const ActorProvider: React.FC<ActorProviderProps>;
+//# sourceMappingURL=ActorProvider.d.ts.map

package/dist/ActorProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.d.ts","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAsD,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAE,oBAAoB,EAAY,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5F,OAAO,KAAK,EAAY,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAIpG;;;;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;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CA0FtD,CAAC"}

package/dist/ActorProvider.js

@@ -0,0 +1,167 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ActorProvider — escape hatch primitive for actor lifecycle management.
+ *
+ * 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.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @packageDocumentation
+ */
+import React, { useState, useRef, createContext, useContext } from "react";
+import { StateProvider, 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 { assertNonNullable } from "@xmachines/play";
+import { ActorContext } from "./useActor.js";
+/**
+ * Internal React context for ViewContextValue.
+ * Accessed via usePlayView() hook.
+ */
+const ViewContext = createContext(null);
+/**
+ * Hook to access the current view spec, handlers, and registry.
+ *
+ * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ *
+ * @throws {Error} If called outside an ActorProvider/PlayUIProvider tree
+ *
+ * @example
+ * ```typescript
+ * import { usePlayView } from "@xmachines/play-react";
+ *
+ * function MyRenderer() {
+ *   const view = usePlayView();
+ *   return <Renderer spec={view.spec} registry={view.registry} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+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.
+ */
+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.
+ */
+function ActorProviderInner({ registryResult, spec, store, children, }) {
+    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());
+    const viewValue = {
+        spec,
+        handlers,
+        registry: registryResult.registry,
+        store,
+    };
+    return _jsx(ViewContext.Provider, { value: viewValue, children: children });
+}
+/**
+ * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ *
+ * Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+ * wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+ * into the component registry.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @example
+ * ```tsx
+ * // Custom composition (escape hatch):
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ *
+ * // Standard usage: prefer PlayUIProvider
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @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
+    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);
+    });
+    // Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)
+    // Centralised here per D-19 — one location for all framework renderers
+    const activeRegistryResult = onRenderError
+        ? {
+            ...registryResult,
+            registry: (() => {
+                const r = { ...registryResult.registry };
+                Object.defineProperty(r, "onRenderError", {
+                    value: onRenderError,
+                    enumerable: false,
+                    configurable: true,
+                });
+                return r;
+            })(),
+        }
+        : registryResult;
+    // No view in current state — render fallback
+    if (!view) {
+        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;
+    }
+    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) {
+            // Proto-safe guard (T-37-03-01): prevents Date/Array/class-instance from being
+            // passed to createAtom. Replaces the weak `?? {}` guard from old code_context.
+            const rawState = view.state;
+            const initialState = rawState !== null &&
+                rawState !== undefined &&
+                typeof rawState === "object" &&
+                !Array.isArray(rawState) &&
+                (Object.getPrototypeOf(rawState) === Object.prototype ||
+                    Object.getPrototypeOf(rawState) === null)
+                ? rawState
+                : {};
+            internalStoreRef.current = createViewStore(initialState);
+            lastViewRef.current = view;
+        }
+        store = internalStoreRef.current;
+    }
+    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, ...(onError && { onError }), children: _jsx(StateProvider, { store: store, children: _jsx(ActorProviderInner, { registryResult: activeRegistryResult, spec: view, store: store, children: children }) }) }) }));
+};
+//# sourceMappingURL=ActorProvider.js.map

package/dist/ActorProvider.js.map

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

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,57 +1,36 @@
 /**
- * PlayRenderer - Main React renderer component for XMachines Play architecture
+ * PlayRenderer — zero-prop leaf component for rendering the current actor view.
  *
- * @packageDocumentation
- */
-import React from "react";
-import type { PlayRendererProps } from "./types.js";
-/**
- * Main renderer component that subscribes to actor signals and renders UI
- *
- * Architecture (per RESEARCH.md Pattern 1):
- * - Subscribes to actor.currentView signal via useSignalEffect
- * - Dynamically renders catalog components based on view.component string
- * - Forwards user events to actor via actor.send()
- * - React state only for triggering renders, NOT business logic
- *
- * Invariant: Actor Authority - Actor decides all state transitions via guards.
- * Invariant: Passive Infrastructure - Component observes signals and sends events.
- * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
- *
- * @example
- * ```typescript
- * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
- *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * Must be rendered inside <ActorProvider> or <PlayUIProvider>.
+ * Reads view spec, handlers, and registry from usePlayView() context,
+ * then delegates to @json-render/react Renderer.
  *
- * 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} />
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
  * ```
  *
- * @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.
+ * For custom provider composition, use <ActorProvider> (escape hatch):
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
  *
- * **Event forwarding:** Injects `send` function as prop to components. Components
- * call `send(event)` to forward intents to actor. Actor guards decide validity.
+ * @packageDocumentation
+ */
+import React from "react";
+/**
+ * Zero-prop leaf component that renders the current actor view.
  *
- * **Error handling:** If component not found in catalog, logs error and shows
- * fallback. This indicates missing component registration, not runtime error.
+ * Reads the current PlaySpec, handlers, and registry from the ActorProvider
+ * context via usePlayView(), then renders via @json-render/react Renderer.
  *
- * **CRITICAL:** Never call actor.send() during render - only in event handlers.
- * Calling send during render causes infinite render loops.
+ * @public
  */
-export declare const PlayRenderer: React.FC<PlayRendererProps>;
+export declare const PlayRenderer: React.FC<Record<string, never>>;
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAGxD,CAAC"}

package/dist/PlayRenderer.js

@@ -1,87 +1,42 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
- * PlayRenderer - Main React renderer component for XMachines Play architecture
+ * PlayRenderer — zero-prop leaf component for rendering the current actor view.
  *
- * @packageDocumentation
- */
-import React, { useState } from "react";
-import { useSignalEffect } from "./useSignalEffect.js";
-/**
- * Main renderer component that subscribes to actor signals and renders UI
- *
- * Architecture (per RESEARCH.md Pattern 1):
- * - Subscribes to actor.currentView signal via useSignalEffect
- * - Dynamically renders catalog components based on view.component string
- * - Forwards user events to actor via actor.send()
- * - React state only for triggering renders, NOT business logic
- *
- * Invariant: Actor Authority - Actor decides all state transitions via guards.
- * Invariant: Passive Infrastructure - Component observes signals and sends events.
- * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
- *
- * @example
- * ```typescript
- * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
- *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * Must be rendered inside <ActorProvider> or <PlayUIProvider>.
+ * Reads view spec, handlers, and registry from usePlayView() context,
+ * then delegates to @json-render/react Renderer.
  *
- * 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} />
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
  * ```
  *
- * @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.
+ * For custom provider composition, use <ActorProvider> (escape hatch):
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
  *
- * **Event forwarding:** Injects `send` function as prop to components. Components
- * call `send(event)` to forward intents to actor. Actor guards decide validity.
+ * @packageDocumentation
+ */
+import React from "react";
+import { Renderer } from "@json-render/react";
+import { usePlayView } from "./ActorProvider.js";
+/**
+ * Zero-prop leaf component that renders the current actor view.
  *
- * **Error handling:** If component not found in catalog, logs error and shows
- * fallback. This indicates missing component registration, not runtime error.
+ * Reads the current PlaySpec, handlers, and registry from the ActorProvider
+ * context via usePlayView(), then renders via @json-render/react Renderer.
  *
- * **CRITICAL:** Never call actor.send() during render - only in event handlers.
- * Calling send during render causes infinite render loops.
+ * @public
  */
-export const PlayRenderer = ({ actor, components, fallback = null, }) => {
-    // 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());
-    // Subscribe to signal changes
-    useSignalEffect(() => {
-        const currentView = actor.currentView.get();
-        setView(currentView);
-    });
-    // No view in current state
-    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 });
-    }
-    // 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 });
-    }
-    // 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) });
+export const PlayRenderer = () => {
+    const view = usePlayView();
+    return _jsx(Renderer, { spec: view.spec, registry: view.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":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoC,GAAG,EAAE;IACjE,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,OAAO,KAAC,QAAQ,IAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,GAAI,CAAC;AAC/D,CAAC,CAAC"}

package/dist/PlayUIProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PlayUIProvider — batteries-included composite provider for actor-driven UI rendering.
+ *
+ * Wraps ActorProvider + JSONUIProvider (from @json-render/react) to provide a single
+ * entry point for all actor lifecycle and UI rendering concerns.
+ *
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * For custom provider composition (escape hatch), use <ActorProvider> directly.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import { type JSONUIProviderProps } from "@json-render/react";
+import { type ActorProviderProps } from "./ActorProvider.js";
+type JSONUIForwardedProps = Pick<JSONUIProviderProps, "validationFunctions" | "navigate" | "functions">;
+/**
+ * Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own props.
+ *
+ * @public
+ */
+export interface PlayUIProviderProps extends ActorProviderProps, Partial<JSONUIForwardedProps> {
+}
+/**
+ * PlayUIProvider — batteries-included entry point for actor-driven UI rendering.
+ *
+ * Combines actor lifecycle management (ActorProvider) with full UI provider setup
+ * (JSONUIProvider including ActionProvider, ValidationProvider, VisibilityProvider,
+ * StateProvider, and ConfirmDialogManager).
+ *
+ * @example
+ * ```tsx
+ * import { PlayUIProvider, PlayRenderer } from "@xmachines/play-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' }),
+ *   },
+ * });
+ *
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ *
+ * // With JSONUIProvider options:
+ * <PlayUIProvider
+ *   actor={actor}
+ *   registryResult={registryResult}
+ *   navigate={(path) => router.push(path)}
+ *   validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+ * >
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export declare const PlayUIProvider: React.FC<PlayUIProviderProps>;
+export {};
+//# sourceMappingURL=PlayUIProvider.d.ts.map