@xmachines/play-actor 3.0.0 → 4.0.0

package/dist/abstract-actor.d.ts

@@ -1,207 +0,0 @@
-/**
- * The AbstractActor base class of the Play Architecture
- *
- * It extends the XState Actor class, which keeps the compatibility with the
- * ecosystem, such as the inspection and the devtools. It also enforces the signal
- * protocol of the communication between the Actor and the infrastructure.
- *
- * RFC section 5.3 gives the minimal protocol of the Actor:
- * - state: the snapshot of the current machine state
- * - send: the method that sends an event
- *
- * Two interfaces give the optional capabilities:
- * - Routable: for an actor with a routing support
- * - Viewable: for an actor with a view rendering
- *
- * An adapter, such as @xmachines/play-xstate, makes the concrete implementations.
- *
- * @packageDocumentation
- */
-import { Actor, type AnyActorLogic, type EventObject } from "xstate";
-import type { Signal } from "@xmachines/play-signals";
-import type { Spec, StateStore, RenderErrorHandler, ActionHandler } from "@xmachines/json-render-core";
-/**
- * An optional capability: the routing support
- */
-export interface Routable {
-    readonly currentRoute: Signal.Computed<string | null>;
-    readonly initialRoute: string | null;
-}
-/**
- * The XMachines extension of the `Spec` type of `@xmachines/json-render-core`.
- *
- * Each derived view receives the 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`. The store always holds the complete context, and a
- * spec reads only the paths that it needs.
- */
-export interface PlaySpec extends Spec {
-    /**
-     * The identity of the view of this derived spec. `deriveCurrentView` sets it from
-     * the meta entry that the derivation selected. A provider uses it as the key of its
-     * store lifecycle: a new `viewKey` seeds the store again, and the same `viewKey`
-     * refreshes `/context` in place, which keeps the ephemeral view state. Never write
-     * this field in `meta.view`.
-     */
-    readonly viewKey?: string;
-}
-/**
- * The identity helper gives a view spec literal the type `PlaySpec` at the
- * definition site. The compiler therefore checks the spec, and the IDE completes it.
- *
- * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
- * therefore infers no spec shape from the context. `typedSpec(...)` is the
- * mechanism that starts the check where you write the spec. The parameter holds no
- * `viewKey`: the derivation stamps that field, and it overwrites a value from an
- * author without a notice. Therefore the compiler refuses a `viewKey` here.
- *
- * The check of an excess property works on an inline object literal only. For a
- * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
- * the literal instead.
- *
- * At run time this function does nothing: it returns the spec object without a
- * change.
- *
- * @example
- * ```ts
- * meta: {
- *   view: typedSpec({
- *     root: "root",
- *     elements: {
- *       root: {
- *         type: "Dashboard",
- *         props: { username: { $state: "/context/username" } },
- *         children: [],
- *       },
- *     },
- *   }),
- * }
- * ```
- */
-export declare function typedSpec(spec: Omit<PlaySpec, "viewKey">): PlaySpec;
-/**
- * The actor capability that exposes a renderable view state.
- *
- * `Viewable` marks an actor that publishes a `currentView` signal.
- * A renderer, such as `PlayRenderer`, reads this contract. It converts the
- * description of the current view into a concrete UI, and the framework adapter
- * therefore holds no view logic.
- */
-export interface Viewable {
-    /**
-     * The signal of the current view. It holds the json-render PlaySpec of the current
-     * machine state, or null when no view is active.
-     *
-     * The infrastructure renders the view. This is the Logic-Driven UI invariant.
-     */
-    readonly currentView: Signal.State<PlaySpec | null>;
-}
-/**
- * The framework-agnostic base of the `ViewContextValue` type in each framework.
- *
- * It holds the three fields that are identical in React, Vue, Solid, and Svelte.
- * The `registry` field belongs to one framework, because each framework has its own
- * `ComponentRegistry` type. Therefore `TRegistry` gives its type, and this is the
- * same generic parameter as in `BaseActorProviderProps`.
- *
- * @typeParam TRegistry - The registry type of the component of the framework, for example `ComponentRegistry` from `@xmachines/json-render-react`.
- */
-export interface BaseViewContextValue<TRegistry extends object> {
-    /** The current PlaySpec to render. */
-    spec: PlaySpec;
-    /** The action handlers, resolved against the live StateStore. */
-    handlers: Record<string, ActionHandler>;
-    /** The component registry, from registryResult.registry. */
-    registry: TRegistry;
-    /**
-     * The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state.
-     */
-    store: StateStore;
-}
-/**
- * The framework-agnostic base props. Every `ActorProvider` implementation shares
- * them: React, Vue, Solid, and Svelte. `TRegistry` holds the
- * `DefineRegistryResult` type of the framework. `RenderErrorHandler` comes from
- * `@xmachines/json-render-core`, and a second generic parameter is therefore not
- * necessary.
- *
- * Each framework package extends this interface with its `fallback` field, its
- * `onError` field, and its `children` field.
- *
- * @typeParam TRegistry - The `DefineRegistryResult` type of the framework.
- *
- * @example
- * ```ts
- * import type { BaseActorProviderProps } from "@xmachines/play-actor";
- * import type { DefineRegistryResult } from "@xmachines/json-render-react";
- *
- * interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
- *   fallback?: React.ReactNode;
- *   children: React.ReactNode;
- * }
- * ```
- */
-export interface BaseActorProviderProps<TRegistry extends {
-    registry: object;
-    handlers: (...args: never[]) => unknown;
-}> {
-    /** The actor instance with the currentView signal. It requires the Viewable capability. */
-    actor: AbstractActor<AnyActorLogic> & Viewable;
-    /** The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers. */
-    registryResult: TRegistry;
-    /**
-     * The optional external StateStore, which is the controlled mode.
-     * With this option, the provider ignores spec.state, and this store is the single
-     * source of truth. Without it, the provider makes a new @xstate/store atom for each
-     * view transition, with the values of spec.state.
-     */
-    store?: StateStore;
-    /**
-     * The provider calls it when one catalog component throws during a render.
-     * This handler replaces every onRenderError of defineRegistry.
-     */
-    onRenderError?: RenderErrorHandler;
-}
-/**
- * The abstract base class of an actor of the Play Architecture.
- *
- * 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.** 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.
- *
- * @typeParam TLogic - The type of the XState actor logic
- * @typeParam TEvent - The constraint of the event type. The default is EventObject
- */
-export declare abstract class AbstractActor<TLogic extends AnyActorLogic, TEvent extends EventObject = EventObject> extends Actor<TLogic> {
-    /**
-     * 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.
-     */
-    abstract state: Signal.State<unknown>;
-    /**
-     * Sends an event to the Actor.
-     *
-     * The constraint is TEvent, which gives the type safety of a concrete
-     * implementation.
-     *
-     * 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.
-     */
-    abstract send(event: TEvent): void;
-}
-//# sourceMappingURL=abstract-actor.d.ts.map

package/dist/abstract-actor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,QAAQ,CAEnE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,4DAA4D;IAC5D,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,2FAA2F;IAC3F,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uHAAuH;IACvH,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;;OAaG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}

package/dist/abstract-actor.js

@@ -1,76 +0,0 @@
-/**
- * The AbstractActor base class of the Play Architecture
- *
- * It extends the XState Actor class, which keeps the compatibility with the
- * ecosystem, such as the inspection and the devtools. It also enforces the signal
- * protocol of the communication between the Actor and the infrastructure.
- *
- * RFC section 5.3 gives the minimal protocol of the Actor:
- * - state: the snapshot of the current machine state
- * - send: the method that sends an event
- *
- * Two interfaces give the optional capabilities:
- * - Routable: for an actor with a routing support
- * - Viewable: for an actor with a view rendering
- *
- * An adapter, such as @xmachines/play-xstate, makes the concrete implementations.
- *
- * @packageDocumentation
- */
-import { Actor } from "xstate";
-/**
- * The identity helper gives a view spec literal the type `PlaySpec` at the
- * definition site. The compiler therefore checks the spec, and the IDE completes it.
- *
- * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
- * therefore infers no spec shape from the context. `typedSpec(...)` is the
- * mechanism that starts the check where you write the spec. The parameter holds no
- * `viewKey`: the derivation stamps that field, and it overwrites a value from an
- * author without a notice. Therefore the compiler refuses a `viewKey` here.
- *
- * The check of an excess property works on an inline object literal only. For a
- * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
- * the literal instead.
- *
- * At run time this function does nothing: it returns the spec object without a
- * change.
- *
- * @example
- * ```ts
- * meta: {
- *   view: typedSpec({
- *     root: "root",
- *     elements: {
- *       root: {
- *         type: "Dashboard",
- *         props: { username: { $state: "/context/username" } },
- *         children: [],
- *       },
- *     },
- *   }),
- * }
- * ```
- */
-export function typedSpec(spec) {
-    return spec;
-}
-/**
- * The abstract base class of an actor of the Play Architecture.
- *
- * 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.** 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.
- *
- * @typeParam TLogic - The type of the XState actor logic
- * @typeParam TEvent - The constraint of the event type. The default is EventObject
- */
-export class AbstractActor extends Actor {
-}
-//# sourceMappingURL=abstract-actor.js.map

package/dist/abstract-actor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAqCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,SAAS,CAAC,IAA+B;IACxD,OAAO,IAAI,CAAC;AACb,CAAC;AAuFD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAwBtB"}

package/dist/context-projection.d.ts

@@ -1,116 +0,0 @@
-/**
- * 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 "./abstract-actor.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";
-/**
- * The shallow equality of the own keys, with `Object.is`. It can ignore one key on
- * both sides.
- *
- * This is the one comparison rule behind every decision of the emission dedup: the
- * equality of a slice, and also the emit gate of the player, which compares the
- * spec fields in `viewSpecsEquivalent` and reuses the composed state in
- * {@link reuseComposedState}.
- */
-export declare function shallowEqualExcept(a: object, b: object, except?: string): boolean;
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"context-projection.d.ts","sourceRoot":"","sources":["../src/context-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAiB3C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAUjF;AAED;;;;;;;;;;;;;;;;;;;;;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,CA8ChE;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

@@ -1,236 +0,0 @@
-/**
- * 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
- */
-/**
- * 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);
-}
-/**
- * The shallow equality of the own keys, with `Object.is`. It can ignore one key on
- * both sides.
- *
- * This is the one comparison rule behind every decision of the emission dedup: the
- * equality of a slice, and also the emit gate of the player, which compares the
- * spec fields in `viewSpecsEquivalent` and reuses the composed state in
- * {@link reuseComposedState}.
- */
-export function shallowEqualExcept(a, b, except) {
-    const aEntries = Object.entries(a).filter(([key]) => key !== except);
-    const bKeyCount = Object.keys(b).filter((key) => key !== except).length;
-    if (aEntries.length !== bKeyCount)
-        return false;
-    const bRecord = b;
-    for (const [key, value] of aEntries) {
-        // nosemgrep: gitlab.eslint.detect-object-injection
-        if (!Object.hasOwn(b, key) || !Object.is(value, bRecord[key]))
-            return false;
-    }
-    return true;
-}
-/**
- * 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 Error(`[play-actor] "${path}" is read-only: /${CONTEXT_STATE_KEY} mirrors the machine's context. ` +
-            `Send the actor an event to change it — context never changes through the view store.`);
-    };
-    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-actor] 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

@@ -1 +0,0 @@
-{"version":3,"file":"context-projection.js","sourceRoot":"","sources":["../src/context-projection.ts"],"names":[],"mappings":"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"}