@xmachines/play-actor 1.0.0-beta.52 → 1.0.0-beta.54

package/dist/index.d.ts

@@ -16,4 +16,5 @@
  * @see [Play RFC](../../docs/rfc/play.md)
  */
 export { AbstractActor, typedSpec, type Routable, type Viewable, type PlaySpec, type BaseActorProviderProps, type BaseViewContextValue, } from "./abstract-actor.js";
+export { toAtomState, attachRenderErrorHandler } from "./provider-guards.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;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -16,4 +16,5 @@
  * @see [Play RFC](../../docs/rfc/play.md)
  */
 export { AbstractActor, typedSpec, } from "./abstract-actor.js";
+export { toAtomState, attachRenderErrorHandler } from "./provider-guards.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/provider-guards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared provider guards for framework ActorProvider implementations.
+ *
+ * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
+ * two rituals when bridging an actor's view to a json-render tree:
+ *
+ * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ *    ({@link toAtomState}).
+ * 2. Inject a component-level `onRenderError` handler into the component
+ *    registry without mutating the caller's registry
+ *    ({@link attachRenderErrorHandler}).
+ *
+ * Centralising them here keeps the guard semantics identical across frameworks.
+ *
+ * @packageDocumentation
+ */
+import type { RenderErrorHandler } from "@json-render/core";
+/**
+ * Safely coerce a spec's `state` field to a plain object for `createAtom`.
+ *
+ * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
+ * `null`, `undefined`, a primitive, or a plain object depending on what the
+ * machine author put in the view spec. `createAtom` requires a plain object as
+ * its initial value — anything else produces a broken store at runtime.
+ *
+ * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
+ * and returned as-is. Everything else — `null`, `undefined`, primitives,
+ * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
+ * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+ *
+ * @param state - The raw `spec.state` value from a `PlaySpec`.
+ * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ */
+export declare function toAtomState(state: unknown): Record<string, unknown>;
+/**
+ * Clone a component registry and inject an `onRenderError` handler.
+ *
+ * The handler is defined as a non-enumerable, configurable own property on the
+ * clone (per D-19 — one injection convention for all framework renderers), so
+ * it overrides any handler set at `defineRegistry` level without showing up
+ * when the registry's component entries are enumerated.
+ *
+ * The caller's registry is never mutated — a shallow clone is returned. Callers
+ * that need per-instance handlers (e.g. an `onRenderError` prop on
+ * `ActorProvider`) can therefore share one `defineRegistry` result across
+ * providers safely.
+ *
+ * @typeParam TRegistry - The framework-specific component registry type.
+ * @param registry - The component registry from `defineRegistry().registry`.
+ * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
+ * @returns A shallow clone of `registry` with `onRenderError` attached.
+ */
+export declare function attachRenderErrorHandler<TRegistry extends object>(registry: TRegistry, handler: RenderErrorHandler): TRegistry;
+//# sourceMappingURL=provider-guards.d.ts.map

package/dist/provider-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-guards.d.ts","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,MAAM,EAChE,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,kBAAkB,GACzB,SAAS,CAQX"}

package/dist/provider-guards.js

@@ -0,0 +1,69 @@
+/**
+ * Shared provider guards for framework ActorProvider implementations.
+ *
+ * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
+ * two rituals when bridging an actor's view to a json-render tree:
+ *
+ * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ *    ({@link toAtomState}).
+ * 2. Inject a component-level `onRenderError` handler into the component
+ *    registry without mutating the caller's registry
+ *    ({@link attachRenderErrorHandler}).
+ *
+ * Centralising them here keeps the guard semantics identical across frameworks.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Safely coerce a spec's `state` field to a plain object for `createAtom`.
+ *
+ * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
+ * `null`, `undefined`, a primitive, or a plain object depending on what the
+ * machine author put in the view spec. `createAtom` requires a plain object as
+ * its initial value — anything else produces a broken store at runtime.
+ *
+ * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
+ * and returned as-is. Everything else — `null`, `undefined`, primitives,
+ * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
+ * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+ *
+ * @param state - The raw `spec.state` value from a `PlaySpec`.
+ * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ */
+export function toAtomState(state) {
+    if (state !== null && typeof state === "object" && !Array.isArray(state)) {
+        const proto = Object.getPrototypeOf(state);
+        if (proto === Object.prototype || proto === null) {
+            return state;
+        }
+    }
+    return {};
+}
+/**
+ * Clone a component registry and inject an `onRenderError` handler.
+ *
+ * The handler is defined as a non-enumerable, configurable own property on the
+ * clone (per D-19 — one injection convention for all framework renderers), so
+ * it overrides any handler set at `defineRegistry` level without showing up
+ * when the registry's component entries are enumerated.
+ *
+ * The caller's registry is never mutated — a shallow clone is returned. Callers
+ * that need per-instance handlers (e.g. an `onRenderError` prop on
+ * `ActorProvider`) can therefore share one `defineRegistry` result across
+ * providers safely.
+ *
+ * @typeParam TRegistry - The framework-specific component registry type.
+ * @param registry - The component registry from `defineRegistry().registry`.
+ * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
+ * @returns A shallow clone of `registry` with `onRenderError` attached.
+ */
+export function attachRenderErrorHandler(registry, handler) {
+    const clone = { ...registry };
+    Object.defineProperty(clone, "onRenderError", {
+        value: handler,
+        enumerable: false,
+        configurable: true,
+    });
+    return clone;
+}
+//# sourceMappingURL=provider-guards.js.map

package/dist/provider-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-guards.js","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;QACtD,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAClD,OAAO,KAAgC,CAAC;QACzC,CAAC;IACF,CAAC;IACD,OAAO,EAAE,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmB,EACnB,OAA2B;IAE3B,MAAM,KAAK,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC9B,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE;QAC7C,KAAK,EAAE,OAAO;QACd,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KAClB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "1.0.0-beta.52",
+  "version": "1.0.0-beta.54",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-*",
+    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
     "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
@@ -42,16 +42,17 @@
     "@json-render/core": "^0.18.0"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.52",
+    "@xmachines/shared": "1.0.0-beta.54",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.62.0",
     "vitest": "^4.1.5",
     "xstate": "^5.31.0"
   },
   "peerDependencies": {
-    "@xmachines/play": "1.0.0-beta.52",
-    "@xmachines/play-signals": "1.0.0-beta.52",
+    "@xmachines/play": "1.0.0-beta.54",
+    "@xmachines/play-signals": "1.0.0-beta.54",
     "xstate": "^5.31.0"
   },
   "engines": {