@xmachines/play-react 1.0.0-beta.8 → 1.0.0

package/dist/ActorProvider.js

@@ -0,0 +1,178 @@
+import { jsx as _jsx } 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, useMemo, createContext, useContext } from "react";
+import { StateProvider, useStateStore } from "@xmachines/json-render-react";
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
+import { useSignalEffect } from "./useSignalEffect.js";
+import { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+import { assertNonNullable } from "@xmachines/play";
+import { toAtomState, attachRenderErrorHandler, } from "@xmachines/play-actor";
+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();
+    // Stable refs for stateCtx methods so the useMemo below doesn't need to depend
+    // on stateCtx identity (useStateStore() may return a new object each render even
+    // when the underlying store hasn't changed). The handlers factory passes these as
+    // getter functions and calls them at action-execution time, not at creation time,
+    // so reading from a ref is always correct.
+    const stateCtxRef = useRef(stateCtx);
+    stateCtxRef.current = stateCtx;
+    // Build a SetState adapter: the handlers factory expects an updater-function pattern
+    // ((prev) => next), while stateCtx provides path-based set/update. This adapter
+    // bridges the two so action functions can use setState if needed.
+    // Stable function reference — reads stateCtxRef.current at invocation time.
+    const setStateAdapterRef = useRef((updater) => {
+        const prev = stateCtxRef.current.getSnapshot();
+        stateCtxRef.current.update(updater(prev));
+    });
+    // Memoize handlers keyed to registryResult identity. The getter functions are
+    // stable refs so they do not contribute to invalidation. Handlers are only
+    // recreated when the registry definition itself changes (e.g. a new defineRegistry
+    // call), not on every render cycle.
+    const handlers = useMemo(() => registryResult.handlers(() => setStateAdapterRef.current, () => stateCtxRef.current.getSnapshot()), [registryResult]);
+    // Memoize the context value on its actual inputs — a fresh object every
+    // render would re-render every usePlayView() consumer even when nothing
+    // changed (wasted renders).
+    const viewValue = useMemo(() => ({
+        spec,
+        handlers,
+        registry: registryResult.registry,
+        store,
+    }), [spec, handlers, 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. The [actor] dep re-creates the watcher when
+    // the actor prop swaps — without it the watcher keeps tracking the OLD
+    // actor's currentView signal and the rendered view freezes on the old actor
+    // while events flow to the new one.
+    useSignalEffect(() => {
+        const currentView = actor.currentView.get();
+        setView(currentView);
+    }, [actor]);
+    // Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)
+    // Centralised here per D-19 — one location for all framework renderers.
+    // Memoized on its actual inputs: rebuilding the injected registry every render
+    // would churn registry identity and invalidate ActorProviderInner's handlers
+    // useMemo on every render (wasted work + wasted consumer re-renders).
+    const activeRegistryResult = useMemo(() => {
+        if (!onRenderError)
+            return registryResult;
+        return {
+            ...registryResult,
+            registry: attachRenderErrorHandler(registryResult.registry, onRenderError),
+        };
+    }, [registryResult, onRenderError]);
+    // No view in current state — render fallback INSIDE ActorContext so a
+    // fallback component can call useActor() (e.g. to send a retry event).
+    // Parity with the error-boundary fallback below and with the Solid/Svelte/Vue
+    // renderers, which all provide context to their null-view fallbacks.
+    // ViewContext is intentionally NOT provided: there is no view spec to expose.
+    if (!view) {
+        return (_jsx(ActorContext.Provider, { value: actor, 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.
+            internalStoreRef.current = createViewStore(toAtomState(view.state));
+            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 @xmachines/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 @xmachines/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;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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 @xmachines/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 "@xmachines/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 @xmachines/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;AAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAAsB,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAErF,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,8BAA8B,CAAC;AACxD,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 @xmachines/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 "@xmachines/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

package/dist/PlayUIProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayUIProvider.d.ts","sourceRoot":"","sources":["../src/PlayUIProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGzF,KAAK,oBAAoB,GAAG,IAAI,CAC/B,mBAAmB,EACnB,qBAAqB,GAAG,UAAU,GAAG,WAAW,CAChD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB,EAAE,OAAO,CAAC,oBAAoB,CAAC;CAAG;AAgCjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAiBxD,CAAC"}