@xmachines/play-solid 1.0.0-beta.1

package/README.md

@@ -0,0 +1,110 @@
+# @xmachines/play-solid
+
+SolidJS renderer for XMachines Play architecture. Enables catalog-driven view rendering with actor-owned business state.
+
+## Installation
+
+```bash
+npm install @xmachines/play-solid solid-js
+```
+
+## Current Exports
+
+- `PlayRenderer`
+- `PlayRendererProps` (type)
+
+## Usage
+
+```typescript
+import { PlayRenderer } from '@xmachines/play-solid';
+import { definePlayer } from '@xmachines/play-xstate';
+import { defineCatalog } from '@xmachines/play-catalog';
+
+// Define catalog
+const catalog = defineCatalog({
+  Home: { component: 'Home', props: {} },
+  Login: { component: 'Login', props: { error: { type: 'string' } } }
+});
+
+// Create player
+const createPlayer = definePlayer({
+  machine: authMachine,
+  catalog
+});
+
+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} />
+```
+
+## API
+
+### PlayRenderer
+
+Component that observes `actor.currentView` signal and renders the appropriate component from the catalog.
+
+**Props:**
+
+- `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
+
+**Features:**
+
+- 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
+
+## Canonical Watcher Lifecycle
+
+Use the same watcher flow as React/Vue/router packages:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. read actor signals and update framework-local render trigger
+5. re-arm with `watch(...)` or `watch()`
+
+Watcher notifications are one-shot, so re-arm is mandatory.
+
+## Cleanup Contract
+
+Solid integrations must perform explicit teardown:
+
+- Use `onCleanup` for lifecycle teardown.
+- Call `unwatch(...)` on teardown, not only reference nulling.
+- Keep adapters/renderers passive; state validity remains actor-owned.
+
+## Architecture
+
+PlayRenderer follows the XMachines Play architecture:
+
+- **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
+
+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.
+
+Signals remain observation plumbing, not an alternate mutation channel.
+
+## License
+
+MIT

package/dist/PlayRenderer.js

@@ -0,0 +1,30 @@
+import { memo as o, insert as r, createComponent as i, Dynamic as u, mergeProps as s, template as d } from "solid-js/web";
+import { createSignal as g, onMount as b } from "solid-js";
+import { Signal as w } from "@xmachines/play-signals";
+var f = /* @__PURE__ */ d('<div class=play-renderer-error>Component "<!>" not found in catalog. Available: ');
+const h = (n) => {
+  const [e, a] = g(n.actor.currentView.get());
+  b(() => {
+    const t = new w.subtle.Watcher(() => {
+      queueMicrotask(() => {
+        t.getPending(), a(n.actor.currentView.get()), t.watch(n.actor.currentView);
+      });
+    });
+    t.watch(n.actor.currentView);
+  });
+  const l = n.actor.send.bind(n.actor);
+  return [o(() => o(() => !e())() && (n.fallback || null)), o(() => o(() => !!(e() && !n.components))() && (console.error(`Components catalog is ${n.components === null ? "null" : "undefined"}. Cannot render component "${e().component}".`), n.fallback || null)), o(() => o(() => !!(e() && n.components && !n.components[e().component]))() && (console.error(`Component "${e().component}" not found in catalog. Available components: ${Object.keys(n.components).join(", ")}`), (() => {
+    var t = f(), m = t.firstChild, c = m.nextSibling;
+    return c.nextSibling, r(t, () => e().component, c), r(t, () => Object.keys(n.components).join(", "), null), t;
+  })())), o(() => o(() => !!(e() && n.components && n.components[e().component]))() && i(u, s({
+    get component() {
+      return n.components[e().component];
+    }
+  }, () => e().props, {
+    send: l
+  })))];
+};
+export {
+  h as PlayRenderer
+};
+//# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayRenderer.js","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"],"names":["PlayRenderer","props","view","setView","createSignal","actor","currentView","get","onMount","watcher","Signal","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","_$insert","_$createComponent","Dynamic","_$mergeProps"],"mappings":";;;;AAiEO,MAAMA,IAA8CC,CAAAA,MAAU;AAGpE,QAAM,CAACC,GAAMC,CAAO,IAAIC,EAAwBH,EAAMI,MAAMC,YAAYC,KAAkB;AAI1FC,EAAAA,EAAQ,MAAM;AACb,UAAMC,IAAU,IAAIC,EAAOC,OAAOC,QAAQ,MAAM;AAC/CC,qBAAe,MAAM;AAEpBJ,QAAAA,EAAQK,WAAAA,GAGRX,EAAQF,EAAMI,MAAMC,YAAYC,IAAAA,CAAkB,GAIlDE,EAAQM,MAAMd,EAAMI,MAAMC,WAAW;AAAA,MACtC,CAAC;AAAA,IACF,CAAC;AAGDG,IAAAA,EAAQM,MAAMd,EAAMI,MAAMC,WAAW;AAAA,EAItC,CAAC;AAGD,QAAMU,IAAYf,EAAMI,MAAMY,KAAKC,KAAKjB,EAAMI,KAAK;AAEnD,SAAA,CAAAc,EAAA,MAGGA,EAAA,MAAA,CAACjB,EAAAA,CAAM,EAAA,MAAKD,EAAMmB,YAAY,KAAK,GAAAD,EAAA,MAGnCA,EAAA,MAAA,CAAA,EAAAjB,EAAAA,KACA,CAACD,EAAMoB,WAAU,EAAA,MAEhBC,QAAQC,MACP,yBAAyBtB,EAAMoB,eAAe,OAAO,SAAS,WAAW,8BAC5CnB,EAAAA,EAAQsB,SAAS,IAC/C,GACOvB,EAAMmB,YAAY,KACtB,GAAAD,EAAA,MAGJA,EAAA,MAAA,CAAA,EAAAjB,EAAAA,KACAD,EAAMoB,cACN,CAACpB,EAAMoB,WAAWnB,EAAAA,EAAQsB,SAAS,EAAC,EAAA,MAEnCF,QAAQC,MACP,cAAcrB,EAAAA,EAAQsB,SAAS,iDACLC,OAAOC,KAAKzB,EAAMoB,UAAU,EAAEM,KAAK,IAAI,CAAC,EACnE,IACA,MAAA;AAAA,QAAAC,IAAAC,KAAAC,IAAAF,EAAAG,YAAAC,IAAAF,EAAAG;AAAAD,WAAAA,EAAAC,aAAAC,EAAAN,GAAA,MAEc1B,EAAAA,EAAQsB,WAASQ,CAAA,GAAAE,EAAAN,GAAA,MAC5BH,OAAOC,KAAKzB,EAAMoB,UAAU,EAAEM,KAAK,IAAI,GAAC,IAAA,GAAAC;AAAAA,EAAA,GAAA,EAGxC,GAAAT,EAAA,MAGJA,EAAA,MAAA,CAAA,EAAAjB,EAAAA,KAAUD,EAAMoB,cAAcpB,EAAMoB,WAAWnB,EAAAA,EAAQsB,SAAS,EAAC,OAAAW,EAChEC,GAAOC,EAAA;AAAA,IAAA,IACPb,YAAS;AAAA,aAAEvB,EAAMoB,WAAWnB,EAAAA,EAAQsB,SAAS;AAAA,IAAC;AAAA,EAAA,GAAA,MAC1CtB,EAAAA,EAAQD,OAAK;AAAA,IACjBgB,MAAMD;AAAAA,EAAAA,CAAS,CAAA,CAEhB,CAAA;AAGJ;"}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { PlayRenderer as o } from "./PlayRenderer.js";
+export {
+  o as PlayRenderer
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@xmachines/play-solid",
+  "version": "1.0.0-beta.1",
+  "description": "SolidJS renderer for XMachines Play architecture",
+  "keywords": [
+    "catalog",
+    "play",
+    "renderer",
+    "signals",
+    "solidjs",
+    "xmachines"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc --build",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xmachines/play-actor": "1.0.0-beta.1",
+    "@xmachines/play-catalog": "1.0.0-beta.1",
+    "@xmachines/play-signals": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@solidjs/testing-library": "^0.8.10",
+    "@types/node": "^25.4.0",
+    "solid-js": "^1.9.3",
+    "typescript": "^5.7.0",
+    "vite": "^7.3.1",
+    "vite-plugin-solid": "^2.11.4",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.8.0 || ^1.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}