@xmachines/play-react 1.0.0-beta.18 → 1.0.0-beta.19

package/README.md

@@ -13,7 +13,7 @@ Bridges TC39 Signal-driven actors to React's render cycle. Business logic stays
 - Routes action names from spec elements to `actor.send()` via the `actions` prop
 - Manages per-view UI state in an `@xstate/store` atom (automatic or caller-supplied)
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md):
+Per [Play RFC](../docs/rfc/play.md):
 
 - **Actor Authority (INV-01):** Guards in the machine decide all state transitions
 - **Passive Infrastructure (INV-04):** React observes signals and dispatches events — never decides
@@ -260,10 +260,15 @@ function NavBar({ actor }: { actor: ReturnType<typeof createPlayer> }) {
 
 Class error boundary that wraps the rendered output. Catches errors thrown during component render and logs them without crashing the full page. `PlayRenderer` wraps its own output in this boundary automatically.
 
+`componentDidCatch` invokes the `onError` prop (for observability tools) but does **not** re-throw — re-throwing from `componentDidCatch` can unmount the entire React 19 root. `getDerivedStateFromError` handles fallback state transition instead.
+
 ```tsx
 import { PlayErrorBoundary } from "@xmachines/play-react";
 
-<PlayErrorBoundary fallback={<p>Something went wrong.</p>}>
+<PlayErrorBoundary
+	fallback={<p>Something went wrong.</p>}
+	onError={(err, info) => Sentry.captureException(err, { extra: info })}
+>
 	<PlayRenderer actor={actor} registry={registry} />
 </PlayErrorBoundary>;
 ```

package/dist/PlayErrorBoundary.d.ts

@@ -33,6 +33,10 @@ export interface PlayErrorBoundaryState {
  * 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

package/dist/PlayErrorBoundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayErrorBoundary.d.ts","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;;;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;;;;;;;;;;;;;;;GAeG;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;IAO5D,MAAM,IAAI,KAAK,CAAC,SAAS;CAMlC"}
+{"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

@@ -4,7 +4,6 @@
  * @packageDocumentation
  */
 import React from "react";
-import { RendererError } from "./errors.js";
 /**
  * React class component error boundary for catching catalog component render errors.
  *
@@ -12,6 +11,10 @@ import { RendererError } from "./errors.js";
  * 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
@@ -31,9 +34,6 @@ export class PlayErrorBoundary extends React.Component {
     }
     componentDidCatch(error, info) {
         this.props.onError?.(error, info);
-        throw new RendererError("Component render error caught by PlayErrorBoundary.", {
-            cause: error,
-        });
     }
     render() {
         if (this.state.hasError) {

package/dist/PlayErrorBoundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayErrorBoundary.js","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA0B5C;;;;;;;;;;;;;;;GAeG;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;QAClC,MAAM,IAAI,aAAa,CAAC,qDAAqD,EAAE;YAC9E,KAAK,EAAE,KAAK;SACZ,CAAC,CAAC;IACJ,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"}
+{"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/errors.d.ts

@@ -1,10 +1,11 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown by `PlayErrorBoundary.componentDidCatch()` when a React component inside
- * the boundary throws during rendering.
+ * Error class for renderer-level errors in the Play architecture.
  *
- * The original render error is set as `cause`. The `onError` prop callback fires
- * before this error is thrown, allowing observability tools to record the incident.
+ * **Note (Phase 29):** `PlayErrorBoundary.componentDidCatch()` no longer throws
+ * this error. Re-throwing from `componentDidCatch` can unmount the entire React 19
+ * root. `RendererError` is retained for programmatic use in custom error handlers
+ * and parent boundaries — it is no longer emitted by the built-in boundary itself.
  *
  * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
  *
@@ -12,11 +13,8 @@ import { PlayError } from "@xmachines/play";
  * ```typescript
  * import { RendererError } from "@xmachines/play-react/errors";
  *
- * // In a parent error boundary or global handler:
- * if (err instanceof RendererError) {
- *   // err.cause is the original component error
- *   reportRenderError(err.cause as Error);
- * }
+ * // Create a RendererError programmatically in a custom boundary:
+ * throw new RendererError("Custom render failure", { cause: originalError });
  * ```
  */
 export declare class RendererError extends PlayError {

package/dist/errors.d.ts.map

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

@@ -1,10 +1,11 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown by `PlayErrorBoundary.componentDidCatch()` when a React component inside
- * the boundary throws during rendering.
+ * Error class for renderer-level errors in the Play architecture.
  *
- * The original render error is set as `cause`. The `onError` prop callback fires
- * before this error is thrown, allowing observability tools to record the incident.
+ * **Note (Phase 29):** `PlayErrorBoundary.componentDidCatch()` no longer throws
+ * this error. Re-throwing from `componentDidCatch` can unmount the entire React 19
+ * root. `RendererError` is retained for programmatic use in custom error handlers
+ * and parent boundaries — it is no longer emitted by the built-in boundary itself.
  *
  * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
  *
@@ -12,11 +13,8 @@ import { PlayError } from "@xmachines/play";
  * ```typescript
  * import { RendererError } from "@xmachines/play-react/errors";
  *
- * // In a parent error boundary or global handler:
- * if (err instanceof RendererError) {
- *   // err.cause is the original component error
- *   reportRenderError(err.cause as Error);
- * }
+ * // Create a RendererError programmatically in a custom boundary:
+ * throw new RendererError("Custom render failure", { cause: originalError });
  * ```
  */
 export class RendererError extends PlayError {

package/dist/errors.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-react",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "description": "React renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -26,6 +26,7 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
@@ -35,9 +36,7 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__",
     "typecheck:browser": "tsc --noEmit -p tsconfig.browser.json",
     "test": "vitest",
     "test:vitest": "vitest run",
@@ -45,8 +44,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play-actor": "1.0.0-beta.18",
-    "@xmachines/play-signals": "1.0.0-beta.18"
+    "@xmachines/play-actor": "1.0.0-beta.19",
+    "@xmachines/play-signals": "1.0.0-beta.19"
   },
   "devDependencies": {
     "@json-render/core": "^0.16.0",
@@ -57,7 +56,7 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@xmachines/shared": "1.0.0-beta.18",
+    "@xmachines/shared": "1.0.0-beta.19",
     "@xstate/store": ">=3.17.0",
     "jsdom": "^29.0.1",
     "react": "^19.2.4",