@xmachines/play-actor 2.0.0-alpha.1 → 2.1.0

package/dist/abstract-actor.js

@@ -1,47 +1,52 @@
 /**
- * AbstractActor base class for Play Architecture
+ * The AbstractActor base class of the Play Architecture
  *
- * Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
- * while enforcing signal protocol for Actor ↔ Infrastructure communication.
+ * 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.
  *
- * Per RFC section 5.3, the Actor exposes a minimal protocol:
- * - state: Current machine state snapshot
- * - send: Event dispatch method
+ * 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
  *
- * Optional capabilities are provided via interfaces:
- * - Routable: For actors that support routing
- * - Viewable: For actors that support view rendering
+ * Two interfaces give the optional capabilities:
+ * - Routable: for an actor with a routing support
+ * - Viewable: for an actor with a view rendering
  *
- * Concrete implementations are created by adapters (e.g., @xmachines/play-xstate).
+ * An adapter, such as @xmachines/play-xstate, makes the concrete implementations.
  *
  * @packageDocumentation
  */
 import { Actor } from "xstate";
 /**
- * Identity helper that constrains a `PlaySpec` object's `contextProps` to keys
- * of a specific machine context type, giving compile-time validation and IDE
- * autocomplete at the definition site.
+ * 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.
  *
- * XState's `meta` field is typed as `Record<string, unknown>`, so TypeScript
- * cannot infer the constraint from context. `typedSpec<MyCtx>(...)` is the
- * opt-in mechanism that activates enforcement where the spec is written.
+ * 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.
  *
- * At runtime this is a no-op — the spec object is returned unchanged.
+ * 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
- * interface DashboardCtx {
- *   username: string;
- *   params: Record<string, string>;
- *   query: Record<string, string>;
- * }
- *
  * meta: {
- *   view: typedSpec<DashboardCtx>({
+ *   view: typedSpec({
  *     root: "root",
- *     contextProps: ["username"],    // ✓ key of DashboardCtx
- *     // contextProps: ["usernaem"], // ✗ compile error
- *     elements: { root: { type: "Dashboard", props: {}, children: [] } },
+ *     elements: {
+ *       root: {
+ *         type: "Dashboard",
+ *         props: { username: { $state: "/context/username" } },
+ *         children: [],
+ *       },
+ *     },
  *   }),
  * }
  * ```
@@ -50,14 +55,21 @@ export function typedSpec(spec) {
     return spec;
 }
 /**
- * Abstract base class for Play Architecture actors.
+ * 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.
  *
- * Provides signal-driven state observation that integrates with XState ecosystem
- * tooling (devtools, inspection) while exposing reactive signals for
- * Infrastructure layer communication.
+ * **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 - XState actor logic type
- * @typeParam TEvent - Event type constraint (defaults to EventObject)
+ * @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 {
 }

package/dist/abstract-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAuCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAiFD;;;;;;;;;GASG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAetB"}
+{"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

@@ -0,0 +1,116 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,236 @@
+/**
+ * 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

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

package/dist/index.d.ts

@@ -1,20 +1,25 @@
 /**
- * @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:
- * - Routable: For actors that support routing
- * - Viewable: For actors that support view rendering
+ * The core protocol is minimal: state and send. Two interfaces give the optional
+ * capabilities:
+ * - 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.
  *
  * @packageDocumentation
  * @see [Play RFC](../../docs/rfc/play.md)
  */
 export { AbstractActor, typedSpec, type Routable, type Viewable, type PlaySpec, type BaseActorProviderProps, type BaseViewContextValue, } from "./abstract-actor.js";
 export { toAtomState, attachRenderErrorHandler } from "./provider-guards.js";
+export { CONTEXT_STATE_KEY, guardContextWrites, refreshContextSubtree, composePlayState, shallowEqualExcept, reuseComposedState, } from "./context-projection.js";
+export { createViewStoreLifecycle } from "./view-store-lifecycle.js";
+export type { ViewStoreLifecycle, ViewStoreResolution, ResolveViewStoreOptions, } from "./view-store-lifecycle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,GACvB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -1,20 +1,24 @@
 /**
- * @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:
- * - Routable: For actors that support routing
- * - Viewable: For actors that support view rendering
+ * The core protocol is minimal: state and send. Two interfaces give the optional
+ * capabilities:
+ * - 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.
  *
  * @packageDocumentation
  * @see [Play RFC](../../docs/rfc/play.md)
  */
 export { AbstractActor, typedSpec, } from "./abstract-actor.js";
 export { toAtomState, attachRenderErrorHandler } from "./provider-guards.js";
+export { CONTEXT_STATE_KEY, guardContextWrites, refreshContextSubtree, composePlayState, shallowEqualExcept, reuseComposedState, } from "./context-projection.js";
+export { createViewStoreLifecycle } from "./view-store-lifecycle.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}