@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/{play-actor → play/index}/functions/shallowEqualExcept.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-actor](../README.md) / shallowEqualExcept
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / shallowEqualExcept
 
 # Function: shallowEqualExcept()
 
@@ -6,7 +6,7 @@
 function shallowEqualExcept(a, b, except?): boolean;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/context-projection.ts#L58)
+Defined in: [packages/play/src/utils.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/utils.ts#L59)
 
 The shallow equality of the own keys, with `Object.is`. It can ignore one key on
 both sides.
@@ -14,7 +14,7 @@ both sides.
 This is the one comparison rule behind every decision of the emission dedup: the
 equality of a slice, and also the emit gate of the player, which compares the
 spec fields in `viewSpecsEquivalent` and reuses the composed state in
-[reuseComposedState](reuseComposedState.md).
+`reuseComposedState` of `@xmachines/play-view`.
 
 ## Parameters
 

package/api/@xmachines/play/index/type-aliases/Cleanup.md

@@ -0,0 +1,38 @@
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / Cleanup
+
+# Type Alias: Cleanup
+
+```ts
+type Cleanup = () => void & { [Key in DisposeKey]: () => void };
+```
+
+Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L66)
+
+The release of a subscription. A caller runs it, or a scope releases it.
+
+The type is a function AND a `Disposable`, so one value serves both forms. A caller
+that holds the release in a field and runs it from a teardown keeps that code. A
+caller inside one scope writes `using` and writes no teardown at all:
+
+```ts
+// The explicit form. It stays correct.
+const stop = watchSignal(count, render);
+stop();
+
+// The scoped form. The scope releases it, and an exception releases it too.
+{
+	using stop = watchSignal(count, render);
+	render(count.get());
+}
+```
+
+`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
+`"lib": ["ESNext"]` of the consumer. The publishable packages build at
+`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
+how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
+still calls it as a function, and a consumer that declares a lower `lib` still reads
+the type. See [DisposeKey](DisposeKey.md) for the second half of that.
+
+## See
+
+[Play RFC](../../../../../rfc/play.md)

package/api/@xmachines/play/index/type-aliases/DisposeKey.md

@@ -0,0 +1,32 @@
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DisposeKey
+
+# Type Alias: DisposeKey
+
+```ts
+type DisposeKey = SymbolConstructor extends object ? Key : never;
+```
+
+Defined in: [packages/play/src/disposable.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L34)
+
+The dispose key of the ambient library, and `never` where the consumer omits it.
+
+`Symbol.dispose` and the `Disposable` interface arrive with `lib.esnext.disposable`. A
+consumer gets that library from `"lib": ["ESNext"]`, and NOT from `"lib": ["ES2022"]`
+or `["ES2023"]`. A published `.d.ts` that names either one therefore refuses to
+type-check for every consumer of the second kind, and this package cannot ask for the
+library on their behalf: TypeScript copies no `/// <reference lib="..." />` into
+declaration output.
+
+The conditional asks the compiler instead of naming the key. Where the library is
+present the key resolves to `typeof Symbol.dispose`, and [Cleanup](Cleanup.md) is a
+`Disposable` that a `using` declaration accepts. Where the library is absent the key
+resolves to `never`, the mapped type of [Cleanup](Cleanup.md) adds no member, and `Cleanup`
+IS the plain `() => void` that these functions returned before this protocol existed.
+That consumer loses nothing, because `using` is syntax that the same library gates: a
+compiler that cannot name `Symbol.dispose` cannot compile the form either.
+
+The runtime is not involved. [asCleanup](../functions/asCleanup.md) stores the release under [DISPOSE](../variables/DISPOSE.md)
+whatever the consumer declares, so one build serves both.
+
+The type is exported because the published `.d.ts` names it, and a reader who asks why
+[Cleanup](Cleanup.md) carries no dispose member needs to reach the answer.

package/api/@xmachines/play/{type-aliases → index/type-aliases}/PlayEvent.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / PlayEvent
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / PlayEvent
 
 # Type Alias: PlayEvent\<TPayload\>
 
@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/types.ts#L71)
+Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/types.ts#L71)
 
 The generic event type of the Play Architecture
 
@@ -35,7 +35,7 @@ and of the other state machine libraries.
 
 | Name   | Type     | Defined in                                                                                                               |
 | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/types.ts#L72) |
+| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/types.ts#L72) |
 
 ## Type Parameters
 
@@ -79,4 +79,4 @@ const invalid: LoginEvent = { type: "auth.login" }; // Error!
 
 ## See
 
-[Play RFC](../../../../rfc/play.md)
+[Play RFC](../../../../../rfc/play.md)

package/api/@xmachines/play/index/variables/DISPOSE.md

@@ -0,0 +1,34 @@
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DISPOSE
+
+# Variable: DISPOSE
+
+```ts
+const DISPOSE: DisposeKey;
+```
+
+Defined in: [packages/play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L94)
+
+The key that a release is stored under.
+
+`Symbol.dispose` where the runtime has it, and `Symbol.for("Symbol.dispose")` where it
+does not. This is not a convenience — it is the difference between a `using` that
+releases and one that raises.
+
+A bundler that downlevels `using` for a target below Chrome 134 emits a helper that
+reads `object[Symbol.dispose || Symbol.for("Symbol.dispose")]`. A release stored under
+a bare `[Symbol.dispose]` lands on the string key `"undefined"` in that runtime,
+because the well-known symbol is absent and the computed key takes the value
+`undefined`. The helper then looks up the registered symbol, finds nothing, and throws
+`TypeError: Object is not disposable`. Storing under the same fallback closes the gap.
+
+The type assertion states what the fallback IS. `Symbol.for` returns a plain `symbol`,
+TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
+a `unique symbol` other than the declaration itself.
+
+This binding resolves ONE time, when the module evaluates. [asCleanup](../functions/asCleanup.md) therefore
+reads `Symbol.dispose` again at each call and stores the release under both keys, so a
+polyfill that installs the well-known symbol after this module evaluates still finds
+the release. A class or an object literal that writes `[DISPOSE]()` has no such second
+chance: it carries the key that existed when it was defined. Install an Explicit
+Resource Management polyfill before the first import of `@xmachines/play`, which is the
+ordinary contract of a polyfill.

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-2.2.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,278 +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)
-- [PlaySpec](interfaces/PlaySpec.md)
-- [ResolveViewStoreOptions](interfaces/ResolveViewStoreOptions.md)
-- [Routable](interfaces/Routable.md)
-- [Viewable](interfaces/Viewable.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)
-- [createViewStoreLifecycle](functions/createViewStoreLifecycle.md)
-- [guardContextWrites](functions/guardContextWrites.md)
-- [refreshContextSubtree](functions/refreshContextSubtree.md)
-- [reuseComposedState](functions/reuseComposedState.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`