@xmachines/play-vue 1.0.0-beta.8 → 1.0.0

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,280 +1,209 @@
-# @xmachines/play-vue
+<!-- generated-by: gsd-doc-writer -->
 
-**Vue renderer consuming signals and UI schema with provider pattern**
+# `@xmachines/play-vue`
 
-Signal-driven Vue rendering layer observing actor state with zero Vue state for business logic.
+> Vue 3 renderer for the XMachines Play Architecture — passively observes actor signals and renders UI via `@xmachines/json-render-vue`.
 
-## Overview
+Part of the [XMachines Play monorepo](../../README.md).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0--beta.51-blue.svg)](package.json)
 
-`@xmachines/play-vue` provides `PlayRenderer` for building Vue 3 UIs that passively observe actor signals. This package enables framework-swappable architecture where Vue is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+---
+
+## Overview
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+`@xmachines/play-vue` is the Vue 3 rendering layer for XMachines Play. It bridges TC39 Signals (actor state) to Vue reactivity and drives component rendering through `@xmachines/json-render-vue`.
 
-- **Signal-Only Reactivity (INV-05):** No refs/reactive for business logic, TC39 signals only
-- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+**Architecture invariants this package upholds:**
 
-**Key Principle:** Vue state is never used for business logic. Signals are the source of truth.
+- **Passive Infrastructure** — Components observe actor signals; they never decide state transitions.
+- **Signal-Only Reactivity** — TC39 Signals are the source of truth; Vue reactivity is used only to trigger re-renders.
+- **Actor Authority** — The actor controls view selection; the renderer reflects it.
 
-Renderer receives actor via props (provider pattern), not children.
+---
 
 ## Installation
 
 ```bash
-npm install vue@^3.0.0
-npm install @xmachines/play-vue
+pnpm add @xmachines/play-vue
 ```
 
-## Current Exports
+**Peer dependencies** (install alongside):
 
-- `PlayRenderer` (Vue component)
-- `PlayRendererProps` (TypeScript interface)
-
-**Peer dependencies:**
+```bash
+pnpm add vue@^3.5.0 xstate@^5.31.0 @xstate/store@^3.17.0 @xmachines/json-render-vue@^0.18.0 @xmachines/json-render-core@^0.18.0 @xmachines/json-render-xstate@^0.18.0
+```
 
-- `vue` ^3.0.0 - Vue 3 runtime
+---
 
 ## Quick Start
 
 ```vue
 <!-- App.vue -->
+<template>
+	<PlayUIProvider :actor="actor" :registryResult="registryResult">
+		<PlayRenderer />
+	</PlayUIProvider>
+</template>
+
 <script setup lang="ts">
+import { defineRegistry, PlayUIProvider, PlayRenderer } from "@xmachines/play-vue";
 import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-vue";
-import { z } from "zod";
-import LoginForm from "./components/LoginForm.vue";
-import Dashboard from "./components/Dashboard.vue";
-
-// 1. Define catalog (business logic layer)
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({
-		userId: z.string(),
-		username: z.string(),
-	}),
-});
-
-// 2. Define component map (view layer)
-const components = {
-	LoginForm,
-	Dashboard,
-};
+import { myMachine } from "./machine.js";
+import { myCatalog } from "./catalog.js";
+import HomeSFC from "./views/Home.vue";
+import LoginSFC from "./views/Login.vue";
 
-// 3. Create player actor (business logic runtime)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
+const createPlayer = definePlayer({ machine: myMachine });
 const actor = createPlayer();
 actor.start();
-</script>
 
-<template>
-	<!-- 4. Render UI (actor via props) -->
-	<PlayRenderer :actor="actor" :components="components">
-		<template #fallback>
-			<div>Loading...</div>
-		</template>
-	</PlayRenderer>
-</template>
+const registryResult = defineRegistry(myCatalog, {
+	components: {
+		Home: HomeSFC, // .vue SFCs are auto-wrapped
+		Login: LoginSFC,
+	},
+	actions: {
+		login: async (args) => actor.send({ type: "auth.login", ...args }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+</script>
 ```
 
-## API Reference
+---
 
-### PlayRenderer
+## API Summary
 
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+### Components
 
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<any>;
-	components: Record<string, Component>;
-}
-```
+#### `<PlayUIProvider>`
 
-**Props:**
+Batteries-included composite provider. Wraps `<ActorProvider>` and `JSONUIProvider` in one component. **Recommended for most apps.**
 
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to Vue components
+| Prop                  | Type                       | Required | Description                                 |
+| --------------------- | -------------------------- | -------- | ------------------------------------------- |
+| `actor`               | `AbstractActor & Viewable` | ✅       | The XMachines actor instance                |
+| `registryResult`      | `DefineRegistryResult`     | ✅       | Result of `defineRegistry()`                |
+| `store`               | `StateStore`               | —        | External controlled state store (optional)  |
+| `onRenderError`       | `RenderErrorHandler`       | —        | Error handler for render failures           |
+| `navigate`            | `(path: string) => void`   | —        | Link navigation function                    |
+| `validationFunctions` | `Record<string, Function>` | —        | Custom validation functions                 |
+| `functions`           | `Record<string, Function>` | —        | Named functions for `$computed` expressions |
 
-**Slots:**
+**Slots:** `default` (rendered content), `fallback` (shown while actor view is `null`)
 
-- `fallback` - Slot shown when `currentView` is null
+#### `<PlayRenderer>`
 
-**Behavior:**
+Zero-prop leaf component. Reads the current `spec` and `registry` from the nearest `<ActorProvider>` or `<PlayUIProvider>` context and renders via `<Renderer>`. Must be placed inside one of those providers.
 
-1. Subscribes to `actor.currentView` signal using a `Signal.subtle.Watcher` inside a Vue component
-2. Looks up component from `components` map using `view.component` string
-3. Renders component with props from `view.props` + `send` function via Vue's dynamic `<component :is="..."/>`
+```vue
+<PlayUIProvider :actor="actor" :registryResult="registryResult">
+  <PlayRenderer />
+</PlayUIProvider>
+```
 
-**Example Component (LoginForm.vue):**
+#### `<ActorProvider>`
 
-```vue
-<script setup lang="ts">
-import type { AbstractActor } from "@xmachines/play-actor";
-import { ref } from "vue";
-
-const props = defineProps<{
-	error?: string;
-	send: AbstractActor<any>["send"];
-}>();
-
-const username = ref("");
-
-function handleSubmit() {
-	props.send({
-		type: "auth.login",
-		username: username.value,
-	});
-}
-</script>
+Low-level escape hatch for custom provider composition. Owns the full actor lifecycle — signal subscription, per-view state store, handler resolution, and Vue context provision. Use `<PlayUIProvider>` unless you need fine-grained control.
 
-<template>
-	<form @submit.prevent="handleSubmit">
-		<p v-if="error" style="color: red">{{ error }}</p>
-		<input v-model="username" required placeholder="Username" />
-		<button type="submit">Log In</button>
-	</form>
-</template>
-```
+| Prop             | Type                       | Required | Description                     |
+| ---------------- | -------------------------- | -------- | ------------------------------- |
+| `actor`          | `AbstractActor & Viewable` | ✅       | The XMachines actor instance    |
+| `registryResult` | `DefineRegistryResult`     | ✅       | Result of `defineRegistry()`    |
+| `store`          | `StateStore`               | —        | External controlled state store |
+| `onRenderError`  | `RenderErrorHandler`       | —        | Override render error handler   |
 
-## Examples
+---
 
-### Provider Pattern
+### Functions
 
-```vue
-<!-- App.vue -->
-<script setup lang="ts">
-import { PlayVueRouterProvider } from "@xmachines/play-vue-router";
-import { PlayRenderer } from "@xmachines/play-vue";
-import { provide } from "vue";
-import Header from "./components/Header.vue";
-import Footer from "./components/Footer.vue";
-
-// Provide actor to nested components like Header
-provide("actor", actor);
-</script>
+#### `defineRegistry(catalog, options)`
 
-<template>
-	<PlayVueRouterProvider :actor="actor" :router="router" :routeMap="routeMap">
-		<template #default="{ currentActor, currentRouter }">
-			<div>
-				<Header />
-				<PlayRenderer :actor="currentActor" :components="components" />
-				<Footer />
-			</div>
-		</template>
-	</PlayVueRouterProvider>
-</template>
-```
+Drop-in replacement for `defineRegistry` from `@xmachines/json-render-vue`. **Always import from `@xmachines/play-vue`** rather than `@xmachines/json-render-vue` when working with Vue SFCs — this wrapper automatically detects `.vue` SFCs in the `components` map and wraps them via `h()` so Vue composables (including `inject`-based ones) work correctly inside `<script setup>`.
 
-```vue
-<!-- Header.vue -->
-<script setup lang="ts">
-import { inject, ref, onMounted, onUnmounted } from "vue";
-import type { AbstractActor } from "@xmachines/play-actor";
-
-const actor = inject<AbstractActor<any>>("actor")!;
-const route = ref<string | null>(null);
-
-let watcher: any;
-
-onMounted(() => {
-	let pending = false;
-	watcher = new Signal.subtle.Watcher(() => {
-		if (!pending) {
-			pending = true;
-			queueMicrotask(() => {
-				pending = false;
-				for (const s of watcher.getPending()) s.get();
-				route.value = actor.currentRoute.get();
-				watcher.watch(actor.currentRoute);
-			});
-		}
-	});
-	route.value = actor.currentRoute.get();
-	watcher.watch(actor.currentRoute);
+```typescript
+import { defineRegistry } from "@xmachines/play-vue";
+// NOT: import { defineRegistry } from "@xmachines/json-render-vue"
+
+import LoginSFC from "./views/Login.vue";
+import DashboardSFC from "./views/Dashboard.vue";
+
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Login: LoginSFC, // .vue SFC — auto-wrapped via h()
+		Dashboard: DashboardSFC,
+	},
+	actions: {
+		login: async (args, setState, getState) => {
+			/* ... */
+		},
+	},
 });
+```
 
-onUnmounted(() => {
-	if (watcher) watcher.unwatch(actor.currentRoute);
-});
-</script>
+Plain `ComponentFn` functions (non-SFC) also work and are passed through unchanged. Mixing SFCs and plain functions in the same registry is supported.
 
-<template>
-	<header>
-		<nav>Current: {{ route }}</nav>
-	</header>
-</template>
+#### `useActor()`
+
+Vue composable for accessing the raw actor inside a `PlayRenderer` tree. Avoids prop drilling for deeply nested components.
+
+```typescript
+import { useActor } from "@xmachines/play-vue";
+
+// Inside a component rendered by PlayRenderer:
+const actor = useActor();
+actor.send({ type: "SUBMIT" });
 ```
 
-## Architecture
+Throws if called outside an `<ActorProvider>` or `<PlayUIProvider>` tree.
 
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+#### `getPlayViewContext()`
 
-1. **No Business Logic in Vue:**
-    - No ref/reactive for business state
-    - No watch/watchEffect for business side effects
-    - Vue only triggers renders, doesn't control state
+Access the current `ViewContextValue` — `{ spec, handlers, registry, store }` — from inside an `<ActorProvider>` tree.
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via explicit watcher patterns
+```typescript
+import { getPlayViewContext } from "@xmachines/play-vue";
 
-3. **Event Forwarding:**
-    - Components receive `send` function via props
-    - User actions send events to actor (e.g., `{ type: "auth.login" }`)
-    - Actor guards validate and process events
+// Inside setup() of a component within an ActorProvider tree:
+const view = getPlayViewContext();
+// view.spec, view.handlers, view.registry, view.store
+```
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents Vue thrashing from multiple signal updates
-    - Single Vue render per microtask batch
+---
 
-5. **Explicit Disposal Contract:**
-    - Component teardown calls watcher `unwatch` in `onUnmounted`
-    - Do not rely on GC-only cleanup
+### Re-exported from `@xmachines/json-render-vue`
 
-**Pattern:**
+The following are re-exported so consumers import everything from `@xmachines/play-vue`:
 
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
+**Components:** `JSONUIProvider`, `StateProvider`, `ActionProvider`, `VisibilityProvider`, `ValidationProvider`, `Renderer`
 
-**Architectural Invariants:**
+**Composables:** `useBoundProp`
 
-- **Signal-Only Reactivity (INV-05):** No Vue state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+**Types:** `JSONUIProviderProps`, `StateProviderProps`, `ActionProviderProps`, `ValidationProviderProps`, `RendererProps`, `ComponentFn`, `ComponentContext`, `DefineRegistryResult`
 
-## Canonical Watcher Lifecycle
+---
 
-If you write your own custom integration, use the same watcher flow as `PlayRenderer`:
+## Testing
 
-1. `notify` callback runs
-2. Schedule work with `queueMicrotask`
-3. Drain `watcher.getPending()`
-4. Read actor signals and update Vue-local ref state
-5. Re-arm with `watch(...)` or `watch()`
+Run tests for this package in isolation:
 
-Watcher notify is one-shot. Re-arm is required for continuous observation.
+```bash
+# From the monorepo root
+pnpm --filter @xmachines/play-vue test
 
-## Benefits
+# Watch mode
+pnpm --filter @xmachines/play-vue run test:watch
 
-- **Framework Swappable:** Business logic has zero Vue imports
-- **Type Safety:** Props validated against catalog schemas
-- **Simple Testing:** Test actors without Vue renderer
-- **Performance:** Microtask batching reduces unnecessary renders
-- **Composability:** Renderer prop enables complex layouts
+# With coverage (80% threshold enforced on lines, functions, branches, statements)
+pnpm exec vitest run --coverage --config packages/play-vue/vitest.config.ts
+```
 
-## Related Packages
+Tests use [Vitest](https://vitest.dev/) with `jsdom` environment and `@vue/test-utils` for component mounting.
 
-- **[@xmachines/play-xstate](../play-xstate)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
-- **[@xmachines/play-vue-router](../play-vue-router)** - Vue Router integration
-- **[@xmachines/play-actor](../play-actor)** - Actor base
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
+---
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE).

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 {\n\tdefineComponent,\n\tref,\n\tcomputed,\n\ttoRaw,\n\tmarkRaw,\n\tonUnmounted,\n\th,\n\tprovide,\n\tshallowRef,\n\twatch,\n} from \"vue\";\nimport type { PropType } from \"vue\";\nimport { watchSignal } from \"@xmachines/play-signals\";\nimport { toAtomState, attachRenderErrorHandler } from \"@xmachines/play-actor\";\nimport type { AbstractActor, Viewable, PlaySpec } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\nimport type {\n\tDefineRegistryResult,\n\tSetState,\n\tRenderErrorHandler,\n} from \"@xmachines/json-render-vue\";\n\nimport {\n\tStateProvider,\n\tuseStateStore,\n\tActionProvider,\n\tVisibilityProvider,\n} from \"@xmachines/json-render-vue\";\nimport type { StateStore } from \"@xmachines/json-render-core\";\nimport { createAtom } from \"@xstate/store\";\nimport { xstateStoreStateStore } from \"@xmachines/json-render-xstate\";\nimport { provideActor, type AnyPlayActor } 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 stateStore = useStateStore();\n\n\t\t// Build a SetState adapter: handlers factory expects updater-function pattern.\n\t\t// Defined once in setup() — reads stateStore.getSnapshot/update at invocation\n\t\t// time so it always operates on the live store state without needing to be\n\t\t// recreated when stateStore identity changes across renders.\n\t\tconst setStateAdapter: SetState = (updater) => {\n\t\t\tconst prev = stateStore.getSnapshot();\n\t\t\tstateStore.update(updater(prev));\n\t\t};\n\n\t\t// Memoize handlers keyed to registryResult prop identity. The getter functions\n\t\t// are stable closures capturing stateStore from setup(), so they do not\n\t\t// contribute to invalidation. Handlers are only recomputed when the registry\n\t\t// definition itself changes — not on every render triggered by view updates.\n\t\tconst handlers = computed(() =>\n\t\t\tprops.registryResult.handlers(\n\t\t\t\t() => setStateAdapter,\n\t\t\t\t() => stateStore.getSnapshot(),\n\t\t\t),\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\tviewRef.value = {\n\t\t\t\tspec: props.spec,\n\t\t\t\thandlers: handlers.value,\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: handlers.value }, () =>\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\t// Held in a shallowRef so the provided injection and the signal watcher\n\t\t// can follow `props.actor` when the prop swaps after mount.\n\t\tconst actorRef = shallowRef(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 rawRegistry = Object.fromEntries(\n\t\t\tObject.entries(toRaw(props.registryResult).registry).map(([k, v]) => [\n\t\t\t\tk,\n\t\t\t\tmarkRaw(v as object),\n\t\t\t]),\n\t\t) as DefineRegistryResult[\"registry\"];\n\n\t\t// Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level\n\t\t// handler). attachRenderErrorHandler clones — the caller's registry is never mutated.\n\t\t// The clone must be re-markRaw'd: markRaw's non-enumerable flag is not carried by the clone.\n\t\tconst rawRegistryResult: DefineRegistryResult = {\n\t\t\t...toRaw(props.registryResult),\n\t\t\tregistry: markRaw(\n\t\t\t\tprops.onRenderError\n\t\t\t\t\t? attachRenderErrorHandler(rawRegistry, props.onRenderError)\n\t\t\t\t\t: rawRegistry,\n\t\t\t),\n\t\t};\n\n\t\t// Provide the actor to all descendants via Vue's provide/inject mechanism.\n\t\t//\n\t\t// A stable Proxy (same pattern as ActorProviderInner's ViewKey proxy) is\n\t\t// provided instead of the raw actor so the injection tracks the CURRENT\n\t\t// `props.actor`: injectors keep the reference obtained at setup() time,\n\t\t// yet every trap resolves against the latest actor (actorRef.value) after a\n\t\t// prop swap. All relevant traps are forwarded so the proxy behaves like the\n\t\t// underlying actor for reads, writes, membership (`in`), enumeration\n\t\t// (Object.keys / spread), and prototype checks (`instanceof`). Methods are\n\t\t// bound to the current raw actor so `this` (including private fields) works\n\t\t// exactly as with a direct call.\n\t\t//\n\t\t// IMPORTANT: this proxy is NOT identity-equal to `props.actor` — it is a\n\t\t// distinct object, hence a distinct WeakMap key. Identity-keyed consumers —\n\t\t// notably RouterBridgeBase's one-bridge-per-actor guard, which keys a\n\t\t// module-level WeakMap on actor identity — must be handed the `props.actor`\n\t\t// value itself, never this injected proxy.\n\t\t//\n\t\t// Method identity: bound methods are cached per underlying method so repeated\n\t\t// reads return the SAME function (actor.send === actor.send — allocation-free\n\t\t// hot path). A read rebinds only when the underlying method changes; the cache\n\t\t// is CLEARED on actor swap (see the watch handler below) so prototype methods\n\t\t// rebind to the new actor.\n\t\tconst boundMethodCache = new Map<PropertyKey, { source: unknown; bound: unknown }>();\n\t\tprovideActor(\n\t\t\tnew Proxy({} as AnyPlayActor, {\n\t\t\t\tget(_target, prop) {\n\t\t\t\t\tconst current = actorRef.value;\n\t\t\t\t\tconst value = Reflect.get(current, prop, current) as unknown;\n\t\t\t\t\tif (typeof value !== \"function\") return value;\n\t\t\t\t\tconst cached = boundMethodCache.get(prop);\n\t\t\t\t\tif (cached && cached.source === value) return cached.bound;\n\t\t\t\t\tconst bound = (value as (...args: unknown[]) => unknown).bind(current);\n\t\t\t\t\tboundMethodCache.set(prop, { source: value, bound });\n\t\t\t\t\treturn bound;\n\t\t\t\t},\n\t\t\t\thas(_target, prop) {\n\t\t\t\t\treturn prop in actorRef.value;\n\t\t\t\t},\n\t\t\t\tset(_target, prop, value) {\n\t\t\t\t\treturn Reflect.set(actorRef.value, prop, value, actorRef.value);\n\t\t\t\t},\n\t\t\t\tdeleteProperty(_target, prop) {\n\t\t\t\t\treturn Reflect.deleteProperty(actorRef.value, prop);\n\t\t\t\t},\n\t\t\t\townKeys() {\n\t\t\t\t\treturn Reflect.ownKeys(actorRef.value);\n\t\t\t\t},\n\t\t\t\tgetOwnPropertyDescriptor(_target, prop) {\n\t\t\t\t\tconst desc = Reflect.getOwnPropertyDescriptor(actorRef.value, prop);\n\t\t\t\t\tif (!desc) return undefined;\n\t\t\t\t\t// Proxy invariant: the proxy target is an empty {}, so every key\n\t\t\t\t\t// reported via ownKeys must resolve to a configurable descriptor here\n\t\t\t\t\t// — otherwise the [[GetOwnProperty]] invariant throws (a non-existent\n\t\t\t\t\t// target property may not be reported as non-configurable). The actor's\n\t\t\t\t\t// own props are runtime-mutable anyway, so reporting configurable:true\n\t\t\t\t\t// is faithful enough for Object.keys / spread enumeration.\n\t\t\t\t\tdesc.configurable = true;\n\t\t\t\t\treturn desc;\n\t\t\t\t},\n\t\t\t\tgetPrototypeOf() {\n\t\t\t\t\treturn Reflect.getPrototypeOf(actorRef.value);\n\t\t\t\t},\n\t\t\t}) as AnyPlayActor,\n\t\t);\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>(actorRef.value.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\t// Re-assigned on actor swap so cleanup always releases the live watcher.\n\t\tlet unwatch = watchSignal(actorRef.value.currentView, (nextView) => {\n\t\t\tview.value = nextView;\n\t\t});\n\n\t\t// React to `props.actor` swaps: unsubscribe the OLD actor's currentView,\n\t\t// re-seed the view from the NEW actor synchronously (flush: \"sync\" — no\n\t\t// scheduler gap, matching the mount-time seed+watch pattern above), and\n\t\t// subscribe the new signal. The re-seeded view is a new object identity,\n\t\t// so the internal-store branch below rebuilds the store and bumps\n\t\t// storeKey exactly like a regular view transition.\n\t\twatch(\n\t\t\t() => toRaw(props.actor as AbstractActor<AnyActorLogic> & Viewable),\n\t\t\t(nextActor) => {\n\t\t\t\tif (nextActor === actorRef.value) return;\n\t\t\t\tunwatch();\n\t\t\t\tactorRef.value = nextActor;\n\t\t\t\t// Invalidate cached bound methods so prototype methods rebind to the\n\t\t\t\t// new actor on the next read (see the injected proxy's get trap).\n\t\t\t\tboundMethodCache.clear();\n\t\t\t\tview.value = nextActor.currentView.get();\n\t\t\t\tunwatch = watchSignal(nextActor.currentView, (nextView) => {\n\t\t\t\t\tview.value = nextView;\n\t\t\t\t});\n\t\t\t},\n\t\t\t{ flush: \"sync\" },\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\tinternalStore = xstateStoreStateStore({\n\t\t\t\t\t\tatom: createAtom(toAtomState(spec.state)),\n\t\t\t\t\t});\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 '@xmachines/json-render-vue';
+import { StateStore } from '@xmachines/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/runtime-core').DefineComponent<import('@vue/runtime-core').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/runtime-core').VNode<import('@vue/runtime-core').RendererNode, import('@vue/runtime-core').RendererElement, {
+    [key: string]: any;
+}> | import('@vue/runtime-core').VNode<import('@vue/runtime-core').RendererNode, import('@vue/runtime-core').RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, import('@vue/runtime-core').ComponentOptionsMixin, import('@vue/runtime-core').ComponentOptionsMixin, {}, string, import('@vue/runtime-core').PublicProps, Readonly<import('@vue/runtime-core').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<{}>, {
+    onRenderError: RenderErrorHandler;
+    store: StateStore;
+}, {}, {}, {}, string, import('@vue/runtime-core').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":"AAkXA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAKpC,OAAO,KAAK,EACX,oBAAoB,EAEpB,kBAAkB,EAClB,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAK9D,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;;;cA8FjD,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,wBA0LG"}