@xmachines/docs 3.0.0 → 4.0.0

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

@@ -2,9 +2,9 @@
 
 # @xmachines/play-actor
 
-Abstract Actor base class for XMachines Play Architecture.
+The actor contract of the XMachines Play Architecture. It names no state machine library.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
 
 ## Installation
 
@@ -15,285 +15,134 @@ pnpm add @xmachines/play-actor
 **Peer dependencies.** Install them with the package:
 
 ```bash
-pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
+pnpm add @xmachines/play-signals
 ```
 
 ## Overview
 
-`@xmachines/play-actor` gives you `AbstractActor`, a minimal base class. The class extends the XState `Actor` class, and it enforces the **signal protocol** of the Play Architecture (RFC section 5.3). It exposes reactive TC39 Signals for the infrastructure layer. It also keeps the complete compatibility with the XState ecosystem, which includes the devtools and the inspection.
+`@xmachines/play-actor` gives you `PlayActor`, the contract that every layer above reads.
+An actor of XMachines holds exactly two things:
 
-The core protocol is small on purpose:
+| Member  | Type                      | Description                                |
+| ------- | ------------------------- | ------------------------------------------ |
+| `state` | `Signal.State<TSnapshot>` | The reactive snapshot of the current state |
+| `send`  | `(event: TEvent) => void` | The typed event dispatch                   |
 
-| Property | Type                      | Description                              |
-| -------- | ------------------------- | ---------------------------------------- |
-| `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
-| `send`   | `(event: TEvent) => void` | Event dispatch method                    |
+**It is an interface, and no base class.** A state machine library is the concern of an
+adapter, and [`@xmachines/play-xstate`](../play-xstate/README.md) is the adapter of XState
+v5. This package therefore names `xstate` nowhere.
 
-Separate interfaces declare the optional capabilities. A concrete actor implements only the interfaces that it needs:
+The contract was an abstract CLASS that extended `Actor` of `xstate`, and the class carried
+no implementation at all: both of its members were abstract. Its whole effect was to force
+the inheritance of XState on every consumer of the contract, including
+[`@xmachines/play-view`](../play-view/README.md) and
+[`@xmachines/play-router`](../play-router/README.md), which read `currentView`,
+`currentRoute` and `send`, and no other member.
 
-| Interface  | Property                                        | Description                           |
-| ---------- | ----------------------------------------------- | ------------------------------------- |
-| `Routable` | `currentRoute: Signal.Computed<string \| null>` | Current route path derived from state |
-| `Routable` | `initialRoute: string \| null`                  | The route where the actor starts      |
-| `Viewable` | `currentView: Signal.State<PlaySpec \| null>`   | Current JSON-render view spec         |
+### The capabilities are optional, and separate
 
-An adapter, such as [`@xmachines/play-xstate`](../play-xstate/README.md), makes the concrete implementations.
+A capability lives with the package that holds its shared machinery. Neither one implies
+the other, and neither one names an engine.
 
-## API Summary
+| Capability | Interface  | Package                                              | Adds                           |
+| ---------- | ---------- | ---------------------------------------------------- | ------------------------------ |
+| Routing    | `Routable` | [`@xmachines/play-router`](../play-router/README.md) | `currentRoute`, `initialRoute` |
+| View       | `Viewable` | [`@xmachines/play-view`](../play-view/README.md)     | `currentView`                  |
 
-### `AbstractActor<TLogic, TEvent>`
+## API Summary
 
-The abstract base class extends the XState `Actor<TLogic>` class.
+### `PlayActor<TSnapshot, TEvent>`
 
-A subclass **is** the actor. Give the logic and its options to `super()`, so that one
-instance holds the running machine. Reach the `send` method of XState through the
-prototype. This class declares `send` as abstract for one reason only: to narrow the
-event type. TypeScript forbids a `super` call to an abstract member.
+Both type parameters carry their real type through, and neither one erases it.
 
 ```ts
-import { AbstractActor } from "@xmachines/play-actor";
+import type { PlayActor } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
-import { Actor, type ActorOptions, type AnyActorLogic } from "xstate";
 
-class MyActor extends AbstractActor<AnyActorLogic> {
-	// Required: reactive state signal
-	state: Signal.State<unknown>;
+type Snapshot = { readonly value: string };
+type AuthEvent =
+	{ readonly type: "auth.login"; readonly username: string } | { readonly type: "auth.logout" };
 
-	constructor(logic: AnyActorLogic, options?: ActorOptions<AnyActorLogic>) {
-		super(logic, options);
-		this.state = new Signal.State(this.getSnapshot());
-		super.subscribe((snapshot) => this.state.set(snapshot));
-	}
+class AuthActor implements PlayActor<Snapshot, AuthEvent> {
+	readonly state = new Signal.State<Snapshot>({ value: "guest" });
 
-	// Required: typed event dispatch
-	override send(event: { type: string }): void {
-		Actor.prototype.send.call(this, event);
+	send(event: AuthEvent): void {
+		if (event.type === "auth.login") this.state.set({ value: "authenticated" });
 	}
 }
-```
-
-With a typed event union:
-
-```ts
-// imports as in the previous example
-type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
-
-class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
-	state = new Signal.State({ isAuthenticated: false, username: null });
 
-	override send(event: AuthEvent): void {
-		Actor.prototype.send.call(this, event);
-	}
-}
+// The snapshot type reaches the reader, and it is no `unknown`:
+const actor: PlayActor<Snapshot, AuthEvent> = new AuthActor();
+const value: string = actor.state.get().value;
 ```
 
-### `typedSpec(spec)`
-
-This identity helper gives a view-spec literal the type `PlaySpec` at the definition site. The
-XState `meta` field has the type `Record<string, unknown>`. Therefore this helper is the place
-where the spec shape receives the compile-time check and the IDE autocomplete. The helper has no
-cost at run time.
+A plain object satisfies the contract as well. Nothing here asks for a class.
 
 ```ts
-import { typedSpec } from "@xmachines/play-actor";
-
-// In an XState machine meta block:
-meta: {
-  view: typedSpec({
-    root: "root",
-    elements: {
-      root: {
-        type: "Dashboard",
-        props: { username: { $state: "/context/username" } },
-        children: [],
-      },
-    },
-  }),
-}
-```
-
-### `PlaySpec`
-
-This type extends the `Spec` type of `@xmachines/json-render-core`. Each derived view receives
-the complete machine context in its state store, under the read-only **`/context` subtree**. A
-spec therefore reads the context through the ordinary `{ $state: "/context/…" }` grammar: in a
-prop, in a `visible` condition, and in `repeat.statePath`.
-
-`/context` is read-only by design. Nothing can write to it. The machine context changes through
-an event only. A `$bindState` write or a `setState` write under `/context` throws an error, and
-the error names the event to send. This is the model: the bindable ephemeral state is at the
-root of the store, from `spec.state`; the domain state is in the machine, and it changes through
-events that are meaningful and easy to inspect.
-
-The path shows the origin of each value. `/context/params/username` comes from the URL.
-`/context/username` belongs to the machine. One value can never hide the other.
-
-The model projects everything, and this has two consequences. The first consequence is
-**exposure**. The complete context is visible to the client in the view store, which includes a
-debug panel, an inspector, and a validator. The context is a client-side value in each case, so
-keep a secret out of it.
-
-The second consequence is **emission granularity**. The emit gate compares the context field by
-field, at the top level only. Therefore an event that changes any field emits the view again
-with the same `viewKey`. A provider refreshes `/context` in the live store, and it does not seed
-the store again. The component does not remount, and the ephemeral view state and the focus
-stay. However, a new emission is still a render pass in the framework layer. Keep
-high-frequency ephemeral data, such as a draft for each keystroke or a timer, in the view store
-(`spec.state` with `$bindState`) or in a child actor. The domain state belongs in the context. A
-keystroke does not.
-
-```ts
-import type { PlaySpec } from "@xmachines/play-actor";
-
-const spec: PlaySpec = {
-	root: "root",
-	elements: {
-		root: {
-			type: "Profile",
-			props: { username: { $state: "/context/username" } },
-			children: [],
-		},
-	},
+const actor: PlayActor<Snapshot, AuthEvent> = {
+	state: new Signal.State<Snapshot>({ value: "guest" }),
+	send: () => {},
 };
 ```
 
-> Historical note: an earlier version had a `contextProps` field. At first the field drove an
-> implicit prop-enrichment pass. That pass merged the allowlisted context fields and the URL
-> params into the props of every element. We removed it, because it put values into components
-> that never asked for them, and it let URL data from the user hide machine-owned state. The
-> field was then a projection filter for a short time. We removed that filter too, because a
-> limit on what a view can read added machinery without a real problem to solve. Always
-> validate the **derived** view (`actor.currentView.get()`), not the raw `meta.view`. The
-> `state` of the derived spec carries the projection, so a tool such as `validateSpec` sees a
-> spec that is consistent with itself.
+### `ActorEvent`
 
-### `Routable`
+The minimal shape of an event that an actor receives: `{ readonly type: string }`. It is
+the constraint of `TEvent`, and it is the base of `PlayEvent` of
+[`@xmachines/play`](../play/README.md).
 
-Interface for actors that support routing.
+### An actor with a capability
 
-```ts
-import { AbstractActor, type Routable } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
-import type { AnyActorLogic, EventObject } from "xstate";
-
-// Implement in a concrete actor (note: RoutableActor interface is exported from @xmachines/play-router):
-class MyRoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
-	state = new Signal.State<{ path?: string }>({});
-	currentRoute = new Signal.Computed<string | null>(() => this.state.get().path ?? null);
-	initialRoute = "/";
-	override send(event: EventObject): void {
-		/* dispatch */
-	}
-}
-```
-
-### `Viewable`
-
-Interface for actors that expose a renderable view signal.
+A concrete actor implements the contract and the capabilities that it needs. It extends the
+actor class of its own engine, and the contract stays out of the inheritance.
 
 ```ts
-import type { Viewable } from "@xmachines/play-actor";
-import type { PlaySpec } from "@xmachines/play-actor";
+import type { PlayActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
-
-// currentView carries PlaySpec | null
-const signal = new Signal.State<PlaySpec | null>(null);
-const viewable: Viewable = { currentView: signal };
-```
-
-### `BaseActorProviderProps<TRegistry>`
-
-The framework-agnostic base props. Every `ActorProvider` implementation shares them: React, Vue, Solid, and Svelte. Each framework renderer package extends this interface.
-
-```ts
-import type { BaseActorProviderProps } from "@xmachines/play-actor";
-import type { DefineRegistryResult } from "@xmachines/json-render-react";
-
-interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
-	fallback?: React.ReactNode;
-	children: React.ReactNode;
+import { Actor, type AnyActorLogic } from "xstate";
+
+class MyRoutableActor
+	extends Actor<AnyActorLogic>
+	implements PlayActor<unknown, { readonly type: string }>, Routable
+{
+	readonly state = new Signal.State<unknown>({});
+	readonly currentRoute = new Signal.Computed<string | null>(() => null);
+	readonly initialRoute = "/";
 }
 ```
 
-### `BaseViewContextValue<TRegistry>`
-
-The framework-agnostic base of the `ViewContextValue` type in each framework. It holds the `spec`, `handlers`, `registry`, and `store` fields. These fields are identical in React, Vue, Solid, and Svelte.
-
-## Testing
-
-Run the test suite for this package in isolation:
-
-```bash
-# From the package directory
-pnpm test
-
-# From the monorepo root (workspace-scoped)
-pnpm --filter @xmachines/play-actor test
-
-# Watch mode
-pnpm --filter @xmachines/play-actor run test:watch
-```
+[`@xmachines/play-xstate`](../play-xstate/README.md) does exactly this, and it composes
+each capability with `compose(PlayerActor, withRouting, withView)`.
 
 ## Requirements
 
-- **Node.js** `>=22.0.0`
+- **Node.js** `>=24.0.0`
 - **TypeScript** `>=5.7` (strict mode)
 - **ESM only** — `"type": "module"`
 
-@xmachines/play-actor - the abstract Actor base class of the Play Architecture
+@xmachines/play-actor - the actor contract of the Play Architecture
 
-This package gives you AbstractActor, a minimal base class. It extends the XState
-Actor class, and it enforces the signal protocol of the Play Architecture (RFC
-section 5.3).
+The contract is minimal, and it names no engine: `state` and `send`. A state machine
+library is the concern of an adapter, and `@xmachines/play-xstate` is the adapter of
+XState v5.
 
-The core protocol is minimal: state and send. Two interfaces give the optional
-capabilities:
+A capability is optional, and each one lives with the package that holds its shared
+machinery:
 
-- Routable: for an actor with a routing support
-- Viewable: for an actor with a view rendering
+- `Routable`, for an actor with a routing support, is in `@xmachines/play-router`, with
+  the bridge that reads it
+- `Viewable`, for an actor with a view rendering, is in `@xmachines/play-view`, with the
+  view store lifecycle, the context projection and the provider guards
 
-The class keeps the compatibility with the XState ecosystem, such as the
-inspection and the devtools. It also exposes the reactive signals of the
-communication with the infrastructure layer.
+A consumer that needs one capability installs one package, and a consumer that needs
+neither installs neither. Neither capability implies the other.
 
 ## See
 
 [Play RFC](../../../rfc/play.md)
 
-## Classes
-
-- [AbstractActor](classes/AbstractActor.md)
-
 ## Interfaces
 
-- [BaseActorProviderProps](interfaces/BaseActorProviderProps.md)
-- [BaseViewContextValue](interfaces/BaseViewContextValue.md)
-- [FailureLatch](interfaces/FailureLatch.md)
-- [PlaySpec](interfaces/PlaySpec.md)
-- [ReportGuard](interfaces/ReportGuard.md)
-- [ReportGuardMessages](interfaces/ReportGuardMessages.md)
-- [ResolveViewStoreOptions](interfaces/ResolveViewStoreOptions.md)
-- [Routable](interfaces/Routable.md)
-- [Viewable](interfaces/Viewable.md)
-- [ViewInputs](interfaces/ViewInputs.md)
-- [ViewStoreLifecycle](interfaces/ViewStoreLifecycle.md)
-- [ViewStoreResolution](interfaces/ViewStoreResolution.md)
-
-## Variables
-
-- [CONTEXT\_STATE\_KEY](variables/CONTEXT_STATE_KEY.md)
-
-## Functions
-
-- [attachRenderErrorHandler](functions/attachRenderErrorHandler.md)
-- [composePlayState](functions/composePlayState.md)
-- [createFailureLatch](functions/createFailureLatch.md)
-- [createReportGuard](functions/createReportGuard.md)
-- [createViewStoreLifecycle](functions/createViewStoreLifecycle.md)
-- [guardContextWrites](functions/guardContextWrites.md)
-- [refreshContextSubtree](functions/refreshContextSubtree.md)
-- [reuseComposedState](functions/reuseComposedState.md)
-- [sameViewInputs](functions/sameViewInputs.md)
-- [shallowEqualExcept](functions/shallowEqualExcept.md)
-- [toAtomState](functions/toAtomState.md)
-- [typedSpec](functions/typedSpec.md)
+- [ActorEvent](interfaces/ActorEvent.md)
+- [PlayActor](interfaces/PlayActor.md)

package/api/@xmachines/play-actor/interfaces/ActorEvent.md

@@ -0,0 +1,18 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / ActorEvent
+
+# Interface: ActorEvent
+
+Defined in: [play-actor.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-actor/src/play-actor.ts#L38)
+
+The minimal shape of an event that an actor receives.
+
+It is the base of `PlayEvent` of `@xmachines/play`, and this package declares it again
+rather than import it: the constraint must accept the event union of a CONCRETE machine,
+and `PlayEvent` carries `Record<string, unknown>` in its default payload. An interface of
+a union member holds no index signature, so it satisfies that default never.
+
+## Properties
+
+| Property                          | Modifier   | Type     | Defined in                                                                                                             |
+| --------------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-type"></a> `type` | `readonly` | `string` | [play-actor.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-actor/src/play-actor.ts#L39) |

package/api/@xmachines/play-actor/interfaces/PlayActor.md

@@ -0,0 +1,73 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / PlayActor
+
+# Interface: PlayActor\<TSnapshot, TEvent\>
+
+Defined in: [play-actor.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-actor/src/play-actor.ts#L75)
+
+The actor contract of the Play Architecture. It names NO engine.
+
+An actor of XMachines holds exactly two things, and this interface names both: the
+reactive snapshot, and the typed event dispatch. A state machine library is the concern
+of an adapter, and `@xmachines/play-xstate` is the adapter of XState v5.
+
+Both type parameters carry their real type through, and neither one erases it.
+`AbstractActor` declares `Signal.State<unknown>`, so every consumer of a snapshot reads
+`unknown` and asserts its way back.
+
+A capability is optional, and each one lives with the package that holds its shared
+machinery: `Routable` is in `@xmachines/play-router`, and `Viewable` is in
+`@xmachines/play-view`. Neither one names an engine either, and neither one implies the
+other.
+
+## Example
+
+```typescript
+import type { PlayActor } from "@xmachines/play-actor";
+import type { Viewable } from "@xmachines/play-view";
+
+// A renderer reads the view capability and the send of the contract. It names no
+// engine, and it keeps the event union of the machine.
+function mount<TSnapshot, TEvent extends ActorEvent>(
+	actor: PlayActor<TSnapshot, TEvent> & Viewable,
+): void {
+	actor.currentView.get();
+}
+```
+
+## Type Parameters
+
+| Type Parameter                                   | Default type                  | Description                                                                        |
+| ------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------- |
+| `TSnapshot`                                      | `unknown`                     | The type of the snapshot that `state` holds, for example `SnapshotFrom<TMachine>`. |
+| `TEvent` _extends_ [`ActorEvent`](ActorEvent.md) | [`ActorEvent`](ActorEvent.md) | The event union that `send` accepts, for example `EventFromLogic<TMachine>`.       |
+
+## Properties
+
+| Property                            | Modifier   | Type                                                                            | Description                                                                                                                                                                                               | Defined in                                                                                                             |
+| ----------------------------------- | ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-state"></a> `state` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`TSnapshot`\> | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | [play-actor.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-actor/src/play-actor.ts#L82) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-actor.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-actor/src/play-actor.ts#L90)
+
+Sends an event to the actor.
+
+`TEvent` gives the type safety: a concrete adapter binds it to the event union of its
+own machine, and the compiler then refuses an event that the machine does not declare.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `TEvent` |
+
+#### Returns
+
+`void`

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

@@ -4,7 +4,7 @@
 
 Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -15,14 +15,15 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
+pnpm add @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
 ```
 
 ## Quick Start
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withView } from "@xmachines/play-xstate/view";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { createMachine } from "xstate";
 import { z } from "zod";
@@ -82,7 +83,8 @@ const machine = createMachine({
 		},
 	},
 });
-const actor = definePlayer({ machine })();
+// `mount` needs the view capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withView) })();
 actor.start();
 
 // 5. Mount when actor and container are ready
@@ -364,34 +366,32 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 | Export                                   | Kind     | Description                                                         |
 | ---------------------------------------- | -------- | ------------------------------------------------------------------- |
 | `createRenderer(catalog, components)`    | function | The one-call factory. Its `mount` hands a `Cleanup` back            |
-| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `DisposablePlayUI`               |
+| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                        |
 | `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle |
 | `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers             |
 | `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                              |
 | `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()` |
-| `Cleanup`                                | type     | The release a mount returns, re-exported from `@xmachines/play`     |
+| `asCleanup`, `Cleanup`                   | —        | The release a mount returns, re-exported from `@xmachines/play`     |
 
 ### Key Types
 
-| Type                     | Description                                                                                   |
-| ------------------------ | --------------------------------------------------------------------------------------------- |
-| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                      |
-| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`       |
-| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                          |
-| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound` |
-| `SetState`               | State updater: `(prev => next) => void`                                                       |
-| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`            |
-| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`, adds `fallback` and `onError`       |
-| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback` and `onError`       |
-| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                           |
-| `MountFn`                | The type of a mount that a consumer writes: `(actor, container, options?) → disconnect`       |
-| `DisposablePlayUI`       | The mount that `createPlayUI` builds. It hands a `Cleanup` back, so `using` releases it       |
-| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`               |
-| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                               |
-| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                     |
-| `DomSchema`              | Type of the `schema` export                                                                   |
-| `ComputedFunction`       | The type of a named compute function for the `functions` option                               |
-| `Cleanup`                | The release of a mount, re-exported from `@xmachines/play`                                    |
+| Type                     | Description                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                                      |
+| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`                       |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                                          |
+| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound`                 |
+| `SetState`               | State updater: `(prev => next) => void`                                                                       |
+| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`                            |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`, adds `fallback` and `onError`                       |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback` and `onError`                       |
+| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                                           |
+| `MountFn`                | The mount: `(actor, container, options?) → Cleanup`. `createPlayUI` returns one, and a consumer may write one |
+| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`                               |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                                               |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                                     |
+| `DomSchema`              | Type of the `schema` export                                                                                   |
+| `Cleanup`                | The release of a mount, re-exported from `@xmachines/play`                                                    |
 
 ## Rendering Behavior
 
@@ -401,18 +401,6 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 - **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
 - **`disconnect()` clears the container** and cancels every signal watcher and store watcher.
 
-## Testing
-
-```bash
-# Run all tests (jsdom environment)
-pnpm test
-
-# Run with coverage
-pnpm run test:coverage
-```
-
-The tests are in `test/`. They use [Vitest](https://vitest.dev/) in a jsdom environment. The coverage thresholds are 80% for lines, functions, branches, and statements.
-
 @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
 
 The public API has two layers:
@@ -420,9 +408,9 @@ The public API has two layers:
 **The XMachines layer**, in this package:
 
 - `createRenderer()` — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
-- `createPlayUI()` — the complete factory, with every option. It returns a `DisposablePlayUI`
+- `createPlayUI()` — the complete factory, with every option. It returns a `MountFn`
 - `PlayRenderer` — the renderer class, with a `connect()` and `disconnect()` lifecycle
-- `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `DisposablePlayUI`, `MountOptions`
+- `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
 
 **The json-render layer**, re-exported from @xmachines/json-render-dom:
 
@@ -468,7 +456,6 @@ The public API has two layers:
 - [ComponentRegistry](type-aliases/ComponentRegistry.md)
 - [ConfirmHandler](type-aliases/ConfirmHandler.md)
 - [DefineRegistryOptions](type-aliases/DefineRegistryOptions.md)
-- [DisposablePlayUI](type-aliases/DisposablePlayUI.md)
 - [DomComponentRenderer](type-aliases/DomComponentRenderer.md)
 - [DomRegistry](type-aliases/DomRegistry.md)
 - [DomSchema](type-aliases/DomSchema.md)
@@ -482,6 +469,7 @@ The public API has two layers:
 
 ## Functions
 
+- [asCleanup](functions/asCleanup.md)
 - [createPlayUI](functions/createPlayUI.md)
 - [createRenderer](functions/createRenderer.md)
 - [createValidationRegistry](functions/createValidationRegistry.md)