@xmachines/play-actor 2.0.0 → 2.1.0

package/dist/provider-guards.d.ts

@@ -1,54 +1,58 @@
 /**
- * Shared provider guards for framework ActorProvider implementations.
+ * The shared provider guards of the ActorProvider implementation of each framework.
  *
- * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
- * two rituals when bridging an actor's view to a json-render tree:
+ * Every framework integration (React, Vue, Solid, Svelte, and DOM) does the same
+ * two steps when it connects the view of an actor to a json-render tree:
  *
- * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ * 1. It cleans `spec.state` before it seeds a new `@xstate/store` atom
  *    ({@link toAtomState}).
- * 2. Inject a component-level `onRenderError` handler into the component
- *    registry without mutating the caller's registry
+ * 2. It puts an `onRenderError` handler of the component level into the component
+ *    registry, and it does not change the registry of the caller
  *    ({@link attachRenderErrorHandler}).
  *
- * Centralising them here keeps the guard semantics identical across frameworks.
+ * Both functions are here. Therefore the semantics of the guards are identical in
+ * every framework.
  *
  * @packageDocumentation
  */
 import type { RenderErrorHandler } from "@xmachines/json-render-core";
 /**
- * Safely coerce a spec's `state` field to a plain object for `createAtom`.
- *
- * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
- * `null`, `undefined`, a primitive, or a plain object depending on what the
- * machine author put in the view spec. `createAtom` requires a plain object as
- * its initial value — anything else produces a broken store at runtime.
- *
- * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
- * and returned as-is. Everything else — `null`, `undefined`, primitives,
- * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
- * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
- *
- * @param state - The raw `spec.state` value from a `PlaySpec`.
- * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ * Converts the `state` field of a spec into a plain object for `createAtom`, in a safe way.
+ *
+ * `spec.state` has the type `unknown` in `PlaySpec`. At run time it is `null`,
+ * `undefined`, a primitive, or a plain object, and this depends on the value that
+ * the author of the machine put in the view spec. `createAtom` requires a plain
+ * object as its first value, because every other value makes a broken store at run
+ * time.
+ *
+ * The function accepts a plain object only, which means that its prototype is
+ * `Object.prototype` or `null`, and it returns that object without a change. Every
+ * other value becomes a new `{}`: `null`, `undefined`, a primitive, an array, an
+ * instance of a class, and a built-in object such as a Date, a Map, or a Set. A
+ * broken store therefore never appears at run time.
+ *
+ * @param state - The raw `spec.state` value of a `PlaySpec`.
+ * @returns `state` itself when it is a plain object. In every other case, a new empty object.
  */
 export declare function toAtomState(state: unknown): Record<string, unknown>;
 /**
- * Clone a component registry and inject an `onRenderError` handler.
+ * Copies a component registry, and puts an `onRenderError` handler into the copy.
  *
- * The handler is defined as a non-enumerable, configurable own property on the
- * clone (per D-19 — one injection convention for all framework renderers), so
- * it overrides any handler set at `defineRegistry` level without showing up
- * when the registry's component entries are enumerated.
+ * The function defines the handler as an own property of the copy. That property is
+ * not enumerable, and it is configurable (D-19 gives one convention of the
+ * injection for every framework renderer). The handler therefore replaces each
+ * handler of the `defineRegistry` level, and it does not appear in an enumeration of
+ * the component entries of the registry.
  *
- * The caller's registry is never mutated — a shallow clone is returned. Callers
- * that need per-instance handlers (e.g. an `onRenderError` prop on
- * `ActorProvider`) can therefore share one `defineRegistry` result across
- * providers safely.
+ * The function never changes the registry of the caller: it returns a shallow copy.
+ * Therefore a caller that needs a handler for each instance, such as an
+ * `onRenderError` prop of `ActorProvider`, can share one result of `defineRegistry`
+ * between the providers in a safe way.
  *
- * @typeParam TRegistry - The framework-specific component registry type.
+ * @typeParam TRegistry - The component registry type of the framework.
  * @param registry - The component registry from `defineRegistry().registry`.
- * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
- * @returns A shallow clone of `registry` with `onRenderError` attached.
+ * @param handler - The renderer calls it with `(error, componentName)` when a catalog component throws during a render.
+ * @returns A shallow copy of `registry`, with `onRenderError` on it.
  */
 export declare function attachRenderErrorHandler<TRegistry extends object>(registry: TRegistry, handler: RenderErrorHandler): TRegistry;
 //# sourceMappingURL=provider-guards.d.ts.map

package/dist/provider-guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-guards.d.ts","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,MAAM,EAChE,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,kBAAkB,GACzB,SAAS,CAQX"}
+{"version":3,"file":"provider-guards.d.ts","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,MAAM,EAChE,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,kBAAkB,GACzB,SAAS,CAQX"}

package/dist/provider-guards.js

@@ -1,34 +1,37 @@
 /**
- * Shared provider guards for framework ActorProvider implementations.
+ * The shared provider guards of the ActorProvider implementation of each framework.
  *
- * Every framework integration (React, Vue, Solid, Svelte, DOM) performs the same
- * two rituals when bridging an actor's view to a json-render tree:
+ * Every framework integration (React, Vue, Solid, Svelte, and DOM) does the same
+ * two steps when it connects the view of an actor to a json-render tree:
  *
- * 1. Sanitize `spec.state` before seeding a fresh `@xstate/store` atom
+ * 1. It cleans `spec.state` before it seeds a new `@xstate/store` atom
  *    ({@link toAtomState}).
- * 2. Inject a component-level `onRenderError` handler into the component
- *    registry without mutating the caller's registry
+ * 2. It puts an `onRenderError` handler of the component level into the component
+ *    registry, and it does not change the registry of the caller
  *    ({@link attachRenderErrorHandler}).
  *
- * Centralising them here keeps the guard semantics identical across frameworks.
+ * Both functions are here. Therefore the semantics of the guards are identical in
+ * every framework.
  *
  * @packageDocumentation
  */
 /**
- * Safely coerce a spec's `state` field to a plain object for `createAtom`.
+ * Converts the `state` field of a spec into a plain object for `createAtom`, in a safe way.
  *
- * `spec.state` is typed as `unknown` in `PlaySpec`. At runtime it can be
- * `null`, `undefined`, a primitive, or a plain object depending on what the
- * machine author put in the view spec. `createAtom` requires a plain object as
- * its initial value — anything else produces a broken store at runtime.
+ * `spec.state` has the type `unknown` in `PlaySpec`. At run time it is `null`,
+ * `undefined`, a primitive, or a plain object, and this depends on the value that
+ * the author of the machine put in the view spec. `createAtom` requires a plain
+ * object as its first value, because every other value makes a broken store at run
+ * time.
  *
- * Only plain objects (prototype is `Object.prototype` or `null`) are accepted
- * and returned as-is. Everything else — `null`, `undefined`, primitives,
- * arrays, class instances, and built-in objects (Date, Map, Set, etc.) — falls
- * back to a fresh `{}`, preventing silent broken-store bugs at runtime.
+ * The function accepts a plain object only, which means that its prototype is
+ * `Object.prototype` or `null`, and it returns that object without a change. Every
+ * other value becomes a new `{}`: `null`, `undefined`, a primitive, an array, an
+ * instance of a class, and a built-in object such as a Date, a Map, or a Set. A
+ * broken store therefore never appears at run time.
  *
- * @param state - The raw `spec.state` value from a `PlaySpec`.
- * @returns `state` itself when it is a plain object, otherwise a new empty object.
+ * @param state - The raw `spec.state` value of a `PlaySpec`.
+ * @returns `state` itself when it is a plain object. In every other case, a new empty object.
  */
 export function toAtomState(state) {
     if (state !== null && typeof state === "object" && !Array.isArray(state)) {
@@ -40,22 +43,23 @@ export function toAtomState(state) {
     return {};
 }
 /**
- * Clone a component registry and inject an `onRenderError` handler.
+ * Copies a component registry, and puts an `onRenderError` handler into the copy.
  *
- * The handler is defined as a non-enumerable, configurable own property on the
- * clone (per D-19 — one injection convention for all framework renderers), so
- * it overrides any handler set at `defineRegistry` level without showing up
- * when the registry's component entries are enumerated.
+ * The function defines the handler as an own property of the copy. That property is
+ * not enumerable, and it is configurable (D-19 gives one convention of the
+ * injection for every framework renderer). The handler therefore replaces each
+ * handler of the `defineRegistry` level, and it does not appear in an enumeration of
+ * the component entries of the registry.
  *
- * The caller's registry is never mutated — a shallow clone is returned. Callers
- * that need per-instance handlers (e.g. an `onRenderError` prop on
- * `ActorProvider`) can therefore share one `defineRegistry` result across
- * providers safely.
+ * The function never changes the registry of the caller: it returns a shallow copy.
+ * Therefore a caller that needs a handler for each instance, such as an
+ * `onRenderError` prop of `ActorProvider`, can share one result of `defineRegistry`
+ * between the providers in a safe way.
  *
- * @typeParam TRegistry - The framework-specific component registry type.
+ * @typeParam TRegistry - The component registry type of the framework.
  * @param registry - The component registry from `defineRegistry().registry`.
- * @param handler - Called with `(error, componentName)` when a catalog component throws during render.
- * @returns A shallow clone of `registry` with `onRenderError` attached.
+ * @param handler - The renderer calls it with `(error, componentName)` when a catalog component throws during a render.
+ * @returns A shallow copy of `registry`, with `onRenderError` on it.
  */
 export function attachRenderErrorHandler(registry, handler) {
     const clone = { ...registry };

package/dist/provider-guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-guards.js","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;QACtD,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAClD,OAAO,KAAgC,CAAC;QACzC,CAAC;IACF,CAAC;IACD,OAAO,EAAE,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmB,EACnB,OAA2B;IAE3B,MAAM,KAAK,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC9B,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE;QAC7C,KAAK,EAAE,OAAO;QACd,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KAClB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACd,CAAC"}
+{"version":3,"file":"provider-guards.js","sourceRoot":"","sources":["../src/provider-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;QACtD,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAClD,OAAO,KAAgC,CAAC;QACzC,CAAC;IACF,CAAC;IACD,OAAO,EAAE,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmB,EACnB,OAA2B;IAE3B,MAAM,KAAK,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC9B,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE;QAC7C,KAAK,EAAE,OAAO;QACd,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KAClB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/view-store-lifecycle.d.ts

@@ -1,77 +1,82 @@
 /**
- * View-store lifecycle — the framework-agnostic reseed-vs-refresh decision
- * every provider wires into its own reactivity.
+ * The lifecycle of the view store — the framework-agnostic decision between a new
+ * seed and a refresh. Each provider connects it to its own reactivity.
  *
- * The policy in one place (previously hand-copied per renderer, where the
- * copies drifted into real bugs):
+ * The policy is in one place now. Each renderer held a copy of it before, and those
+ * copies moved apart into real faults:
  *
- * - `viewKey` changed (or first resolve, or actor swapped) → RESEED: a fresh
- *   store from the view's composed state.
- * - `viewKey` unchanged → REFRESH: only the /context projection moved, so the
- *   `/context` subtree is replaced in place and ephemeral root-level state
- *   (drafts, toggles) survives.
- * - No `viewKey` (a hand-built Viewable that does not stamp one) → reseed per
- *   EMISSION, the safe pre-viewKey behavior.
- * - Actor swap → the kept-alive store dies with its actor (lifetime rule).
- * - Controlled mode (caller-supplied store) → the caller owns seeding and
- *   lifecycle, but /context is machinery-owned in both modes and is refreshed
- *   here — unless the caller defers it ({@link ResolveViewStoreOptions}),
- *   which React's render path needs (store subscribers must not be notified
- *   mid-render; its effects refresh instead).
+ * - The `viewKey` changed, or this is the first resolve, or the tree provides a
+ *   different actor → NEW SEED: a new store, from the composed state of the view.
+ * - The `viewKey` did not change → REFRESH: only the /context projection moved.
+ *   Therefore the code replaces the `/context` subtree in place, and the ephemeral
+ *   state at the root level, such as a draft or a toggle, stays.
+ * - No `viewKey`, from a Viewable that a person built and that stamps no key → a new
+ *   seed for each EMISSION, which is the safe behavior from the time before the
+ *   viewKey.
+ * - A different actor → the store that stays alive dies with its actor. This is the
+ *   rule of the lifetime.
+ * - The controlled mode, where the caller gives the store → the caller owns the seed
+ *   and the lifecycle. The machinery owns /context in both modes, and this file
+ *   refreshes it. The caller can move that refresh to a later moment
+ *   ({@link ResolveViewStoreOptions}), and the render path of React needs this,
+ *   because a store must notify no subscriber during a render. The effects of React
+ *   then do the refresh.
  *
- * What stays in each provider is only reactivity wiring: WHEN to resolve, and
- * how the result reaches children.
+ * Each provider therefore holds the wiring of its reactivity only: the moment of
+ * the resolve, and the path of the result to the children.
  *
  * @packageDocumentation
  */
 import type { StateStore } from "@xmachines/json-render-core";
 import type { PlaySpec } from "./abstract-actor.js";
-/** What a resolve produced — see {@link ViewStoreLifecycle.resolve}. */
+/** The result of a resolve — see {@link ViewStoreLifecycle.resolve}. */
 export interface ViewStoreResolution {
-    /** The UNGUARDED store — the machinery's own refresh reference. */
+    /** The store WITHOUT the guard — the reference of the machinery for its own refresh. */
     store: StateStore;
     /**
-     * The store to hand children ($bindState, setState, chained set): writes
-     * under /context throw. One wrapper per underlying store — the identity is
-     * cached so `useSyncExternalStore`-style consumers stay stable.
+     * The store to give to the children ($bindState, setState, and a chained set): a
+     * write under /context throws. There is one wrapper for each store below it, and
+     * the code caches the identity. Therefore a consumer in the style of
+     * `useSyncExternalStore` stays stable.
      */
     guardedStore: StateStore;
     /**
-     * True when this resolve created a fresh store (first resolve, viewKey
-     * change, per-emission fallback, actor swap). Providers that remount a
-     * subtree per store (Vue's storeKey) key on it.
+     * It is true when this resolve made a new store: at the first resolve, on a change
+     * of the viewKey, in the fallback for each emission, and on a change of the actor. A
+     * provider that mounts a subtree again for each store, such as the storeKey of Vue,
+     * uses this field as its key.
      */
     reseeded: boolean;
 }
 export interface ResolveViewStoreOptions {
     /**
-     * Controlled mode only: refresh the external store's /context during this
-     * resolve (default true). Pass false where notifying store subscribers is
-     * not allowed at the call site (React's render path) and refresh from an
-     * effect instead.
+     * The controlled mode only: refresh the /context subtree of the external store
+     * during this resolve. The default is true. Give false where the call site permits
+     * no notification of the store subscribers, which is the render path of React, and
+     * refresh from an effect instead.
      */
     refreshExternalStore?: boolean;
 }
 export interface ViewStoreLifecycle {
     /**
-     * Bring the store in line with an emission and return it (with its guard).
+     * Brings the store in line with an emission, and returns it with its guard.
      *
-     * @param actor - The actor the emission came from — a swap drops the kept store.
-     * @param view - The derived view (non-null; a null emission is a GAP, not a
-     *   new view — callers simply do not resolve on null, keeping the store).
-     * @param externalStore - Controlled mode: the caller-owned store.
+     * @param actor - The actor of the emission. A different actor drops the store that the code kept.
+     * @param view - The derived view. It is not null: a null emission is a GAP, and not
+     *   a new view. A caller resolves nothing on a null value, and it keeps the store.
+     * @param externalStore - The controlled mode: the store of the caller.
      * @param options - See {@link ResolveViewStoreOptions}.
      */
     resolve(actor: unknown, view: PlaySpec, externalStore?: StateStore | undefined, options?: ResolveViewStoreOptions): ViewStoreResolution;
-    /** Drop everything (unmount/disconnect) — the next resolve reseeds. */
+    /** Drops everything, on an unmount or a disconnect. The next resolve makes a new seed. */
     reset(): void;
 }
 /**
- * Create a lifecycle coordinator.
+ * Creates a coordinator of the lifecycle.
  *
- * @param createStore - Framework-supplied store factory; receives the
- *   proto-safe seed (`toAtomState(view.state)` — the composed state already
- *   carries /context).
+ * @param createStore - The store factory of the framework. It receives the seed
+ *   that is safe for the prototype (`toAtomState(view.state)`), and the composed
+ *   state carries /context already.
  */
 export declare function createViewStoreLifecycle(createStore: (seed: Record<string, unknown>) => StateStore): ViewStoreLifecycle;
 //# sourceMappingURL=view-store-lifecycle.d.ts.map

package/dist/view-store-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-store-lifecycle.d.ts","sourceRoot":"","sources":["../src/view-store-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IACnC,mEAAmE;IACnE,KAAK,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,YAAY,EAAE,UAAU,CAAC;IACzB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;OAQG;IACH,OAAO,CACN,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,QAAQ,EACd,aAAa,CAAC,EAAE,UAAU,GAAG,SAAS,EACtC,OAAO,CAAC,EAAE,uBAAuB,GAC/B,mBAAmB,CAAC;IACvB,uEAAuE;IACvE,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,GACxD,kBAAkB,CA4DpB"}
+{"version":3,"file":"view-store-lifecycle.d.ts","sourceRoot":"","sources":["../src/view-store-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IACnC,wFAAwF;IACxF,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;OAKG;IACH,YAAY,EAAE,UAAU,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;OAQG;IACH,OAAO,CACN,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,QAAQ,EACd,aAAa,CAAC,EAAE,UAAU,GAAG,SAAS,EACtC,OAAO,CAAC,EAAE,uBAAuB,GAC/B,mBAAmB,CAAC;IACvB,0FAA0F;IAC1F,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,GACxD,kBAAkB,CA4DpB"}

package/dist/view-store-lifecycle.js

@@ -1,44 +1,47 @@
 /**
- * View-store lifecycle — the framework-agnostic reseed-vs-refresh decision
- * every provider wires into its own reactivity.
+ * The lifecycle of the view store — the framework-agnostic decision between a new
+ * seed and a refresh. Each provider connects it to its own reactivity.
  *
- * The policy in one place (previously hand-copied per renderer, where the
- * copies drifted into real bugs):
+ * The policy is in one place now. Each renderer held a copy of it before, and those
+ * copies moved apart into real faults:
  *
- * - `viewKey` changed (or first resolve, or actor swapped) → RESEED: a fresh
- *   store from the view's composed state.
- * - `viewKey` unchanged → REFRESH: only the /context projection moved, so the
- *   `/context` subtree is replaced in place and ephemeral root-level state
- *   (drafts, toggles) survives.
- * - No `viewKey` (a hand-built Viewable that does not stamp one) → reseed per
- *   EMISSION, the safe pre-viewKey behavior.
- * - Actor swap → the kept-alive store dies with its actor (lifetime rule).
- * - Controlled mode (caller-supplied store) → the caller owns seeding and
- *   lifecycle, but /context is machinery-owned in both modes and is refreshed
- *   here — unless the caller defers it ({@link ResolveViewStoreOptions}),
- *   which React's render path needs (store subscribers must not be notified
- *   mid-render; its effects refresh instead).
+ * - The `viewKey` changed, or this is the first resolve, or the tree provides a
+ *   different actor → NEW SEED: a new store, from the composed state of the view.
+ * - The `viewKey` did not change → REFRESH: only the /context projection moved.
+ *   Therefore the code replaces the `/context` subtree in place, and the ephemeral
+ *   state at the root level, such as a draft or a toggle, stays.
+ * - No `viewKey`, from a Viewable that a person built and that stamps no key → a new
+ *   seed for each EMISSION, which is the safe behavior from the time before the
+ *   viewKey.
+ * - A different actor → the store that stays alive dies with its actor. This is the
+ *   rule of the lifetime.
+ * - The controlled mode, where the caller gives the store → the caller owns the seed
+ *   and the lifecycle. The machinery owns /context in both modes, and this file
+ *   refreshes it. The caller can move that refresh to a later moment
+ *   ({@link ResolveViewStoreOptions}), and the render path of React needs this,
+ *   because a store must notify no subscriber during a render. The effects of React
+ *   then do the refresh.
  *
- * What stays in each provider is only reactivity wiring: WHEN to resolve, and
- * how the result reaches children.
+ * Each provider therefore holds the wiring of its reactivity only: the moment of
+ * the resolve, and the path of the result to the children.
  *
  * @packageDocumentation
  */
 import { guardContextWrites, refreshContextSubtree } from "./context-projection.js";
 import { toAtomState } from "./provider-guards.js";
 /**
- * Create a lifecycle coordinator.
+ * Creates a coordinator of the lifecycle.
  *
- * @param createStore - Framework-supplied store factory; receives the
- *   proto-safe seed (`toAtomState(view.state)` — the composed state already
- *   carries /context).
+ * @param createStore - The store factory of the framework. It receives the seed
+ *   that is safe for the prototype (`toAtomState(view.state)`), and the composed
+ *   state carries /context already.
  */
 export function createViewStoreLifecycle(createStore) {
     let internalStore = null;
     let lastViewKey = undefined;
     let lastView = null;
     let lastActor = null;
-    // Guard identity cache — one wrapper per underlying store.
+    // The identity cache of the guard: one wrapper for each store below it.
     let guardedSource = null;
     let guardedStore = null;
     const reset = () => {
@@ -52,7 +55,7 @@ export function createViewStoreLifecycle(createStore) {
     return {
         reset,
         resolve(actor, view, externalStore, options) {
-            // Lifetime rule: a kept-alive store must not outlive its actor.
+            // The rule of the lifetime: a store that stays alive must not outlive its actor.
             if (lastActor !== actor) {
                 const firstResolve = lastActor === null && internalStore === null;
                 if (!firstResolve)

package/dist/view-store-lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"view-store-lifecycle.js","sourceRoot":"","sources":["../src/view-store-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAkDnD;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACvC,WAA0D;IAE1D,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,WAAW,GAAuB,SAAS,CAAC;IAChD,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,SAAS,GAAY,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,YAAY,GAAsB,IAAI,CAAC;IAE3C,MAAM,KAAK,GAAG,GAAS,EAAE;QACxB,aAAa,GAAG,IAAI,CAAC;QACrB,WAAW,GAAG,SAAS,CAAC;QACxB,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;QACjB,aAAa,GAAG,IAAI,CAAC;QACrB,YAAY,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC;IAEF,OAAO;QACN,KAAK;QACL,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO;YAC1C,gEAAgE;YAChE,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;gBACzB,MAAM,YAAY,GAAG,SAAS,KAAK,IAAI,IAAI,aAAa,KAAK,IAAI,CAAC;gBAClE,IAAI,CAAC,YAAY;oBAAE,KAAK,EAAE,CAAC;gBAC3B,SAAS,GAAG,KAAK,CAAC;YACnB,CAAC;YAED,IAAI,QAAoB,CAAC;YACzB,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,aAAa,EAAE,CAAC;gBACnB,QAAQ,GAAG,aAAa,CAAC;gBACzB,IAAI,OAAO,EAAE,oBAAoB,KAAK,KAAK,EAAE,CAAC;oBAC7C,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBACvC,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;gBAC7B,IAAI,SAAS,GAAsB,aAAa,CAAC;gBACjD,IACC,SAAS,KAAK,IAAI;oBAClB,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,EACpE,CAAC;oBACF,SAAS,GAAG,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;oBACjD,aAAa,GAAG,SAAS,CAAC;oBAC1B,WAAW,GAAG,OAAO,CAAC;oBACtB,QAAQ,GAAG,IAAI,CAAC;gBACjB,CAAC;qBAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;oBAClC,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;gBACD,QAAQ,GAAG,IAAI,CAAC;gBAChB,QAAQ,GAAG,SAAS,CAAC;YACtB,CAAC;YAED,IAAI,aAAa,KAAK,QAAQ,EAAE,CAAC;gBAChC,aAAa,GAAG,QAAQ,CAAC;gBACzB,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,YAA0B,EAAE,QAAQ,EAAE,CAAC;QAChF,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"view-store-lifecycle.js","sourceRoot":"","sources":["../src/view-store-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAoDnD;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACvC,WAA0D;IAE1D,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,WAAW,GAAuB,SAAS,CAAC;IAChD,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,SAAS,GAAY,IAAI,CAAC;IAC9B,wEAAwE;IACxE,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,YAAY,GAAsB,IAAI,CAAC;IAE3C,MAAM,KAAK,GAAG,GAAS,EAAE;QACxB,aAAa,GAAG,IAAI,CAAC;QACrB,WAAW,GAAG,SAAS,CAAC;QACxB,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;QACjB,aAAa,GAAG,IAAI,CAAC;QACrB,YAAY,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC;IAEF,OAAO;QACN,KAAK;QACL,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO;YAC1C,iFAAiF;YACjF,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;gBACzB,MAAM,YAAY,GAAG,SAAS,KAAK,IAAI,IAAI,aAAa,KAAK,IAAI,CAAC;gBAClE,IAAI,CAAC,YAAY;oBAAE,KAAK,EAAE,CAAC;gBAC3B,SAAS,GAAG,KAAK,CAAC;YACnB,CAAC;YAED,IAAI,QAAoB,CAAC;YACzB,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,aAAa,EAAE,CAAC;gBACnB,QAAQ,GAAG,aAAa,CAAC;gBACzB,IAAI,OAAO,EAAE,oBAAoB,KAAK,KAAK,EAAE,CAAC;oBAC7C,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBACvC,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;gBAC7B,IAAI,SAAS,GAAsB,aAAa,CAAC;gBACjD,IACC,SAAS,KAAK,IAAI;oBAClB,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,EACpE,CAAC;oBACF,SAAS,GAAG,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;oBACjD,aAAa,GAAG,SAAS,CAAC;oBAC1B,WAAW,GAAG,OAAO,CAAC;oBACtB,QAAQ,GAAG,IAAI,CAAC;gBACjB,CAAC;qBAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;oBAClC,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;gBACD,QAAQ,GAAG,IAAI,CAAC;gBAChB,QAAQ,GAAG,SAAS,CAAC;YACtB,CAAC;YAED,IAAI,aAAa,KAAK,QAAQ,EAAE,CAAC;gBAChC,aAAa,GAAG,QAAQ,CAAC;gBACzB,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,YAA0B,EAAE,QAAQ,EAAE,CAAC;QAChF,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "Abstract Actor base class for XMachines Play Architecture",
   "keywords": [
@@ -40,6 +40,7 @@
     "build": "vite build && tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
     "test": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
@@ -57,8 +58,8 @@
   },
   "peerDependencies": {
     "@xmachines/json-render-core": "^0.20.0-xm.2",
-    "@xmachines/play": "2.0.0",
-    "@xmachines/play-signals": "2.0.0",
+    "@xmachines/play": "2.1.0",
+    "@xmachines/play-signals": "2.1.0",
     "xstate": "^5.31.0"
   },
   "engines": {