@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -6,50 +6,51 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/types.ts#L69)
+Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/types.ts#L71)
 
-Generic event type for Play Architecture
+The generic event type of the Play Architecture
 
-PlayEvent represents the minimal event contract for Actor communication: any object
-with a `type` string property. Infrastructure forwards events to the Actor, and the
-Actor's state machine guards determine validity.
+PlayEvent is the minimal event contract of the Actor communication: it is every
+object with a `type` string property. The infrastructure sends each event to the
+Actor, and the guards of the Actor state machine decide the validity.
 
-**Type Parameter:** The generic `TPayload` allows specifying the shape of additional
-event fields beyond `type`. It defaults to `Record<string, unknown>` for maximum flexibility.
+**The type parameter:** the generic `TPayload` gives the shape of the event fields
+after `type`. Its default is `Record<string, unknown>`, which accepts each shape.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** where
-infrastructure reflects user actions as events without making decisions. The Actor's
-state machine guards determine whether each event is valid from the current state.
+**Architectural context:** the type implements **Passive Infrastructure
+(INV-04)**. The infrastructure converts each user action into an event, and it
+makes no decision. The guards of the Actor state machine decide if each event is
+valid in the current state.
 
-**Framework Agnostic:** This type is intentionally generic and not tied to any
-specific state machine framework. It matches the common event shape used by XState,
-Robot, and other state machine libraries.
+**Framework-agnostic:** this type is generic on purpose, and it is bound to no
+state machine framework. It matches the common event shape of XState, of Robot,
+and of the other state machine libraries.
 
-**Common Event Types:**
+**The common event types:**
 
-- Domain events: `{ type: 'auth.login', userId: '123' }`
-- Custom events: `{ type: 'form.submit', data: {...} }`
+- A domain event: `{ type: 'auth.login', userId: '123' }`
+- Your own event: `{ type: 'form.submit', data: {...} }`
 
 ## Type Declaration
 
 | Name   | Type     | Defined in                                                                                                               |
 | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/types.ts#L70) |
+| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/types.ts#L72) |
 
 ## Type Parameters
 
-| Type Parameter                                       | Default type                    | Description                                                             |
-| ---------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
-| `TPayload` _extends_ `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> | Additional fields beyond `type` (defaults to `Record<string, unknown>`) |
+| Type Parameter                                       | Default type                    | Description                                                       |
+| ---------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
+| `TPayload` _extends_ `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> | The fields after `type`. The default is `Record<string, unknown>` |
 
 ## Examples
 
-Using without type parameter (flexible)
+The use without the type parameter, which is flexible
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
 
-// Accepts any event with type: string
+// It accepts every event with type: string
 const loginEvent: PlayEvent = {
 	type: "auth.login",
 	userId: "user123",
@@ -58,12 +59,12 @@ const loginEvent: PlayEvent = {
 actor.send(loginEvent);
 ```
 
-Using with type parameter (type-safe)
+The use with the type parameter, which is type-safe
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
 
-// Type-safe event with known shape
+// A type-safe event with a known shape
 type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 
 const loginEvent: LoginEvent = {
@@ -72,7 +73,7 @@ const loginEvent: LoginEvent = {
 	timestamp: Date.now(),
 };
 
-// TypeScript error: missing required field
+// A TypeScript error: a necessary field is absent
 const invalid: LoginEvent = { type: "auth.login" }; // Error!
 ```
 

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

@@ -4,9 +4,7 @@
 
 Abstract Actor base class for XMachines Play Architecture.
 
-[![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-actor)
-
-Part of the [xmachines-js 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.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-actor
 ```
 
-**Peer dependencies** — install alongside the package:
+**Peer dependencies.** Install them with the package:
 
 ```bash
 pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
@@ -22,35 +20,35 @@ pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-c
 
 ## Overview
 
-`@xmachines/play-actor` provides `AbstractActor`, a minimal base class that extends the XState `Actor` class while enforcing the Play Architecture's **signal protocol** (RFC section 5.3). It exposes reactive TC39 Signals for infrastructure-layer communication while preserving full XState ecosystem compatibility (devtools, inspection).
+`@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.
 
-The core protocol is deliberately minimal:
+The core protocol is small on purpose:
 
 | Property | Type                      | Description                              |
 | -------- | ------------------------- | ---------------------------------------- |
 | `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
 | `send`   | `(event: TEvent) => void` | Event dispatch method                    |
 
-Optional capabilities are declared as separate interfaces — a concrete actor opts in only to what it needs:
+Separate interfaces declare the optional capabilities. A concrete actor implements only the interfaces that it needs:
 
 | Interface  | Property                                        | Description                           |
 | ---------- | ----------------------------------------------- | ------------------------------------- |
 | `Routable` | `currentRoute: Signal.Computed<string \| null>` | Current route path derived from state |
-| `Routable` | `initialRoute: string \| null`                  | Route the actor starts on             |
+| `Routable` | `initialRoute: string \| null`                  | The route where the actor starts      |
 | `Viewable` | `currentView: Signal.State<PlaySpec \| null>`   | Current JSON-render view spec         |
 
-Concrete implementations are created by adapters such as [`@xmachines/play-xstate`](../play-xstate/README.md).
+An adapter, such as [`@xmachines/play-xstate`](../play-xstate/README.md), makes the concrete implementations.
 
 ## API Summary
 
 ### `AbstractActor<TLogic, TEvent>`
 
-Abstract base class extending XState `Actor<TLogic>`.
+The abstract base class extends the XState `Actor<TLogic>` class.
 
-A subclass **is** the actor: hand the logic and its options to `super()` so one
-instance holds the running machine, and reach XState's own `send` through the
-prototype — `send` is declared abstract here only to narrow the event type, and
-TypeScript forbids `super` calls to an abstract member.
+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.
 
 ```ts
 import { AbstractActor } from "@xmachines/play-actor";
@@ -77,6 +75,7 @@ class MyActor extends AbstractActor<AnyActorLogic> {
 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> {
@@ -90,9 +89,10 @@ class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
 
 ### `typedSpec(spec)`
 
-Identity helper that types a view-spec literal as `PlaySpec` at the definition site. XState's
-`meta` field is `Record<string, unknown>`, so this is where the spec shape gets compile-time
-validation and IDE autocomplete — without any runtime cost.
+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.
 
 ```ts
 import { typedSpec } from "@xmachines/play-actor";
@@ -114,28 +114,33 @@ meta: {
 
 ### `PlaySpec`
 
-Extends `@xmachines/json-render-core`'s `Spec`. The machine's whole context is projected into
-every derived view's state store under the read-only **`/context` subtree**, so specs read it
-through the ordinary `{ $state: "/context/…" }` grammar — in props, `visible` conditions, and
-`repeat.statePath` alike.
-
-`/context` is read-only by design — never writable. Machine context changes only through events;
-a `$bindState` or `setState` write under `/context` throws with an error naming the event to
-send instead. This is the model: bindable ephemeral state lives at the store root (seeded from
-`spec.state`), domain state lives in the machine and changes via meaningful, inspectable events.
-
-Provenance is legible in the path: `/context/params/username` is visibly URL-derived, while
-`/context/username` is machine-owned — one can never shadow the other.
-
-Two consequences of the everything-is-projected model are worth knowing. First, **exposure**:
-the whole context is client-visible in the view store (debug panels, inspectors, validators) —
-context is a client-side value either way, so keep secrets out of it. Second, **emission
-granularity**: the emit gate compares context per top-level field, so an event that changes any
-field re-emits the view with the same `viewKey`. Providers refresh `/context` in the live store
-rather than reseeding it — no remount, ephemeral view state and focus survive — but a
-re-emission is still a render pass in the framework layer. Keep high-frequency ephemeral data
-(per-keystroke drafts, timers) in the view store (`spec.state` + `$bindState`) or a child actor
-rather than in machine context; domain state belongs in context, keystrokes do not.
+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";
@@ -152,31 +157,33 @@ const spec: PlaySpec = {
 };
 ```
 
-> Historical note: earlier versions had a `contextProps` field. It first drove an implicit
-> prop-enrichment pass that merged allowlisted context fields and URL params into every
-> element's props (removed — it injected values into components that never asked for them and
-> let user-manipulable URL data silently shadow machine-owned state), and was then briefly a
-> projection filter (removed — filtering what a view may read added machinery without a real
-> problem to solve). Validate the **derived** view (`actor.currentView.get()`), not the raw
-> `meta.view`: the derived spec's `state` carries the projection, so tools like `validateSpec`
-> see a self-consistent spec.
+> 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.
 
 ### `Routable`
 
 Interface for actors that support routing.
 
 ```ts
-import type { Routable } from "@xmachines/play-actor";
+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({});
-	currentRoute = new Signal.Computed(() => this.state.get().path ?? null);
+	state = new Signal.State<{ path?: string }>({});
+	currentRoute = new Signal.Computed<string | null>(() => this.state.get().path ?? null);
 	initialRoute = "/";
-	send = (event) => {
+	override send(event: EventObject): void {
 		/* dispatch */
-	};
+	}
 }
 ```
 
@@ -196,7 +203,7 @@ const viewable: Viewable = { currentView: signal };
 
 ### `BaseActorProviderProps<TRegistry>`
 
-Framework-agnostic base props shared by every `ActorProvider` implementation (React, Vue, Solid, Svelte). Framework renderer packages extend this interface.
+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";
@@ -210,7 +217,7 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 ### `BaseViewContextValue<TRegistry>`
 
-Framework-agnostic base for every framework's `ViewContextValue`. Holds `spec`, `handlers`, `registry`, and `store` fields that are identical across React, Vue, Solid, and Svelte.
+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
 
@@ -233,19 +240,21 @@ pnpm --filter @xmachines/play-actor run test:watch
 - **TypeScript** `>=5.7` (strict mode)
 - **ESM only** — `"type": "module"`
 
-@xmachines/play-actor - Abstract Actor base class for Play Architecture
+@xmachines/play-actor - the abstract Actor base class of the Play Architecture
 
-This package provides AbstractActor, a minimal base class that extends XState Actor
-while enforcing the Play Architecture's signal protocol (RFC section 5.3).
+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 core protocol is minimal (state + send). Optional capabilities are provided
-via interfaces:
+The core protocol is minimal: state and send. Two interfaces give the optional
+capabilities:
 
-- Routable: For actors that support routing
-- Viewable: For actors that support view rendering
+- Routable: for an actor with a routing support
+- Viewable: for an actor with a view rendering
 
-Maintains XState ecosystem compatibility (inspection, devtools) while exposing
-reactive signals for Infrastructure layer communication.
+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.
 
 ## See
 

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -2,21 +2,20 @@
 
 # Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L190)
+Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L197)
 
-Abstract base class for Play Architecture actors.
+The abstract base class of an actor of the Play Architecture.
 
-Provides signal-driven state observation that integrates with XState ecosystem
-tooling (devtools, inspection) while exposing reactive signals for
-Infrastructure layer communication.
+It observes the state through the signals, and it works with the tools of the
+XState ecosystem, such as the devtools and the inspection. It also exposes the
+reactive signals of the communication with the infrastructure layer.
 
-**A subclass IS the actor.** Forward the logic _and_ its options to
-`super(logic, options)`, then observe `this`. Holding a separately
-constructed actor alongside leaves this instance running as an empty second
-actor, and every inherited member — `system`, `sessionId`, `clock`, the
-internal `_send` that receives `sendTo()` traffic, and anything a future
-XState version adds — answers from that empty one until it is individually
-forwarded.
+**A subclass IS the actor.** Give the logic _and_ its options to
+`super(logic, options)`, then observe `this`. A separate actor beside this
+instance leaves this instance as an empty second actor. Every inherited member
+then answers from that empty actor, until you forward each one: `system`,
+`sessionId`, `clock`, the internal `_send` that receives the traffic of
+`sendTo()`, and each member that a later XState version adds.
 
 ## Extends
 
@@ -28,10 +27,10 @@ forwarded.
 
 ## Type Parameters
 
-| Type Parameter                                                                           | Default type                                                      | Description                                     |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type                         |
-| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type constraint (defaults to EventObject) |
+| Type Parameter                                                                           | Default type                                                      | Description                                                  |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | The type of the XState actor logic                           |
+| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | The constraint of the event type. The default is EventObject |
 
 ## Constructors
 
@@ -65,19 +64,19 @@ Actor<TLogic>.constructor
 
 ## Properties
 
-| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                             | Inherited from    | Defined in                                                                                                                                               |
-| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                       | `Actor._parent`   | -                                                                                                                                                        |
-| <a id="property-clock"></a> `clock`         | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                              | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                | `Actor.clock`     | -                                                                                                                                                        |
-| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                            | `Actor.id`        | -                                                                                                                                                        |
-| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                       | `Actor.logic`     | -                                                                                                                                                        |
-| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                       | `Actor.options`   | -                                                                                                                                                        |
-| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`       | -                                                                                                                                                        |
-| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId` | -                                                                                                                                                        |
-| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor.src`       | -                                                                                                                                                        |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:200](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L200) |
-| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`    | -                                                                                                                                                        |
-| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.systemId`  | -                                                                                                                                                        |
+| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                                               | Inherited from    | Defined in                                                                                                                                               |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                                         | `Actor._parent`   | -                                                                                                                                                        |
+| <a id="property-clock"></a> `clock`         | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                              | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                  | `Actor.clock`     | -                                                                                                                                                        |
+| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                                              | `Actor.id`        | -                                                                                                                                                        |
+| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                                         | `Actor.logic`     | -                                                                                                                                                        |
+| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                                         | `Actor.options`   | -                                                                                                                                                        |
+| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                                         | `Actor.ref`       | -                                                                                                                                                        |
+| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                                       | `Actor.sessionId` | -                                                                                                                                                        |
+| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                                         | `Actor.src`       | -                                                                                                                                                        |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | 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. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L207) |
+| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                   | `Actor.system`    | -                                                                                                                                                        |
+| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                                         | `Actor.systemId`  | -                                                                                                                                                        |
 
 ## Methods
 
@@ -246,19 +245,20 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:215](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L215)
+Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L223)
 
-Send event to Actor.
+Sends an event to the Actor.
 
-Constrained to TEvent for type safety in concrete implementations.
+The constraint is TEvent, which gives the type safety of a concrete
+implementation.
 
-Note for implementations that wrap `send` (validating the event, or
-notifying hooks around it): this declaration is abstract purely to narrow
-the event type, and TypeScript forbids `super` calls to an abstract
-member. Reach XState's own implementation with
-`Actor.prototype.send.call(this, event)` instead. Making this concrete
-would allow `super.send()` but would force every existing subclass to add
-an `override` modifier — a breaking change for adapters outside this repo.
+A note for an implementation that wraps `send`, to check the event or to notify a
+hook around it: this declaration is abstract for one reason only, to narrow the
+event type, and TypeScript forbids a `super` call to an abstract member. Reach
+the implementation of XState with `Actor.prototype.send.call(this, event)`
+instead. A concrete declaration permits `super.send()`, but it also forces an
+`override` modifier in every subclass that exists now, and that is a breaking
+change for an adapter outside this repository.
 
 #### Parameters
 

package/api/@xmachines/play-actor/functions/attachRenderErrorHandler.md

@@ -6,35 +6,36 @@
 function attachRenderErrorHandler<TRegistry>(registry, handler): TRegistry;
 ```
 
-Defined in: [packages/play-actor/src/provider-guards.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/provider-guards.ts#L64)
+Defined in: [packages/play-actor/src/provider-guards.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/provider-guards.ts#L68)
 
-Clone a component registry and inject an `onRenderError` handler.
+Copies a component registry, and puts an `onRenderError` handler into the copy.
 
-The handler is defined as a non-enumerable, configurable own property on the
-clone (per D-19 — one injection convention for all framework renderers), so
-it overrides any handler set at `defineRegistry` level without showing up
-when the registry's component entries are enumerated.
+The function defines the handler as an own property of the copy. That property is
+not enumerable, and it is configurable (D-19 gives one convention of the
+injection for every framework renderer). The handler therefore replaces each
+handler of the `defineRegistry` level, and it does not appear in an enumeration of
+the component entries of the registry.
 
-The caller's registry is never mutated — a shallow clone is returned. Callers
-that need per-instance handlers (e.g. an `onRenderError` prop on
-`ActorProvider`) can therefore share one `defineRegistry` result across
-providers safely.
+The function never changes the registry of the caller: it returns a shallow copy.
+Therefore a caller that needs a handler for each instance, such as an
+`onRenderError` prop of `ActorProvider`, can share one result of `defineRegistry`
+between the providers in a safe way.
 
 ## Type Parameters
 
-| Type Parameter                 | Description                                     |
-| ------------------------------ | ----------------------------------------------- |
-| `TRegistry` _extends_ `object` | The framework-specific component registry type. |
+| Type Parameter                 | Description                                   |
+| ------------------------------ | --------------------------------------------- |
+| `TRegistry` _extends_ `object` | The component registry type of the framework. |
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `registry` | `TRegistry`                                                               | The component registry from `defineRegistry().registry`.                            |
-| `handler`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md) | Called with `(error, componentName)` when a catalog component throws during render. |
+| Parameter  | Type                                                                      | Description                                                                                          |
+| ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `registry` | `TRegistry`                                                               | The component registry from `defineRegistry().registry`.                                             |
+| `handler`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md) | The renderer calls it with `(error, componentName)` when a catalog component throws during a render. |
 
 ## Returns
 
 `TRegistry`
 
-A shallow clone of `registry` with `onRenderError` attached.
+A shallow copy of `registry`, with `onRenderError` on it.

package/api/@xmachines/play-actor/functions/composePlayState.md

@@ -6,20 +6,21 @@
 function composePlayState(authoredState, slice): Record<string, unknown> | undefined;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L220)
+Defined in: [packages/play-actor/src/context-projection.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L228)
 
-Compose a view's effective state: the authored `spec.state` plus the
+Composes the effective state of a view: the authored `spec.state` and the
 `/context` slice.
 
-When the authored state already declares the reserved key, the projection is
-skipped (authored state wins) with a dev warning — no existing spec breaks.
+When the authored state declares the reserved key already, the function skips the
+projection, the authored state wins, and the code writes a warning in
+development. No spec that exists now therefore fails.
 
 ## Parameters
 
-| Parameter       | Type                                           | Description                                                                       |
-| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
-| `authoredState` | `Record`\<`string`, `unknown`\> \| `undefined` | The raw `meta.view.state` (may be anything; sanitized by the caller/toAtomState). |
-| `slice`         | `Record`\<`string`, `unknown`\> \| `undefined` | The machine's context, projected wholesale.                                       |
+| Parameter       | Type                                           | Description                                                                                   |
+| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `authoredState` | `Record`\<`string`, `unknown`\> \| `undefined` | The raw `meta.view.state` value. It can be anything, and the caller or toAtomState cleans it. |
+| `slice`         | `Record`\<`string`, `unknown`\> \| `undefined` | The context of the machine, as one complete value.                                            |
 
 ## Returns