@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,23 +2,21 @@
 
 # `@xmachines/play-vue`
 
-> Vue 3 renderer for the XMachines Play Architecture — passively observes actor signals and renders UI via `@xmachines/json-render-vue`.
+> Vue 3 renderer for the XMachines Play Architecture. It observes the actor signals and renders the UI through `@xmachines/json-render-vue`.
 
-Part of the [XMachines Play monorepo](../../README.md).
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-vue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-vue)
 
 ---
 
 ## Overview
 
-`@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`.
+`@xmachines/play-vue` is the Vue 3 rendering layer of XMachines Play. It connects the TC39 Signals (the actor state) to the Vue reactivity, and it renders the components through `@xmachines/json-render-vue`.
 
-**Architecture invariants this package upholds:**
+**The architecture invariants that this package keeps:**
 
-- **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.
+- **Passive Infrastructure** — the components observe the actor signals. They never decide a state transition.
+- **Signal-Only Reactivity** — the TC39 Signals are the source of truth. Vue reactivity only triggers the re-render.
+- **Actor Authority** — the actor controls the view selection. The renderer reflects it.
 
 ---
 
@@ -28,7 +26,7 @@ Part of the [XMachines Play monorepo](../../README.md).
 pnpm add @xmachines/play-vue
 ```
 
-**Peer dependencies** (install alongside):
+**Peer dependencies.** Install them with the package:
 
 ```bash
 pnpm add vue@^3.5.0 xstate@^5.31.0 @xstate/store@^3.17.0 @xmachines/json-render-vue@^0.20.0-xm.2 @xmachines/json-render-core@^0.20.0-xm.2 @xmachines/json-render-xstate@^0.20.0-xm.2
@@ -79,7 +77,7 @@ const registryResult = defineRegistry(myCatalog, {
 
 #### `<PlayUIProvider>`
 
-Batteries-included composite provider. Wraps `<ActorProvider>` and `JSONUIProvider` in one component. **Recommended for most apps.**
+The composite provider. It wraps `<ActorProvider>` and `JSONUIProvider` in one component. **Use it in most applications.**
 
 | Prop                  | Type                       | Required | Description                                 |
 | --------------------- | -------------------------- | -------- | ------------------------------------------- |
@@ -91,11 +89,11 @@ Batteries-included composite provider. Wraps `<ActorProvider>` and `JSONUIProvid
 | `validationFunctions` | `Record<string, Function>` | —        | Custom validation functions                 |
 | `functions`           | `Record<string, Function>` | —        | Named functions for `$computed` expressions |
 
-**Slots:** `default` (rendered content), `fallback` (shown while actor view is `null`)
+**Slots:** `default` (the rendered content), `fallback` (the content while the actor view is `null`)
 
 #### `<PlayRenderer>`
 
-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.
+The leaf component without props. It reads the current `spec` and `registry` from the nearest `<ActorProvider>` or `<PlayUIProvider>` context, then renders them with `<Renderer>`. Put it inside one of those providers.
 
 ```vue
 <PlayUIProvider :actor="actor" :registryResult="registryResult">
@@ -105,7 +103,7 @@ Zero-prop leaf component. Reads the current `spec` and `registry` from the neare
 
 #### `<ActorProvider>`
 
-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.
+The low-level provider for a custom provider composition. It owns the complete actor lifecycle: the signal subscription, the state store of each view, the handler resolution, and the Vue context. Use `<PlayUIProvider>` when you do not need this control.
 
 | Prop             | Type                       | Required | Description                     |
 | ---------------- | -------------------------- | -------- | ------------------------------- |
@@ -120,33 +118,34 @@ Low-level escape hatch for custom provider composition. Owns the full actor life
 
 #### `defineRegistry(catalog, options)`
 
-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>`.
+This function is the drop-in replacement for `defineRegistry` from `@xmachines/json-render-vue`. **Always import it from `@xmachines/play-vue`** when you work with a Vue SFC, not from `@xmachines/json-render-vue`. The wrapper finds each `.vue` SFC in the `components` map, and wraps it with `h()`. A Vue composable, and also a composable that uses `inject`, then works correctly inside `<script setup>`.
 
 ```typescript
 import { defineRegistry } from "@xmachines/play-vue";
 // NOT: import { defineRegistry } from "@xmachines/json-render-vue"
 
+import { myCatalog } from "./catalog.js"; // as in the Quick Start
 import LoginSFC from "./views/Login.vue";
 import DashboardSFC from "./views/Dashboard.vue";
 
-const registryResult = defineRegistry(catalog, {
+const registryResult = defineRegistry(myCatalog, {
 	components: {
 		Login: LoginSFC, // .vue SFC — auto-wrapped via h()
 		Dashboard: DashboardSFC,
 	},
 	actions: {
-		login: async (args, setState, getState) => {
+		login: async (args, setState, state) => {
 			/* ... */
 		},
 	},
 });
 ```
 
-Plain `ComponentFn` functions (non-SFC) also 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.
 
 #### `useActor()`
 
-Vue composable for accessing the raw actor inside a `PlayRenderer` tree. Avoids prop drilling for deeply nested components.
+The Vue composable that gives the raw actor inside a `PlayRenderer` tree. A deeply nested component then does not need the actor as a prop.
 
 ```typescript
 import { useActor } from "@xmachines/play-vue";
@@ -156,25 +155,27 @@ const actor = useActor();
 actor.send({ type: "SUBMIT" });
 ```
 
-Throws if called outside an `<ActorProvider>` or `<PlayUIProvider>` tree.
+It throws when the caller is outside an `<ActorProvider>` or a `<PlayUIProvider>` tree.
 
-#### `getPlayViewContext()`
+#### `usePlayView()`
 
 Access the current `ViewContextValue` — `{ spec, handlers, registry, store }` — from inside an `<ActorProvider>` tree.
 
 ```typescript
-import { getPlayViewContext } from "@xmachines/play-vue";
+import { usePlayView } from "@xmachines/play-vue";
 
 // Inside setup() of a component within an ActorProvider tree:
-const view = getPlayViewContext();
+const view = usePlayView();
 // view.spec, view.handlers, view.registry, view.store
 ```
 
+> **Note:** `usePlayView` was previously named `getPlayViewContext`. The old name is still exported as a deprecated alias and will be removed in the next major.
+
 ---
 
 ### Re-exported from `@xmachines/json-render-vue`
 
-The following are re-exported so consumers import everything from `@xmachines/play-vue`:
+This package re-exports the following, so that a consumer imports everything from `@xmachines/play-vue`:
 
 **Components:** `JSONUIProvider`, `StateProvider`, `ActionProvider`, `VisibilityProvider`, `ValidationProvider`, `Renderer`
 
@@ -199,7 +200,7 @@ pnpm --filter @xmachines/play-vue run test:watch
 pnpm exec vitest run --coverage --config packages/play-vue/vitest.config.ts
 ```
 
-Tests use [Vitest](https://vitest.dev/) with `jsdom` environment and `@vue/test-utils` for component mounting.
+The tests use [Vitest](https://vitest.dev/) in a `jsdom` environment. They mount the components with `@vue/test-utils`.
 
 ---
 
@@ -207,16 +208,16 @@ Tests use [Vitest](https://vitest.dev/) with `jsdom` environment and `@vue/test-
 
 MIT — see [LICENSE](LICENSE).
 
-@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`.
 
 ## Interfaces
 
@@ -230,7 +231,7 @@ so consumers import everything from `@xmachines/play-vue` rather than
 - [StateProviderProps](interfaces/StateProviderProps.md)
 - [ValidationProviderProps](interfaces/ValidationProviderProps.md)
 - [ViewContextValue](interfaces/ViewContextValue.md)
-- [VisibilityProviderProps](interfaces/VisibilityProviderProps.md)
+- [~~VisibilityProviderProps~~](interfaces/VisibilityProviderProps.md)
 
 ## Type Aliases
 
@@ -244,6 +245,7 @@ so consumers import everything from `@xmachines/play-vue` rather than
 ## Variables
 
 - [ActionProvider](variables/ActionProvider.md)
+- [~~getPlayViewContext~~](variables/getPlayViewContext.md)
 - [JSONUIProvider](variables/JSONUIProvider.md)
 - [PlayRenderer](variables/PlayRenderer.md)
 - [Renderer](variables/Renderer.md)
@@ -254,10 +256,10 @@ so consumers import everything from `@xmachines/play-vue` rather than
 ## Functions
 
 - [defineRegistry](functions/defineRegistry.md)
-- [getPlayViewContext](functions/getPlayViewContext.md)
 - [useActor](functions/useActor.md)
 - [useBoundProp](functions/useBoundProp.md)
 - [useFieldValidation](functions/useFieldValidation.md)
+- [usePlayView](functions/usePlayView.md)
 
 ## References
 

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

@@ -6,13 +6,14 @@
 function defineRegistry<C>(catalog, options): DefineRegistryResult;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/define-registry.ts#L131)
+Defined in: [packages/play-vue/src/define-registry.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/define-registry.ts#L138)
 
-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.
 
 ## Type Parameters
 
@@ -22,10 +23,10 @@ Drop-in replacement for `defineRegistry` from `@xmachines/json-render-vue`. Impo
 
 ## 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. |
+| Parameter | Type                                                                       | Description                                                                                                                                     |
+| --------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `catalog` | `C`                                                                        | The json-render catalog. It defines the prop shape of each component.                                                                           |
+| `options` | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> | The registry options. Each `components` entry is a `.vue` SFC, which is an object, or a plain `ComponentFn` function. The wrapper handles both. |
 
 ## Returns
 

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

@@ -6,7 +6,7 @@
 function useActor(): AnyPlayActor;
 ```
 
-Defined in: [packages/play-vue/src/useActor.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/useActor.ts#L58)
+Defined in: [packages/play-vue/src/useActor.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/useActor.ts#L64)
 
 ## Returns
 

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

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-vue](../README.md) / usePlayView
+
+# Function: usePlayView()
+
+```ts
+function usePlayView(): ViewContextValue;
+```
+
+Defined in: [packages/play-vue/src/actor-provider-context.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/actor-provider-context.ts#L46)
+
+Returns the current ViewContextValue inside an ActorProvider tree.
+
+## Returns
+
+[`ViewContextValue`](../interfaces/ViewContextValue.md)
+
+## Throws
+
+When the caller is outside an <ActorProvider> tree or a <PlayUIProvider> tree
+
+## Example
+
+```typescript
+import { usePlayView } from "@xmachines/play-vue";
+
+const view = usePlayView();
+// view.spec, view.handlers, view.registry
+```

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

@@ -2,10 +2,11 @@
 
 # Interface: ActorProviderProps
 
-Defined in: [packages/play-vue/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L14)
+Defined in: [packages/play-vue/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L15)
 
-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.
 
 ## Extends
 
@@ -17,9 +18,9 @@ Extracted to types.ts so TypeScript can re-export without the vue-shim limitatio
 
 ## Properties
 
-| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                               |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L156) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L169) |
-| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L158) |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L164) |
+| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                               |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | The actor instance with the currentView signal. It requires the Viewable capability.                                                                                                                                                                                              | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L163) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                             | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L177) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                  | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L165) |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L172) |

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

@@ -2,10 +2,11 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-vue/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L25)
+Defined in: [packages/play-vue/src/types.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L29)
 
-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.
 
 ## Extends
 
@@ -13,12 +14,12 @@ Extracted to types.ts so TypeScript can re-export without the vue-shim limitatio
 
 ## Properties
 
-| Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                  | Defined in                                                                                                                                               |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L156) |
-| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, (`args?`, `state?`) => `unknown`\>                                                                                                                                                                                                           | Named functions for $computed expressions in props                                                                                                                                                                          | -                                                                                                               | [packages/play-vue/src/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L34)                         |
-| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigate function forwarded to JSONUIProvider for link resolution                                                                                                                                                           | -                                                                                                               | [packages/play-vue/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L27)                         |
-| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L169) |
-| <a id="property-registryresult"></a> `registryResult`            | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L158) |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L164) |
-| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | Validation functions forwarded to JSONUIProvider                                                                                                                                                                            | -                                                                                                               | [packages/play-vue/src/types.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L29)                         |
+| Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                       | Inherited from                                                                                                  | Defined in                                                                                                                                               |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | The actor instance with the currentView signal. It requires the Viewable capability.                                                                                                                                                                                              | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L163) |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, (`args?`, `state?`) => `unknown`\>                                                                                                                                                                                                           | The named functions of a $computed expression in a prop                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-vue/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L38)                         |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | The navigate function. The provider gives it to JSONUIProvider, which resolves each link with it                                                                                                                                                                                  | -                                                                                                               | [packages/play-vue/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L31)                         |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L177) |
+| <a id="property-registryresult"></a> `registryResult`            | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                  | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L165) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L172) |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | The validation functions. The provider gives them to JSONUIProvider                                                                                                                                                                                                               | -                                                                                                               | [packages/play-vue/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L33)                         |

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

@@ -2,10 +2,11 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-vue/src/actor-provider-context.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/actor-provider-context.ts#L21)
+Defined in: [packages/play-vue/src/actor-provider-context.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/actor-provider-context.ts#L23)
 
-Context value provided by ActorProvider and consumed by PlayRenderer (zero-prop leaf).
-Accessible via getPlayViewContext() inside any ActorProvider/PlayUIProvider tree.
+The context value that ActorProvider provides and PlayRenderer, the leaf without
+props, reads. usePlayView() gives it inside every ActorProvider tree and
+PlayUIProvider tree.
 
 ## Extends
 
@@ -13,9 +14,9 @@ Accessible via getPlayViewContext() inside any ActorProvider/PlayUIProvider tree
 
 ## Properties
 
-| Property                                  | Type                                                  | Description                                                                                               | Inherited from                                                                                                                                                    | Defined in                                                                                                                                               |
-| ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L124) |
-| <a id="property-registry"></a> `registry` | `TRegistry`                                           | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L126) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L122) |
-| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L128) |
+| Property                                  | Type                                                  | Description                                                                                                            | Inherited from                                                                                                                                                    | Defined in                                                                                                                                               |
+| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | The action handlers, resolved against the live StateStore.                                                             | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                                           | The component registry, from registryResult.registry.                                                                  | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L129) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                                        | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L133) |

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

@@ -1,5 +1,9 @@
 [API](../../../README.md) / [@xmachines/play-vue](../README.md) / VisibilityProviderProps
 
-# Interface: VisibilityProviderProps
+# ~~Interface: VisibilityProviderProps~~
 
-Defined in: [packages/play-vue/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/types.ts#L23)
+Defined in: [packages/play-vue/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/types.ts#L27)
+
+## Deprecated
+
+Unused; will be removed in the next major.

package/api/@xmachines/play-vue/type-aliases/AnyPlayActor.md

@@ -6,6 +6,6 @@
 type AnyPlayActor = AbstractActor<AnyActorLogic>;
 ```
 
-Defined in: [packages/play-vue/src/useActor.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/useActor.ts#L41)
+Defined in: [packages/play-vue/src/useActor.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/useActor.ts#L46)
 
-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`.

package/api/@xmachines/play-vue/type-aliases/ComponentEntry.md

@@ -6,7 +6,7 @@
 type ComponentEntry<C, K> = ComponentFn<C, K> | Component;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/define-registry.ts#L105)
+Defined in: [packages/play-vue/src/define-registry.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/define-registry.ts#L111)
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/type-aliases/ComponentsMap.md

@@ -6,7 +6,7 @@
 type ComponentsMap<C> = { [K in keyof InferCatalogComponents<C>]?: ComponentEntry<C, K> };
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:109](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/define-registry.ts#L109)
+Defined in: [packages/play-vue/src/define-registry.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/define-registry.ts#L115)
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/type-aliases/DefineRegistryOptions.md

@@ -7,13 +7,13 @@ type DefineRegistryOptions<C> = Omit<Parameters<typeof defineRegistryBase>[1], "
 	object;
 ```
 
-Defined in: [packages/play-vue/src/define-registry.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/define-registry.ts#L113)
+Defined in: [packages/play-vue/src/define-registry.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/define-registry.ts#L119)
 
 ## Type Declaration
 
 | Name          | Type                                       | Defined in                                                                                                                                             |
 | ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `components?` | [`ComponentsMap`](ComponentsMap.md)\<`C`\> | [packages/play-vue/src/define-registry.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/define-registry.ts#L117) |
+| `components?` | [`ComponentsMap`](ComponentsMap.md)\<`C`\> | [packages/play-vue/src/define-registry.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/define-registry.ts#L123) |
 
 ## Type Parameters
 

package/api/@xmachines/play-vue/variables/PlayRenderer.md

@@ -6,4 +6,4 @@
 const PlayRenderer: DefineComponent<{}, {}, unknown>;
 ```
 
-Defined in: [packages/play-vue/src/vue-shim.d.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/vue-shim.d.ts#L3)
+Defined in: [packages/play-vue/src/vue-shim.d.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/vue-shim.d.ts#L3)

package/api/@xmachines/play-vue/variables/getPlayViewContext.md

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-vue](../README.md) / getPlayViewContext
+
+# ~~Variable: getPlayViewContext~~
+
+```ts
+const getPlayViewContext: () => ViewContextValue = usePlayView;
+```
+
+Defined in: [packages/play-vue/src/actor-provider-context.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-vue/src/actor-provider-context.ts#L55)
+
+Access the current ViewContextValue from inside an ActorProvider tree.
+
+Returns the current ViewContextValue inside an ActorProvider tree.
+
+## Returns
+
+[`ViewContextValue`](../interfaces/ViewContextValue.md)
+
+## Throws
+
+When the caller is outside an <ActorProvider> tree or a <PlayUIProvider> tree
+
+## Example
+
+```typescript
+import { usePlayView } from "@xmachines/play-vue";
+
+const view = usePlayView();
+// view.spec, view.handlers, view.registry
+```
+
+## Deprecated
+
+Renamed to [usePlayView](../functions/usePlayView.md); will be removed in the next major.