@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.18

package/api/@xmachines/play-vue/README.md

@@ -2,291 +2,301 @@
 
 # @xmachines/play-vue
 
-**Vue renderer consuming signals and UI schema with provider pattern**
+**Vue 3 renderer for XMachines Play Architecture**
 
-Signal-driven Vue rendering layer observing actor state with zero Vue state for business logic.
+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` 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.
+`@xmachines/play-vue` provides `PlayRenderer`, a Vue component that:
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+- 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)
 
-- **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
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md):
 
-**Key Principle:** Vue state is never used for business logic. Signals are the source of truth.
-
-Renderer receives actor via props (provider pattern), not children.
+- **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 vue@^3.5.0
 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)
-- `PlayRendererProps` (TypeScript interface)
-
-**Peer dependencies:**
-
-- `vue` ^3.5.0 — Vue 3 runtime
+- `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)
 
 ## Quick Start
 
-```vue
-<!-- App.vue -->
-<script setup lang="ts">
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-vue";
+```ts
+// catalog.ts — shared contract
+import { defineCatalog } from "@json-render/core";
 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,
-};
-
-// 3. Create player actor (business logic runtime)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
-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>
-```
-
-## API Reference
-
-### PlayRenderer
-
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+export const catalog = defineCatalog({
+	elements: {
+		Login: { props: z.object({ title: z.string() }), description: "Login form" },
+		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+	},
+});
 
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<any>;
-	components: Record<string, Component>;
-}
+export type Catalog = typeof catalog;
 ```
 
-**Props:**
-
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to Vue components
-
-**Slots:**
-
-- `fallback` - Slot shown when `currentView` is null
-
-**Behavior:**
-
-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="..."/>`
-
-**Example Component (LoginForm.vue):**
-
 ```vue
+<!-- Login.vue — Vue SFC; useStateBinding works in <script setup> -->
 <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,
-	});
-}
+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>
-	<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>
+	<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>
 ```
 
-## Examples
+```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 { registry } = defineRegistry(catalog, {
+	components: { Login: LoginSFC, Dashboard: DashboardSFC },
+	actions: { login: async () => {}, logout: async () => {} },
+});
+```
 
-### Provider Pattern
+```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 }),
+			},
+		},
+	}),
+);
+```
 
 ```vue
 <!-- App.vue -->
 <script setup lang="ts">
-import { PlayVueRouterProvider } from "@xmachines/play-vue-router";
+import { definePlayer } from "@xmachines/play-xstate";
 import { PlayRenderer } from "@xmachines/play-vue";
-import { provide } from "vue";
-import Header from "./components/Header.vue";
-import Footer from "./components/Footer.vue";
+import { machine } from "./machine.js";
+import { registry } from "./registry.js";
 
-// Provide actor to nested components like Header
-provide("actor", actor);
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
 </script>
 
 <template>
-	<PlayVueRouterProvider :actor="actor" :router="router" :routeMap="routeMap">
-		<template #default="{ currentActor, currentRouter }">
-			<div>
-				<Header />
-				<PlayRenderer :actor="currentActor" :components="components" />
-				<Footer />
-			</div>
-		</template>
-	</PlayVueRouterProvider>
+	<PlayRenderer
+		:actor="actor"
+		:registry="registry"
+		:actions="{ login: 'auth.login', logout: 'auth.logout' }"
+	/>
 </template>
 ```
 
-```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);
-});
+## API Reference
 
-onUnmounted(() => {
-	if (watcher) watcher.unwatch(actor.currentRoute);
-});
-</script>
+### `PlayRenderer`
 
-<template>
-	<header>
-		<nav>Current: {{ route }}</nav>
-	</header>
-</template>
+Main Vue component. Subscribes to `actor.currentView` and renders the spec.
+
+```vue
+<PlayRenderer
+	:actor="actor"
+	:registry="registry"
+	:actions="{ login: 'auth.login' }"
+	:store="myStore"
+/>
 ```
 
-## Architecture
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+**`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>`.
 
-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
+**`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.
 
-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
+**`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
 
-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
+- **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.
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents Vue thrashing from multiple signal updates
-    - Single Vue render per microtask batch
+```ts
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
 
-5. **Explicit Disposal Contract:**
-    - Component teardown calls watcher `unwatch` in `onUnmounted`
-    - Do not rely on GC-only cleanup
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
+```
 
-**Pattern:**
+```vue
+<PlayRenderer
+	:actor="actor"
+	:registry="registry"
+	:store="store"
+	:actions="{ login: 'auth.login' }"
+/>
+```
 
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
+---
 
-**Architectural Invariants:**
+### `useActor`
 
-- **Signal-Only Reactivity (INV-05):** No Vue state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+Vue composable for accessing the actor from inside any component rendered by `PlayRenderer`.
 
-## Canonical Watcher Lifecycle
+```ts
+import { useActor } from "@xmachines/play-vue";
 
-If you write your own custom integration, use the same watcher flow as `PlayRenderer`:
+// Inside any component rendered inside PlayRenderer:
+const actor = useActor();
+actor.send({ type: "auth.logout" });
+```
 
-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()`
+Throws `"useActor() must be called inside <PlayRenderer>"` if called outside the tree.
 
-Watcher notify is one-shot. Re-arm is required for continuous observation.
+---
 
-## Benefits
+## Route Parameters in Props
 
-- **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
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-## Related Packages
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.routeParams = { section: "profile" }
+// Component receives: { section: "profile", user: "alice" }
+```
+
+Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
-- **[@xmachines/play-vue-router](../play-vue-router/README.md)** - Vue Router integration
-- **[@xmachines/play-actor](../play-actor/README.md)** - Actor base
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+---
 
-## License
+## Architecture Notes
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+- 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
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+@xmachines/play-vue - Vue 3 renderer for XMachines Play architecture
 
-@xmachines/play-vue - Vue 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.
 
 ## Interfaces
 
+- [ComponentContext](interfaces/ComponentContext.md)
 - [PlayRendererProps](interfaces/PlayRendererProps.md)
 
+## Type Aliases
+
+- [ComponentEntry](type-aliases/ComponentEntry.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [ComponentsMap](type-aliases/ComponentsMap.md)
+- [DefineRegistryOptions](type-aliases/DefineRegistryOptions.md)
+- [PlayActor](type-aliases/PlayActor.md)
+
 ## Variables
 
 - [PlayRenderer](variables/PlayRenderer.md)
+
+## Functions
+
+- [defineRegistry](functions/defineRegistry.md)
+- [useActor](functions/useActor.md)
+- [useStateBinding](functions/useStateBinding.md)

package/api/@xmachines/play-vue/functions/defineRegistry.md

@@ -0,0 +1,32 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / defineRegistry
+
+# Function: defineRegistry()
+
+```ts
+function defineRegistry<C>(catalog, options): DefineRegistryResult;
+```
+
+Defined in: [packages/play-vue/src/define-registry.ts:114](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-vue/src/define-registry.ts#L114)
+
+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.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## Parameters
+
+| Parameter | Type                                                                       | Description                                                                                                                            |
+| --------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `catalog` | `C`                                                                        | The json-render catalog defining component prop shapes.                                                                                |
+| `options` | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> | Registry options. `components` entries may be `.vue` SFCs (objects) or plain `ComponentFn` functions — both are handled automatically. |
+
+## Returns
+
+`DefineRegistryResult`

package/api/@xmachines/play-vue/functions/useActor.md

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / useActor
+
+# Function: useActor()
+
+```ts
+function useActor(): PlayActor;
+```
+
+Defined in: [packages/play-vue/src/useActor.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-vue/src/useActor.ts#L42)
+
+## Returns
+
+[`PlayActor`](../type-aliases/PlayActor.md)

package/api/@xmachines/play-vue/functions/useStateBinding.md

@@ -0,0 +1,30 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / useStateBinding
+
+# Function: useStateBinding()
+
+```ts
+function useStateBinding<T>(path): [ComputedRef<T | undefined>, (value) => void];
+```
+
+Composable to get and set a value from the state model by path.
+
+This is the path-based variant for use in arbitrary composables. For
+registry components that receive `bindings` from the renderer, prefer
+`useBoundProp` which reads the already-resolved prop value and writes back
+to the bound path.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+\[`ComputedRef`\<`T` \| `undefined`\>, (`value`) => `void`\]

package/api/@xmachines/play-vue/interfaces/ComponentContext.md

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+Context passed to component render functions
+
+## Example
+
+```ts
+const Button: ComponentFn<typeof catalog, "Button"> = (ctx) => {
+	return h("button", { onClick: () => ctx.emit("press") }, ctx.props.label);
+};
+```
+
+## Extends
+
+- `BaseComponentProps`\<`InferComponentProps`\<`C`, `K`\>\>
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Properties
+
+| Property                                   | Type                                                                                                                                                                    | Description                                                                                                                      | Inherited from                | Defined in |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings?` | `Record`\<`string`, `string`\>                                                                                                                                          | Two-way binding paths resolved from `$bindState` / `$bindItem` expressions. Maps prop name → absolute state path for write-back. | `BaseComponentProps.bindings` | -          |
+| <a id="property-children"></a> `children?` | \| `VNode`\<`RendererNode`, `RendererElement`, \{ \[`key`: `string`\]: `any`; \}\> \| `VNode`\<`RendererNode`, `RendererElement`, \{ \[`key`: `string`\]: `any`; \}\>[] | Rendered children (from the default slot)                                                                                        | `BaseComponentProps.children` | -          |
+| <a id="property-emit"></a> `emit`          | (`event`) => `void`                                                                                                                                                     | Simple event emitter (shorthand). Fires the event and returns void.                                                              | `BaseComponentProps.emit`     | -          |
+| <a id="property-loading"></a> `loading?`   | `boolean`                                                                                                                                                               | -                                                                                                                                | `BaseComponentProps.loading`  | -          |
+| <a id="property-on"></a> `on`              | (`event`) => `EventHandle`                                                                                                                                              | Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks.                                       | `BaseComponentProps.on`       | -          |
+| <a id="property-props"></a> `props`        | `InferComponentProps`                                                                                                                                                   | -                                                                                                                                | `BaseComponentProps.props`    | -          |