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

package/dist/PlayUIProvider.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { JSONUIProvider } from "@xmachines/json-render-react";
+import { ActorProvider, usePlayView } from "./ActorProvider.js";
+/**
+ * Inner bridge component — reads ViewContext (usePlayView) to get the resolved handlers,
+ * registry, and store, then passes them to JSONUIProvider. The store is passed explicitly
+ * so JSONUIProvider's internal StateProvider uses the same store ActorProvider set up —
+ * without this, JSONUIProvider would create a fresh empty store, shadowing the seeded one.
+ *
+ * Must be inside ActorProvider's tree so usePlayView() has access to ViewContextValue.
+ */
+function JSONUIBridge({ validationFunctions, navigate, functions, children, }) {
+    const view = usePlayView();
+    return (_jsx(JSONUIProvider, { registry: view.registry, handlers: view.handlers, store: view.store, ...(validationFunctions && { validationFunctions }), ...(navigate && { navigate }), ...(functions && { functions }), children: children }));
+}
+/**
+ * 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 const PlayUIProvider = ({ validationFunctions, navigate, functions, ...actorProps }) => {
+    return (_jsx(ActorProvider, { ...actorProps, children: _jsx(JSONUIBridge, { ...(validationFunctions && { validationFunctions }), ...(navigate && { navigate }), ...(functions && { functions }), children: actorProps.children }) }));
+};
+//# sourceMappingURL=PlayUIProvider.js.map

package/dist/PlayUIProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayUIProvider.js","sourceRoot":"","sources":["../src/PlayUIProvider.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,cAAc,EAA4B,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,WAAW,EAA2B,MAAM,oBAAoB,CAAC;AAezF;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,EACrB,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,QAAQ,GACuD;IAC/D,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAE3B,OAAO,CACN,KAAC,cAAc,IACd,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,KAAK,EAAE,IAAI,CAAC,KAAK,KACb,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC,KAChD,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,CAAC,KAC1B,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,YAE/B,QAAQ,GACO,CACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkC,CAAC,EAC7D,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,GAAG,UAAU,EACb,EAAE,EAAE;IACJ,OAAO,CACN,KAAC,aAAa,OAAK,UAAU,YAC5B,KAAC,YAAY,OACR,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC,KAChD,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,CAAC,KAC1B,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,YAE/B,UAAU,CAAC,QAAQ,GACN,GACA,CAChB,CAAC;AACH,CAAC,CAAC"}

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_REACT_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_REACT_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_REACT_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,yBAAyB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC7B,CAAC;CACD"}

package/dist/index.d.ts

@@ -1,18 +1,46 @@
 /**
  * @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
+ * Provides a provider-based React rendering layer that passively observes actor signals
+ * and renders UI components via @xmachines/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.
  *
+ * **Standard usage:**
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * **Escape hatch (custom composition):**
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 export { PlayRenderer } from "./PlayRenderer.js";
+export { ActorProvider } from "./ActorProvider.js";
+export type { ActorProviderProps, ViewContextValue } from "./ActorProvider.js";
+export { usePlayView } from "./ActorProvider.js";
+export { PlayUIProvider } from "./PlayUIProvider.js";
+export type { PlayUIProviderProps } from "./PlayUIProvider.js";
 export { useSignalEffect } from "./useSignalEffect.js";
-export type { PlayRendererProps } from "./types.js";
+export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+export { useActor } from "./useActor.js";
+export type { AnyPlayActor } from "./useActor.js";
+export { defineRegistry, useBoundProp, JSONUIProvider, StateProvider, ActionProvider, VisibilityProvider, ValidationProvider, Renderer, } from "@xmachines/json-render-react";
+export type { ComponentFn, ComponentContext, JSONUIProviderProps, StateProviderProps, ActionProviderProps, VisibilityProviderProps, ValidationProviderProps, RendererProps, } from "@xmachines/json-render-react";
+export type { ActorProviderProps as PlayRendererProps } from "./ActorProvider.js";
+export type { RenderErrorHandler } from "./types.js";
+export type { PlayErrorBoundaryProps, PlayErrorBoundaryState } from "./PlayErrorBoundary.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EACN,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,GACR,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACX,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,GACb,MAAM,8BAA8B,CAAC;AAGtC,YAAY,EAAE,kBAAkB,IAAI,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClF,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,18 +1,41 @@
 /**
  * @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
+ * Provides a provider-based React rendering layer that passively observes actor signals
+ * and renders UI components via @xmachines/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.
  *
+ * **Standard usage:**
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * **Escape hatch (custom composition):**
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 // Main exports
 export { PlayRenderer } from "./PlayRenderer.js";
+export { ActorProvider } from "./ActorProvider.js";
+export { usePlayView } from "./ActorProvider.js";
+export { PlayUIProvider } from "./PlayUIProvider.js";
 export { useSignalEffect } from "./useSignalEffect.js";
+export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+export { useActor } from "./useActor.js";
+// Re-exports from @xmachines/json-render-react (per D-14)
+export { defineRegistry, useBoundProp, JSONUIProvider, StateProvider, ActionProvider, VisibilityProvider, ValidationProvider, Renderer, } from "@xmachines/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,0DAA0D;AAC1D,OAAO,EACN,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,GACR,MAAM,8BAA8B,CAAC"}

package/dist/types.d.ts

@@ -1,24 +1,12 @@
 /**
  * TypeScript type definitions for play-react
  *
- * @packageDocumentation
- */
-import type { AbstractActor, Viewable } from "@xmachines/play-actor";
-import type React from "react";
-import type { AnyActorLogic } from "xstate";
-/**
- * Props for PlayRenderer component
+ * PlayRendererProps has been removed — use ActorProviderProps or PlayUIProviderProps instead.
+ * See ActorProvider.tsx and PlayUIProvider.tsx.
  *
- * @property actor - Actor instance with currentView signal (requires Viewable capability)
- * @property components - Map of component names to React components
- * @property fallback - Optional component shown when currentView is null
+ * @packageDocumentation
  */
-export interface PlayRendererProps {
-    /** 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 */
-    fallback?: React.ReactNode;
-}
+export type { ActorProviderProps } from "./ActorProvider.js";
+export type { PlayUIProviderProps } from "./PlayUIProvider.js";
+export type { RenderErrorHandler } from "@xmachines/json-render-react";
 //# 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;;;;;;;GAOG;AAGH,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/types.js

@@ -1,6 +1,9 @@
 /**
  * TypeScript type definitions for play-react
  *
+ * PlayRendererProps has been removed — use ActorProviderProps or PlayUIProviderProps instead.
+ * See ActorProvider.tsx and PlayUIProvider.tsx.
+ *
  * @packageDocumentation
  */
 export {};

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/useActor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 {NonNullableError} If called outside an ActorProvider/PlayUIProvider 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";
+/** Bare actor type accepted by React context providers. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`. */
+export type AnyPlayActor = AbstractActor<AnyActorLogic>;
+export declare const ActorContext: import("react").Context<AnyPlayActor | null>;
+export declare function useActor(): AnyPlayActor;
+//# 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;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,6IAA6I;AAC7I,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAExD,eAAO,MAAM,YAAY,8CAA2C,CAAC;AAErE,wBAAgB,QAAQ,IAAI,YAAY,CAEvC"}

package/dist/useActor.js

@@ -0,0 +1,27 @@
+/**
+ * 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 {NonNullableError} If called outside an ActorProvider/PlayUIProvider 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";
+import { assertNonNullable } from "@xmachines/play";
+export const ActorContext = createContext(null);
+export function useActor() {
+    return assertNonNullable(useContext(ActorContext), "ActorContext");
+}
+//# 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;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAOpD,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAC;AAErE,MAAM,UAAU,QAAQ;IACvB,OAAO,iBAAiB,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC,CAAC;AACpE,CAAC"}

package/dist/useSignalEffect.d.ts

@@ -3,35 +3,44 @@
  *
  * @packageDocumentation
  */
+import type { DependencyList } from "react";
 /**
  * React hook that subscribes to signal changes and runs effect callback
  *
- * Wraps Signal.subtle.Watcher to automatically track signal dependencies
- * accessed in the callback. When any tracked signal changes, the callback
- * re-runs and React component re-renders.
+ * Wraps the callback in a Signal.Computed to automatically track signal
+ * dependencies accessed inside it, then delegates the watcher lifecycle
+ * (microtask batching, re-arming, disposal) to `watchSignal` from
+ * `@xmachines/play-signals` — the single canonical implementation shared
+ * across framework renderers.
  *
- * Architecture (per RESEARCH.md Pattern 3):
+ * Architecture:
  * - Uses Signal.Computed to wrap callback for automatic dependency tracking
- * - Signal.subtle.Watcher monitors the Computed for changes
+ * - watchSignal owns the Signal.subtle.Watcher lifecycle (Phase 29 memory safety)
  * - Microtask batching coalesces rapid signal updates
- * - Forces React re-render via useReducer when signals change
+ * - Re-rendering is driven by the callback's own setState (see remarks)
  * - Handles cleanup on unmount to prevent memory leaks
  *
  * Invariant: Signal-Only Reactivity - Signals accessed in callback are watched.
  * Invariant: Passive Infrastructure - React observes signals and does not control them.
  *
  * @param callback - Effect function that accesses signals. Can return cleanup function.
+ * @param deps - Optional dependency list (like useEffect). When any dependency
+ * changes, the watcher and Computed are torn down and recreated, re-tracking
+ * signals from scratch. Defaults to `[]` (subscribe once per mount). Pass this
+ * when the identity of the object whose signals you read can change over the
+ * component's lifetime (e.g. an `actor` prop) — otherwise the watcher keeps
+ * tracking the OLD object's signals forever.
  *
  * @example
  * ```typescript
  * const MyComponent = ({ actor }) => {
  *   const [view, setView] = useState(null);
  *
- *   // Subscribe to actor.currentView signal
+ *   // Subscribe to actor.currentView signal; re-subscribe if the actor swaps
  *   useSignalEffect(() => {
  *     const currentView = actor.currentView.get();
  *     setView(currentView);
- *   });
+ *   }, [actor]);
  *
  *   return <div>{view?.component}</div>;
  * };
@@ -41,16 +50,22 @@
  * **CRITICAL:** Signals must be accessed unconditionally (no if statements).
  * Conditional signal access breaks automatic dependency tracking.
  *
- * **Performance:** Microtask batching (queueMicrotask) prevents React thrashing
- * when multiple signals update rapidly. Per signal-polyfill README pattern.
+ * **Performance:** Microtask batching (queueMicrotask, inside watchSignal)
+ * prevents React thrashing when multiple signals update rapidly.
  *
- * **Why forceUpdate:** React needs useState/useReducer to trigger re-render cycle.
- * Signal changes won't automatically re-render React components without forcing
- * update via state change.
+ * **Re-rendering:** the hook itself does NOT force a React render on signal
+ * change — the callback drives re-rendering by calling setState with the new
+ * signal value (as in the example above). This lets React's setState bailout
+ * skip renders when the derived value is unchanged; an unconditional
+ * force-update here previously caused a wasted render per notification even
+ * when the callback's setState bailed. If you need to re-render on every
+ * notification while reading signals during render, mirror the signal value
+ * into React state inside the callback.
  *
  * **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.
+ * The Computed handles dependency tracking; watchSignal evaluates it (which
+ * runs the callback) whenever any tracked signal changes.
  */
-export declare const useSignalEffect: (callback: () => void | (() => void)) => void;
+export declare const useSignalEffect: (callback: () => void | (() => void), deps?: DependencyList) => 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;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAS5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,eAAe,GAC3B,UAAU,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EACnC,OAAM,cAAmB,KACvB,IA0CF,CAAC"}

package/dist/useSignalEffect.js

@@ -3,8 +3,8 @@
  *
  * @packageDocumentation
  */
-import { useEffect, useReducer } from "react";
-import { Signal } from "@xmachines/play-signals";
+import { useEffect, useRef } from "react";
+import { Signal, watchSignal } from "@xmachines/play-signals";
 /**
  * Marker symbol returned by effect Computed to satisfy type requirements
  * The actual value doesn't matter - we only care about side effects
@@ -13,32 +13,40 @@ const EFFECT_RUN_MARKER = Symbol("effect-run");
 /**
  * React hook that subscribes to signal changes and runs effect callback
  *
- * Wraps Signal.subtle.Watcher to automatically track signal dependencies
- * accessed in the callback. When any tracked signal changes, the callback
- * re-runs and React component re-renders.
+ * Wraps the callback in a Signal.Computed to automatically track signal
+ * dependencies accessed inside it, then delegates the watcher lifecycle
+ * (microtask batching, re-arming, disposal) to `watchSignal` from
+ * `@xmachines/play-signals` — the single canonical implementation shared
+ * across framework renderers.
  *
- * Architecture (per RESEARCH.md Pattern 3):
+ * Architecture:
  * - Uses Signal.Computed to wrap callback for automatic dependency tracking
- * - Signal.subtle.Watcher monitors the Computed for changes
+ * - watchSignal owns the Signal.subtle.Watcher lifecycle (Phase 29 memory safety)
  * - Microtask batching coalesces rapid signal updates
- * - Forces React re-render via useReducer when signals change
+ * - Re-rendering is driven by the callback's own setState (see remarks)
  * - Handles cleanup on unmount to prevent memory leaks
  *
  * Invariant: Signal-Only Reactivity - Signals accessed in callback are watched.
  * Invariant: Passive Infrastructure - React observes signals and does not control them.
  *
  * @param callback - Effect function that accesses signals. Can return cleanup function.
+ * @param deps - Optional dependency list (like useEffect). When any dependency
+ * changes, the watcher and Computed are torn down and recreated, re-tracking
+ * signals from scratch. Defaults to `[]` (subscribe once per mount). Pass this
+ * when the identity of the object whose signals you read can change over the
+ * component's lifetime (e.g. an `actor` prop) — otherwise the watcher keeps
+ * tracking the OLD object's signals forever.
  *
  * @example
  * ```typescript
  * const MyComponent = ({ actor }) => {
  *   const [view, setView] = useState(null);
  *
- *   // Subscribe to actor.currentView signal
+ *   // Subscribe to actor.currentView signal; re-subscribe if the actor swaps
  *   useSignalEffect(() => {
  *     const currentView = actor.currentView.get();
  *     setView(currentView);
- *   });
+ *   }, [actor]);
  *
  *   return <div>{view?.component}</div>;
  * };
@@ -48,60 +56,59 @@ const EFFECT_RUN_MARKER = Symbol("effect-run");
  * **CRITICAL:** Signals must be accessed unconditionally (no if statements).
  * Conditional signal access breaks automatic dependency tracking.
  *
- * **Performance:** Microtask batching (queueMicrotask) prevents React thrashing
- * when multiple signals update rapidly. Per signal-polyfill README pattern.
+ * **Performance:** Microtask batching (queueMicrotask, inside watchSignal)
+ * prevents React thrashing when multiple signals update rapidly.
  *
- * **Why forceUpdate:** React needs useState/useReducer to trigger re-render cycle.
- * Signal changes won't automatically re-render React components without forcing
- * update via state change.
+ * **Re-rendering:** the hook itself does NOT force a React render on signal
+ * change — the callback drives re-rendering by calling setState with the new
+ * signal value (as in the example above). This lets React's setState bailout
+ * skip renders when the derived value is unchanged; an unconditional
+ * force-update here previously caused a wasted render per notification even
+ * when the callback's setState bailed. If you need to re-render on every
+ * notification while reading signals during render, mirror the signal value
+ * into React state inside the callback.
  *
  * **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.
+ * The Computed handles dependency tracking; watchSignal evaluates it (which
+ * runs the callback) whenever any tracked signal changes.
  */
-export const useSignalEffect = (callback) => {
-    // Force re-render when signal changes (React needs state change to re-render)
-    const [, forceUpdate] = useReducer((x) => x + 1, 0);
+export const useSignalEffect = (callback, deps = []) => {
+    // Store callback in a ref so the effect closure always calls the latest version
+    // WITHOUT triggering watcher teardown/re-setup on each render (standard React ref pattern)
+    const callbackRef = useRef(callback);
+    // Assignment outside useEffect keeps ref current without triggering re-effect
+    callbackRef.current = callback;
     useEffect(() => {
         let cleanup;
-        let needsEnqueue = true;
         // Wrap callback in a Computed to automatically track dependencies
         // The Computed will re-evaluate when any accessed signal changes
         const effect = new Signal.Computed(() => {
             // Run cleanup from previous effect
-            cleanup?.();
-            // Run user callback (may access signals, return cleanup)
-            cleanup = callback();
+            if (typeof cleanup === "function")
+                cleanup();
+            // Run user callback via ref (always latest version, no dep churn)
+            cleanup = callbackRef.current();
             // Return marker value (Computed requires a return value)
             return EFFECT_RUN_MARKER;
         });
-        // Create watcher to detect when Computed needs re-evaluation
-        const watcher = new Signal.subtle.Watcher(() => {
-            // Batching flag prevents multiple microtasks for rapid changes
-            if (needsEnqueue) {
-                needsEnqueue = false;
-                // Schedule microtask to batch updates (prevent React thrashing)
-                queueMicrotask(() => {
-                    needsEnqueue = true;
-                    // Re-evaluate the Computed (runs callback with new signal values)
-                    effect.get();
-                    // Force React re-render
-                    forceUpdate();
-                    // Re-watch for next change
-                    watcher.watch();
-                });
-            }
-        });
-        // Watch the Computed signal
-        watcher.watch(effect);
+        // watchSignal owns the watcher lifecycle: microtask batching, disposed
+        // guard, and re-arming after each notification (Phase 29 memory safety
+        // lives there — single source of truth, no copy-pasted watcher code).
+        // Reading the Computed inside watchSignal re-evaluates it, which runs the
+        // user callback; re-rendering is the callback's job (setState), so no
+        // extra work is needed in onValue.
+        const unwatch = watchSignal(effect, () => { });
         // Initial run of callback (via Computed)
         effect.get();
-        // Cleanup on unmount
+        // Cleanup on unmount or deps change
         return () => {
-            cleanup?.();
-            // Unwatch to stop receiving signal updates
-            watcher.unwatch(effect);
+            // Stop receiving signal updates (idempotent, disposes pending microtasks)
+            unwatch();
+            if (typeof cleanup === "function")
+                cleanup();
         };
-    }, [callback]);
+        // oxlint-disable-next-line exhaustive-deps -- deps forwarded from caller; callback intentionally excluded (ref pattern)
+    }, deps);
 };
 //# sourceMappingURL=useSignalEffect.js.map

package/dist/useSignalEffect.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSignalEffect.js","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD;;;GAGG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAmC,EAAQ,EAAE;IAC5E,8EAA8E;IAC9E,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpD,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAA4B,CAAC;QACjC,IAAI,YAAY,GAAG,IAAI,CAAC;QAExB,kEAAkE;QAClE,iEAAiE;QACjE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE;YACvC,mCAAmC;YACnC,OAAO,EAAE,EAAE,CAAC;YAEZ,yDAAyD;YACzD,OAAO,GAAG,QAAQ,EAAE,CAAC;YAErB,yDAAyD;YACzD,OAAO,iBAAiB,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,6DAA6D;QAC7D,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YAC9C,+DAA+D;YAC/D,IAAI,YAAY,EAAE,CAAC;gBAClB,YAAY,GAAG,KAAK,CAAC;gBACrB,gEAAgE;gBAChE,cAAc,CAAC,GAAG,EAAE;oBACnB,YAAY,GAAG,IAAI,CAAC;oBAEpB,kEAAkE;oBAClE,MAAM,CAAC,GAAG,EAAE,CAAC;oBAEb,wBAAwB;oBACxB,WAAW,EAAE,CAAC;oBAEd,2BAA2B;oBAC3B,OAAO,CAAC,KAAK,EAAE,CAAC;gBACjB,CAAC,CAAC,CAAC;YACJ,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,4BAA4B;QAC5B,OAAO,CAAC,KAAK,CAAC,MAAkC,CAAC,CAAC;QAElD,yCAAyC;QACzC,MAAM,CAAC,GAAG,EAAE,CAAC;QAEb,qBAAqB;QACrB,OAAO,GAAG,EAAE;YACX,OAAO,EAAE,EAAE,CAAC;YACZ,2CAA2C;YAC3C,OAAO,CAAC,OAAO,CAAC,MAAkC,CAAC,CAAC;QACrD,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChB,CAAC,CAAC"}
+{"version":3,"file":"useSignalEffect.js","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;GAGG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,QAAmC,EACnC,OAAuB,EAAE,EAClB,EAAE;IACT,gFAAgF;IAChF,2FAA2F;IAC3F,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,8EAA8E;IAC9E,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IAE/B,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAA4B,CAAC;QAEjC,kEAAkE;QAClE,iEAAiE;QACjE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE;YACvC,mCAAmC;YACnC,IAAI,OAAO,OAAO,KAAK,UAAU;gBAAE,OAAO,EAAE,CAAC;YAE7C,kEAAkE;YAClE,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;YAEhC,yDAAyD;YACzD,OAAO,iBAAiB,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,0EAA0E;QAC1E,sEAAsE;QACtE,mCAAmC;QACnC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAkC,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAE1E,yCAAyC;QACzC,MAAM,CAAC,GAAG,EAAE,CAAC;QAEb,oCAAoC;QACpC,OAAO,GAAG,EAAE;YACX,0EAA0E;YAC1E,OAAO,EAAE,CAAC;YACV,IAAI,OAAO,OAAO,KAAK,UAAU;gBAAE,OAAO,EAAE,CAAC;QAC9C,CAAC,CAAC;QACF,wHAAwH;IACzH,CAAC,EAAE,IAAI,CAAC,CAAC;AACV,CAAC,CAAC"}