@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/api/@xmachines/play/functions/assertNonNullable.md

@@ -6,19 +6,19 @@
 function assertNonNullable<V>(value, name?): NonNullable<V>;
 ```
 
-Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play/src/utils.ts#L39)
+Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/utils.ts#L39)
 
-Assert that `value` is neither `null` nor `undefined`, and return it typed
-as `NonNullable<V>` — combining the guard and the narrowed value in a single
-expression.
+Asserts that `value` is not `null` and not `undefined`, then returns it with the
+type `NonNullable<V>`. One expression therefore holds the guard and the narrowed
+value.
 
-Unlike a non-null assertion (`value!`), this throws a descriptive error at
-the point of failure rather than producing `undefined`-is-not-an-object`
-crashes somewhere downstream.
+A non-null assertion (`value!`) is different: it produces `undefined`, and your
+code then fails later with a message such as "undefined is not an object". This
+function throws a clear error at the point of the failure.
 
-Unlike an `asserts value is T` assertion function, this returns the narrowed
-value directly, so no separate variable or `as` cast is required at the call
-site.
+An assertion function of the form `asserts value is T` is also different: this
+function returns the narrowed value directly. Therefore the call site needs no
+second variable and no `as` cast.
 
 ## Type Parameters
 
@@ -28,16 +28,16 @@ site.
 
 ## Parameters
 
-| Parameter | Type     | Description                                                                                                          |
-| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
-| `value`   | `V`      | The value to check.                                                                                                  |
-| `name?`   | `string` | Optional name included in the error message to identify the missing value (e.g. the variable or injection key name). |
+| Parameter | Type     | Description                                                                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`   | `V`      | The value to check.                                                                                                                    |
+| `name?`   | `string` | The optional name in the error message. It identifies the missing value, for example the name of the variable or of the injection key. |
 
 ## Returns
 
 `NonNullable`\<`V`\>
 
-`value` typed as `NonNullable<V>` — `null` and `undefined` removed.
+`value` with the type `NonNullable<V>`, without `null` and without `undefined`.
 
 ## Throws
 
@@ -48,9 +48,9 @@ When `value` is `null` or `undefined`.
 ```ts
 import { assertNonNullable } from "@xmachines/play";
 
-// inject() + assertNonNullable in one line — no `!` or intermediate variable:
+// inject() and assertNonNullable in one line, with no `!` and no second variable:
 const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
 
-// Element lookup:
+// A lookup of an element:
 const el = assertNonNullable(document.getElementById("app"), "#app");
 ```

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-alpha.1/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-alpha.1/packages/play/src/types.ts#L70) |
+| Name   | Type     | Defined in                                                                                                               |
+| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `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

@@ -1,12 +1,10 @@
 [API](../../README.md) / @xmachines/play-actor
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-actor
 
 Abstract Actor base class for XMachines Play Architecture.
 
-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,90 +12,101 @@ 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
+pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
 ```
 
 ## 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. 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";
 import { Signal } from "@xmachines/play-signals";
-import type { AnyActorLogic } from "xstate";
+import { Actor, type ActorOptions, type AnyActorLogic } from "xstate";
 
 class MyActor extends AbstractActor<AnyActorLogic> {
 	// Required: reactive state signal
-	state = new Signal.State({});
+	state: Signal.State<unknown>;
+
+	constructor(logic: AnyActorLogic, options?: ActorOptions<AnyActorLogic>) {
+		super(logic, options);
+		this.state = new Signal.State(this.getSnapshot());
+		super.subscribe((snapshot) => this.state.set(snapshot));
+	}
 
 	// Required: typed event dispatch
-	send = (event: { type: string }) => {
-		/* dispatch to XState */
-	};
+	override send(event: { type: string }): void {
+		Actor.prototype.send.call(this, event);
+	}
 }
 ```
 
 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 });
 
-	send = (event: AuthEvent) => {
-		/* dispatch */
-	};
+	override send(event: AuthEvent): void {
+		Actor.prototype.send.call(this, event);
+	}
 }
 ```
 
-### `typedSpec<TContext>(spec)`
+### `typedSpec(spec)`
 
-Identity helper that constrains a `PlaySpec` object's `contextProps` to keys of a specific machine context type. This enables 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";
 
-interface DashboardCtx {
-  username: string;
-  params: Record<string, string>;
-  query: Record<string, string>;
-}
-
 // In an XState machine meta block:
 meta: {
-  view: typedSpec<DashboardCtx>({
+  view: typedSpec({
     root: "root",
-    contextProps: ["username"],      // ✓ key of DashboardCtx
-    // contextProps: ["usernaem"],   // ✗ compile error
     elements: {
-      root: { type: "Dashboard", props: {}, children: [] },
+      root: {
+        type: "Dashboard",
+        props: { username: { $state: "/context/username" } },
+        children: [],
+      },
     },
   }),
 }
@@ -105,36 +114,76 @@ meta: {
 
 ### `PlaySpec`
 
-Extends `@xmachines/json-render-core`'s `Spec` with an optional `contextProps` field — an explicit allowlist of machine context fields that are merged into element props at view derivation time.
+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",
-	contextProps: ["username"], // only these keys are exposed to components
 	elements: {
-		root: { type: "Profile", props: { username: undefined }, children: [] },
+		root: {
+			type: "Profile",
+			props: { username: { $state: "/context/username" } },
+			children: [],
+		},
 	},
 };
 ```
 
+> 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 */
-	};
+	}
 }
 ```
 
@@ -154,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";
@@ -168,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
 
@@ -191,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
 
@@ -218,11 +269,24 @@ reactive signals for Infrastructure layer communication.
 - [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)