@xmachines/play-vue 1.0.0-beta.2 → 1.0.0-beta.21

package/README.md

@@ -1,137 +1,267 @@
 # @xmachines/play-vue
 
-Vue renderer component for XMachines Play architecture.
+**Vue 3 renderer for XMachines Play Architecture**
 
-This package keeps Vue as passive infrastructure: it observes actor signals and forwards events, but does not enforce business policy.
+Bridges TC39 Signal-driven actors to Vue's reactivity. Business logic stays in the actor; Vue is purely a rendering target.
+
+## Overview
+
+`@xmachines/play-vue` provides `PlayRenderer`, a Vue 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/vue`
+- 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):** Vue 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-vue vue
+npm install @xmachines/play-vue
+npm install @json-render/vue @json-render/core    # peer deps
+npm install @json-render/xstate @xstate/store     # store integration
 ```
 
 ## Current Exports
 
-- `PlayRenderer` (Vue component)
+- `PlayRenderer` — main renderer component (Vue SFC)
+- `useActor` — composable for accessing the actor inside a `PlayRenderer` tree
+- `defineRegistry` — SFC-aware wrapper; auto-wraps `.vue` SFCs via `h(SFC, ctx)`
+- `useStateBinding` — re-exported from `@json-render/vue`
+- `ComponentFn` (type) — re-exported from `@json-render/vue`
+- `ComponentContext` (type) — re-exported from `@json-render/vue`
 - `PlayRendererProps` (type)
+- `PlayActor` (type)
 
-## Usage
+## Quick Start
 
-```vue
-<script setup lang="ts">
-import { PlayRenderer } from "@xmachines/play-vue";
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
+```ts
+// catalog.ts — shared contract
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
 
-// Define catalog
-const catalog = defineCatalog({
-	home: { component: "Home", props: { title: "string" } },
-	login: { component: "Login", props: { error: "string?" } },
-	dashboard: { component: "Dashboard", props: { userId: "string" } },
+export const catalog = defineCatalog({
+	elements: {
+		Login: { props: z.object({ title: z.string() }), description: "Login form" },
+		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+	},
 });
 
-// Create actor
-const actor = definePlayer({ machine: authMachine, catalog })();
-actor.start();
+export type Catalog = typeof catalog;
+```
 
-// Define component map
-const components = {
-	Home: HomeComponent,
-	Login: LoginComponent,
-	Dashboard: DashboardComponent,
-};
+```vue
+<!-- Login.vue — Vue SFC; useStateBinding works in <script setup> -->
+<script setup lang="ts">
+import { useStateBinding } from "@xmachines/play-vue";
+import type { ComponentContext } from "@xmachines/play-vue";
+import type { Catalog } from "./catalog.js";
+
+const { props, emit, bindings } = defineProps<ComponentContext<Catalog, "Login">>();
+const [username, setUsername] = useStateBinding<string>(bindings?.username ?? "/username");
 </script>
 
 <template>
-	<PlayRenderer :actor="actor" :components="components">
-		<template #fallback>
-			<div>Loading...</div>
-		</template>
-	</PlayRenderer>
+	<div class="view">
+		<h2>{{ props.title }}</h2>
+		<form @submit.prevent="emit('submit')">
+			<input id="username" v-model="username" @input="setUsername(username)" />
+			<button type="submit">Log In</button>
+		</form>
+	</div>
 </template>
 ```
 
-## API
+```ts
+// registry.ts — pass SFCs directly; defineRegistry auto-wraps them
+import { defineRegistry } from "@xmachines/play-vue";
+import { catalog } from "./catalog.js";
+import LoginSFC from "./Login.vue";
+import DashboardSFC from "./Dashboard.vue";
 
-### PlayRenderer
+export const { registry } = defineRegistry(catalog, {
+	components: { Login: LoginSFC, Dashboard: DashboardSFC },
+	actions: { login: async () => {}, logout: async () => {} },
+});
+```
 
-Main renderer component that observes `actor.currentView` signal and dynamically renders catalog components.
+```ts
+// machine.ts
+import { setup, assign } from "xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+export const machine = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			username: string | null;
+			routeParams: Record<string, string>;
+			queryParams: 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, routeParams: {}, queryParams: {} },
+		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 }),
+			},
+		},
+	}),
+);
+```
 
-**Props:**
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRenderer } from "@xmachines/play-vue";
+import { machine } from "./machine.js";
+import { registry } from "./registry.js";
 
-- `actor` (required) - Actor instance with `currentView` signal
-- `components` (required) - Map of component names to Vue components
-- `fallback` (optional) - Slot shown when `currentView` is null
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+</script>
 
-**Component Props:**
+<template>
+	<PlayRenderer
+		:actor="actor"
+		:registry="registry"
+		:actions="{ login: 'auth.login', logout: 'auth.logout' }"
+	/>
+</template>
+```
 
-Each rendered component receives:
+## API Reference
 
-- All props from `view.props` (spread via `v-bind`)
-- `send` function for sending events to actor
+### `PlayRenderer`
 
-**Example Component:**
+Main Vue component. Subscribes to `actor.currentView` and renders the spec.
 
 ```vue
-<script setup lang="ts">
-import type { AbstractActor } from "@xmachines/play-actor";
+<PlayRenderer
+	:actor="actor"
+	:registry="registry"
+	:actions="{ login: 'auth.login' }"
+	:store="myStore"
+/>
+```
 
-defineProps<{
-	userId: string;
-	send: AbstractActor<any>["send"];
-}>();
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-function handleClick() {
-	send({ type: "user.click", payload: { action: "details" } });
-}
-</script>
+**`registry`** — Built with `defineRegistry(catalog, { components, actions })` from `@xmachines/play-vue`. Pass `.vue` SFCs directly — they are auto-wrapped via `h(SFC, ctx)` so `useStateBinding` and other composables work inside `<script setup>`.
 
-<template>
-	<div>
-		<h1>User: {{ userId }}</h1>
-		<button @click="handleClick">View Details</button>
-	</div>
-</template>
+**`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.
+
+**`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.
+
+```ts
+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: "" }) });
 ```
 
-## Features
+```vue
+<PlayRenderer
+	:actor="actor"
+	:registry="registry"
+	:store="store"
+	:actions="{ login: 'auth.login' }"
+/>
+```
 
-- **Signal Bridge:** Uses TC39 Signal.subtle.Watcher to bridge actor signals to Vue reactivity
-- **Dynamic Rendering:** Renders components based on `actor.currentView.component` string
-- **Type Safe:** Full TypeScript support with generic type inference
-- **Error Handling:** Gracefully handles missing components and null catalogs
-- **One-Shot Re-Watch:** Implements proper signal watcher pattern with microtask batching
+---
 
-## Canonical Watcher Lifecycle
+### `useActor`
 
-Use the same watcher flow as other adapters/packages:
+Vue composable for accessing the actor from inside any component rendered by `PlayRenderer`.
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. read actor signals and update framework-local state
-5. re-arm with `watch(...)` or `watch()`
+```ts
+import { useActor } from "@xmachines/play-vue";
 
-Watcher notify is one-shot. Re-arm is required for continuous observation.
+// Inside any component rendered inside PlayRenderer:
+const actor = useActor();
+actor.send({ type: "auth.logout" });
+```
 
-## Cleanup Contract
+Throws `"useActor() must be called inside <PlayRenderer>"` if called outside the tree.
 
-Cleanup must be explicit:
+---
 
-- Call `unwatch(...)` during Vue lifecycle teardown (`onUnmounted`).
-- Treat renderer/provider disposal as deterministic teardown, not GC-only cleanup.
-- Keep actor-driven routing and view decisions in the actor layer.
+## Route Parameters in Props
 
-## Architecture
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-PlayRenderer follows the XMachines Play architecture principles:
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.routeParams = { section: "profile" }
+// Component receives: { section: "profile", user: "alice" }
+```
 
-1. **Actor Authority:** Actor decides all state transitions
-2. **Passive Infrastructure:** Renderer observes signals, sends events
-3. **Signal-Only Reactivity:** Business logic state lives in actor signals
+Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
 
-Signals are reactivity substrate only. They are not a business mutation channel.
+---
 
-## License
+## Architecture Notes
 
-MIT
+- Vue reactivity is only used to trigger re-renders — not for business logic
+- `actor.currentView` (TC39 Signal) is bridged to Vue's reactive system inside `PlayRenderer`
+- Per-view UI state lives in an `@xstate/store` atom, not in Vue reactive state
+- `@json-render/vue` drives rendering; `PlayRenderer` is the signal bridge — import `defineRegistry`, `ComponentFn`, `ComponentContext`, and `useStateBinding` from `@xmachines/play-vue`
+- Vue views should be `.vue` SFCs using `ComponentContext<MyCatalog, "X">` — `defineRegistry` from `@xmachines/play-vue` auto-wraps them via `h(SFC, ctx)`, giving each SFC its own `setup()` context where `useStateBinding` and Vue composables work correctly

package/dist/PlayRenderer.js

@@ -0,0 +1,7 @@
+import e from "./PlayRenderer.vue_vue_type_script_lang.js";
+//#region src/PlayRenderer.vue
+var t = e;
+//#endregion
+export { t as default };
+
+//# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayRenderer.js","names":[],"sources":["../src/PlayRenderer.vue"],"sourcesContent":["<script lang=\"ts\">\n/**\n * PlayRenderer - Main Vue renderer component for XMachines Play architecture\n *\n * Architecture (per RESEARCH.md Pattern 1):\n * - Subscribes to actor.currentView signal via Signal.subtle.Watcher\n * - Renders view.spec via @json-render/vue Renderer + StateProvider + ActionProvider\n * - Routes actor.send() calls via ActionProvider handlers\n * - Vue ref only for triggering renders, NOT business logic\n *\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 * The atom resets automatically when the actor transitions to a new view.\n *\n * Signal bridge uses one-shot re-watch pattern:\n * TC39 Signal watchers stop watching after notification, so watcher.watch()\n * must be called inside a microtask after getPending() to re-arm for the\n * next notification.\n *\n * CRITICAL: Never call signal.get() or signal.set() inside the Watcher's\n * notify callback. The callback runs synchronously during the signal graph's\n * dirty-propagation phase. All reads must be deferred to a queueMicrotask.\n *\n * @invariant Actor Authority - Actor decides all state transitions via guards\n * @invariant Passive Infrastructure - Component observes signals, sends events\n * @invariant Signal-Only Reactivity - Business logic state lives in actor signals\n */\n\nimport { defineComponent, ref, toRaw, onUnmounted, h } from \"vue\";\nimport type { PropType } from \"vue\";\nimport { watchSignal } from \"@xmachines/play-signals\";\nimport type { PlayRendererProps } from \"./types.js\";\nimport type { AbstractActor, Viewable, ViewMetadata } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\nimport type { ComponentRegistry } from \"@json-render/vue\";\nimport type { StateStore } from \"@json-render/core\";\nimport { Renderer, StateProvider, ActionProvider, VisibilityProvider } from \"@json-render/vue\";\nimport { createAtom } from \"@xstate/store\";\nimport { xstateStoreStateStore } from \"@json-render/xstate\";\nimport { provideActor, type PlayActor } from \"./useActor.js\";\n\nexport default defineComponent({\n\tname: \"PlayRenderer\",\n\tprops: {\n\t\tactor: {\n\t\t\ttype: Object as PropType<AbstractActor<AnyActorLogic> & Viewable>,\n\t\t\trequired: true,\n\t\t},\n\t\tregistry: {\n\t\t\ttype: Object as PropType<ComponentRegistry>,\n\t\t\trequired: true,\n\t\t},\n\t\tstore: {\n\t\t\ttype: Object as PropType<StateStore>,\n\t\t\tdefault: undefined,\n\t\t},\n\t\tactions: {\n\t\t\ttype: Object as PropType<Record<string, string>>,\n\t\t\tdefault: () => ({}),\n\t\t},\n\t},\n\tsetup(props, { slots }) {\n\t\t// Unwrap actor from Vue's reactive proxy to access raw Signal objects\n\t\t// CRITICAL: toRaw() preserves Signal's 'this' binding for .get() and watcher operations\n\t\tconst actor = toRaw(props.actor);\n\n\t\t// Provide the raw actor to all descendants via Vue's provide/inject mechanism\n\t\tprovideActor(actor as PlayActor);\n\n\t\t// Get initial value from unwrapped signal\n\t\tconst initialView = actor.currentView.get();\n\n\t\t// Vue ref for triggering re-renders (NOT business logic state)\n\t\t// Signal is source of truth, ref is just Vue's render trigger\n\t\tconst view = ref<ViewMetadata | null>(initialView);\n\n\t\t// Internal per-view store — recreated on each view transition when no external store.\n\t\tlet internalStore: StateStore | null = null;\n\t\tlet lastView: ViewMetadata | null = null;\n\t\t// Key counter: forces Vue to remount StateProvider (and all descendants) when the\n\t\t// store changes. Without this, StateProvider's setup() only runs once — its provide()\n\t\t// call captures the FIRST store and never updates, leaving ActionProvider and child\n\t\t// components referencing a stale store.\n\t\tlet storeKey = 0;\n\n\t\t// Signal watcher for bridging TC39 Signals to Vue reactivity\n\t\tconst unwatch = watchSignal(actor.currentView, (nextView) => {\n\t\t\tview.value = nextView;\n\t\t});\n\n\t\tonUnmounted(() => {\n\t\t\tunwatch();\n\t\t});\n\n\t\t// Use render function to avoid Vue 3.5 SFC template <slot> + jsdom renderSlot crash\n\t\treturn () => {\n\t\t\t// No view — show fallback slot\n\t\t\tif (!view.value) {\n\t\t\t\treturn slots.fallback ? slots.fallback() : null;\n\t\t\t}\n\n\t\t\tconst spec = view.value.spec;\n\n\t\t\t// Resolve the store: external (controlled) or internal per-view atom\n\t\t\tlet store: StateStore;\n\t\t\tif (props.store) {\n\t\t\t\tstore = props.store;\n\t\t\t} else {\n\t\t\t\tif (internalStore === null || lastView !== view.value) {\n\t\t\t\t\tconst initialState = (spec.state as Record<string, unknown>) ?? {};\n\t\t\t\t\tinternalStore = xstateStoreStateStore({ atom: createAtom(initialState) });\n\t\t\t\t\tlastView = view.value;\n\t\t\t\t\tstoreKey++;\n\t\t\t\t}\n\t\t\t\tstore = internalStore;\n\t\t\t}\n\n\t\t\t// Map json-render action names to actor.send() calls\n\t\t\tconst handlers = Object.fromEntries(\n\t\t\t\tObject.entries(props.actions ?? {}).map(([actionName, eventType]) => [\n\t\t\t\t\tactionName,\n\t\t\t\t\tasync (params: Record<string, unknown> = {}) =>\n\t\t\t\t\t\tactor.send({ type: eventType, ...params }),\n\t\t\t\t]),\n\t\t\t);\n\n\t\t\treturn h(StateProvider, { store, key: storeKey }, () =>\n\t\t\t\th(ActionProvider, { handlers }, () =>\n\t\t\t\t\th(VisibilityProvider, {}, () =>\n\t\t\t\t\t\th(Renderer, { spec, registry: props.registry }),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t};\n\t},\n});\n</script>\n"],"mappings":""}

package/dist/PlayRenderer.vue_vue_type_script_lang.js

@@ -0,0 +1,57 @@
+import { ActionProvider as e, Renderer as t, StateProvider as n, VisibilityProvider as r } from "./node_modules/@json-render/vue/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 { provideActor as o } from "./useActor.js";
+import { defineComponent as s, h as c, onUnmounted as l, ref as u, toRaw as d } from "vue";
+import { watchSignal as f } from "@xmachines/play-signals";
+//#region src/PlayRenderer.vue?vue&type=script&lang.ts
+var p = s({
+	name: "PlayRenderer",
+	props: {
+		actor: {
+			type: Object,
+			required: !0
+		},
+		registry: {
+			type: Object,
+			required: !0
+		},
+		store: {
+			type: Object,
+			default: void 0
+		},
+		actions: {
+			type: Object,
+			default: () => ({})
+		}
+	},
+	setup(s, { slots: p }) {
+		let m = d(s.actor);
+		o(m);
+		let h = u(m.currentView.get()), g = null, _ = null, v = 0, y = f(m.currentView, (e) => {
+			h.value = e;
+		});
+		return l(() => {
+			y();
+		}), () => {
+			if (!h.value) return p.fallback ? p.fallback() : null;
+			let o = h.value.spec, l;
+			s.store ? l = s.store : ((g === null || _ !== h.value) && (g = a({ atom: i(o.state ?? {}) }), _ = h.value, v++), l = g);
+			let u = Object.fromEntries(Object.entries(s.actions ?? {}).map(([e, t]) => [e, async (e = {}) => m.send({
+				type: t,
+				...e
+			})]));
+			return c(n, {
+				store: l,
+				key: v
+			}, () => c(e, { handlers: u }, () => c(r, {}, () => c(t, {
+				spec: o,
+				registry: s.registry
+			}))));
+		};
+	}
+});
+//#endregion
+export { p as default };
+
+//# sourceMappingURL=PlayRenderer.vue_vue_type_script_lang.js.map

package/dist/PlayRenderer.vue_vue_type_script_lang.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayRenderer.vue_vue_type_script_lang.js","names":[],"sources":["../src/PlayRenderer.vue"],"sourcesContent":["<script lang=\"ts\">\n/**\n * PlayRenderer - Main Vue renderer component for XMachines Play architecture\n *\n * Architecture (per RESEARCH.md Pattern 1):\n * - Subscribes to actor.currentView signal via Signal.subtle.Watcher\n * - Renders view.spec via @json-render/vue Renderer + StateProvider + ActionProvider\n * - Routes actor.send() calls via ActionProvider handlers\n * - Vue ref only for triggering renders, NOT business logic\n *\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 * The atom resets automatically when the actor transitions to a new view.\n *\n * Signal bridge uses one-shot re-watch pattern:\n * TC39 Signal watchers stop watching after notification, so watcher.watch()\n * must be called inside a microtask after getPending() to re-arm for the\n * next notification.\n *\n * CRITICAL: Never call signal.get() or signal.set() inside the Watcher's\n * notify callback. The callback runs synchronously during the signal graph's\n * dirty-propagation phase. All reads must be deferred to a queueMicrotask.\n *\n * @invariant Actor Authority - Actor decides all state transitions via guards\n * @invariant Passive Infrastructure - Component observes signals, sends events\n * @invariant Signal-Only Reactivity - Business logic state lives in actor signals\n */\n\nimport { defineComponent, ref, toRaw, onUnmounted, h } from \"vue\";\nimport type { PropType } from \"vue\";\nimport { watchSignal } from \"@xmachines/play-signals\";\nimport type { PlayRendererProps } from \"./types.js\";\nimport type { AbstractActor, Viewable, ViewMetadata } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\nimport type { ComponentRegistry } from \"@json-render/vue\";\nimport type { StateStore } from \"@json-render/core\";\nimport { Renderer, StateProvider, ActionProvider, VisibilityProvider } from \"@json-render/vue\";\nimport { createAtom } from \"@xstate/store\";\nimport { xstateStoreStateStore } from \"@json-render/xstate\";\nimport { provideActor, type PlayActor } from \"./useActor.js\";\n\nexport default defineComponent({\n\tname: \"PlayRenderer\",\n\tprops: {\n\t\tactor: {\n\t\t\ttype: Object as PropType<AbstractActor<AnyActorLogic> & Viewable>,\n\t\t\trequired: true,\n\t\t},\n\t\tregistry: {\n\t\t\ttype: Object as PropType<ComponentRegistry>,\n\t\t\trequired: true,\n\t\t},\n\t\tstore: {\n\t\t\ttype: Object as PropType<StateStore>,\n\t\t\tdefault: undefined,\n\t\t},\n\t\tactions: {\n\t\t\ttype: Object as PropType<Record<string, string>>,\n\t\t\tdefault: () => ({}),\n\t\t},\n\t},\n\tsetup(props, { slots }) {\n\t\t// Unwrap actor from Vue's reactive proxy to access raw Signal objects\n\t\t// CRITICAL: toRaw() preserves Signal's 'this' binding for .get() and watcher operations\n\t\tconst actor = toRaw(props.actor);\n\n\t\t// Provide the raw actor to all descendants via Vue's provide/inject mechanism\n\t\tprovideActor(actor as PlayActor);\n\n\t\t// Get initial value from unwrapped signal\n\t\tconst initialView = actor.currentView.get();\n\n\t\t// Vue ref for triggering re-renders (NOT business logic state)\n\t\t// Signal is source of truth, ref is just Vue's render trigger\n\t\tconst view = ref<ViewMetadata | null>(initialView);\n\n\t\t// Internal per-view store — recreated on each view transition when no external store.\n\t\tlet internalStore: StateStore | null = null;\n\t\tlet lastView: ViewMetadata | null = null;\n\t\t// Key counter: forces Vue to remount StateProvider (and all descendants) when the\n\t\t// store changes. Without this, StateProvider's setup() only runs once — its provide()\n\t\t// call captures the FIRST store and never updates, leaving ActionProvider and child\n\t\t// components referencing a stale store.\n\t\tlet storeKey = 0;\n\n\t\t// Signal watcher for bridging TC39 Signals to Vue reactivity\n\t\tconst unwatch = watchSignal(actor.currentView, (nextView) => {\n\t\t\tview.value = nextView;\n\t\t});\n\n\t\tonUnmounted(() => {\n\t\t\tunwatch();\n\t\t});\n\n\t\t// Use render function to avoid Vue 3.5 SFC template <slot> + jsdom renderSlot crash\n\t\treturn () => {\n\t\t\t// No view — show fallback slot\n\t\t\tif (!view.value) {\n\t\t\t\treturn slots.fallback ? slots.fallback() : null;\n\t\t\t}\n\n\t\t\tconst spec = view.value.spec;\n\n\t\t\t// Resolve the store: external (controlled) or internal per-view atom\n\t\t\tlet store: StateStore;\n\t\t\tif (props.store) {\n\t\t\t\tstore = props.store;\n\t\t\t} else {\n\t\t\t\tif (internalStore === null || lastView !== view.value) {\n\t\t\t\t\tconst initialState = (spec.state as Record<string, unknown>) ?? {};\n\t\t\t\t\tinternalStore = xstateStoreStateStore({ atom: createAtom(initialState) });\n\t\t\t\t\tlastView = view.value;\n\t\t\t\t\tstoreKey++;\n\t\t\t\t}\n\t\t\t\tstore = internalStore;\n\t\t\t}\n\n\t\t\t// Map json-render action names to actor.send() calls\n\t\t\tconst handlers = Object.fromEntries(\n\t\t\t\tObject.entries(props.actions ?? {}).map(([actionName, eventType]) => [\n\t\t\t\t\tactionName,\n\t\t\t\t\tasync (params: Record<string, unknown> = {}) =>\n\t\t\t\t\t\tactor.send({ type: eventType, ...params }),\n\t\t\t\t]),\n\t\t\t);\n\n\t\t\treturn h(StateProvider, { store, key: storeKey }, () =>\n\t\t\t\th(ActionProvider, { handlers }, () =>\n\t\t\t\t\th(VisibilityProvider, {}, () =>\n\t\t\t\t\t\th(Renderer, { spec, registry: props.registry }),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t};\n\t},\n});\n</script>\n"],"mappings":";;;;;;;AAyCA,IAAA,IAAe,EAAgB;CAC9B,MAAM;CACN,OAAO;EACN,OAAO;GACN,MAAM;GACN,UAAU;GACV;EACD,UAAU;GACT,MAAM;GACN,UAAU;GACV;EACD,OAAO;GACN,MAAM;GACN,SAAS,KAAA;GACT;EACD,SAAS;GACR,MAAM;GACN,gBAAgB,EAAE;GAClB;EACD;CACD,MAAM,GAAO,EAAE,YAAS;EAGvB,IAAM,IAAQ,EAAM,EAAM,MAAM;AAGhC,IAAa,EAAmB;EAOhC,IAAM,IAAO,EAJO,EAAM,YAAY,KAAK,CAIO,EAG9C,IAAmC,MACnC,IAAgC,MAKhC,IAAW,GAGT,IAAU,EAAY,EAAM,cAAc,MAAa;AAC5D,KAAK,QAAQ;IACZ;AAOF,SALA,QAAkB;AACjB,MAAS;IACR,QAGW;AAEZ,OAAI,CAAC,EAAK,MACT,QAAO,EAAM,WAAW,EAAM,UAAS,GAAI;GAG5C,IAAM,IAAO,EAAK,MAAM,MAGpB;AACJ,GAAI,EAAM,QACT,IAAQ,EAAM,UAEV,MAAkB,QAAQ,MAAa,EAAK,WAE/C,IAAgB,EAAsB,EAAE,MAAM,EADxB,EAAK,SAAqC,EAAE,CACG,EAAG,CAAC,EACzE,IAAW,EAAK,OAChB,MAED,IAAQ;GAIT,IAAM,IAAW,OAAO,YACvB,OAAO,QAAQ,EAAM,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,GAAY,OAAe,CACpE,GACA,OAAO,IAAkC,EAAE,KAC1C,EAAM,KAAK;IAAE,MAAM;IAAW,GAAG;IAAQ,CAAC,CAC3C,CAAC,CACF;AAED,UAAO,EAAE,GAAe;IAAE;IAAO,KAAK;IAAU,QAC/C,EAAE,GAAgB,EAAE,aAAU,QAC7B,EAAE,GAAoB,EAAE,QACvB,EAAE,GAAU;IAAE;IAAM,UAAU,EAAM;IAAU,CAAC,CAC/C,CACD,CACD;;;CAGH,CAAC"}

package/dist/define-registry.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `defineRegistry` wrapper for @xmachines/play-vue.
+ *
+ * Wraps `defineRegistry` from `@json-render/vue` with automatic SFC support.
+ *
+ * ## Vue-specific — React and Solid do not need this
+ *
+ * In React, `useContext()` works anywhere inside the component call tree.
+ * In Solid, `useContext()` works inside reactive computations and component renders.
+ * Neither has the strict "synchronous setup() only" constraint that Vue's `inject()`
+ * imposes — so their `defineRegistry` implementations call `componentFn(ctx)` directly
+ * with no wrapping needed.
+ *
+ * For the DOM renderer, there is no component system at all — just render functions
+ * returning `HTMLElement` — so injection context is not applicable.
+ *
+ * Only Vue requires this adapter.
+ *
+ * ## Why this wrapper exists
+ *
+ * `@json-render/vue`'s `defineRegistry` calls each registered component as a plain
+ * function: `componentFn(ctx)`. A `.vue` SFC (output of `defineComponent` or
+ * `<script setup>`) is an **object**, not a function — calling it throws.
+ *
+ * More fundamentally, `defineRegistry` calls components inside its own render
+ * function (the return value of `setup()`). Vue's `inject()` — and composables built
+ * on it: `useStateBinding`, `useStateStore` — only work during synchronous `setup()`
+ * execution, not inside render functions. Plain `.ts` `ComponentFn` files cannot
+ * call any Vue composable for this reason.
+ *
+ * This wrapper auto-detects Vue SFCs in the `components` map and wraps them via
+ * `h(SFC, ctx)`. The SFC renders as a child component with its own `setup()`,
+ * giving full access to composables inside `<script setup>`.
+ *
+ * ## Usage
+ *
+ * Import `defineRegistry` from `@xmachines/play-vue` instead of `@json-render/vue`:
+ *
+ * ```ts
+ * import { defineRegistry } from "@xmachines/play-vue";
+ * // not: import { defineRegistry } from "@json-render/vue";
+ *
+ * import LoginSFC from "./views/Login.vue";
+ * import DashboardSFC from "./views/Dashboard.vue";
+ *
+ * const { registry } = defineRegistry(catalog, {
+ *   components: {
+ *     Login: LoginSFC,       // .vue SFC — auto-wrapped
+ *     Dashboard: DashboardSFC, // .vue SFC — auto-wrapped
+ *   },
+ * });
+ * ```
+ *
+ * Plain `ComponentFn` functions still work and are passed through unchanged.
+ * Mixing SFCs and plain functions in the same registry is supported.
+ */
+import { type Component } from "vue";
+import { defineRegistry as defineRegistryBase, type ComponentFn } from "@json-render/vue";
+import type { Catalog, InferCatalogComponents } from "@json-render/core";
+export type ComponentEntry<C extends Catalog, K extends keyof InferCatalogComponents<C>> = ComponentFn<C, K> | Component;
+export type ComponentsMap<C extends Catalog> = {
+    [K in keyof InferCatalogComponents<C>]?: ComponentEntry<C, K>;
+};
+export type DefineRegistryOptions<C extends Catalog> = Parameters<typeof defineRegistryBase<C>>[1] & {
+    components?: ComponentsMap<C>;
+};
+/**
+ * Create a component registry, automatically wrapping `.vue` SFCs so they work
+ * correctly with `@json-render/vue`'s rendering pipeline.
+ *
+ * Drop-in replacement for `defineRegistry` from `@json-render/vue`. Import from
+ * `@xmachines/play-vue` to get SFC support for free.
+ *
+ * @param catalog - The json-render catalog defining component prop shapes.
+ * @param options - Registry options. `components` entries may be `.vue` SFCs
+ *   (objects) or plain `ComponentFn` functions — both are handled automatically.
+ */
+export declare function defineRegistry<C extends Catalog>(catalog: C, options: DefineRegistryOptions<C>): ReturnType<typeof defineRegistryBase<C>>;
+//# sourceMappingURL=define-registry.d.ts.map

package/dist/define-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-registry.d.ts","sourceRoot":"","sources":["../src/define-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EACN,cAAc,IAAI,kBAAkB,EAEpC,KAAK,WAAW,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAyBzE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,MAAM,sBAAsB,CAAC,CAAC,CAAC,IACpF,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACjB,SAAS,CAAC;AAEb,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,IAAI;KAC7C,CAAC,IAAI,MAAM,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,OAAO,IAAI,UAAU,CAChE,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAC5B,CAAC,CAAC,CAAC,GAAG;IACN,UAAU,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAc1C"}

package/dist/define-registry.js

@@ -0,0 +1,21 @@
+import { defineRegistry as e } from "./node_modules/@json-render/vue/dist/index.js";
+import { h as t } from "vue";
+//#region src/define-registry.ts
+function n(e) {
+	return typeof e == "object" && !!e;
+}
+function r(e) {
+	return (n) => t(e, n);
+}
+function i(t, i) {
+	let a = {};
+	for (let [e, t] of Object.entries(i.components ?? {})) t !== void 0 && (a[e] = n(t) ? r(t) : t);
+	return e(t, {
+		...i,
+		components: a
+	});
+}
+//#endregion
+export { i as defineRegistry };
+
+//# sourceMappingURL=define-registry.js.map

package/dist/define-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-registry.js","names":[],"sources":["../src/define-registry.ts"],"sourcesContent":["/**\n * `defineRegistry` wrapper for @xmachines/play-vue.\n *\n * Wraps `defineRegistry` from `@json-render/vue` with automatic SFC support.\n *\n * ## Vue-specific — React and Solid do not need this\n *\n * In React, `useContext()` works anywhere inside the component call tree.\n * In Solid, `useContext()` works inside reactive computations and component renders.\n * Neither has the strict \"synchronous setup() only\" constraint that Vue's `inject()`\n * imposes — so their `defineRegistry` implementations call `componentFn(ctx)` directly\n * with no wrapping needed.\n *\n * For the DOM renderer, there is no component system at all — just render functions\n * returning `HTMLElement` — so injection context is not applicable.\n *\n * Only Vue requires this adapter.\n *\n * ## Why this wrapper exists\n *\n * `@json-render/vue`'s `defineRegistry` calls each registered component as a plain\n * function: `componentFn(ctx)`. A `.vue` SFC (output of `defineComponent` or\n * `<script setup>`) is an **object**, not a function — calling it throws.\n *\n * More fundamentally, `defineRegistry` calls components inside its own render\n * function (the return value of `setup()`). Vue's `inject()` — and composables built\n * on it: `useStateBinding`, `useStateStore` — only work during synchronous `setup()`\n * execution, not inside render functions. Plain `.ts` `ComponentFn` files cannot\n * call any Vue composable for this reason.\n *\n * This wrapper auto-detects Vue SFCs in the `components` map and wraps them via\n * `h(SFC, ctx)`. The SFC renders as a child component with its own `setup()`,\n * giving full access to composables inside `<script setup>`.\n *\n * ## Usage\n *\n * Import `defineRegistry` from `@xmachines/play-vue` instead of `@json-render/vue`:\n *\n * ```ts\n * import { defineRegistry } from \"@xmachines/play-vue\";\n * // not: import { defineRegistry } from \"@json-render/vue\";\n *\n * import LoginSFC from \"./views/Login.vue\";\n * import DashboardSFC from \"./views/Dashboard.vue\";\n *\n * const { registry } = defineRegistry(catalog, {\n *   components: {\n *     Login: LoginSFC,       // .vue SFC — auto-wrapped\n *     Dashboard: DashboardSFC, // .vue SFC — auto-wrapped\n *   },\n * });\n * ```\n *\n * Plain `ComponentFn` functions still work and are passed through unchanged.\n * Mixing SFCs and plain functions in the same registry is supported.\n */\n\nimport { h, type Component } from \"vue\";\nimport {\n\tdefineRegistry as defineRegistryBase,\n\ttype ComponentContext,\n\ttype ComponentFn,\n} from \"@json-render/vue\";\nimport type { Catalog, InferCatalogComponents } from \"@json-render/core\";\n\n/**\n * Detect whether a value is a Vue component object (SFC) rather than a plain\n * `ComponentFn` function.\n *\n * Vue SFCs produced by `defineComponent` or `<script setup>` compilation are\n * plain objects (not callable). A `ComponentFn` is always a plain function.\n */\nfunction isVueSFC(value: unknown): value is Component {\n\treturn typeof value === \"object\" && value !== null;\n}\n\n/**\n * Wrap a Vue SFC as a `ComponentFn` by rendering it via `h()`.\n *\n * The SFC receives the full `ComponentContext` as its props and renders in its\n * own child component `setup()`, where Vue composables work correctly.\n */\nfunction wrapSFC<C extends Catalog, K extends keyof InferCatalogComponents<C>>(\n\tcomponent: Component,\n): ComponentFn<C, K> {\n\treturn (ctx: ComponentContext<C, K>) => h(component, ctx);\n}\n\nexport type ComponentEntry<C extends Catalog, K extends keyof InferCatalogComponents<C>> =\n\t| ComponentFn<C, K>\n\t| Component;\n\nexport type ComponentsMap<C extends Catalog> = {\n\t[K in keyof InferCatalogComponents<C>]?: ComponentEntry<C, K>;\n};\n\nexport type DefineRegistryOptions<C extends Catalog> = Parameters<\n\ttypeof defineRegistryBase<C>\n>[1] & {\n\tcomponents?: ComponentsMap<C>;\n};\n\n/**\n * Create a component registry, automatically wrapping `.vue` SFCs so they work\n * correctly with `@json-render/vue`'s rendering pipeline.\n *\n * Drop-in replacement for `defineRegistry` from `@json-render/vue`. Import from\n * `@xmachines/play-vue` to get SFC support for free.\n *\n * @param catalog - The json-render catalog defining component prop shapes.\n * @param options - Registry options. `components` entries may be `.vue` SFCs\n *   (objects) or plain `ComponentFn` functions — both are handled automatically.\n */\nexport function defineRegistry<C extends Catalog>(\n\tcatalog: C,\n\toptions: DefineRegistryOptions<C>,\n): ReturnType<typeof defineRegistryBase<C>> {\n\tconst wrappedComponents: Record<string, ComponentFn<C, keyof InferCatalogComponents<C>>> = {};\n\n\tfor (const [key, component] of Object.entries(options.components ?? {})) {\n\t\tif (component === undefined) continue;\n\t\twrappedComponents[key] = isVueSFC(component)\n\t\t\t? wrapSFC(component as Component)\n\t\t\t: (component as ComponentFn<C, keyof InferCatalogComponents<C>>);\n\t}\n\n\treturn defineRegistryBase(catalog, {\n\t\t...options,\n\t\tcomponents: wrappedComponents,\n\t});\n}\n"],"mappings":";;;AAwEA,SAAS,EAAS,GAAoC;AACrD,QAAO,OAAO,KAAU,cAAY;;AASrC,SAAS,EACR,GACoB;AACpB,SAAQ,MAAgC,EAAE,GAAW,EAAI;;AA4B1D,SAAgB,EACf,GACA,GAC2C;CAC3C,IAAM,IAAqF,EAAE;AAE7F,MAAK,IAAM,CAAC,GAAK,MAAc,OAAO,QAAQ,EAAQ,cAAc,EAAE,CAAC,CAClE,OAAc,KAAA,MAClB,EAAkB,KAAO,EAAS,EAAU,GACzC,EAAQ,EAAuB,GAC9B;AAGL,QAAO,EAAmB,GAAS;EAClC,GAAG;EACH,YAAY;EACZ,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,22 @@
 /**
- * @xmachines/play-vue - Vue renderer for XMachines Play architecture
+ * @xmachines/play-vue - Vue 3 renderer for XMachines Play architecture
+ *
+ * Provides a thin Vue rendering layer that passively observes actor signals
+ * and renders UI components via @json-render/vue. Vue reactivity is only used
+ * to trigger re-renders — signals are the source of truth.
+ *
+ * Re-exports `defineRegistry` (SFC-aware — auto-wraps `.vue` SFCs via `h()`),
+ * `useStateBinding`, `ComponentFn`, and `ComponentContext` so consumers import
+ * everything from `@xmachines/play-vue` rather than `@json-render/vue` directly.
  *
  * @packageDocumentation
  */
 export { default as PlayRenderer } from "./PlayRenderer.vue";
+export { useActor } from "./useActor.js";
+export { defineRegistry } from "./define-registry.js";
+export type { DefineRegistryOptions, ComponentsMap, ComponentEntry } from "./define-registry.js";
+export { useStateBinding } from "@json-render/vue";
+export type { ComponentFn, ComponentContext } from "@json-render/vue";
 export type { PlayRendererProps } from "./types.js";
+export type { PlayActor } from "./useActor.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;;;;GAIG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEjG,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
-import { default as a } from "./PlayRenderer.vue.js";
-export {
-  a as PlayRenderer
-};
-//# sourceMappingURL=index.js.map
+import { useStateBinding as e } from "./node_modules/@json-render/vue/dist/index.js";
+import { useActor as t } from "./useActor.js";
+import n from "./PlayRenderer.js";
+import { defineRegistry as r } from "./define-registry.js";
+export { n as PlayRenderer, r as defineRegistry, t as useActor, e as useStateBinding };