@xmachines/play-vue 2.0.0 → 2.1.0

package/dist/actor-provider-context.js

@@ -2,38 +2,45 @@ import { inject } from "vue";
 import { assertNonNullable } from "@xmachines/play";
 //#region packages/play-vue/src/actor-provider-context.ts
 /**
-* ViewContextValue and getPlayViewContext — shared context types for Vue provider architecture.
+* ViewContextValue and usePlayView — the shared context types of the Vue provider architecture.
 *
-* Extracted from ActorProvider.vue so TypeScript can re-export these types from index.ts.
-* (The vue-shim.d.ts only declares a default export from *.vue files, so named exports
-* from .vue SFCs are not visible to TypeScript's re-export resolution.)
+* This file holds them, and not ActorProvider.vue, so that TypeScript can
+* re-export the types from index.ts. (The file vue-shim.d.ts declares a default
+* export of each *.vue file only. Therefore TypeScript does not see a named export
+* of a .vue SFC when it resolves a re-export.)
 *
 * @packageDocumentation
 */
 /**
-* Injection key for the ViewContextValue. Exported so ActorProvider.vue can use it
-* as the canonical key without re-declaring.
+* The injection key of the ViewContextValue. This file exports it, so that
+* ActorProvider.vue uses it as the canonical key and declares no second key.
 *
-* @internal Use getPlayViewContext() as the public API; do not inject ViewKey directly.
+* @internal Use usePlayView() as the public API. Never inject ViewKey directly.
 */
 var ViewKey = Symbol("xmachines.view");
 /**
-* Access the current ViewContextValue from inside an ActorProvider tree.
+* Returns the current ViewContextValue inside an ActorProvider tree.
 *
-* @throws {Error} If called outside an <ActorProvider> (or <PlayUIProvider>) tree
+* @throws {Error} When the caller is outside an <ActorProvider> tree or a <PlayUIProvider> tree
 *
 * @example
 * ```typescript
-* import { getPlayViewContext } from "@xmachines/play-vue";
+* import { usePlayView } from "@xmachines/play-vue";
 *
-* const view = getPlayViewContext();
+* const view = usePlayView();
 * // view.spec, view.handlers, view.registry
 * ```
 */
-function getPlayViewContext() {
+function usePlayView() {
 	return assertNonNullable(inject(ViewKey), "ViewKey");
 }
+/**
+* Access the current ViewContextValue from inside an ActorProvider tree.
+*
+* @deprecated Renamed to {@link usePlayView}; will be removed in the next major.
+*/
+var getPlayViewContext = usePlayView;
 //#endregion
-export { ViewKey, getPlayViewContext };
+export { ViewKey, getPlayViewContext, usePlayView };
 
 //# sourceMappingURL=actor-provider-context.js.map

package/dist/actor-provider-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"actor-provider-context.js","names":[],"sources":["../src/actor-provider-context.ts"],"sourcesContent":["/**\n * ViewContextValue and getPlayViewContext — shared context types for Vue provider architecture.\n *\n * Extracted from ActorProvider.vue so TypeScript can re-export these types from index.ts.\n * (The vue-shim.d.ts only declares a default export from *.vue files, so named exports\n * from .vue SFCs are not visible to TypeScript's re-export resolution.)\n *\n * @packageDocumentation\n */\n\nimport { inject } from \"vue\";\nimport type { InjectionKey } from \"vue\";\nimport { assertNonNullable } from \"@xmachines/play\";\nimport type { ComponentRegistry } from \"@xmachines/json-render-vue\";\nimport type { BaseViewContextValue } from \"@xmachines/play-actor\";\n\n/**\n * Context value provided by ActorProvider and consumed by PlayRenderer (zero-prop leaf).\n * Accessible via getPlayViewContext() inside any ActorProvider/PlayUIProvider tree.\n */\nexport interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {}\n\n/**\n * Injection key for the ViewContextValue. Exported so ActorProvider.vue can use it\n * as the canonical key without re-declaring.\n *\n * @internal Use getPlayViewContext() as the public API; do not inject ViewKey directly.\n */\nexport const ViewKey: InjectionKey<ViewContextValue> = Symbol(\"xmachines.view\");\n\n/**\n * Access the current ViewContextValue from inside an ActorProvider tree.\n *\n * @throws {Error} If called outside an <ActorProvider> (or <PlayUIProvider>) tree\n *\n * @example\n * ```typescript\n * import { getPlayViewContext } from \"@xmachines/play-vue\";\n *\n * const view = getPlayViewContext();\n * // view.spec, view.handlers, view.registry\n * ```\n */\nexport function getPlayViewContext(): ViewContextValue {\n\treturn assertNonNullable(inject(ViewKey), \"ViewKey\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA4BA,IAAa,UAA0C,OAAO,gBAAgB;;;;;;;;;;;;;;AAe9E,SAAgB,qBAAuC;CACtD,OAAO,kBAAkB,OAAO,OAAO,GAAG,SAAS;AACpD"}
+{"version":3,"file":"actor-provider-context.js","names":[],"sources":["../src/actor-provider-context.ts"],"sourcesContent":["/**\n * ViewContextValue and usePlayView — the shared context types of the Vue provider architecture.\n *\n * This file holds them, and not ActorProvider.vue, so that TypeScript can\n * re-export the types from index.ts. (The file vue-shim.d.ts declares a default\n * export of each *.vue file only. Therefore TypeScript does not see a named export\n * of a .vue SFC when it resolves a re-export.)\n *\n * @packageDocumentation\n */\n\nimport { inject } from \"vue\";\nimport type { InjectionKey } from \"vue\";\nimport { assertNonNullable } from \"@xmachines/play\";\nimport type { ComponentRegistry } from \"@xmachines/json-render-vue\";\nimport type { BaseViewContextValue } from \"@xmachines/play-actor\";\n\n/**\n * The context value that ActorProvider provides and PlayRenderer, the leaf without\n * props, reads. usePlayView() gives it inside every ActorProvider tree and\n * PlayUIProvider tree.\n */\nexport interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {}\n\n/**\n * The injection key of the ViewContextValue. This file exports it, so that\n * ActorProvider.vue uses it as the canonical key and declares no second key.\n *\n * @internal Use usePlayView() as the public API. Never inject ViewKey directly.\n */\nexport const ViewKey: InjectionKey<ViewContextValue> = Symbol(\"xmachines.view\");\n\n/**\n * Returns the current ViewContextValue inside an ActorProvider tree.\n *\n * @throws {Error} When the caller is outside an <ActorProvider> tree or a <PlayUIProvider> tree\n *\n * @example\n * ```typescript\n * import { usePlayView } from \"@xmachines/play-vue\";\n *\n * const view = usePlayView();\n * // view.spec, view.handlers, view.registry\n * ```\n */\nexport function usePlayView(): ViewContextValue {\n\treturn assertNonNullable(inject(ViewKey), \"ViewKey\");\n}\n\n/**\n * Access the current ViewContextValue from inside an ActorProvider tree.\n *\n * @deprecated Renamed to {@link usePlayView}; will be removed in the next major.\n */\nexport const getPlayViewContext = usePlayView;\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8BA,IAAa,UAA0C,OAAO,gBAAgB;;;;;;;;;;;;;;AAe9E,SAAgB,cAAgC;CAC/C,OAAO,kBAAkB,OAAO,OAAO,GAAG,SAAS;AACpD;;;;;;AAOA,IAAa,qBAAqB"}

package/dist/define-registry.d.ts

@@ -1,40 +1,44 @@
 /**
- * `defineRegistry` wrapper for @xmachines/play-vue.
+ * The `defineRegistry` wrapper of @xmachines/play-vue.
  *
- * Wraps `defineRegistry` from `@xmachines/json-render-vue` with automatic SFC support.
+ * It wraps `defineRegistry` from `@xmachines/json-render-vue`, and it adds support
+ * for an SFC.
  *
- * ## Vue-specific — React and Solid do not need this
+ * ## Vue only — React and Solid do not need this wrapper
  *
- * 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.
+ * In React, `useContext()` works everywhere inside the component call tree. In
+ * Solid, `useContext()` works inside a reactive computation and inside a component
+ * render. Neither framework has the strict rule of the Vue function `inject()`,
+ * which runs during a synchronous `setup()` only. Therefore the `defineRegistry`
+ * implementation of each of them calls `componentFn(ctx)` directly, and it wraps
+ * nothing.
  *
- * For the DOM renderer, there is no component system at all — just render functions
- * returning `HTMLElement` — so injection context is not applicable.
+ * The DOM renderer has no component system at all. It has render functions that
+ * return an `HTMLElement`. An injection context is therefore not relevant.
  *
- * Only Vue requires this adapter.
+ * Vue alone needs this adapter.
  *
- * ## Why this wrapper exists
+ * ## The reason for this wrapper
  *
- * `@xmachines/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.
+ * The `defineRegistry` function of `@xmachines/json-render-vue` calls each
+ * registered component as a plain function: `componentFn(ctx)`. A `.vue` SFC, which
+ * is the output of `defineComponent` or of `<script setup>`, is an **object**, not a
+ * function. A call to that object 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.
+ * There is a second and deeper reason. `defineRegistry` calls each component inside
+ * its own render function, which is the return value of `setup()`. The Vue function
+ * `inject()`, and each composable on it, such as `useStateBinding` and
+ * `useStateStore`, works during the synchronous run of `setup()` only, not inside a
+ * render function. For this reason a plain `.ts` `ComponentFn` file can call no Vue
+ * composable.
  *
- * 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>`.
+ * This wrapper finds each Vue SFC in the `components` map, and it wraps the SFC with
+ * `h(SFC, ctx)`. The SFC then renders as a child component with its own `setup()`,
+ * and every composable works inside `<script setup>`.
  *
- * ## Usage
+ * ## Use
  *
- * Import `defineRegistry` from `@xmachines/play-vue` instead of `@xmachines/json-render-vue`:
+ * Import `defineRegistry` from `@xmachines/play-vue`, not from `@xmachines/json-render-vue`:
  *
  * ```ts
  * import { defineRegistry } from "@xmachines/play-vue";
@@ -45,14 +49,14 @@
  *
  * const { registry } = defineRegistry(catalog, {
  *   components: {
- *     Login: LoginSFC,       // .vue SFC — auto-wrapped
- *     Dashboard: DashboardSFC, // .vue SFC — auto-wrapped
+ *     Login: LoginSFC,       // a .vue SFC — the wrapper handles it
+ *     Dashboard: DashboardSFC, // a .vue SFC — the wrapper handles it
  *   },
  * });
  * ```
  *
- * Plain `ComponentFn` functions still work and are passed through unchanged.
- * Mixing SFCs and plain functions in the same registry is supported.
+ * A plain `ComponentFn` function also works, and the wrapper passes it through
+ * without a change. One registry can hold both SFCs and plain functions.
  */
 import { type Component } from "vue";
 import { defineRegistry as defineRegistryBase, type ComponentFn } from "@xmachines/json-render-vue";
@@ -65,15 +69,16 @@ export type DefineRegistryOptions<C extends Catalog> = Omit<Parameters<typeof de
     components?: ComponentsMap<C>;
 };
 /**
- * Create a component registry, automatically wrapping `.vue` SFCs so they work
- * correctly with `@xmachines/json-render-vue`'s rendering pipeline.
+ * Creates a component registry. It wraps each `.vue` SFC, so that the SFC works
+ * correctly with the render pipeline of `@xmachines/json-render-vue`.
  *
- * Drop-in replacement for `defineRegistry` from `@xmachines/json-render-vue`. Import from
- * `@xmachines/play-vue` to get SFC support for free.
+ * This function is the drop-in replacement for `defineRegistry` from
+ * `@xmachines/json-render-vue`. Import it from `@xmachines/play-vue`, and you get
+ * the support for an SFC.
  *
- * @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.
+ * @param catalog - The json-render catalog. It defines the prop shape of each component.
+ * @param options - The registry options. Each `components` entry is a `.vue` SFC,
+ *   which is an object, or a plain `ComponentFn` function. The wrapper handles both.
  */
 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

@@ -1 +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,EAEhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAwCnF,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,IAAI,CAC1D,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAC3C,YAAY,CACZ,GAAG;IACH,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,CAa1C"}
+{"version":3,"file":"define-registry.d.ts","sourceRoot":"","sources":["../src/define-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EACN,cAAc,IAAI,kBAAkB,EAEpC,KAAK,WAAW,EAEhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AA0CnF,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,IAAI,CAC1D,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAC3C,YAAY,CACZ,GAAG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;GAWG;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,CAa1C"}

package/dist/define-registry.js

@@ -2,42 +2,46 @@ import { h } from "vue";
 import { defineRegistry } from "@xmachines/json-render-vue";
 //#region packages/play-vue/src/define-registry.ts
 /**
-* `defineRegistry` wrapper for @xmachines/play-vue.
+* The `defineRegistry` wrapper of @xmachines/play-vue.
 *
-* Wraps `defineRegistry` from `@xmachines/json-render-vue` with automatic SFC support.
+* It wraps `defineRegistry` from `@xmachines/json-render-vue`, and it adds support
+* for an SFC.
 *
-* ## Vue-specific — React and Solid do not need this
+* ## Vue only — React and Solid do not need this wrapper
 *
-* 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.
+* In React, `useContext()` works everywhere inside the component call tree. In
+* Solid, `useContext()` works inside a reactive computation and inside a component
+* render. Neither framework has the strict rule of the Vue function `inject()`,
+* which runs during a synchronous `setup()` only. Therefore the `defineRegistry`
+* implementation of each of them calls `componentFn(ctx)` directly, and it wraps
+* nothing.
 *
-* For the DOM renderer, there is no component system at all — just render functions
-* returning `HTMLElement` — so injection context is not applicable.
+* The DOM renderer has no component system at all. It has render functions that
+* return an `HTMLElement`. An injection context is therefore not relevant.
 *
-* Only Vue requires this adapter.
+* Vue alone needs this adapter.
 *
-* ## Why this wrapper exists
+* ## The reason for this wrapper
 *
-* `@xmachines/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.
+* The `defineRegistry` function of `@xmachines/json-render-vue` calls each
+* registered component as a plain function: `componentFn(ctx)`. A `.vue` SFC, which
+* is the output of `defineComponent` or of `<script setup>`, is an **object**, not a
+* function. A call to that object 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.
+* There is a second and deeper reason. `defineRegistry` calls each component inside
+* its own render function, which is the return value of `setup()`. The Vue function
+* `inject()`, and each composable on it, such as `useStateBinding` and
+* `useStateStore`, works during the synchronous run of `setup()` only, not inside a
+* render function. For this reason a plain `.ts` `ComponentFn` file can call no Vue
+* composable.
 *
-* 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>`.
+* This wrapper finds each Vue SFC in the `components` map, and it wraps the SFC with
+* `h(SFC, ctx)`. The SFC then renders as a child component with its own `setup()`,
+* and every composable works inside `<script setup>`.
 *
-* ## Usage
+* ## Use
 *
-* Import `defineRegistry` from `@xmachines/play-vue` instead of `@xmachines/json-render-vue`:
+* Import `defineRegistry` from `@xmachines/play-vue`, not from `@xmachines/json-render-vue`:
 *
 * ```ts
 * import { defineRegistry } from "@xmachines/play-vue";
@@ -48,31 +52,32 @@ import { defineRegistry } from "@xmachines/json-render-vue";
 *
 * const { registry } = defineRegistry(catalog, {
 *   components: {
-*     Login: LoginSFC,       // .vue SFC — auto-wrapped
-*     Dashboard: DashboardSFC, // .vue SFC — auto-wrapped
+*     Login: LoginSFC,       // a .vue SFC — the wrapper handles it
+*     Dashboard: DashboardSFC, // a .vue SFC — the wrapper handles it
 *   },
 * });
 * ```
 *
-* Plain `ComponentFn` functions still work and are passed through unchanged.
-* Mixing SFCs and plain functions in the same registry is supported.
+* A plain `ComponentFn` function also works, and the wrapper passes it through
+* without a change. One registry can hold both SFCs and plain functions.
 */
 /**
-* Detect whether a value is a Vue component object (SFC) rather than a plain
+* Tells you if a value is a Vue component object, which is an SFC, and not a plain
 * `ComponentFn` function.
 *
-* Vue SFCs produced by `defineComponent` or `<script setup>` compilation are
-* plain objects (not callable). A `ComponentFn` is always a plain function.
+* A Vue SFC from `defineComponent` or from the compilation of `<script setup>` is a
+* plain object, and a call to it is not possible. A `ComponentFn` is always a plain
+* function.
 *
-* Detection strategy (checked in order):
-* 1. `__vccOpts` — set by vite-plugin-vue / vue-loader on every `<script setup>` SFC.
-* 2. `__name` — set by Vite on named SFCs (present alongside `__vccOpts` but also
-*    on `defineComponent({ name: "..." })` output without `<script setup>`).
-* 3. `setup` is a function — the `defineComponent({ setup() {} })` signature.
-* 4. `render` is a function — the `defineComponent({ render() {} })` signature.
+* The function makes four tests, in this order:
+* 1. `__vccOpts` — vite-plugin-vue and vue-loader set it on every `<script setup>` SFC.
+* 2. `__name` — Vite sets it on a named SFC. It is present beside `__vccOpts`, and
+*    also on the output of `defineComponent({ name: "..." })` without `<script setup>`.
+* 3. `setup` is a function — this is the `defineComponent({ setup() {} })` signature.
+* 4. `render` is a function — this is the `defineComponent({ render() {} })` signature.
 *
-* Requiring `setup` / `render` to be **functions** prevents plain POJOs that
-* happen to have a `setup` or `render` key from being misidentified as components.
+* Tests 3 and 4 require a **function**. A plain object with a `setup` key or a
+* `render` key is therefore not a component for this function.
 */
 function isVueSFC(value) {
 	if (typeof value !== "object" || value === null) return false;
@@ -81,24 +86,26 @@ function isVueSFC(value) {
 	return typeof v["setup"] === "function" || typeof v["render"] === "function";
 }
 /**
-* Wrap a Vue SFC as a `ComponentFn` by rendering it via `h()`.
+* Wraps a Vue SFC as a `ComponentFn`, and renders it with `h()`.
 *
-* The SFC receives the full `ComponentContext` as its props and renders in its
-* own child component `setup()`, where Vue composables work correctly.
+* The SFC receives the complete `ComponentContext` as its props. It renders in the
+* `setup()` function of its own child component, where each Vue composable works
+* correctly.
 */
 function wrapSFC(component) {
 	return (ctx) => h(component, ctx);
 }
 /**
-* Create a component registry, automatically wrapping `.vue` SFCs so they work
-* correctly with `@xmachines/json-render-vue`'s rendering pipeline.
+* Creates a component registry. It wraps each `.vue` SFC, so that the SFC works
+* correctly with the render pipeline of `@xmachines/json-render-vue`.
 *
-* Drop-in replacement for `defineRegistry` from `@xmachines/json-render-vue`. Import from
-* `@xmachines/play-vue` to get SFC support for free.
+* This function is the drop-in replacement for `defineRegistry` from
+* `@xmachines/json-render-vue`. Import it from `@xmachines/play-vue`, and you get
+* the support for an SFC.
 *
-* @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.
+* @param catalog - The json-render catalog. It defines the prop shape of each component.
+* @param options - The registry options. Each `components` entry is a `.vue` SFC,
+*   which is an object, or a plain `ComponentFn` function. The wrapper handles both.
 */
 function defineRegistry$1(catalog, options) {
 	const wrappedComponents = {};

package/dist/define-registry.js.map

@@ -1 +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 `@xmachines/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 * `@xmachines/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 `@xmachines/json-render-vue`:\n *\n * ```ts\n * import { defineRegistry } from \"@xmachines/play-vue\";\n * // not: import { defineRegistry } from \"@xmachines/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\ttype Components,\n} from \"@xmachines/json-render-vue\";\nimport type { Catalog, InferCatalogComponents } from \"@xmachines/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 *\n * Detection strategy (checked in order):\n * 1. `__vccOpts` — set by vite-plugin-vue / vue-loader on every `<script setup>` SFC.\n * 2. `__name` — set by Vite on named SFCs (present alongside `__vccOpts` but also\n *    on `defineComponent({ name: \"...\" })` output without `<script setup>`).\n * 3. `setup` is a function — the `defineComponent({ setup() {} })` signature.\n * 4. `render` is a function — the `defineComponent({ render() {} })` signature.\n *\n * Requiring `setup` / `render` to be **functions** prevents plain POJOs that\n * happen to have a `setup` or `render` key from being misidentified as components.\n */\nfunction isVueSFC(value: unknown): value is Component {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst v = value as Record<string, unknown>;\n\t// Compiler-injected markers — unambiguous Vue component identifiers.\n\tif (\"__vccOpts\" in v || \"__name\" in v) return true;\n\t// defineComponent() output: setup or render must be callable, not just present.\n\treturn typeof v[\"setup\"] === \"function\" || typeof v[\"render\"] === \"function\";\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> = Omit<\n\tParameters<typeof defineRegistryBase<C>>[1],\n\t\"components\"\n> & {\n\tcomponents?: ComponentsMap<C>;\n};\n\n/**\n * Create a component registry, automatically wrapping `.vue` SFCs so they work\n * correctly with `@xmachines/json-render-vue`'s rendering pipeline.\n *\n * Drop-in replacement for `defineRegistry` from `@xmachines/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 = {} as Components<C>;\n\n\tfor (const [key, component] of Object.entries(options.components ?? {})) {\n\t\tif (component === undefined) continue;\n\t\tconst k = key as keyof InferCatalogComponents<C>;\n\t\twrappedComponents[k] = isVueSFC(component)\n\t\t\t? wrapSFC(component as Component)\n\t\t\t: (component as ComponentFn<C, typeof k>);\n\t}\n\n\tconst baseOptions = options as Parameters<typeof defineRegistryBase<C>>[1];\n\treturn defineRegistryBase(catalog, { ...baseOptions, components: wrappedComponents });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,SAAS,SAAS,OAAoC;CACrD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,IAAI;CAEV,IAAI,eAAe,KAAK,YAAY,GAAG,OAAO;CAE9C,OAAO,OAAO,EAAE,aAAa,cAAc,OAAO,EAAE,cAAc;AACnE;;;;;;;AAQA,SAAS,QACR,WACoB;CACpB,QAAQ,QAAgC,EAAE,WAAW,GAAG;AACzD;;;;;;;;;;;;AA4BA,SAAgB,iBACf,SACA,SAC2C;CAC3C,MAAM,oBAAoB,CAAC;CAE3B,KAAK,MAAM,CAAC,KAAK,cAAc,OAAO,QAAQ,QAAQ,cAAc,CAAC,CAAC,GAAG;EACxE,IAAI,cAAc,KAAA,GAAW;EAC7B,MAAM,IAAI;EACV,kBAAkB,KAAK,SAAS,SAAS,IACtC,QAAQ,SAAsB,IAC7B;CACL;CAGA,OAAO,eAAmB,SAAS;EAAE,GAAG;EAAa,YAAY;CAAkB,CAAC;AACrF"}
+{"version":3,"file":"define-registry.js","names":[],"sources":["../src/define-registry.ts"],"sourcesContent":["/**\n * The `defineRegistry` wrapper of @xmachines/play-vue.\n *\n * It wraps `defineRegistry` from `@xmachines/json-render-vue`, and it adds support\n * for an SFC.\n *\n * ## Vue only — React and Solid do not need this wrapper\n *\n * In React, `useContext()` works everywhere inside the component call tree. In\n * Solid, `useContext()` works inside a reactive computation and inside a component\n * render. Neither framework has the strict rule of the Vue function `inject()`,\n * which runs during a synchronous `setup()` only. Therefore the `defineRegistry`\n * implementation of each of them calls `componentFn(ctx)` directly, and it wraps\n * nothing.\n *\n * The DOM renderer has no component system at all. It has render functions that\n * return an `HTMLElement`. An injection context is therefore not relevant.\n *\n * Vue alone needs this adapter.\n *\n * ## The reason for this wrapper\n *\n * The `defineRegistry` function of `@xmachines/json-render-vue` calls each\n * registered component as a plain function: `componentFn(ctx)`. A `.vue` SFC, which\n * is the output of `defineComponent` or of `<script setup>`, is an **object**, not a\n * function. A call to that object throws.\n *\n * There is a second and deeper reason. `defineRegistry` calls each component inside\n * its own render function, which is the return value of `setup()`. The Vue function\n * `inject()`, and each composable on it, such as `useStateBinding` and\n * `useStateStore`, works during the synchronous run of `setup()` only, not inside a\n * render function. For this reason a plain `.ts` `ComponentFn` file can call no Vue\n * composable.\n *\n * This wrapper finds each Vue SFC in the `components` map, and it wraps the SFC with\n * `h(SFC, ctx)`. The SFC then renders as a child component with its own `setup()`,\n * and every composable works inside `<script setup>`.\n *\n * ## Use\n *\n * Import `defineRegistry` from `@xmachines/play-vue`, not from `@xmachines/json-render-vue`:\n *\n * ```ts\n * import { defineRegistry } from \"@xmachines/play-vue\";\n * // not: import { defineRegistry } from \"@xmachines/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,       // a .vue SFC — the wrapper handles it\n *     Dashboard: DashboardSFC, // a .vue SFC — the wrapper handles it\n *   },\n * });\n * ```\n *\n * A plain `ComponentFn` function also works, and the wrapper passes it through\n * without a change. One registry can hold both SFCs and plain functions.\n */\n\nimport { h, type Component } from \"vue\";\nimport {\n\tdefineRegistry as defineRegistryBase,\n\ttype ComponentContext,\n\ttype ComponentFn,\n\ttype Components,\n} from \"@xmachines/json-render-vue\";\nimport type { Catalog, InferCatalogComponents } from \"@xmachines/json-render-core\";\n\n/**\n * Tells you if a value is a Vue component object, which is an SFC, and not a plain\n * `ComponentFn` function.\n *\n * A Vue SFC from `defineComponent` or from the compilation of `<script setup>` is a\n * plain object, and a call to it is not possible. A `ComponentFn` is always a plain\n * function.\n *\n * The function makes four tests, in this order:\n * 1. `__vccOpts` — vite-plugin-vue and vue-loader set it on every `<script setup>` SFC.\n * 2. `__name` — Vite sets it on a named SFC. It is present beside `__vccOpts`, and\n *    also on the output of `defineComponent({ name: \"...\" })` without `<script setup>`.\n * 3. `setup` is a function — this is the `defineComponent({ setup() {} })` signature.\n * 4. `render` is a function — this is the `defineComponent({ render() {} })` signature.\n *\n * Tests 3 and 4 require a **function**. A plain object with a `setup` key or a\n * `render` key is therefore not a component for this function.\n */\nfunction isVueSFC(value: unknown): value is Component {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst v = value as Record<string, unknown>;\n\t// The markers of the compiler. They identify a Vue component without a doubt.\n\tif (\"__vccOpts\" in v || \"__name\" in v) return true;\n\t// The output of defineComponent(): the code must be able to call setup or render, and their presence is not sufficient.\n\treturn typeof v[\"setup\"] === \"function\" || typeof v[\"render\"] === \"function\";\n}\n\n/**\n * Wraps a Vue SFC as a `ComponentFn`, and renders it with `h()`.\n *\n * The SFC receives the complete `ComponentContext` as its props. It renders in the\n * `setup()` function of its own child component, where each Vue composable works\n * 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> = Omit<\n\tParameters<typeof defineRegistryBase<C>>[1],\n\t\"components\"\n> & {\n\tcomponents?: ComponentsMap<C>;\n};\n\n/**\n * Creates a component registry. It wraps each `.vue` SFC, so that the SFC works\n * correctly with the render pipeline of `@xmachines/json-render-vue`.\n *\n * This function is the drop-in replacement for `defineRegistry` from\n * `@xmachines/json-render-vue`. Import it from `@xmachines/play-vue`, and you get\n * the support for an SFC.\n *\n * @param catalog - The json-render catalog. It defines the prop shape of each component.\n * @param options - The registry options. Each `components` entry is a `.vue` SFC,\n *   which is an object, or a plain `ComponentFn` function. The wrapper handles both.\n */\nexport function defineRegistry<C extends Catalog>(\n\tcatalog: C,\n\toptions: DefineRegistryOptions<C>,\n): ReturnType<typeof defineRegistryBase<C>> {\n\tconst wrappedComponents = {} as Components<C>;\n\n\tfor (const [key, component] of Object.entries(options.components ?? {})) {\n\t\tif (component === undefined) continue;\n\t\tconst k = key as keyof InferCatalogComponents<C>;\n\t\twrappedComponents[k] = isVueSFC(component)\n\t\t\t? wrapSFC(component as Component)\n\t\t\t: (component as ComponentFn<C, typeof k>);\n\t}\n\n\tconst baseOptions = options as Parameters<typeof defineRegistryBase<C>>[1];\n\treturn defineRegistryBase(catalog, { ...baseOptions, components: wrappedComponents });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAS,SAAS,OAAoC;CACrD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,IAAI;CAEV,IAAI,eAAe,KAAK,YAAY,GAAG,OAAO;CAE9C,OAAO,OAAO,EAAE,aAAa,cAAc,OAAO,EAAE,cAAc;AACnE;;;;;;;;AASA,SAAS,QACR,WACoB;CACpB,QAAQ,QAAgC,EAAE,WAAW,GAAG;AACzD;;;;;;;;;;;;;AA6BA,SAAgB,iBACf,SACA,SAC2C;CAC3C,MAAM,oBAAoB,CAAC;CAE3B,KAAK,MAAM,CAAC,KAAK,cAAc,OAAO,QAAQ,QAAQ,cAAc,CAAC,CAAC,GAAG;EACxE,IAAI,cAAc,KAAA,GAAW;EAC7B,MAAM,IAAI;EACV,kBAAkB,KAAK,SAAS,SAAS,IACtC,QAAQ,SAAsB,IAC7B;CACL;CAGA,OAAO,eAAmB,SAAS;EAAE,GAAG;EAAa,YAAY;CAAkB,CAAC;AACrF"}

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 /**
- * @xmachines/play-vue - Vue 3 renderer for XMachines Play architecture
+ * @xmachines/play-vue - Vue 3 renderer for the XMachines Play architecture
  *
- * Provides a thin Vue rendering layer that passively observes actor signals
- * and renders UI components via @xmachines/json-render-vue. Vue reactivity is only used
- * to trigger re-renders — signals are the source of truth.
+ * This package is a thin Vue rendering layer. It observes the actor signals and
+ * renders the UI components with @xmachines/json-render-vue. Vue reactivity only
+ * triggers the re-render. The signals are the source of truth.
  *
- * Re-exports `defineRegistry` (SFC-aware — auto-wraps `.vue` SFCs via `h()`),
- * `useBoundProp`, `ComponentFn`, `ComponentContext`, and all json-render providers
- * so consumers import everything from `@xmachines/play-vue` rather than
- * `@xmachines/json-render-vue` directly.
+ * The package re-exports `defineRegistry`, which knows an SFC and wraps each `.vue`
+ * SFC with `h()`. It also re-exports `useBoundProp`, `ComponentFn`,
+ * `ComponentContext`, and every json-render provider. A consumer therefore imports
+ * everything from `@xmachines/play-vue`, and not from `@xmachines/json-render-vue`.
  *
  * @packageDocumentation
  */
@@ -16,7 +16,7 @@ export { default as PlayRenderer } from "./PlayRenderer.vue";
 export { default as ActorProvider } from "./ActorProvider.vue";
 export { default as PlayUIProvider } from "./PlayUIProvider.vue";
 export type { ActorProviderProps, PlayUIProviderProps, RenderErrorHandler, VisibilityProviderProps, } from "./types.js";
-export { getPlayViewContext } from "./actor-provider-context.js";
+export { usePlayView, getPlayViewContext } from "./actor-provider-context.js";
 export type { ViewContextValue } from "./actor-provider-context.js";
 export { useActor } from "./useActor.js";
 export type { AnyPlayActor } from "./useActor.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGjE,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGjG,OAAO,EACN,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,kBAAkB,GAClB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGjE,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGjG,OAAO,EACN,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,kBAAkB,GAClB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -1,8 +1,8 @@
-import { getPlayViewContext } from "./actor-provider-context.js";
+import { getPlayViewContext, usePlayView } from "./actor-provider-context.js";
 import PlayRenderer_default from "./PlayRenderer.js";
 import { useActor } from "./useActor.js";
 import ActorProvider_default from "./ActorProvider.js";
 import PlayUIProvider_default from "./PlayUIProvider.js";
 import { defineRegistry } from "./define-registry.js";
 import { ActionProvider, JSONUIProvider, Renderer, StateProvider, ValidationProvider, VisibilityProvider, useBoundProp, useFieldValidation } from "@xmachines/json-render-vue";
-export { ActionProvider, ActorProvider_default as ActorProvider, JSONUIProvider, PlayRenderer_default as PlayRenderer, PlayUIProvider_default as PlayUIProvider, Renderer, StateProvider, ValidationProvider, VisibilityProvider, defineRegistry, getPlayViewContext, useActor, useBoundProp, useFieldValidation };
+export { ActionProvider, ActorProvider_default as ActorProvider, JSONUIProvider, PlayRenderer_default as PlayRenderer, PlayUIProvider_default as PlayUIProvider, Renderer, StateProvider, ValidationProvider, VisibilityProvider, defineRegistry, getPlayViewContext, useActor, useBoundProp, useFieldValidation, usePlayView };

package/dist/types.d.ts

@@ -1,28 +1,32 @@
 /**
- * TypeScript type definitions for play-vue
+ * The TypeScript type definitions of play-vue
  *
  * @packageDocumentation
  */
 import type { DefineRegistryResult } from "@xmachines/json-render-vue";
 import type { BaseActorProviderProps } from "@xmachines/play-actor";
 /**
- * Props for the ActorProvider component.
- * Extracted to types.ts so TypeScript can re-export without the vue-shim limitation.
+ * The props of the ActorProvider component.
+ * This file holds them, so that TypeScript can re-export them. The vue-shim has a
+ * limit that stops a re-export from the .vue file.
  */
 export interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
 }
 /**
- * Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own props.
+ * The props of PlayUIProvider — every ActorProvider prop, and also the props of JSONUIProvider.
  */
 export type { RenderErrorHandler } from "@xmachines/json-render-vue";
+/**
+ * @deprecated Unused; will be removed in the next major.
+ */
 export interface VisibilityProviderProps {
 }
 export interface PlayUIProviderProps extends ActorProviderProps {
-    /** Navigate function forwarded to JSONUIProvider for link resolution */
+    /** The navigate function. The provider gives it to JSONUIProvider, which resolves each link with it */
     navigate?: (path: string) => void;
-    /** Validation functions forwarded to JSONUIProvider */
+    /** The validation functions. The provider gives them to JSONUIProvider */
     validationFunctions?: Record<string, (value: unknown, args?: Record<string, unknown>) => boolean>;
-    /** Named functions for $computed expressions in props */
+    /** The named functions of a $computed expression in a prop */
     functions?: Record<string, (args?: Record<string, unknown>, state?: Record<string, unknown>) => unknown>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;CAAG;AAE3F;;GAEG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,MAAM,WAAW,uBAAuB;CAAG;AAE3C,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC9D,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,MAAM,CAC3B,MAAM,EACN,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAC3D,CAAC;IACF,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CACjB,MAAM,EACN,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAC5E,CAAC;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;CAAG;AAE3F;;GAEG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,uBAAuB;CAAG;AAE3C,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC9D,uGAAuG;IACvG,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAC3B,MAAM,EACN,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAC3D,CAAC;IACF,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CACjB,MAAM,EACN,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAC5E,CAAC;CACF"}

package/dist/useActor.d.ts

@@ -1,24 +1,27 @@
 /**
- * useActor — Vue composable for accessing the provided actor inside a PlayRenderer tree.
- *
- * Components rendered inside PlayRenderer can call useActor() to reach the actor
- * instance without prop drilling.
- *
- * What is returned is a **swap-following proxy**, not the raw actor object:
- * - It is a stable reference for the lifetime of the injection, yet forwards every
- *   operation (property reads/writes, `in`, `Object.keys` / spread, `instanceof`)
- *   to whichever actor is CURRENTLY provided — so it transparently follows a
- *   `props.actor` swap on `<ActorProvider>` without consumers re-injecting.
- * - Method identity is stable per underlying method: `actor.send === actor.send`
- *   across repeated reads (allocation-free), and rebinds only when the underlying
- *   method changes or the actor is swapped.
- * - It is NOT `===` the `actor` prop passed to `<ActorProvider>` (it is a distinct
- *   Proxy object). Any consumer keyed on actor identity — most notably a router
- *   bridge extending `RouterBridgeBase`, whose one-bridge-per-actor guard keys a
- *   WeakMap on the actor instance — must be given the actor prop itself, not the
- *   value returned by `useActor()`.
- *
- * @throws {Error} If called outside a PlayRenderer tree
+ * useActor — the Vue composable that gives the actor inside a PlayRenderer tree.
+ *
+ * A component inside PlayRenderer calls useActor() to reach the actor instance. The
+ * actor is then not necessary as a prop.
+ *
+ * The composable returns a **proxy that follows a swap**, and not the raw actor
+ * object:
+ * - The proxy is a stable reference for the life of the injection. It forwards
+ *   every operation (a property read, a property write, `in`, `Object.keys`, a
+ *   spread, and `instanceof`) to the actor that the tree provides at that moment.
+ *   Therefore it follows a swap of `props.actor` on `<ActorProvider>`, and a
+ *   consumer does not inject the actor again.
+ * - The identity of each method is stable: `actor.send === actor.send` across
+ *   repeated reads, with no allocation. The proxy binds the method again only when
+ *   the method below it changes, or when the tree provides a different actor.
+ * - The proxy is NOT `===` the `actor` prop of `<ActorProvider>`, because it is a
+ *   separate Proxy object. Therefore give the actor prop itself, and not the value
+ *   of `useActor()`, to each consumer that uses the identity of the actor as a key.
+ *   The most important such consumer is a router bridge that extends
+ *   `RouterBridgeBase`: its guard of one bridge for each actor uses the actor
+ *   instance as the key of a WeakMap.
+ *
+ * @throws {Error} When the caller is outside a PlayRenderer tree
  *
  * @example
  * ```typescript
@@ -33,15 +36,18 @@
 import type { InjectionKey } from "vue";
 import type { AbstractActor } from "@xmachines/play-actor";
 import type { AnyActorLogic } from "xstate";
-/** Bare actor type accepted by Vue context providers. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`. */
+/**
+ * The bare actor type that the Vue context providers accept. For the complete routing and view shape, use `PlayActor` from `@xmachines/play-router`.
+ */
 export type AnyPlayActor = AbstractActor<AnyActorLogic>;
 export declare const ActorKey: InjectionKey<AnyPlayActor>;
 /**
- * Provide the actor to all descendant components via Vue's inject/provide mechanism.
+ * Provides the actor to every descendant component, through the inject and provide
+ * mechanism of Vue.
  *
- * Called inside `PlayRenderer.vue`'s `setup()` to make the actor available to any
- * child component that calls `useActor()`. Not typically needed outside framework
- * internals unless building a custom renderer wrapper.
+ * The `setup()` function of `PlayRenderer.vue` calls it. The actor is then
+ * available to each child component that calls `useActor()`. You need this function
+ * outside the framework internals only when you build your own renderer wrapper.
  *
  * @param actor - The actor instance to inject into the component tree.
  */

package/dist/useActor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useActor.d.ts","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAExC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,2IAA2I;AAC3I,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAExD,eAAO,MAAM,QAAQ,EAAE,YAAY,CAAC,YAAY,CAA6B,CAAC;AAE9E;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEtD;AAED,wBAAgB,QAAQ,IAAI,YAAY,CAEvC"}
+{"version":3,"file":"useActor.d.ts","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAExC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAExD,eAAO,MAAM,QAAQ,EAAE,YAAY,CAAC,YAAY,CAA6B,CAAC;AAE9E;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEtD;AAED,wBAAgB,QAAQ,IAAI,YAAY,CAEvC"}