@xmachines/play-view 0.0.0-bootstrap.0 → 4.0.0

package/README.md

@@ -1,17 +1,158 @@
 # @xmachines/play-view
 
-The shared view half of every XMachines renderer: the Viewable capability, the PlaySpec, and the view store lifecycle.
+The shared view half of every renderer of the XMachines Play Architecture.
 
-## This version is a placeholder
+[![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-view)
 
-Version `0.0.0-bootstrap.0` contains no code. It holds the name on the registry, so that
-the maintainers can configure trusted publishing before the first real release.
-
-The first release of this package is **4.0.0**. Install it with the other packages of the
-XMachines Play Architecture:
+## Installation
 
 ```bash
 pnpm add @xmachines/play-view
 ```
 
-Read the documentation at <https://gitlab.com/xmachin-es/xmachines-js>.
+**Peer dependencies.** Install them with the package:
+
+```bash
+pnpm add @xmachines/json-render-core
+```
+
+A renderer of a framework depends on this package already. Install it directly when you write a renderer of your own.
+
+## Overview
+
+A renderer of a framework is two things: the view lifecycle, and the code that binds that lifecycle to the effects of the framework. This package holds the first one. [`@xmachines/play-react`](../play-react/README.md), [`@xmachines/play-vue`](../play-vue/README.md), [`@xmachines/play-solid`](../play-solid/README.md), [`@xmachines/play-svelte`](../play-svelte/README.md) and [`@xmachines/play-dom`](../play-dom/README.md) hold the second one.
+
+It also holds `Viewable` and `PlaySpec`. Every type here names a type of `@xmachines/json-render-core`, and that is the reason they are here and not in [`@xmachines/play-actor`](../play-actor/README.md): an application that routes and renders no view installs this package never, and json-render never.
+
+| Export                                           | Description                                                           |
+| ------------------------------------------------ | --------------------------------------------------------------------- |
+| `Viewable`                                       | The capability of an actor that publishes a `currentView` signal      |
+| `PlaySpec`, `typedSpec`                          | The spec that an actor publishes, and its identity helper             |
+| `BaseActorProviderProps`, `BaseViewContextValue` | The framework-free half of the props and of the context of a provider |
+| `createViewStoreLifecycle`                       | The lifecycle of the state store of one view                          |
+| `createFailureLatch`, `createReportGuard`        | The report of a render failure, one time for each view                |
+| `toAtomState`, `attachRenderErrorHandler`        | The guards that a provider puts around a registry                     |
+| `composePlayState`, `refreshContextSubtree`, …   | The projection of the machine context into the store                  |
+
+## API Summary
+
+### `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.
+
+```ts
+import { typedSpec } from "@xmachines/play-view";
+
+// 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-view";
+
+const spec: PlaySpec = {
+	root: "root",
+	elements: {
+		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.
+
+### `Viewable`
+
+Interface for actors that expose a renderable view signal.
+
+```ts
+import type { Viewable } from "@xmachines/play-view";
+import type { PlaySpec } from "@xmachines/play-view";
+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-view";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
+
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
+
+### `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.
+
+## Documentation
+
+- [Architecture](../docs/contributing/architecture.md)
+- [Play RFC](../docs/rfc/play.md)
+
+## License
+
+MIT

package/dist/context-projection.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The context projection — the machine context as the read-only `/context`
+ * subtree of the view state store.
+ *
+ * `deriveCurrentView` composes the `state` field of each emitted view as
+ * `{ ...meta.view.state, context: <slice> }`. The spec is therefore consistent with
+ * itself: its `state` field describes the contents of the store correctly, and
+ * `repeat.statePath`, `visible.$state`, a `$state` prop, and a validator all read
+ * the machine context through the ordinary `{ $state: "/context/…" }` grammar.
+ *
+ * The subtree is read-only **to the spec, and not to the machinery**: a provider
+ * gives the bindings and the action handlers a store with the wrapper of
+ * {@link guardContextWrites}, and it refreshes the projection through the store
+ * below that wrapper, which has no guard. The context changes through a machine
+ * event only. Therefore a write under `/context` is always a fault of the spec, and
+ * the guard says so.
+ *
+ * @packageDocumentation
+ */
+import type { StateStore } from "@xmachines/json-render-core";
+import type { PlaySpec } from "./view-types.js";
+/**
+ * The reserved top-level state key of the projection.
+ *
+ * The `spec.state` object of a view must not declare this key. When it does, the
+ * derivation skips the projection for that view, the authored state wins, and the
+ * code writes a warning in development. See {@link composePlayState}.
+ */
+export declare const CONTEXT_STATE_KEY = "context";
+/**
+ * Reuses the composed `state` of the previous emission, or the complete previous
+ * spec, when the value of the projection did not change.
+ *
+ * `deriveCurrentView` composes `state: { ...meta.view.state, context: slice }` new
+ * on each call, and the XState function `assign` makes a new context object on
+ * every event. Without this reuse, every event therefore presents a new `state`
+ * reference, and the `Object.is` test of each field in the emit gate emits the view
+ * again and remounts it, without an end. The function compares the slices field by
+ * field ({@link shallowEqualExcept}), because the XState function `assign` makes a
+ * new context object for each event, and a test of the identity of the whole object
+ * therefore reports a change every time. The authored fields come from the static
+ * `meta.view.state` through a spread. Therefore their references are stable for an
+ * unchanged `viewKey`, and a plain `Object.is` test is correct for them.
+ *
+ * The function returns one of three values, in this order of preference:
+ * - `prev` itself, when nothing observable changed. The emit gate then stops at the
+ *   identity of the reference, and it walks no element;
+ * - `{ ...next, state: prev.state }`, when the value of the state did not change
+ *   but another top-level field is different;
+ * - `next`, when something changed.
+ */
+export declare function reuseComposedState(prev: PlaySpec | null, next: PlaySpec | null): PlaySpec | null;
+/**
+ * Wraps a StateStore, and the wrapper refuses each write under `/context`.
+ *
+ * A provider applies it to the store that it gives to the bindings and to the
+ * action handlers (`$bindState`, `setState`, and a chained `set`). The provider
+ * keeps the store without the wrapper, and it refreshes the projection through that
+ * store. The subtree is therefore read-only to the spec, and not to the machinery.
+ *
+ * A write with a value that is **identical** to the current value passes in
+ * silence. A handler in the style of `setState` reads the complete snapshot,
+ * changes it, and writes the whole object back. The `context` key that goes through
+ * that round trip without a change is no attempt of a mutation. Only a write that
+ * changes the subtree throws.
+ *
+ * Each read passes through without a change. The wrapper delegates every member
+ * explicitly, and it does not use a spread: a store from a consumer can be an
+ * instance of a class, and the methods of that instance are on the prototype. Those
+ * methods do not survive `{ ...store }`, and the first render then fails with
+ * `store.getSnapshot is not a function`. The code builds the wrapper one time for
+ * each resolved store. Therefore the identity of the delegating `getSnapshot` and
+ * of the delegating `subscribe` stays stable for a consumer in the style of
+ * `useSyncExternalStore`.
+ *
+ * @param store - The store below the wrapper.
+ * @returns A store with a guard on `set` and on `update`.
+ */
+export declare function guardContextWrites(store: StateStore): StateStore;
+/**
+ * Refreshes the `/context` subtree of a live store from the composed state of a
+ * derived view. An emission with the same `viewKey` means that only the projection
+ * changed. The function therefore replaces the complete subtree, and it never
+ * merges it field by field, because `update` cannot delete a key. Every ephemeral
+ * value at the root level stays. The function does nothing when the view carries no
+ * slice, or when the store holds the slice already.
+ *
+ * @param store - The store WITHOUT the guard. A provider refreshes through it.
+ * @param view - The derived view. Its `state.context` field carries the slice.
+ */
+export declare function refreshContextSubtree(store: StateStore, view: {
+    state?: unknown;
+}): void;
+/**
+ * Composes the effective state of a view: the authored `spec.state` and the
+ * `/context` slice.
+ *
+ * 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.
+ *
+ * @param authoredState - The raw `meta.view.state` value. It can be anything, and the caller or toAtomState cleans it.
+ * @param slice - The context of the machine, as one complete value.
+ */
+export declare function composePlayState(authoredState: Record<string, unknown> | undefined, slice: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+//# sourceMappingURL=context-projection.d.ts.map

package/dist/context-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-projection.d.ts","sourceRoot":"","sources":["../src/context-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAiB3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAiBhG;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA2ChE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAKxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAClD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAcrC"}

package/dist/context-projection.js

@@ -0,0 +1,215 @@
+/**
+ * The context projection — the machine context as the read-only `/context`
+ * subtree of the view state store.
+ *
+ * `deriveCurrentView` composes the `state` field of each emitted view as
+ * `{ ...meta.view.state, context: <slice> }`. The spec is therefore consistent with
+ * itself: its `state` field describes the contents of the store correctly, and
+ * `repeat.statePath`, `visible.$state`, a `$state` prop, and a validator all read
+ * the machine context through the ordinary `{ $state: "/context/…" }` grammar.
+ *
+ * The subtree is read-only **to the spec, and not to the machinery**: a provider
+ * gives the bindings and the action handlers a store with the wrapper of
+ * {@link guardContextWrites}, and it refreshes the projection through the store
+ * below that wrapper, which has no guard. The context changes through a machine
+ * event only. Therefore a write under `/context` is always a fault of the spec, and
+ * the guard says so.
+ *
+ * @packageDocumentation
+ */
+import { ReadOnlyContextError } from "./errors.js";
+import { shallowEqualExcept } from "@xmachines/play";
+/**
+ * The reserved top-level state key of the projection.
+ *
+ * The `spec.state` object of a view must not declare this key. When it does, the
+ * derivation skips the projection for that view, the authored state wins, and the
+ * code writes a warning in development. See {@link composePlayState}.
+ */
+export const CONTEXT_STATE_KEY = "context";
+/**
+ * The record that reports each diagnostic one time for each spec. The condition
+ * here is a static property of the authored meta.view, because its `state` object
+ * never changes between two events. `deriveCurrentView` runs on every machine
+ * snapshot, and a report for each derivation therefore floods the console at the
+ * rate of the events. The key is the identity of the static object. Each spec
+ * therefore reports one time, and a test with a new literal stays separate.
+ */
+const reportedDiagnostics = new WeakSet();
+function warnOnce(anchor, message) {
+    if (reportedDiagnostics.has(anchor))
+        return;
+    reportedDiagnostics.add(anchor);
+    console.warn(message);
+}
+/**
+ * Reuses the composed `state` of the previous emission, or the complete previous
+ * spec, when the value of the projection did not change.
+ *
+ * `deriveCurrentView` composes `state: { ...meta.view.state, context: slice }` new
+ * on each call, and the XState function `assign` makes a new context object on
+ * every event. Without this reuse, every event therefore presents a new `state`
+ * reference, and the `Object.is` test of each field in the emit gate emits the view
+ * again and remounts it, without an end. The function compares the slices field by
+ * field ({@link shallowEqualExcept}), because the XState function `assign` makes a
+ * new context object for each event, and a test of the identity of the whole object
+ * therefore reports a change every time. The authored fields come from the static
+ * `meta.view.state` through a spread. Therefore their references are stable for an
+ * unchanged `viewKey`, and a plain `Object.is` test is correct for them.
+ *
+ * The function returns one of three values, in this order of preference:
+ * - `prev` itself, when nothing observable changed. The emit gate then stops at the
+ *   identity of the reference, and it walks no element;
+ * - `{ ...next, state: prev.state }`, when the value of the state did not change
+ *   but another top-level field is different;
+ * - `next`, when something changed.
+ */
+export function reuseComposedState(prev, next) {
+    if (!prev || !next || prev.viewKey !== next.viewKey)
+        return next;
+    const prevState = prev.state;
+    const nextState = next.state;
+    if (prevState !== nextState) {
+        if (prevState === undefined || nextState === undefined)
+            return next;
+        if (!shallowEqualExcept(prevState, nextState, CONTEXT_STATE_KEY))
+            return next;
+        const prevSlice = prevState[CONTEXT_STATE_KEY];
+        const nextSlice = nextState[CONTEXT_STATE_KEY];
+        if (prevSlice !== nextSlice) {
+            if (prevSlice === undefined || nextSlice === undefined)
+                return next;
+            if (!shallowEqualExcept(prevSlice, nextSlice))
+                return next;
+        }
+        if (shallowEqualExcept(prev, next, "state"))
+            return prev;
+        return { ...next, state: prevState };
+    }
+    return shallowEqualExcept(prev, next, "state") ? prev : next;
+}
+/**
+ * The paths of the reserved subtree: `"/context"` itself, and every path below it.
+ * An update map of the store can hold a bare top-level key ("context") and also a
+ * JSON Pointer ("/context/…"). Both forms address the same subtree.
+ */
+function toPointer(path) {
+    return path.startsWith("/") ? path : `/${path}`;
+}
+/** This function expects a NORMALIZED pointer from {@link toPointer}. */
+function isContextPointer(pointer) {
+    return pointer === `/${CONTEXT_STATE_KEY}` || pointer.startsWith(`/${CONTEXT_STATE_KEY}/`);
+}
+/**
+ * Wraps a StateStore, and the wrapper refuses each write under `/context`.
+ *
+ * A provider applies it to the store that it gives to the bindings and to the
+ * action handlers (`$bindState`, `setState`, and a chained `set`). The provider
+ * keeps the store without the wrapper, and it refreshes the projection through that
+ * store. The subtree is therefore read-only to the spec, and not to the machinery.
+ *
+ * A write with a value that is **identical** to the current value passes in
+ * silence. A handler in the style of `setState` reads the complete snapshot,
+ * changes it, and writes the whole object back. The `context` key that goes through
+ * that round trip without a change is no attempt of a mutation. Only a write that
+ * changes the subtree throws.
+ *
+ * Each read passes through without a change. The wrapper delegates every member
+ * explicitly, and it does not use a spread: a store from a consumer can be an
+ * instance of a class, and the methods of that instance are on the prototype. Those
+ * methods do not survive `{ ...store }`, and the first render then fails with
+ * `store.getSnapshot is not a function`. The code builds the wrapper one time for
+ * each resolved store. Therefore the identity of the delegating `getSnapshot` and
+ * of the delegating `subscribe` stays stable for a consumer in the style of
+ * `useSyncExternalStore`.
+ *
+ * @param store - The store below the wrapper.
+ * @returns A store with a guard on `set` and on `update`.
+ */
+export function guardContextWrites(store) {
+    const reject = (path) => {
+        throw new ReadOnlyContextError(path, CONTEXT_STATE_KEY);
+    };
+    const checkWrite = (path, value) => {
+        const pointer = toPointer(path);
+        if (!isContextPointer(pointer))
+            return true;
+        // A round trip without a change, which is a read-modify-write of the complete
+        // snapshot, does nothing to this subtree, and it is no mutation. Drop the key in
+        // silence.
+        if (Object.is(store.get(pointer), value))
+            return false;
+        return reject(path);
+    };
+    const guarded = {
+        get: (path) => store.get(path),
+        getSnapshot: () => store.getSnapshot(),
+        subscribe: (listener) => store.subscribe(listener),
+        set: (path, value) => {
+            if (checkWrite(path, value))
+                store.set(path, value);
+        },
+        update: (updates) => {
+            const allowed = {};
+            let dropped = false;
+            for (const [path, value] of Object.entries(updates)) {
+                if (checkWrite(path, value)) {
+                    allowed[path] = value; // nosemgrep: gitlab.eslint.detect-object-injection
+                }
+                else {
+                    dropped = true;
+                }
+            }
+            store.update(dropped ? allowed : updates);
+        },
+    };
+    // The contract makes this member optional, and its absence has a meaning:
+    // json-render-core uses `getSnapshot` when the key is absent. Therefore the wrapper
+    // must build no member that returns `undefined`.
+    const { getServerSnapshot } = store;
+    if (getServerSnapshot) {
+        guarded.getServerSnapshot = () => getServerSnapshot.call(store);
+    }
+    return guarded;
+}
+/**
+ * Refreshes the `/context` subtree of a live store from the composed state of a
+ * derived view. An emission with the same `viewKey` means that only the projection
+ * changed. The function therefore replaces the complete subtree, and it never
+ * merges it field by field, because `update` cannot delete a key. Every ephemeral
+ * value at the root level stays. The function does nothing when the view carries no
+ * slice, or when the store holds the slice already.
+ *
+ * @param store - The store WITHOUT the guard. A provider refreshes through it.
+ * @param view - The derived view. Its `state.context` field carries the slice.
+ */
+export function refreshContextSubtree(store, view) {
+    const slice = view.state?.[CONTEXT_STATE_KEY];
+    if (slice !== undefined && !Object.is(store.get(`/${CONTEXT_STATE_KEY}`), slice)) {
+        store.update({ [`/${CONTEXT_STATE_KEY}`]: slice });
+    }
+}
+/**
+ * Composes the effective state of a view: the authored `spec.state` and the
+ * `/context` slice.
+ *
+ * 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.
+ *
+ * @param authoredState - The raw `meta.view.state` value. It can be anything, and the caller or toAtomState cleans it.
+ * @param slice - The context of the machine, as one complete value.
+ */
+export function composePlayState(authoredState, slice) {
+    if (authoredState !== undefined && Object.hasOwn(authoredState, CONTEXT_STATE_KEY)) {
+        warnOnce(authoredState, `[play-view] spec.state declares a top-level "${CONTEXT_STATE_KEY}" key; ` +
+            `skipping the machine-context projection for this view. ` +
+            `Rename the state field to project context at /${CONTEXT_STATE_KEY}.`);
+        return authoredState;
+    }
+    if (slice === undefined) {
+        return authoredState;
+    }
+    return { ...authoredState, [CONTEXT_STATE_KEY]: slice };
+}
+//# sourceMappingURL=context-projection.js.map

package/dist/context-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-projection.js","sourceRoot":"","sources":["../src/context-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAIrD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAAU,CAAC;AAClD,SAAS,QAAQ,CAAC,MAAc,EAAE,OAAe;IAChD,IAAI,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO;IAC5C,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqB,EAAE,IAAqB;IAC9E,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpE,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,iBAAiB,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9E,MAAM,SAAS,GAAG,SAAS,CAAC,iBAAiB,CAAwC,CAAC;QACtF,MAAM,SAAS,GAAG,SAAS,CAAC,iBAAiB,CAAwC,CAAC;QACtF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACpE,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC5D,CAAC;QACD,IAAI,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACzD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,yEAAyE;AACzE,SAAS,gBAAgB,CAAC,OAAe;IACxC,OAAO,OAAO,KAAK,IAAI,iBAAiB,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAiB;IACnD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAS,EAAE;QACtC,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IACzD,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE;QAC5D,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,8EAA8E;QAC9E,iFAAiF;QACjF,WAAW;QACX,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC;IACF,MAAM,OAAO,GAAe;QAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;QAC9B,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE;QACtC,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;QAClD,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACpB,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE;YACnB,MAAM,OAAO,GAA4B,EAAE,CAAC;YAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrD,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;oBAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,mDAAmD;gBAC3E,CAAC;qBAAM,CAAC;oBACP,OAAO,GAAG,IAAI,CAAC;gBAChB,CAAC;YACF,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;KACD,CAAC;IAEF,0EAA0E;IAC1E,oFAAoF;IACpF,iDAAiD;IACjD,MAAM,EAAE,iBAAiB,EAAE,GAAG,KAAK,CAAC;IACpC,IAAI,iBAAiB,EAAE,CAAC;QACvB,OAAO,CAAC,iBAAiB,GAAG,GAAG,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiB,EAAE,IAAyB;IACjF,MAAM,KAAK,GAAI,IAAI,CAAC,KAA6C,EAAE,CAAC,iBAAiB,CAAC,CAAC;IACvF,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,iBAAiB,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAClF,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,iBAAiB,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC/B,aAAkD,EAClD,KAA0C;IAE1C,IAAI,aAAa,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,CAAC,EAAE,CAAC;QACpF,QAAQ,CACP,aAAa,EACb,gDAAgD,iBAAiB,SAAS;YACzE,yDAAyD;YACzD,iDAAiD,iBAAiB,GAAG,CACtE,CAAC;QACF,OAAO,aAAa,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,aAAa,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,GAAG,aAAa,EAAE,CAAC,iBAAiB,CAAC,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The errors of the view half.
+ *
+ * Every error of this workspace extends `PlayError` of `@xmachines/play`, and it carries
+ * a `scope` and a `code` that stay the same across a patch release and a minor release.
+ * Match on the `code`, or on the class. Match on the `message` never.
+ *
+ * @packageDocumentation
+ * @see [Architecture](../../docs/contributing/architecture.md)
+ */
+import { PlayError } from "@xmachines/play/errors";
+/**
+ * A write reached the context projection of the view store.
+ *
+ * The `/context` subtree of a view mirrors the context of the machine, and it is a
+ * READ of that context. A write there would hold a value that the next snapshot of the
+ * machine throws away, so the store refuses it. Send the actor an event instead: the
+ * context changes in the machine, and the projection follows.
+ *
+ * @example
+ * ```typescript
+ * import { ReadOnlyContextError } from "@xmachines/play-view/errors";
+ *
+ * try {
+ *   store.set("/context/user/name", "Alice");
+ * } catch (error) {
+ *   if (error instanceof ReadOnlyContextError) {
+ *     actor.send({ type: "user.rename", name: "Alice" });
+ *   }
+ * }
+ * ```
+ */
+export declare class ReadOnlyContextError extends PlayError {
+    /** The JSON pointer of the write that the store refused, as the caller gave it. */
+    readonly path: string;
+    /**
+     * @param path    - The path of the refused write.
+     * @param stateKey - The key of the context subtree, for the message.
+     */
+    constructor(path: string, stateKey: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU1C"}

package/dist/errors.js

@@ -0,0 +1,47 @@
+/**
+ * The errors of the view half.
+ *
+ * Every error of this workspace extends `PlayError` of `@xmachines/play`, and it carries
+ * a `scope` and a `code` that stay the same across a patch release and a minor release.
+ * Match on the `code`, or on the class. Match on the `message` never.
+ *
+ * @packageDocumentation
+ * @see [Architecture](../../docs/contributing/architecture.md)
+ */
+import { PlayError } from "@xmachines/play/errors";
+/**
+ * A write reached the context projection of the view store.
+ *
+ * The `/context` subtree of a view mirrors the context of the machine, and it is a
+ * READ of that context. A write there would hold a value that the next snapshot of the
+ * machine throws away, so the store refuses it. Send the actor an event instead: the
+ * context changes in the machine, and the projection follows.
+ *
+ * @example
+ * ```typescript
+ * import { ReadOnlyContextError } from "@xmachines/play-view/errors";
+ *
+ * try {
+ *   store.set("/context/user/name", "Alice");
+ * } catch (error) {
+ *   if (error instanceof ReadOnlyContextError) {
+ *     actor.send({ type: "user.rename", name: "Alice" });
+ *   }
+ * }
+ * ```
+ */
+export class ReadOnlyContextError extends PlayError {
+    /** The JSON pointer of the write that the store refused, as the caller gave it. */
+    path;
+    /**
+     * @param path    - The path of the refused write.
+     * @param stateKey - The key of the context subtree, for the message.
+     */
+    constructor(path, stateKey) {
+        super("guardContextWrites", "PLAY_VIEW_READ_ONLY_CONTEXT", `"${path}" is read-only: /${stateKey} mirrors the context of the machine. ` +
+            `Send the actor an event to change it, because the context changes through the view store never.`);
+        this.name = "ReadOnlyContextError";
+        this.path = path;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD,mFAAmF;IAC1E,IAAI,CAAS;IAEtB;;;OAGG;IACH,YAAY,IAAY,EAAE,QAAgB;QACzC,KAAK,CACJ,oBAAoB,EACpB,6BAA6B,EAC7B,IAAI,IAAI,oBAAoB,QAAQ,uCAAuC;YAC1E,iGAAiG,CAClG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD"}