@xmachines/play-solid 1.0.0-beta.3 → 1.0.0-beta.31

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,272 @@
 # @xmachines/play-solid
 
-SolidJS renderer for XMachines Play architecture. Enables catalog-driven view rendering with actor-owned business state.
+**Solid renderer for XMachines Play Architecture**
+
+Bridges TC39 Signal-driven actors to Solid's fine-grained reactivity. Business logic stays in the actor; Solid is purely a rendering target.
+
+## Overview
+
+`@xmachines/play-solid` provides `PlayRenderer`, a Solid component that:
+
+- Subscribes to `actor.currentView` (TC39 Signal) and re-renders on every state transition
+- Renders the current view's JSON spec via `@json-render/solid`
+- 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 [Play RFC](../docs/rfc/play.md):
+
+- **Actor Authority (INV-01):** Guards in the machine decide all state transitions
+- **Passive Infrastructure (INV-04):** Solid observes signals and dispatches events — never decides
+- **Signal-Only Reactivity (INV-05):** `actor.currentView` signal is the sole render trigger
 
 ## Installation
 
 ```bash
-npm install @xmachines/play-solid solid-js
+npm install @xmachines/play-solid
+npm install @json-render/solid @json-render/core   # peer deps
+npm install @json-render/xstate @xstate/store      # store integration
 ```
 
+In this monorepo, the root install applies a `patch-package` patch to `@json-render/solid`
+so `defineRegistry(..., { onRenderError })` can intercept inner element-boundary errors
+without muting console output.
+
 ## Current Exports
 
-- `PlayRenderer`
+- `PlayRenderer` — main renderer component
+- `useActor` — hook for accessing the actor inside a `PlayRenderer` tree
+- `defineRegistry` — re-exported from `@json-render/solid`
+- `useBoundProp` — re-exported from `@json-render/solid`
+- `ComponentFn` (type) — re-exported from `@json-render/solid`
+- `ComponentContext` (type) — re-exported from `@json-render/solid`
 - `PlayRendererProps` (type)
+- `PlayActor` (type)
 
-## Usage
+## Quick Start
 
-```typescript
-import { PlayRenderer } from '@xmachines/play-solid';
-import { definePlayer } from '@xmachines/play-xstate';
-import { defineCatalog } from '@xmachines/play-catalog';
+```tsx
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { PlayRenderer } from "@xmachines/play-solid";
+import { defineCatalog } from "@json-render/core";
+import { defineRegistry } from "@xmachines/play-solid";
+import type { ComponentFn } from "@xmachines/play-solid";
+import { setup, assign } from "xstate";
+import { z } from "zod";
 
-// Define catalog
+// 1. Define catalog — the contract between machine spec and UI components
 const catalog = defineCatalog({
-  Home: { component: 'Home', props: {} },
-  Login: { component: 'Login', props: { error: { type: 'string' } } }
+	elements: {
+		Login: { props: z.object({ title: z.string() }), description: "Login form" },
+		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+	},
 });
 
-// Create player
-const createPlayer = definePlayer({
-  machine: authMachine,
-  catalog
+// 2. Implement components using ComponentFn — typed against catalog entries
+const Login: ComponentFn<typeof catalog, "Login"> = ({ props, emit }) => (
+	<div class="view">
+		<h2>{props.title}</h2>
+		<form
+			onSubmit={(e) => {
+				e.preventDefault();
+				emit("submit");
+			}}
+		>
+			<button type="submit">Log In</button>
+		</form>
+	</div>
+);
+
+const Dashboard: ComponentFn<typeof catalog, "Dashboard"> = ({ props }) => (
+	<div class="view">Welcome, {props.username}!</div>
+);
+
+// 3. Build registry
+const registryResult = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: {
+		login: async (params) => {
+			if (!params) return;
+			actor.send({ type: "auth.login", username: params.username });
+		},
+		logout: async (params) => {
+			actor.send({ type: "auth.logout" });
+		},
+	},
 });
 
+// 4. Define machine with view metadata
+const machine = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			username: string | null;
+			params: Record<string, string>;
+			query: Record<string, string>;
+		},
+		events: {} as
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" }
+			| { type: "play.route"; to: string; params?: Record<string, string> },
+	},
+}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "login",
+		context: { isAuthenticated: false, username: null, params: {}, query: {} },
+		states: {
+			login: {
+				id: "login",
+				meta: {
+					route: "/login",
+					view: {
+						component: "Login",
+						spec: {
+							root: "root",
+							elements: {
+								root: { type: "Login", props: { title: "Sign In" }, children: [] },
+							},
+						},
+					},
+				},
+			},
+			dashboard: {
+				id: "dashboard",
+				meta: {
+					route: "/dashboard",
+					view: {
+						component: "Dashboard",
+						spec: {
+							root: "root",
+							elements: {
+								root: { type: "Dashboard", props: { username: "" }, children: [] },
+							},
+						},
+					},
+				},
+			},
+		},
+		on: {
+			"auth.login": {
+				target: ".dashboard",
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: assign({ isAuthenticated: true, username: ({ event }) => event.username }),
+			},
+			"auth.logout": {
+				target: ".login",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: assign({ isAuthenticated: false, username: null }),
+			},
+		},
+	}),
+);
+
+// 5. Create actor and render
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
-// Define components
-const components = {
-  Home: (props) => <div>Home</div>,
-  Login: (props) => (
-    <form onSubmit={(e) => {
-      e.preventDefault();
-      props.send({ type: 'auth.login', payload: {...} });
-    }}>
-      {props.error && <p>{props.error}</p>}
-      <input type="text" name="username" />
-      <button type="submit">Login</button>
-    </form>
-  )
-};
-
-// Render
-<PlayRenderer actor={actor} components={components} />
+function App() {
+	return <PlayRenderer actor={actor} registryResult={registryResult} />;
+}
+```
+
+## API Reference
+
+### `PlayRenderer`
+
+Main component. Subscribes to `actor.currentView` and renders the spec.
+
+```tsx
+<PlayRenderer
+	actor={actor}
+	registryResult={registryResult}
+	store={myStore}
+	fallback={<p>Loading…</p>}
+/>
 ```
 
-## API
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
+
+**`registryResult`** — The full `DefineRegistryResult` returned by `defineRegistry(catalog, { components, actions })` from `@xmachines/play-solid`.
+
+`defineRegistry` also accepts `onRenderError(error, elementType)`, which receives errors
+caught by `@json-render/solid`'s inner element boundary before the default logger is used.
+
+**`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
 
-### PlayRenderer
+- **Omitted (uncontrolled, default):** A fresh `@xstate/store` atom is created per view transition, seeded from `view.spec.state`.
+- **Provided (controlled):** The caller owns the store; `spec.state` is ignored.
 
-Component that observes `actor.currentView` signal and renders the appropriate component from the catalog.
+```tsx
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
 
-**Props:**
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
 
-- `actor: AbstractActor & Viewable` - Actor instance with currentView signal
-- `components: Record<string, Component<any>>` - Map of component names to SolidJS components
-- `fallback?: JSX.Element` - Optional fallback to show when currentView is null
+<PlayRenderer actor={actor} registryResult={registryResult} store={store} />;
+```
 
-**Features:**
+**Inner render errors** — You can intercept catalog component render failures without
+overriding the outer Solid error boundary:
+
+```tsx
+const registryResult = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: {
+		login: async (params) => {
+			if (!params) return;
+			actor.send({ type: "auth.login", username: params.username });
+		},
+		logout: async (params) => {
+			actor.send({ type: "auth.logout" });
+		},
+	},
+	onRenderError(error, elementType) {
+		reportExpectedRenderError(error, elementType);
+	},
+});
+```
 
-- Automatically bridges TC39 Signals to SolidJS reactivity
-- Passes `send` function to components for event forwarding
-- Handles missing components gracefully with error logging
-- Uses one-shot watcher re-watch pattern for proper signal observation
+**`fallback`** — Shown when `actor.currentView.get()` is `null`.
 
-## Canonical Watcher Lifecycle
+---
 
-Use the same watcher flow as React/Vue/router packages:
+### `useActor`
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. read actor signals and update framework-local render trigger
-5. re-arm with `watch(...)` or `watch()`
+Solid hook for accessing the actor from inside any component rendered by `PlayRenderer`. No prop drilling needed.
 
-Watcher notifications are one-shot, so re-arm is mandatory.
+```tsx
+import { useActor } from "@xmachines/play-solid";
 
-## Cleanup Contract
+// Inside any component rendered inside PlayRenderer:
+function LogoutButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "auth.logout" })}>Log Out</button>;
+}
+```
 
-Solid integrations must perform explicit teardown:
+Throws `"useActor() must be called inside <PlayRenderer>"` if called outside the tree.
 
-- Use `onCleanup` for lifecycle teardown.
-- Call `unwatch(...)` on teardown, not only reference nulling.
-- Keep adapters/renderers passive; state validity remains actor-owned.
+---
 
-## Architecture
+## Route Parameters in Props
 
-PlayRenderer follows the XMachines Play architecture:
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-- **Actor Authority**: Actor controls all state transitions via guards
-- **Passive Infrastructure**: Renderer observes signals, sends events
-- **Signal-Only Reactivity**: Business logic state lives in actor signals
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.params = { section: "profile" }
+// Component receives: { section: "profile", user: "alice" }
+```
 
-The renderer bridges TC39 Signals (used by XMachines actors) to SolidJS's reactivity system using `Signal.subtle.Watcher` with a one-shot re-watch pattern.
+Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
 
-Signals remain observation plumbing, not an alternate mutation channel.
+---
 
-## License
+## Architecture Notes
 
-MIT
+- SolidJS signals are only used to trigger re-renders — not for business logic
+- `actor.currentView` (TC39 Signal) is bridged into a SolidJS `createSignal` inside `PlayRenderer`
+- Per-view UI state lives in an `@xstate/store` atom, not in SolidJS reactive state
+- `@json-render/solid` drives rendering; `PlayRenderer` is the signal bridge — import `defineRegistry`, `ComponentFn`, `ComponentContext`, and `useBoundProp` from `@xmachines/play-solid`

package/dist/PlayRenderer.js

@@ -1,31 +1,71 @@
-import { Dynamic as e, createComponent as t, insert as n, memo as r, mergeProps as i, template as a } from "solid-js/web";
-import { createSignal as o, onMount as s } from "solid-js";
-import { Signal as c } from "@xmachines/play-signals";
+import { ActionProvider as e, Renderer as t, StateProvider as n, VisibilityProvider as r, useStateStore as i } from "./node_modules/@json-render/solid/dist/index.js";
+import { createAtom as a } from "./node_modules/@xstate/store/dist/store-69e7e2d5.esm.js";
+import { xstateStoreStateStore as o } from "./node_modules/@json-render/xstate/dist/index.js";
+import { ActorProvider as s } from "./useActor.js";
+import { createComponent as c } from "solid-js/web";
+import { ErrorBoundary as l, createSignal as u, onCleanup as d } from "solid-js";
+import { watchSignal as f } from "@xmachines/play-signals";
 //#region src/PlayRenderer.tsx
-var l = /* @__PURE__ */ a("<div class=play-renderer-error>Component \"<!>\" not found in catalog. Available: "), u = (a) => {
-	let [u, d] = o(a.actor.currentView.get());
-	s(() => {
-		let e = new c.subtle.Watcher(() => {
-			queueMicrotask(() => {
-				e.getPending(), d(a.actor.currentView.get()), e.watch(a.actor.currentView);
+var p = (n) => {
+	let a = i(), o = (e) => {
+		let t = a.getSnapshot();
+		a.update(e(t));
+	}, s = () => n.registryResult.handlers(() => o, () => a.getSnapshot());
+	return c(e, {
+		get handlers() {
+			return s();
+		},
+		get children() {
+			return c(r, { get children() {
+				return c(t, {
+					get spec() {
+						return n.spec;
+					},
+					get registry() {
+						return n.registryResult.registry;
+					}
+				});
+			} });
+		}
+	});
+}, m = (e) => {
+	let [t, r] = u(e.actor.currentView.get()), i = null, m = null, h = f(e.actor.currentView, (e) => {
+		r(e);
+	});
+	return d(() => {
+		h();
+	}), c(s, {
+		get value() {
+			return e.actor;
+		},
+		get children() {
+			return c(l, {
+				fallback: (t) => (e.onError?.(t), e.fallback ?? null),
+				get children() {
+					return (() => {
+						let r = t();
+						if (!r) return e.fallback ?? null;
+						let s;
+						return e.store ? s = e.store : ((i === null || m !== r) && (i = o({ atom: a(r.spec.state ?? {}) }), m = r), s = i), c(n, {
+							store: s,
+							get children() {
+								return c(p, {
+									get registryResult() {
+										return e.registryResult;
+									},
+									get spec() {
+										return r.spec;
+									}
+								});
+							}
+						});
+					})();
+				}
 			});
-		});
-		e.watch(a.actor.currentView);
+		}
 	});
-	let f = a.actor.send.bind(a.actor);
-	return [
-		r(() => r(() => !u())() && (a.fallback || null)),
-		r(() => r(() => !!(u() && !a.components))() && (console.error(`Components catalog is ${a.components === null ? "null" : "undefined"}. Cannot render component "${u().component}".`), a.fallback || null)),
-		r(() => r(() => !!(u() && a.components && !a.components[u().component]))() && (console.error(`Component "${u().component}" not found in catalog. Available components: ${Object.keys(a.components).join(", ")}`), (() => {
-			var e = l(), t = e.firstChild.nextSibling;
-			return t.nextSibling, n(e, () => u().component, t), n(e, () => Object.keys(a.components).join(", "), null), e;
-		})())),
-		r(() => r(() => !!(u() && a.components && a.components[u().component]))() && t(e, i({ get component() {
-			return a.components[u().component];
-		} }, () => u().props, { send: f })))
-	];
 };
 //#endregion
-export { u as PlayRenderer };
+export { m as PlayRenderer };
 
 //# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","names":["createSignal","onMount","Component","Dynamic","Signal","PlayRendererProps","SolidView","PlayRenderer","props","view","setView","actor","currentView","get","watcher","subtle","Watcher","queueMicrotask","getPending","watch","sendBound","send","bind","_$memo","fallback","components","console","error","component","Object","keys","join","_el$","_tmpl$","_el$2","firstChild","_el$5","nextSibling","_el$3","_$insert","_$createComponent","_$mergeProps"],"sources":["../src/PlayRenderer.tsx"],"sourcesContent":["/**\n * PlayRenderer - Main SolidJS renderer component for XMachines Play architecture\n *\n * @packageDocumentation\n */\n\nimport { createSignal, onMount, type Component } from \"solid-js\";\nimport { Dynamic } from \"solid-js/web\";\nimport { Signal } from \"@xmachines/play-signals\";\nimport type { PlayRendererProps, SolidView } from \"./types.js\";\n\n/**\n * Main renderer component that subscribes to actor signals and renders UI\n *\n * Architecture (per XMachines Play patterns):\n * - Subscribes to actor.currentView signal via TC39 Signal.subtle.Watcher\n * - Dynamically renders catalog components based on view.component string\n * - Forwards user events to actor via actor.send()\n * - SolidJS signal only for triggering renders, NOT business logic\n *\n * Invariant: Actor Authority - Actor decides all state transitions via guards.\n * Invariant: Passive Infrastructure - Component observes signals and sends events.\n * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.\n *\n * @example\n * ```typescript\n * import { PlayRenderer } from \"@xmachines/play-solidjs\";\n * import { definePlayer } from \"@xmachines/play-xstate\";\n *\n * const actor = definePlayer({ machine, catalog })();\n * actor.start();\n *\n * const components = {\n *   Dashboard: (props) => <div>User: {props.userId}</div>,\n *   LoginForm: (props) => (\n *     <form onSubmit={(e) => {\n *       e.preventDefault();\n *       props.send({ type: \"auth.login\", payload: {...} });\n *     }}>...</form>\n *   )\n * };\n *\n * <PlayRenderer actor={actor} components={components} />\n * ```\n *\n * @param props - Component props\n * @returns SolidJS element rendering current view from actor\n *\n * @remarks\n * **Component lookup:** Dynamically looks up component from `components` map\n * using `view.component` string from actor.currentView signal.\n *\n * **Event forwarding:** Injects `send` function as prop to components. Components\n * call `send(event)` to forward intents to actor. Actor guards decide validity.\n *\n * **Error handling:** If component not found in catalog, logs error and shows\n * fallback. This indicates missing component registration, not runtime error.\n *\n * **Signal bridge:** Uses one-shot re-watch pattern. TC39 Signal watchers stop\n * watching after notification, so watcher.watch() must be called in microtask\n * after getPending() to re-arm for next notification.\n *\n * **CRITICAL:** Never call actor.send() during render - only in event handlers.\n * Calling send during render causes infinite render loops.\n */\nexport const PlayRenderer: Component<PlayRendererProps> = (props) => {\n\t// Create SolidJS signal for view\n\t// Signal is NOT business logic state - it's just SolidJS's render trigger\n\tconst [view, setView] = createSignal<SolidView>(props.actor.currentView.get() as SolidView);\n\n\t// Bridge TC39 Signal to SolidJS signal\n\t// Uses one-shot re-watch pattern (must re-watch after each notification)\n\tonMount(() => {\n\t\tconst watcher = new Signal.subtle.Watcher(() => {\n\t\t\tqueueMicrotask(() => {\n\t\t\t\t// Acknowledge the notification\n\t\t\t\twatcher.getPending();\n\n\t\t\t\t// Update SolidJS signal (triggers SolidJS reactivity)\n\t\t\t\tsetView(props.actor.currentView.get() as SolidView);\n\n\t\t\t\t// Re-watch for next notification (one-shot pattern)\n\t\t\t\t// TC39 Signal watchers stop watching after notification\n\t\t\t\twatcher.watch(props.actor.currentView);\n\t\t\t});\n\t\t});\n\n\t\t// Watch actor.currentView for changes\n\t\twatcher.watch(props.actor.currentView);\n\n\t\t// Note: TC39 Signal watchers don't have explicit disposal\n\t\t// The watcher will be garbage collected when the component unmounts\n\t});\n\n\t// Bind send function (ensures correct 'this' context)\n\tconst sendBound = props.actor.send.bind(props.actor);\n\n\treturn (\n\t\t<>\n\t\t\t{/* No view - show fallback */}\n\t\t\t{!view() && (props.fallback || null)}\n\n\t\t\t{/* Handle null/undefined components catalog gracefully */}\n\t\t\t{view() &&\n\t\t\t\t!props.components &&\n\t\t\t\t(() => {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\t`Components catalog is ${props.components === null ? \"null\" : \"undefined\"}. ` +\n\t\t\t\t\t\t\t`Cannot render component \"${view()!.component}\".`,\n\t\t\t\t\t);\n\t\t\t\t\treturn props.fallback || null;\n\t\t\t\t})()}\n\n\t\t\t{/* View exists but component not found */}\n\t\t\t{view() &&\n\t\t\t\tprops.components &&\n\t\t\t\t!props.components[view()!.component] &&\n\t\t\t\t(() => {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\t`Component \"${view()!.component}\" not found in catalog. ` +\n\t\t\t\t\t\t\t`Available components: ${Object.keys(props.components).join(\", \")}`,\n\t\t\t\t\t);\n\t\t\t\t\treturn (\n\t\t\t\t\t\t<div class=\"play-renderer-error\">\n\t\t\t\t\t\t\tComponent \"{view()!.component}\" not found in catalog. Available:{\" \"}\n\t\t\t\t\t\t\t{Object.keys(props.components).join(\", \")}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t);\n\t\t\t\t})()}\n\n\t\t\t{/* Render matched component dynamically */}\n\t\t\t{view() && props.components && props.components[view()!.component] && (\n\t\t\t\t<Dynamic\n\t\t\t\t\tcomponent={props.components[view()!.component]}\n\t\t\t\t\t{...view()!.props}\n\t\t\t\t\tsend={sendBound}\n\t\t\t\t/>\n\t\t\t)}\n\t\t</>\n\t);\n};\n"],"mappings":";;;;iHAiEaO,KAA8CC,MAAU;CAGpE,IAAM,CAACC,GAAMC,KAAWV,EAAwBQ,EAAMG,MAAMC,YAAYC,KAAK,CAAc;AAI3FZ,SAAc;EACb,IAAMa,IAAU,IAAIV,EAAOW,OAAOC,cAAc;AAC/CC,wBAAqB;AASpBH,IAPAA,EAAQI,YAAY,EAGpBR,EAAQF,EAAMG,MAAMC,YAAYC,KAAK,CAAc,EAInDC,EAAQK,MAAMX,EAAMG,MAAMC,YAAY;KACrC;IACD;AAGFE,IAAQK,MAAMX,EAAMG,MAAMC,YAAY;GAIrC;CAGF,IAAMQ,IAAYZ,EAAMG,MAAMU,KAAKC,KAAKd,EAAMG,MAAM;AAEpD,QAAA;EAAAY,QAGGA,QAAA,CAACd,GAAM,CAAA,EAAA,KAAKD,EAAMgB,YAAY,MAAK;EAAAD,QAGnCA,QAAA,CAAA,EAAAd,GAAM,IACN,CAACD,EAAMiB,YAAU,EAAA,KAEhBC,QAAQC,MACP,yBAAyBnB,EAAMiB,eAAe,OAAO,SAAS,YAAW,6BAC5ChB,GAAM,CAAEmB,UAAS,IAC9C,EACMpB,EAAMgB,YAAY,MACtB;EAAAD,QAGJA,QAAA,CAAA,EAAAd,GAAM,IACND,EAAMiB,cACN,CAACjB,EAAMiB,WAAWhB,GAAM,CAAEmB,YAAU,EAAA,KAEnCF,QAAQC,MACP,cAAclB,GAAM,CAAEmB,UAAS,gDACLC,OAAOC,KAAKtB,EAAMiB,WAAW,CAACM,KAAK,KAAK,GAClE,SACD;GAAA,IAAAC,IAAAC,GAAA,EAAAG,IAAAJ,EAAAG,WAAAE;AAG2C,UAH3CD,EAAAC,aAAAE,EAAAP,SAEcvB,GAAM,CAAEmB,WAASQ,EAAA,EAAAG,EAAAP,SAC5BH,OAAOC,KAAKtB,EAAMiB,WAAW,CAACM,KAAK,KAAK,EAAA,KAAA,EAAAC;MAAA,EAGxC;EAAAT,QAGJA,QAAA,CAAA,EAAAd,GAAM,IAAID,EAAMiB,cAAcjB,EAAMiB,WAAWhB,GAAM,CAAEmB,YAAU,EAAA,IAAAY,EAChErC,GAAOsC,EAAA,EAAA,IACPb,YAAS;AAAA,UAAEpB,EAAMiB,WAAWhB,GAAM,CAAEmB;KAAU,QAC1CnB,GAAM,CAAED,OAAK,EACjBa,MAAMD,GAAS,CAAA,CAEhB,CAAA;EAAA"}
+{"version":3,"file":"PlayRenderer.js","names":["createSignal","onCleanup","ErrorBoundary","Component","Renderer","StateProvider","ActionProvider","VisibilityProvider","useStateStore","ActionHandler","StateStore","DefineRegistryResult","SetState","createAtom","xstateStoreStateStore","watchSignal","PlayRendererProps","ViewMetadata","ActorProvider","PlayActor","PlayRendererInner","registryResult","spec","Spec","innerProps","stateCtx","setStateAdapter","updater","prev","getSnapshot","update","handlers","Record","_$createComponent","children","registry","PlayRenderer","props","view","setView","actor","currentView","get","internalStore","lastView","unwatch","nextView","value","fallback","err","onError","store","initialState","state","atom"],"sources":["../src/PlayRenderer.tsx"],"sourcesContent":["/**\n * PlayRenderer - Main SolidJS renderer component for XMachines Play architecture\n *\n * @packageDocumentation\n */\n\nimport { createSignal, onCleanup, ErrorBoundary, type Component } from \"solid-js\";\nimport {\n\tRenderer,\n\tStateProvider,\n\tActionProvider,\n\tVisibilityProvider,\n\tuseStateStore,\n} from \"@json-render/solid\";\nimport type { ActionHandler, StateStore } from \"@json-render/core\";\nimport type { DefineRegistryResult, SetState } from \"@json-render/solid\";\nimport { createAtom } from \"@xstate/store\";\nimport { xstateStoreStateStore } from \"@json-render/xstate\";\nimport { watchSignal } from \"@xmachines/play-signals\";\nimport type { PlayRendererProps } from \"./types.js\";\nimport type { ViewMetadata } from \"@xmachines/play-actor\";\nimport { ActorProvider, type PlayActor } from \"./useActor.js\";\n\n/**\n * Inner component that renders inside StateProvider so it can call useStateStore()\n * to get the live set/getSnapshot functions needed by registryResult.handlers().\n */\nconst PlayRendererInner: Component<{\n\tregistryResult: DefineRegistryResult;\n\tspec: import(\"@json-render/core\").Spec | null;\n}> = (innerProps) => {\n\tconst stateCtx = useStateStore();\n\n\t// Build a SetState adapter: the handlers factory expects an updater-function pattern\n\t// ((prev) => next), while stateCtx provides path-based set/update. This adapter\n\t// bridges the two so action functions can use setState if needed.\n\tconst setStateAdapter: SetState = (updater) => {\n\t\tconst prev = stateCtx.getSnapshot();\n\t\tstateCtx.update(updater(prev));\n\t};\n\n\tconst handlers = (): Record<string, ActionHandler> =>\n\t\tinnerProps.registryResult.handlers(\n\t\t\t() => setStateAdapter,\n\t\t\t() => stateCtx.getSnapshot(),\n\t\t);\n\n\treturn (\n\t\t<ActionProvider handlers={handlers()}>\n\t\t\t<VisibilityProvider>\n\t\t\t\t<Renderer spec={innerProps.spec} registry={innerProps.registryResult.registry} />\n\t\t\t</VisibilityProvider>\n\t\t</ActionProvider>\n\t);\n};\n\n/**\n * Main renderer component that subscribes to actor signals and renders UI\n *\n * Architecture:\n * - Subscribes to actor.currentView signal via TC39 Signal.subtle.Watcher\n * - Renders view.spec via StateProvider → PlayRendererInner (with ActionProvider + handlers)\n * - Routes actions to actor.send() via registryResult.handlers() — real async functions\n * - SolidJS signal only for triggering renders, NOT business logic\n * - State store: uses external `store` prop if provided (controlled mode); otherwise\n *   creates a fresh @xstate/store atom per view transition seeded from spec.state.\n * - Wraps the render path in a SolidJS `ErrorBoundary` to contain catalog component\n *   render failures. The `fallback` prop is shown on error; `onError` is called for\n *   observability forwarding (Sentry, Datadog, etc.).\n *\n * Invariant: Actor Authority - Actor decides all state transitions via guards.\n * Invariant: Passive Infrastructure - Component observes signals and sends events.\n * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.\n */\nexport const PlayRenderer: Component<PlayRendererProps> = (props) => {\n\t// Create SolidJS signal for view\n\tconst [view, setView] = createSignal<ViewMetadata | null>(\n\t\tprops.actor.currentView.get() as ViewMetadata | null,\n\t);\n\n\t// Internal per-view store — recreated on each view transition when no external store.\n\tlet internalStore: StateStore | null = null;\n\tlet lastView: ViewMetadata | null = null;\n\n\t// Bridge TC39 Signal to SolidJS signal — subscribe synchronously during setup\n\tconst unwatch = watchSignal(props.actor.currentView, (nextView: ViewMetadata | null) => {\n\t\tsetView(nextView);\n\t});\n\tonCleanup(() => {\n\t\tunwatch();\n\t});\n\n\treturn (\n\t\t<ActorProvider value={props.actor as PlayActor}>\n\t\t\t<ErrorBoundary\n\t\t\t\tfallback={(err: unknown) => {\n\t\t\t\t\tprops.onError?.(err);\n\t\t\t\t\treturn props.fallback ?? null;\n\t\t\t\t}}\n\t\t\t>\n\t\t\t\t{(() => {\n\t\t\t\t\tconst currentView = view();\n\t\t\t\t\tif (!currentView) return props.fallback ?? null;\n\n\t\t\t\t\t// Resolve the store: external (controlled) or internal per-view atom\n\t\t\t\t\tlet store: StateStore;\n\t\t\t\t\tif (props.store) {\n\t\t\t\t\t\tstore = props.store;\n\t\t\t\t\t} else {\n\t\t\t\t\t\tif (internalStore === null || lastView !== currentView) {\n\t\t\t\t\t\t\tconst initialState =\n\t\t\t\t\t\t\t\t(currentView.spec.state as Record<string, unknown>) ?? {};\n\t\t\t\t\t\t\tinternalStore = xstateStoreStateStore({\n\t\t\t\t\t\t\t\tatom: createAtom(initialState),\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tlastView = currentView;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tstore = internalStore;\n\t\t\t\t\t}\n\n\t\t\t\t\t// PlayRendererInner renders inside StateProvider so useStateStore() works\n\t\t\t\t\treturn (\n\t\t\t\t\t\t<StateProvider store={store}>\n\t\t\t\t\t\t\t<PlayRendererInner\n\t\t\t\t\t\t\t\tregistryResult={props.registryResult}\n\t\t\t\t\t\t\t\tspec={currentView.spec}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t</StateProvider>\n\t\t\t\t\t);\n\t\t\t\t})()}\n\t\t\t</ErrorBoundary>\n\t\t</ActorProvider>\n\t);\n};\n"],"mappings":";;;;;;;;AA2BA,IAAMoB,KAGAI,MAAe;CACpB,IAAMC,IAAWjB,GAAe,EAK1BkB,KAA6BC,MAAY;EAC9C,IAAMC,IAAOH,EAASI,aAAa;AACnCJ,IAASK,OAAOH,EAAQC,EAAK,CAAC;IAGzBG,UACLP,EAAWH,eAAeU,eACnBL,SACAD,EAASI,aAChB,CAAC;AAEF,QAAAI,EACE3B,GAAc;EAAA,IAACyB,WAAQ;AAAA,UAAEA,GAAU;;EAAA,IAAAG,WAAA;AAAA,UAAAD,EAClC1B,GAAkB,EAAA,IAAA2B,WAAA;AAAA,WAAAD,EACjB7B,GAAQ;KAAA,IAACkB,OAAI;AAAA,aAAEE,EAAWF;;KAAI,IAAEa,WAAQ;AAAA,aAAEX,EAAWH,eAAec;;KAAQ,CAAA;MAAA,CAAA;;EAAA,CAAA;GAwBpEC,KAA8CC,MAAU;CAEpE,IAAM,CAACC,GAAMC,KAAWvC,EACvBqC,EAAMG,MAAMC,YAAYC,KAAK,CAC7B,EAGGC,IAAmC,MACnCC,IAAgC,MAG9BC,IAAU9B,EAAYsB,EAAMG,MAAMC,cAAcK,MAAkC;AACvFP,IAAQO,EAAS;GAChB;AAKF,QAJA7C,QAAgB;AACf4C,KAAS;GACR,EAEFZ,EACEf,GAAa;EAAA,IAAC6B,QAAK;AAAA,UAAEV,EAAMG;;EAAkB,IAAAN,WAAA;AAAA,UAAAD,EAC5C/B,GAAa;IACb8C,WAAWC,OACVZ,EAAMa,UAAUD,EAAI,EACbZ,EAAMW,YAAY;IACzB,IAAAd,WAAA;AAAA,mBAEO;MACP,IAAMO,IAAcH,GAAM;AAC1B,UAAI,CAACG,EAAa,QAAOJ,EAAMW,YAAY;MAG3C,IAAIG;AAgBJ,aAfId,EAAMc,QACTA,IAAQd,EAAMc,UAEVR,MAAkB,QAAQC,MAAaH,OAG1CE,IAAgB7B,EAAsB,EACrCwC,MAAMzC,EAFL4B,EAAYnB,KAAK+B,SAAqC,EAAE,CAE5B,EAC7B,CAAC,EACFT,IAAWH,IAEZU,IAAQR,IAITV,EACE5B,GAAa;OAAQ8C;OAAK,IAAAjB,WAAA;AAAA,eAAAD,EACzBb,GAAiB;SAAA,IACjBC,iBAAc;AAAA,iBAAEgB,EAAMhB;;SAAc,IACpCC,OAAI;AAAA,iBAAEmB,EAAYnB;;SAAI,CAAA;;OAAA,CAAA;SAItB;;IAAA,CAAA;;EAAA,CAAA"}

package/dist/index.js

@@ -1,2 +1,4 @@
-import { PlayRenderer as e } from "./PlayRenderer.js";
-export { e as PlayRenderer };
+import { defineRegistry as e, useBoundProp as t } from "./node_modules/@json-render/solid/dist/index.js";
+import { useActor as n } from "./useActor.js";
+import { PlayRenderer as r } from "./PlayRenderer.js";
+export { r as PlayRenderer, e as defineRegistry, n as useActor, t as useBoundProp };

package/dist/node_modules/@json-render/core/dist/chunk-AFLK3Q4T.js

@@ -0,0 +1,111 @@
+import { _null as e, boolean as t, number as n, object as r, string as i, union as a } from "../../../zod/v4/classic/schemas.js";
+//#region ../../node_modules/@json-render/core/dist/chunk-AFLK3Q4T.mjs
+var o = a([
+	i(),
+	n(),
+	t(),
+	e(),
+	r({ $state: i() })
+]);
+a([i(), r({ $state: i() })]), a([n(), r({ $state: i() })]), a([t(), r({ $state: i() })]);
+function s(e, t) {
+	if (e != null) return typeof e == "object" && "$state" in e ? u(t, e.$state) : e;
+}
+function c(e) {
+	return e.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function l(e) {
+	return (e.startsWith("/") ? e.slice(1).split("/") : e.split("/")).map(c);
+}
+function u(e, t) {
+	if (!t || t === "/") return e;
+	let n = l(t), r = e;
+	for (let e of n) {
+		if (r == null) return;
+		if (Array.isArray(r)) r = r[parseInt(e, 10)];
+		else if (typeof r == "object") r = r[e];
+		else return;
+	}
+	return r;
+}
+var d = "spec";
+`${d}`;
+function f(e, t, n) {
+	let r = l(t);
+	if (r.length === 0) return e;
+	let i = { ...e }, a = i;
+	for (let e = 0; e < r.length - 1; e++) {
+		let t = r[e], n = a[t];
+		if (Array.isArray(n)) a[t] = [...n];
+		else if (typeof n == "object" && n) a[t] = { ...n };
+		else {
+			let n = r[e + 1];
+			a[t] = n !== void 0 && /^\d+$/.test(n) ? [] : {};
+		}
+		a = a[t];
+	}
+	let o = r[r.length - 1];
+	return Array.isArray(a) ? o === "-" ? a.push(n) : a[parseInt(o, 10)] = n : a[o] = n, i;
+}
+function p(e = {}) {
+	let t = { ...e }, n = /* @__PURE__ */ new Set();
+	function r() {
+		for (let e of n) e();
+	}
+	return {
+		get(e) {
+			return u(t, e);
+		},
+		set(e, n) {
+			u(t, e) !== n && (t = f(t, e, n), r());
+		},
+		update(e) {
+			let n = !1, i = t;
+			for (let [t, r] of Object.entries(e)) u(i, t) !== r && (i = f(i, t, r), n = !0);
+			n && (t = i, r());
+		},
+		getSnapshot() {
+			return t;
+		},
+		getServerSnapshot() {
+			return t;
+		},
+		subscribe(e) {
+			return n.add(e), () => {
+				n.delete(e);
+			};
+		}
+	};
+}
+function m(e) {
+	return {
+		get(t) {
+			return u(e.getSnapshot(), t);
+		},
+		set(t, n) {
+			let r = e.getSnapshot();
+			u(r, t) !== n && e.setSnapshot(f(r, t, n));
+		},
+		update(t) {
+			let n = e.getSnapshot(), r = !1;
+			for (let [e, i] of Object.entries(t)) u(n, e) !== i && (n = f(n, e, i), r = !0);
+			r && e.setSnapshot(n);
+		},
+		getSnapshot: e.getSnapshot,
+		getServerSnapshot: e.getSnapshot,
+		subscribe: e.subscribe
+	};
+}
+var h = 20;
+function g(e, t = "", n = 0, r, i) {
+	let a = r ?? /* @__PURE__ */ new Set(), o = i ?? { current: !1 }, s = {};
+	for (let [r, i] of Object.entries(e)) {
+		let e = `${t}/${r}`;
+		n < h && typeof i == "object" && i && !Array.isArray(i) && Object.getPrototypeOf(i) === Object.prototype && !a.has(i) ? (a.add(i), Object.assign(s, g(i, e, n + 1, a, o))) : (process.env.NODE_ENV !== "production" && !o.current && n >= h && typeof i == "object" && i && !Array.isArray(i) && Object.getPrototypeOf(i) === Object.prototype && !a.has(i) && (o.current = !0, console.warn(`flattenToPointers: depth limit (${h}) reached. Nested state beyond this depth will be treated as a leaf value.`)), s[e] = i);
+	}
+	return s;
+}
+//#endregion
+export { o as DynamicValueSchema, d as SPEC_DATA_PART, p as createStateStore, m as createStoreAdapter, g as flattenToPointers, u as getByPath, f as immutableSetByPath, s as resolveDynamicValue };
+
+//# sourceMappingURL=chunk-AFLK3Q4T.js.map