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

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,273 @@
 # @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`
+- `useStateBinding` — 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 { registry } = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: { login: async () => {}, logout: async () => {} },
 });
 
+// 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}
+			registry={registry}
+			actions={{ login: "auth.login", logout: "auth.logout" }}
+		/>
+	);
+}
+```
+
+## API Reference
+
+### `PlayRenderer`
+
+Main component. Subscribes to `actor.currentView` and renders the spec.
+
+```tsx
+<PlayRenderer
+	actor={actor}
+	registry={registry}
+	actions={{ login: "auth.login" }}
+	store={myStore}
+	fallback={<p>Loading…</p>}
+/>
 ```
 
-## API
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-### PlayRenderer
+**`registry`** — Built with `defineRegistry(catalog, { components, actions })` from `@xmachines/play-solid`.
 
-Component that observes `actor.currentView` signal and renders the appropriate component from the catalog.
+`defineRegistry` also accepts `onRenderError(error, elementType)`, which receives errors
+caught by `@json-render/solid`'s inner element boundary before the default logger is used.
 
-**Props:**
+**`actions`** — Maps json-render action names (from spec `on` bindings) to XState event type strings. Type-checked against `EventFromLogic<TLogic>["type"]` when `TLogic` is specified:
 
-- `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
+```tsx
+<PlayRenderer<typeof machine>
+	actor={actor}
+	registry={registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
+/>
+```
+
+**`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
+
+- **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.
+
+```tsx
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
+
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
+
+<PlayRenderer actor={actor} registry={registry} store={store} actions={{ login: "auth.login" }} />;
+```
+
+**Inner render errors** — You can intercept catalog component render failures without
+overriding the outer Solid error boundary:
 
-**Features:**
+```tsx
+const { registry } = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: { login: async () => {}, logout: async () => {} },
+	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 `useStateBinding` from `@xmachines/play-solid`

package/dist/PlayRenderer.js

@@ -1,31 +1,61 @@
-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 } from "./node_modules/@json-render/solid/dist/index.js";
+import { createAtom as i } from "./node_modules/@xstate/store/dist/store-69e7e2d5.esm.js";
+import { xstateStoreStateStore as a } from "./node_modules/@json-render/xstate/dist/index.js";
+import { ActorProvider as o } from "./useActor.js";
+import { createComponent as s } from "solid-js/web";
+import { ErrorBoundary as c, createSignal as l, onCleanup as u } from "solid-js";
+import { watchSignal as d } 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 f = (f) => {
+	let [p, m] = l(f.actor.currentView.get()), h = null, g = null, _ = d(f.actor.currentView, (e) => {
+		m(e);
+	});
+	return u(() => {
+		_();
+	}), s(o, {
+		get value() {
+			return f.actor;
+		},
+		get children() {
+			return s(c, {
+				fallback: (e) => (f.onError?.(e), f.fallback ?? null),
+				get children() {
+					return (() => {
+						let o = p();
+						if (!o) return f.fallback ?? null;
+						let c;
+						f.store ? c = f.store : ((h === null || g !== o) && (h = a({ atom: i(o.spec.state ?? {}) }), g = o), c = h);
+						let l = Object.fromEntries(Object.entries(f.actions ?? {}).map(([e, t]) => [e, async (e = {}) => f.actor.send({
+							type: t,
+							...e
+						})]));
+						return s(n, {
+							store: c,
+							get children() {
+								return s(e, {
+									handlers: l,
+									get children() {
+										return s(r, { get children() {
+											return s(t, {
+												get spec() {
+													return o.spec;
+												},
+												get registry() {
+													return f.registry;
+												}
+											});
+										} });
+									}
+								});
+							}
+						});
+					})();
+				}
 			});
-		});
-		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 { f 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","ActionHandler","StateStore","createAtom","xstateStoreStateStore","watchSignal","PlayRendererProps","ViewMetadata","ActorProvider","PlayActor","PlayRenderer","props","view","setView","actor","currentView","get","internalStore","lastView","unwatch","nextView","_$createComponent","value","children","fallback","err","onError","store","initialState","spec","state","Record","atom","handlers","Object","fromEntries","entries","actions","map","actionName","eventType","params","send","type","registry"],"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 { Renderer, StateProvider, ActionProvider, VisibilityProvider } from \"@json-render/solid\";\nimport type { ActionHandler, StateStore } from \"@json-render/core\";\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 * 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 * - Renders view.spec via @json-render/solid Renderer backed by the registry\n * - Routes actions to actor.send() via ActionProvider handlers\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 *\n * @example\n * ```typescript\n * import { PlayRenderer } from \"@xmachines/play-solid\";\n * import { defineRegistry } from \"@json-render/solid\";\n *\n * const { registry } = defineRegistry(catalog, { components: { ... } });\n *\n * // Uncontrolled — fresh atom per view, seeded from spec.state:\n * <PlayRenderer actor={actor} registry={registry} actions={{ login: \"auth.login\" }} />\n *\n * // Controlled — caller provides and owns the store:\n * import { createAtom } from \"@xstate/store\";\n * import { xstateStoreStateStore } from \"@json-render/xstate\";\n * const store = xstateStoreStateStore({ atom: createAtom({ username: \"\" }) });\n * <PlayRenderer actor={actor} registry={registry} store={store} actions={{ login: \"auth.login\" }} />\n *\n * // With observability hook:\n * <PlayRenderer actor={actor} registry={registry} onError={(err) => Sentry.captureException(err)} />\n * ```\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<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\t// (matching React/Vue behavior; onMount would defer until after DOM insertion,\n\t// silently dropping signal changes between createSignal and mount)\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\tconst handlers: Record<string, ActionHandler> = Object.fromEntries(\n\t\t\t\t\t\tObject.entries(props.actions ?? {}).map(([actionName, eventType]) => [\n\t\t\t\t\t\t\tactionName,\n\t\t\t\t\t\t\tasync (params: Record<string, unknown> = {}) =>\n\t\t\t\t\t\t\t\tprops.actor.send({ type: eventType, ...params }),\n\t\t\t\t\t\t]),\n\t\t\t\t\t);\n\n\t\t\t\t\treturn (\n\t\t\t\t\t\t<StateProvider store={store}>\n\t\t\t\t\t\t\t<ActionProvider handlers={handlers}>\n\t\t\t\t\t\t\t\t<VisibilityProvider>\n\t\t\t\t\t\t\t\t\t<Renderer spec={currentView.spec} registry={props.registry} />\n\t\t\t\t\t\t\t\t</VisibilityProvider>\n\t\t\t\t\t\t\t</ActionProvider>\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":";;;;;;;;AAsDA,IAAaiB,KAA8CC,MAAU;CAGpE,IAAM,CAACC,GAAMC,KAAWpB,EACvBkB,EAAMG,MAAMC,YAAYC,KAAK,CAC7B,EAGGC,IAAmC,MACnCC,IAAgC,MAK9BC,IAAUd,EAAYM,EAAMG,MAAMC,cAAcK,MAAkC;AACvFP,IAAQO,EAAS;GAChB;AAKF,QAJA1B,QAAgB;AACfyB,KAAS;GACR,EAEFE,EACEb,GAAa;EAAA,IAACc,QAAK;AAAA,UAAEX,EAAMG;;EAAkB,IAAAS,WAAA;AAAA,UAAAF,EAC5C1B,GAAa;IACb6B,WAAWC,OACVd,EAAMe,UAAUD,EAAI,EACbd,EAAMa,YAAY;IACzB,IAAAD,WAAA;AAAA,mBAEO;MACP,IAAMR,IAAcH,GAAM;AAC1B,UAAI,CAACG,EAAa,QAAOJ,EAAMa,YAAY;MAG3C,IAAIG;AACJ,MAAIhB,EAAMgB,QACTA,IAAQhB,EAAMgB,UAEVV,MAAkB,QAAQC,MAAaH,OAG1CE,IAAgBb,EAAsB,EACrC4B,MAAM7B,EAFLY,EAAYc,KAAKC,SAAqC,EAAE,CAE5B,EAC7B,CAAC,EACFZ,IAAWH,IAEZY,IAAQV;MAGT,IAAMgB,IAA0CC,OAAOC,YACtDD,OAAOE,QAAQzB,EAAM0B,WAAW,EAAE,CAAC,CAACC,KAAK,CAACC,GAAYC,OAAe,CACpED,GACA,OAAOE,IAAkC,EAAE,KAC1C9B,EAAMG,MAAM4B,KAAK;OAAEC,MAAMH;OAAW,GAAGC;OAAQ,CAAC,CACjD,CACF,CAAC;AAED,aAAApB,EACEvB,GAAa;OAAQ6B;OAAK,IAAAJ,WAAA;AAAA,eAAAF,EACzBtB,GAAc;SAAWkC;SAAQ,IAAAV,WAAA;AAAA,iBAAAF,EAChCrB,GAAkB,EAAA,IAAAuB,WAAA;AAAA,kBAAAF,EACjBxB,GAAQ;YAAA,IAACgC,OAAI;AAAA,oBAAEd,EAAYc;;YAAI,IAAEe,WAAQ;AAAA,oBAAEjC,EAAMiC;;YAAQ,CAAA;aAAA,CAAA;;SAAA,CAAA;;OAAA,CAAA;SAK3D;;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, useStateBinding 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 useStateBinding };

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