@xmachines/play-vue 1.0.0-beta.4 → 1.0.0-beta.40

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,137 +1,349 @@
 # @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
 ```
 
+In this monorepo, the root install applies a `patch-package` patch to `@json-render/vue`
+so `defineRegistry(..., { onRenderError })` can intercept inner element-boundary errors
+without muting console output.
+
 ## Current Exports
 
-- `PlayRenderer` (Vue component)
-- `PlayRendererProps` (type)
+- `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)`
+- `useBoundProp` — re-exported from `@json-render/vue`
+- `ComponentFn` (type) — re-exported from `@json-render/vue`
+- `ComponentContext` (type) — re-exported from `@json-render/vue`
+- `ActorProvider` — escape hatch primitive (owns actor bridging, signal bridge, store lifecycle)
+- `PlayUIProvider` — batteries-included composite (wraps `ActorProvider` + `JSONUIProvider`)
+- `getPlayViewContext` — composable for accessing the current view spec inside a provider tree
+- `RenderErrorHandler` (type) — inner per-element error callback signature
+- `ActorProviderProps` (type)
+- `ViewContextValue` (type)
+- `PlayActor` (type)
+
+## Quick Start
+
+```ts
+// catalog.ts — shared contract
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+
+export const catalog = defineCatalog({
+	elements: {
+		Login: { props: z.object({ title: z.string() }), description: "Login form" },
+		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+	},
+});
 
-## Usage
+export type Catalog = typeof catalog;
+```
 
 ```vue
+<!-- Login.vue — Vue SFC; useBoundProp works in <script setup> -->
 <script setup lang="ts">
-import { PlayRenderer } from "@xmachines/play-vue";
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
+import { useBoundProp } 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] = useBoundProp<string>(bindings?.username ?? "/username");
+</script>
+
+<template>
+	<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>
+```
 
-// Define catalog
-const catalog = defineCatalog({
-	home: { component: "Home", props: { title: "string" } },
-	login: { component: "Login", props: { error: "string?" } },
-	dashboard: { component: "Dashboard", props: { userId: "string" } },
+```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";
+
+export const registryResult = defineRegistry(catalog, {
+	components: { Login: LoginSFC, Dashboard: DashboardSFC },
+	actions: {
+		login: async (params) => {
+			if (!params) return;
+			actor.send({ type: "auth.login", username: params.username });
+		},
+		logout: async (params) => {
+			actor.send({ type: "auth.logout" });
+		},
+	},
 });
+```
 
-// Create actor
-const actor = definePlayer({ machine: authMachine, catalog })();
-actor.start();
+```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;
+			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: {
+						root: "root",
+						elements: {
+							root: { type: "Login", props: { title: "Sign In" }, children: [] },
+						},
+					},
+				},
+			},
+			dashboard: {
+				id: "dashboard",
+				meta: {
+					route: "/dashboard",
+					view: {
+						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 }),
+			},
+		},
+	}),
+);
+```
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { definePlayer } from "@xmachines/play-xstate";
+import { PlayUIProvider, PlayRenderer } from "@xmachines/play-vue";
+import { machine } from "./machine.js";
+import { registryResult } from "./registry.js";
 
-// Define component map
-const components = {
-	Home: HomeComponent,
-	Login: LoginComponent,
-	Dashboard: DashboardComponent,
-};
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
 </script>
 
 <template>
-	<PlayRenderer :actor="actor" :components="components">
-		<template #fallback>
-			<div>Loading...</div>
-		</template>
-	</PlayRenderer>
+	<PlayUIProvider :actor="actor" :registryResult="registryResult">
+		<PlayRenderer />
+	</PlayUIProvider>
 </template>
 ```
 
-## API
+## API Reference
 
-### PlayRenderer
+### `PlayUIProvider`
 
-Main renderer component that observes `actor.currentView` signal and dynamically renders catalog components.
+Batteries-included composite provider. Wraps `ActorProvider` + `JSONUIProvider`. Pass `actor` and `registryResult` here, then place `<PlayRenderer />` inside as a zero-prop child.
 
-**Props:**
+```vue
+<PlayUIProvider
+	:actor="actor"
+	:registryResult="registryResult"
+	:store="myStore"
+	:onRenderError="(error, elementType) => console.warn(`<${elementType}> crashed:`, error)"
+>
+	<template #fallback><p>Something went wrong.</p></template>
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-- `actor` (required) - Actor instance with `currentView` signal
-- `components` (required) - Map of component names to Vue components
-- `fallback` (optional) - Slot shown when `currentView` is null
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-**Component Props:**
+**`registryResult`** — The full `DefineRegistryResult` returned by `defineRegistry(catalog, { components, actions })` from `@xmachines/play-vue`. Pass `.vue` SFCs directly — they are auto-wrapped via `h(SFC, ctx)` so `useBoundProp` and other composables work inside `<script setup>`.
 
-Each rendered component receives:
+**`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
 
-- All props from `view.props` (spread via `v-bind`)
-- `send` function for sending events to actor
+- **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.
 
-**Example Component:**
+```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: "" }) });
+```
 
 ```vue
-<script setup lang="ts">
-import type { AbstractActor } from "@xmachines/play-actor";
+<PlayUIProvider :actor="actor" :registryResult="registryResult" :store="store">
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-defineProps<{
-	userId: string;
-	send: AbstractActor<any>["send"];
-}>();
+**`onRenderError`** — Called when an individual catalog component throws during render. Caught by `@json-render/vue`'s inner per-element error boundary — the failed component is silently removed while the rest of the spec continues rendering. When both `onRenderError` on `PlayUIProvider` and on `defineRegistry` are set, the prop wins.
 
-function handleClick() {
-	send({ type: "user.click", payload: { action: "details" } });
-}
-</script>
+---
 
-<template>
-	<div>
-		<h1>User: {{ userId }}</h1>
-		<button @click="handleClick">View Details</button>
-	</div>
-</template>
+### `ActorProvider`
+
+Escape hatch primitive. Owns actor bridging, signal bridge, and store lifecycle. Use this when you need direct control over the provider layer.
+
+```vue
+<ActorProvider :actor="actor" :registryResult="registryResult" :onRenderError="handleError">
+	<!-- your own JSONUIProvider + PlayRenderer tree -->
+</ActorProvider>
+```
+
+---
+
+### `PlayRenderer`
+
+Zero-prop leaf component. Must be rendered inside a `PlayUIProvider` (or `ActorProvider`) tree. Subscribes to `actor.currentView` via context and renders the current spec.
+
+```vue
+<PlayUIProvider :actor="actor" :registryResult="registryResult">
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
-## Features
+`PlayRenderer` accepts no props — all configuration (`actor`, `registryResult`, `store`, `fallback`, `onRenderError`) is provided by the enclosing `PlayUIProvider` or `ActorProvider`.
 
-- **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
+## Error handling
 
-## Canonical Watcher Lifecycle
+The provider tree has two layers of error boundaries:
 
-Use the same watcher flow as other adapters/packages:
+### Outer boundary — `fallback` slot
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. read actor signals and update framework-local state
-5. re-arm with `watch(...)` or `watch()`
+Vue's `onErrorCaptured` wraps the entire renderer. Triggered when the spec or store setup throws, or when the inner boundary is not present. Use Vue's built-in `onErrorCaptured` in a parent component for observability.
 
-Watcher notify is one-shot. Re-arm is required for continuous observation.
+```vue
+<PlayUIProvider :actor="actor" :registryResult="registryResult">
+	<template #fallback>
+		<p>Something went wrong.</p>
+	</template>
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-## Cleanup Contract
+### Inner boundary — `onRenderError`
 
-Cleanup must be explicit:
+Each catalog element is individually wrapped in an error boundary by `@json-render/vue`. When a component throws, it is silently removed while the rest of the spec continues rendering. The outer boundary is **not** triggered.
 
-- 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.
+Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`:
 
-## Architecture
+```vue
+<!-- via PlayUIProvider prop -->
+<PlayUIProvider
+	:actor="actor"
+	:registryResult="registryResult"
+	:onRenderError="(error, elementType) => console.warn(`<${elementType}> crashed:`, error)"
+>
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-PlayRenderer follows the XMachines Play architecture principles:
+```ts
+// via defineRegistry — bakes the handler into the registry
+const registryResult = defineRegistry(catalog, {
+	components: { Login: LoginSFC, Dashboard: DashboardSFC },
+	actions: { login: async (params) => { ... }, logout: async () => { ... } },
+	onRenderError(error, elementType) {
+		reportExpectedRenderError(error, elementType);
+	},
+});
+```
+
+`onRenderError` is typed as `RenderErrorHandler` and exported from `@xmachines/play-vue`.
+
+---
+
+### `useActor`
+
+Vue composable for accessing the actor from inside any component rendered by `PlayRenderer`.
+
+```ts
+import { useActor } from "@xmachines/play-vue";
+
+// Inside any component rendered inside PlayRenderer:
+const actor = useActor();
+actor.send({ type: "auth.logout" });
+```
+
+Throws `NonNullableError: "useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)"` if called outside the tree.
+
+---
+
+## Route Parameters in Props
+
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
+
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.params = { 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 `useBoundProp` 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 `useBoundProp` and Vue composables work correctly

package/dist/ActorProvider.js

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

package/dist/ActorProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.js","names":[],"sources":["../src/ActorProvider.vue"],"sourcesContent":["<script lang=\"ts\">\n/**\n * ActorProvider — escape-hatch primitive for the XMachines Vue render architecture.\n *\n * Owns the full actor lifecycle:\n * - Signal subscription (watchSignal) bridging TC39 Signals to Vue reactivity\n * - Per-view StateStore lifecycle (controlled/uncontrolled)\n * - Handler resolution via ActorProviderInner (must be inside StateProvider)\n * - ViewContextValue provision via ViewKey injection key\n * - ActionProvider + VisibilityProvider wrapping for downstream Renderer\n * - onRenderError injection into registry\n *\n * Library authors who need fine-grained control use this directly.\n * End users should use <PlayUIProvider> instead.\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, markRaw, onUnmounted, h, provide, shallowRef } from \"vue\";\nimport type { PropType } from \"vue\";\nimport { watchSignal } from \"@xmachines/play-signals\";\nimport type { AbstractActor, Viewable, PlaySpec } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\nimport type { DefineRegistryResult, SetState, RenderErrorHandler } from \"@json-render/vue\";\n\nimport { StateProvider, useStateStore, ActionProvider, VisibilityProvider } from \"@json-render/vue\";\nimport type { StateStore } from \"@json-render/core\";\nimport { createAtom } from \"@xstate/store\";\nimport { xstateStoreStateStore } from \"@json-render/xstate\";\nimport { provideActor, type PlayActor } from \"./useActor.js\";\nimport { ViewKey, type ViewContextValue } from \"./actor-provider-context.js\";\nimport type { ActorProviderProps } from \"./types.js\";\n\n// Re-export props type and context accessors for consumers who import from this file\nexport type { ActorProviderProps } from \"./types.js\";\nexport { getPlayViewContext } from \"./actor-provider-context.js\";\nexport type { ViewContextValue } from \"./actor-provider-context.js\";\n\n// ---------------------------------------------------------------------------\n// ActorProviderInner — renders inside StateProvider to call useStateStore()\n// Provides ViewContextValue + ActionProvider + VisibilityProvider for downstream Renderer.\n// ---------------------------------------------------------------------------\n\nconst ActorProviderInner = defineComponent({\n\tname: \"ActorProviderInner\",\n\tprops: {\n\t\tregistryResult: {\n\t\t\ttype: Object as PropType<DefineRegistryResult>,\n\t\t\trequired: true,\n\t\t},\n\t\tspec: {\n\t\t\ttype: Object as PropType<PlaySpec | null>,\n\t\t\tdefault: null,\n\t\t},\n\t\tstore: {\n\t\t\ttype: Object as PropType<StateStore>,\n\t\t\trequired: true,\n\t\t},\n\t},\n\tsetup(props, { slots }) {\n\t\t// Use shallowRef for the view context value to avoid deep reactivity overhead.\n\t\t// The Proxy below allows inject() to always read the latest value.\n\t\tconst viewRef = shallowRef<ViewContextValue | null>(null);\n\n\t\t// Provide the ViewContextValue via Vue's inject/provide system.\n\t\t// Called synchronously in setup() so Vue registers it on the component instance.\n\t\t// Uses Proxy so descendants always receive the latest viewRef.value.\n\t\tprovide(\n\t\t\tViewKey,\n\t\t\tnew Proxy({} as ViewContextValue, {\n\t\t\t\tget(_target, prop: string) {\n\t\t\t\t\treturn viewRef.value?.[prop as keyof ViewContextValue];\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\n\t\t// Call useStateStore() at setup() time (synchronous, before return).\n\t\t// Vue composables that use inject() must be called during setup(), not in a render function.\n\t\tconst { update, getSnapshot } = useStateStore();\n\n\t\t// Build a SetState adapter: handlers factory expects updater-function pattern\n\t\tconst setStateAdapter: SetState = (updater) => {\n\t\t\tconst prev = getSnapshot();\n\t\t\tupdate(updater(prev));\n\t\t};\n\n\t\treturn () => {\n\t\t\tif (!props.spec) {\n\t\t\t\tviewRef.value = null;\n\t\t\t\treturn slots.default?.() ?? null;\n\t\t\t}\n\n\t\t\tconst handlers = props.registryResult.handlers(\n\t\t\t\t() => setStateAdapter,\n\t\t\t\t() => getSnapshot(),\n\t\t\t);\n\n\t\t\tviewRef.value = {\n\t\t\t\tspec: props.spec,\n\t\t\t\thandlers,\n\t\t\t\tregistry: props.registryResult.registry,\n\t\t\t\tstore: props.store,\n\t\t\t};\n\n\t\t\t// Wrap with ActionProvider + VisibilityProvider so PlayRenderer's Renderer works\n\t\t\t// even when ActorProvider is used directly (without PlayUIProvider / JSONUIProvider)\n\t\t\treturn h(ActionProvider, { handlers }, () =>\n\t\t\t\th(VisibilityProvider, {}, () => slots.default?.() ?? null),\n\t\t\t);\n\t\t};\n\t},\n});\n\n// ---------------------------------------------------------------------------\n// ActorProvider — main export\n// ---------------------------------------------------------------------------\n\nexport default defineComponent({\n\tname: \"ActorProvider\",\n\tprops: {\n\t\tactor: {\n\t\t\ttype: Object as PropType<ActorProviderProps[\"actor\"]>,\n\t\t\trequired: true,\n\t\t},\n\t\tregistryResult: {\n\t\t\ttype: Object as PropType<DefineRegistryResult>,\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\tonRenderError: {\n\t\t\ttype: Function as PropType<RenderErrorHandler>,\n\t\t\tdefault: undefined,\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\tconst actor = toRaw(props.actor as AbstractActor<AnyActorLogic> & Viewable);\n\n\t\t// Unwrap the registryResult and mark components as raw to avoid Vue reactivity overhead\n\t\tconst rawRegistryResult: DefineRegistryResult = {\n\t\t\t...toRaw(props.registryResult),\n\t\t\tregistry: markRaw(\n\t\t\t\tObject.fromEntries(\n\t\t\t\t\tObject.entries(toRaw(props.registryResult).registry).map(([k, v]) => [\n\t\t\t\t\t\tk,\n\t\t\t\t\t\tmarkRaw(v as object),\n\t\t\t\t\t]),\n\t\t\t\t) as DefineRegistryResult[\"registry\"],\n\t\t\t),\n\t\t};\n\n\t\t// Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)\n\t\tif (props.onRenderError) {\n\t\t\tObject.defineProperty(rawRegistryResult.registry, \"onRenderError\", {\n\t\t\t\tvalue: props.onRenderError,\n\t\t\t\tenumerable: false,\n\t\t\t\tconfigurable: true,\n\t\t\t});\n\t\t}\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// Seed initial value then subscribe — both synchronous, no scheduler gap.\n\t\t// This mirrors the atomic seed+watch pattern used in Solid (createEffect)\n\t\t// and Svelte ($effect) for cross-framework consistency.\n\t\tconst view = ref<PlaySpec | null>(actor.currentView.get());\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: PlaySpec | null = null;\n\t\t// storeKey is only incremented in the internalStore branch (not when props.store is set)\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\treturn () => {\n\t\t\t// No view — show fallback slot or nothing\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;\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\t// T-37-04-02: Proper proto-safe guard for spec.state\n\t\t\t\t\tconst rawState = spec.state;\n\t\t\t\t\tconst initialState: Record<string, unknown> =\n\t\t\t\t\t\trawState !== null &&\n\t\t\t\t\t\ttypeof rawState === \"object\" &&\n\t\t\t\t\t\t!Array.isArray(rawState) &&\n\t\t\t\t\t\t(Object.getPrototypeOf(rawState) === Object.prototype ||\n\t\t\t\t\t\t\tObject.getPrototypeOf(rawState) === null)\n\t\t\t\t\t\t\t? (rawState as Record<string, unknown>)\n\t\t\t\t\t\t\t: {};\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// ActorProviderInner renders inside StateProvider so useStateStore() works\n\t\t\treturn h(StateProvider, { store, key: storeKey }, () =>\n\t\t\t\th(ActorProviderInner, { registryResult: rawRegistryResult, spec, store }, slots),\n\t\t\t);\n\t\t};\n\t},\n});\n</script>\n"],"mappings":""}

package/dist/ActorProvider.vue.d.ts

@@ -0,0 +1,51 @@
+import { PropType } from 'vue';
+import { DefineRegistryResult, RenderErrorHandler } from '@json-render/vue';
+import { StateStore } from '@json-render/core';
+import { ActorProviderProps } from './types.js';
+export type { ActorProviderProps } from './types.js';
+export { getPlayViewContext } from './actor-provider-context.js';
+export type { ViewContextValue } from './actor-provider-context.js';
+declare const _default: import('vue', { with: { "resolution-mode": "import" } }).DefineComponent<import('vue', { with: { "resolution-mode": "import" } }).ExtractPropTypes<{
+    actor: {
+        type: PropType<ActorProviderProps["actor"]>;
+        required: true;
+    };
+    registryResult: {
+        type: PropType<DefineRegistryResult>;
+        required: true;
+    };
+    store: {
+        type: PropType<StateStore>;
+        default: undefined;
+    };
+    onRenderError: {
+        type: PropType<RenderErrorHandler>;
+        default: undefined;
+    };
+}>, () => import('vue', { with: { "resolution-mode": "import" } }).VNode<import('vue', { with: { "resolution-mode": "import" } }).RendererNode, import('vue', { with: { "resolution-mode": "import" } }).RendererElement, {
+    [key: string]: any;
+}> | import('vue', { with: { "resolution-mode": "import" } }).VNode<import('vue', { with: { "resolution-mode": "import" } }).RendererNode, import('vue', { with: { "resolution-mode": "import" } }).RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, import('vue', { with: { "resolution-mode": "import" } }).ComponentOptionsMixin, import('vue', { with: { "resolution-mode": "import" } }).ComponentOptionsMixin, {}, string, import('vue', { with: { "resolution-mode": "import" } }).PublicProps, Readonly<import('vue', { with: { "resolution-mode": "import" } }).ExtractPropTypes<{
+    actor: {
+        type: PropType<ActorProviderProps["actor"]>;
+        required: true;
+    };
+    registryResult: {
+        type: PropType<DefineRegistryResult>;
+        required: true;
+    };
+    store: {
+        type: PropType<StateStore>;
+        default: undefined;
+    };
+    onRenderError: {
+        type: PropType<RenderErrorHandler>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    store: StateStore;
+    onRenderError: RenderErrorHandler;
+}, {}, {}, {}, string, import('vue', { with: { "resolution-mode": "import" } }).ComponentProvideOptions, true, {}, any>;
+export default _default;
+//# sourceMappingURL=ActorProvider.vue.d.ts.map

package/dist/ActorProvider.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.vue.d.ts","sourceRoot":"","sources":["../src/ActorProvider.vue"],"names":[],"mappings":"AAyPA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAIpC,OAAO,KAAK,EAAE,oBAAoB,EAAY,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAKpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;;;cAqFjD,QAAQ,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;;;;cAIrC,QAAQ,CAAC,oBAAoB,CAAC;;;;cAI9B,QAAQ,CAAC,UAAU,CAAC;;;;cAIlB,QAAQ,CAAC,kBAAkB,CAAC;;;;;;;;;cAZ9B,QAAQ,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;;;;cAIrC,QAAQ,CAAC,oBAAoB,CAAC;;;;cAI9B,QAAQ,CAAC,UAAU,CAAC;;;;cAIlB,QAAQ,CAAC,kBAAkB,CAAC;;;;;;;AAhBjD,wBA0GG"}

package/dist/ActorProvider.vue_vue_type_script_lang.js

@@ -0,0 +1,104 @@
+import { ViewKey as e } from "./actor-provider-context.js";
+import { provideActor as t } from "./useActor.js";
+import { defineComponent as n, h as r, markRaw as i, onUnmounted as a, provide as o, ref as s, shallowRef as c, toRaw as l } from "vue";
+import { ActionProvider as u, StateProvider as d, VisibilityProvider as f, useStateStore as p } from "@json-render/vue";
+import { watchSignal as m } from "@xmachines/play-signals";
+import { createAtom as h } from "@xstate/store";
+import { xstateStoreStateStore as g } from "@json-render/xstate";
+//#region src/ActorProvider.vue?vue&type=script&lang.ts
+var _ = n({
+	name: "ActorProviderInner",
+	props: {
+		registryResult: {
+			type: Object,
+			required: !0
+		},
+		spec: {
+			type: Object,
+			default: null
+		},
+		store: {
+			type: Object,
+			required: !0
+		}
+	},
+	setup(t, { slots: n }) {
+		let i = c(null);
+		o(e, new Proxy({}, { get(e, t) {
+			return i.value?.[t];
+		} }));
+		let { update: a, getSnapshot: s } = p(), l = (e) => {
+			a(e(s()));
+		};
+		return () => {
+			if (!t.spec) return i.value = null, n.default?.() ?? null;
+			let e = t.registryResult.handlers(() => l, () => s());
+			return i.value = {
+				spec: t.spec,
+				handlers: e,
+				registry: t.registryResult.registry,
+				store: t.store
+			}, r(u, { handlers: e }, () => r(f, {}, () => n.default?.() ?? null));
+		};
+	}
+}), v = n({
+	name: "ActorProvider",
+	props: {
+		actor: {
+			type: Object,
+			required: !0
+		},
+		registryResult: {
+			type: Object,
+			required: !0
+		},
+		store: {
+			type: Object,
+			default: void 0
+		},
+		onRenderError: {
+			type: Function,
+			default: void 0
+		}
+	},
+	setup(e, { slots: n }) {
+		let o = l(e.actor), c = {
+			...l(e.registryResult),
+			registry: i(Object.fromEntries(Object.entries(l(e.registryResult).registry).map(([e, t]) => [e, i(t)])))
+		};
+		e.onRenderError && Object.defineProperty(c.registry, "onRenderError", {
+			value: e.onRenderError,
+			enumerable: !1,
+			configurable: !0
+		}), t(o);
+		let u = s(o.currentView.get()), f = null, p = null, v = 0, y = m(o.currentView, (e) => {
+			u.value = e;
+		});
+		return a(() => {
+			y();
+		}), () => {
+			if (!u.value) return n.fallback ? n.fallback() : null;
+			let t = u.value, i;
+			if (e.store) i = e.store;
+			else {
+				if (f === null || p !== u.value) {
+					let e = t.state;
+					f = g({ atom: h(typeof e == "object" && e && !Array.isArray(e) && (Object.getPrototypeOf(e) === Object.prototype || Object.getPrototypeOf(e) === null) ? e : {}) }), p = u.value, v++;
+				}
+				i = f;
+			}
+			return r(d, {
+				store: i,
+				key: v
+			}, () => r(_, {
+				registryResult: c,
+				spec: t,
+				store: i
+			}, n));
+		};
+	}
+});
+//#endregion
+export { v as default };
+
+//# sourceMappingURL=ActorProvider.vue_vue_type_script_lang.js.map