@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/routing/format-play-route-transitions.js

@@ -3,24 +3,26 @@ import { shallowEqualExcept } from "@xmachines/play-actor";
 import { MissingStateIdError } from "../errors.js";
 import { normalizeRoute } from "./derive-route.js";
 /**
- * Reuse the previous params/query container when the incoming one is
- * shallow-equal.
+ * Reuses the previous container of the params and of the query when the new
+ * container is equal to it in a shallow comparison.
  *
- * Route params/query arrive as a FRESH object on every `play.route` event —
- * bridges rebuild them per URL parse, and `|| {}` allocates even for the
- * empty case — while the view emit gate compares context per field with
- * `Object.is`. Without reuse, a value-identical re-navigation (popstate to
- * the current URL, a redundant programmatic send) would re-emit the view
- * for nothing.
+ * The params and the query of a route arrive in a FRESH object on every `play.route`
+ * event: a bridge builds them again for each parse of a URL, and `|| {}` allocates
+ * an object also for the empty case. The emit gate of the view compares the context
+ * field by field, with `Object.is`. Without this reuse, a navigation to the same
+ * values, such as a popstate event to the current URL or a second send from the
+ * code, emits the view again for nothing.
  */
 const keepEqualContainer = (prev, next) => (prev !== undefined && shallowEqualExcept(prev, next) ? prev : next);
 /**
- * Formats play.route transitions from declarative route configs
+ * Makes the play.route transitions from the declarative route configs
  *
- * Crawls machine states looking for states with meta.route and generates
- * transitions that handle `play.route` events by matching event.to to state IDs.
+ * The function walks the machine states. It looks for each state with a `meta.route`
+ * field, and it generates the transitions that handle a `play.route` event: each
+ * transition matches event.to against a state ID.
  *
- * Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
+ * The internal formatRouteTransitions function of XState was the model for this
+ * function (stateUtils.ts, line 391).
  *
  * @example
  * ```typescript
@@ -35,26 +37,28 @@ const keepEqualContainer = (prev, next) => (prev !== undefined && shallowEqualEx
  * const machine = createMachine(formatPlayRouteTransitions(machineConfig));
  * ```
  *
- * This automatically generates play.route handlers at the root level that:
- * - Match event.to against state IDs (e.g., event.to === "#home")
- * - Target the appropriate state
- * - Assign params and query from the event to context
+ * The function generates the `play.route` handlers at the root level. Those
+ * handlers:
+ * - match event.to against a state ID, for example event.to === "#home"
+ * - target the correct state
+ * - assign the params and the query of the event to the context
  *
- * @param machineConfig - XState machine config (before createMachine). Must extend `RouteMachineConfig`.
- * @returns The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
+ * @param machineConfig - The XState machine config, before `createMachine`. It must extend `RouteMachineConfig`.
+ * @returns The same machine config, with the generated `play.route` handlers in it. The original type `T` stays.
  */
 export function formatPlayRouteTransitions(machineConfig) {
     const routeTransitions = [];
     const collectRoutes = (states, parentPath = "") => {
         Object.entries(states).forEach(([key, stateConfig]) => {
             const node = stateConfig;
-            // Build the full key-based path from the root for the transition target
-            // (XState targets use the state key hierarchy, not explicit IDs)
+            // Build the complete path of the keys, from the root, for the target of the
+            // transition. An XState target uses the hierarchy of the state keys, and not the
+            // explicit IDs.
             const statePath = parentPath ? `${parentPath}.${key}` : key;
-            // Validates the metadata (malformed object routes throw
-            // InvalidRouteMetadataError) and normalizes to the path string. Both
-            // the string form ("") and the object form ({ path: "" }) of an empty
-            // path mark the state non-routable.
+            // The function checks the metadata, and a malformed object route therefore throws an
+            // InvalidRouteMetadataError. It then normalizes the value into the string of the
+            // path. An empty path marks the state as a state without a route, in the string form
+            // ("") and also in the object form ({ path: "" }).
             const routePath = node.meta?.route === undefined
                 ? ""
                 : normalizeRoute(node.meta.route, "formatPlayRouteTransitions");
@@ -84,10 +88,10 @@ export function formatPlayRouteTransitions(machineConfig) {
     }
     if (routeTransitions.length > 0) {
         const existingOn = machineConfig.on || {};
-        // Preserve user-defined play.route transitions (e.g. a hand-written 404
-        // fallback) by appending them AFTER the generated ones: XState evaluates
-        // candidate transitions in order, so generated guards win when they match
-        // and the user's transitions act as fallbacks otherwise.
+        // Keep each play.route transition of the user, for example a 404 fallback that a
+        // person wrote, and append those transitions AFTER the generated ones: XState
+        // evaluates the candidate transitions in their order. Therefore a generated guard
+        // wins when it matches, and the transitions of the user are the fallback.
         const userRouteTransitions = existingOn["play.route"];
         const normalizedUserTransitions = userRouteTransitions === undefined
             ? []

package/dist/routing/format-play-route-transitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"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"}

package/dist/routing/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Route derivation and URL building utilities
+ * The utilities of the route derivation and of the URL construction
  *
- * Provides functions for extracting routes from state metadata
- * and building full URLs with parameter substitution.
+ * This module gives you the functions that read a route from the state metadata, and
+ * that build a complete URL with the substitution of each parameter.
  *
  * @packageDocumentation
  */

package/dist/routing/index.js

@@ -1,8 +1,8 @@
 /**
- * Route derivation and URL building utilities
+ * The utilities of the route derivation and of the URL construction
  *
- * Provides functions for extracting routes from state metadata
- * and building full URLs with parameter substitution.
+ * This module gives you the functions that read a route from the state metadata, and
+ * that build a complete URL with the substitution of each parameter.
  *
  * @packageDocumentation
  */

package/dist/routing/types.d.ts

@@ -4,24 +4,25 @@ export interface RouteObject {
 }
 export type RouteMetadata = string | RouteObject;
 /**
- * Route build context from machine context.
+ * The context of the route construction, from the machine context.
  *
- * All URL parameter substitution must go through `params` — flat context fields are not
- * inspected. This is intentional: the index signature was removed to enable compile-time
- * validation of context shapes and IDE autocomplete on context fields.
+ * Every substitution of a URL parameter reads `params`, because the type reads no
+ * flat context field. This is deliberate: the type has no index signature now, and
+ * the compiler therefore checks the shape of a context, and the IDE completes each
+ * context field.
  *
- * Machines using `formatPlayRouteTransitions` have `params` and `query` assigned
- * automatically from each `play.route` event. Machines that call `buildRouteUrl` directly
- * must populate `params` explicitly.
+ * A machine with `formatPlayRouteTransitions` receives its `params` field and its
+ * `query` field from each `play.route` event, and the transitions assign them. A
+ * machine that calls `buildRouteUrl` itself must fill `params` itself.
  */
 export interface RouteContext {
-    /** Base path for relative routes */
+    /** The base path of a relative route */
     basePath?: string;
-    /** Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) */
+    /** The parameters of the path to substitute, for example `:userId` of `/profile/:userId` */
     params?: Record<string, unknown>;
-    /** Query parameters */
+    /** The query parameters */
     query?: Record<string, unknown>;
-    /** Hash fragment */
+    /** The hash fragment */
     hash?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/routing/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}

package/dist/types.d.ts

@@ -1,80 +1,83 @@
 import type { ActorOptions, AnyStateMachine, InputFrom, SnapshotFrom } from "xstate";
 import type { PlayerActor as PlayerActorClass } from "./player-actor.js";
 /**
- * Configuration for definePlayer()
+ * The configuration of definePlayer()
  */
 export interface PlayerConfig<TMachine extends AnyStateMachine> {
-    /** XState v5 state machine */
+    /** The XState v5 state machine */
     machine: TMachine;
-    /** Lifecycle hooks and configuration */
+    /** The lifecycle hooks and the configuration */
     options?: PlayerOptions<TMachine>;
 }
 /**
- * Player lifecycle hooks — the observability surface around the actor.
+ * The lifecycle hooks of the player — the observability surface around the actor.
  */
 export interface PlayerOptions<TMachine extends AnyStateMachine> {
     /**
-     * Called on each real start: every transition from not-running to running,
-     * including a start after a stop. A repeated `start()` while the actor is
-     * already running does not re-fire it.
+     * The actor calls it on each real start, which is every transition from "not
+     * running" to "running". A start after a stop is such a transition. A second
+     * `start()` call while the actor runs fires the hook not again.
      */
     onStart?: (actor: PlayerActorClass<TMachine>) => void;
     /**
-     * Called on each real stop: only when a running actor was actually torn
-     * down. Repeated `stop()`/`dispose()` calls, and stopping an actor that
-     * never started, do not fire it.
+     * The actor calls it on each real stop, which means only after it tore a running
+     * actor down. A second `stop()` call, a second `dispose()` call, and a stop of an
+     * actor that never started fire the hook not.
      */
     onStop?: (actor: PlayerActorClass<TMachine>) => void;
     /**
-     * Called after every event `send()` processes — including events the
-     * machine ignores, where `prevState` and `nextState` are the same
-     * snapshot. Compare the two when only real transitions matter.
+     * The actor calls it after every event that `send()` processes. This includes an
+     * event that the machine ignores, and `prevState` and `nextState` are then the same
+     * snapshot. Compare the two values when only a real transition is important to
+     * you.
      */
     onTransition?: (actor: PlayerActorClass<TMachine>, prevState: SnapshotFrom<TMachine>, nextState: SnapshotFrom<TMachine>) => void;
-    /** Called when state signal changes */
+    /** The actor calls it when the state signal changes */
     onStateChange?: (actor: PlayerActorClass<TMachine>, state: SnapshotFrom<TMachine>) => void;
     /**
-     * Called on actor errors: a snapshot restore that fails at `start()`, a
-     * throwing action or guard, and view-derivation failures.
+     * The actor calls it on an actor error: a snapshot restore that fails at `start()`,
+     * an action or a guard that throws, and a failure of the view derivation.
      *
-     * Read when an error is delivered, not at construction: the options bag is
-     * shared by reference, so a handler attached to it later still receives
-     * actor errors, and removing the handler restores the loud default below.
+     * The actor reads this field at the moment of the delivery of an error, and not at
+     * its construction. The options object is shared by its reference. Therefore a
+     * handler on that object still receives each actor error, also after a later
+     * attachment, and the removal of the handler restores the loud default below.
      *
-     * With a handler in place, the error is routed there and counts as
-     * handled. XState decides its global rethrow per observer, beyond this
-     * option's reach: a subscription of your own without an `error` listener
-     * still forces it, `onError` or not.
+     * With a handler in place, the actor sends the error there, and the error counts as
+     * handled. XState decides its own global rethrow for each observer, and this option
+     * does not reach that decision: a subscription of your own without an `error`
+     * listener still forces the rethrow, with an `onError` handler and without one.
      *
-     * Without `onError`, actor errors stay loud (an unhandled rethrow via
-     * `setTimeout`) so they are never silently swallowed — and your own
-     * `error` subscribers do not suppress that default; only `onError` does.
+     * Without `onError`, each actor error stays loud, with an unhandled rethrow through
+     * `setTimeout`. No error therefore disappears in silence. Your own `error`
+     * subscribers stop that default not: `onError` alone stops it.
      *
-     * An actor failure that is already an `Error` arrives unchanged, keeping the
-     * identity the machine gave it. A machine that throws a non-`Error` value
-     * arrives as `ActorThrewNonErrorError` with the thrown value on `cause`.
+     * A failure of the actor that is an `Error` already arrives without a change, and it
+     * keeps the identity of the machine. A machine that throws a value that is not an
+     * `Error` arrives as an `ActorThrewNonErrorError`, with the value from the throw on
+     * its `cause` field.
      */
     onError?: (actor: PlayerActorClass<TMachine>, error: Error) => void;
     /**
-     * Inspection observer forwarded verbatim to XState's `createActor`.
+     * The inspection observer. The factory gives it to `createActor` of XState without
+     * a change.
      *
-     * This is the creation-time attachment route, and the only one that observes
-     * the actor's construction events. Attaching later via
-     * `actor.system.inspect(fn)` also works, but only sees events from that
-     * point on.
+     * This is the attachment at the moment of the creation, and it is the only route
+     * that observes the construction events of the actor. An attachment later, with
+     * `actor.system.inspect(fn)`, also works, but it sees only the events after that
+     * moment.
      *
-     * A `PlayerActor` is itself the XState actor, so its own events carry
-     * `actorRef === playerActor` and can be recognised by identity. Each
-     * `PlayerActor` is also its own root system, so `event.rootId ===
-     * actor.sessionId` demultiplexes the whole tree — including events from
-     * invoked and spawned children, whose `actorRef` is the child.
+     * A `PlayerActor` is the XState actor itself. Therefore its own events carry
+     * `actorRef === playerActor`, and you can recognize it by its identity. Each
+     * `PlayerActor` is also its own root system. Therefore `event.rootId ===
+     * actor.sessionId` separates the complete tree, and this includes the events of an
+     * invoked child and of a spawned child, whose `actorRef` is the child.
      *
-     * One caveat comes with that identity: the `@xstate.actor` event fires from
-     * inside the actor's constructor, so its `actorRef` is the instance
-     * mid-construction. `state`, `currentRoute`, `currentView` and
-     * `initialRoute` do not exist yet — reading them there throws. Capture the
-     * reference and read the signals from a later event, or from outside the
-     * observer.
+     * That identity brings one point to note: the `@xstate.actor` event fires from
+     * inside the constructor of the actor. Its `actorRef` value is therefore the
+     * instance during the construction, and `state`, `currentRoute`, `currentView`, and
+     * `initialRoute` do not exist yet. A read of one of them there throws. Keep the
+     * reference, and read the signals from a later event, or outside the observer.
      *
      * @example
      * ```typescript
@@ -84,35 +87,36 @@ export interface PlayerOptions<TMachine extends AnyStateMachine> {
      * const createPlayer = definePlayer({ machine, options: { inspect } });
      * ```
      *
-     * For an inspector created after the factory (e.g. behind a dev-tools toggle),
-     * pass a forwarding function: `inspect: (event) => currentInspector?.(event)`.
+     * For an inspector that you create after the factory, for example behind a dev-tools
+     * switch, give the factory a function that forwards each event:
+     * `inspect: (event) => currentInspector?.(event)`.
      */
     inspect?: ActorOptions<TMachine>["inspect"];
 }
 /**
- * Optional restore arguments for the player factory.
+ * The optional restore arguments of the player factory.
  *
- * Mirrors XState's createActor options bag while preserving the existing
- * `createPlayer(input?)` calling convention for fresh actors.
+ * The shape follows the options object of `createActor` in XState. It also keeps the
+ * `createPlayer(input?)` calling convention of a new actor.
  */
 export interface PlayerFactoryResumeOptions<TMachine extends AnyStateMachine> {
     /**
-     * Persisted XState snapshot used to restore actor state.
+     * The persisted XState snapshot. The factory restores the actor state from it.
      *
-     * Typed as XState's own `ActorOptions["snapshot"]` — the exact type
-     * `createActor` accepts and `getPersistedSnapshot()` returns — so restoring
-     * a stored snapshot never needs a cast.
+     * Its type is the `ActorOptions["snapshot"]` type of XState, which is the exact type
+     * that `createActor` accepts and that `getPersistedSnapshot()` returns. The restore
+     * of a stored snapshot therefore needs no cast.
      */
     snapshot?: ActorOptions<TMachine>["snapshot"];
 }
 /**
- * Factory function returned by definePlayer() — each call creates an
- * independent actor instance from the same configuration.
+ * The factory function that definePlayer() returns. Each call makes an independent
+ * actor instance from the same configuration.
  *
- * Input requiredness mirrors XState's `createActor`: a machine whose input
- * cannot be `undefined` makes the factory's first argument required, so
- * forgetting it is a compile error instead of an actor that starts in an
- * error status with a `null` initial route.
+ * The `input` argument follows the rule of `createActor` in XState. If the input of
+ * a machine cannot be `undefined`, the first argument of the factory is necessary.
+ * An absent input is then a compile error, and not an actor that starts in an error
+ * status with a `null` initial route.
  */
 export type PlayerFactory<TMachine extends AnyStateMachine> = undefined extends InputFrom<TMachine> ? (input?: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine> : (input: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,eAAe;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAElB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,eAAe;IAC9D;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,YAAY,CAAC,EAAE,CACd,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,KAC7B,IAAI,CAAC;IAEV,uCAAuC;IACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAE3F;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,eAAe;IAC3E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,eAAe,IACzD,SAAS,SAAS,SAAS,CAAC,QAAQ,CAAC,GAClC,CACA,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,GAC9B,CACA,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC1B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,eAAe;IAC7D,kCAAkC;IAClC,OAAO,EAAE,QAAQ,CAAC;IAElB,gDAAgD;IAChD,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,eAAe;IAC9D;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAErD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CACd,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,KAC7B,IAAI,CAAC;IAEV,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAE3F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,eAAe;IAC3E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,eAAe,IACzD,SAAS,SAAS,SAAS,CAAC,QAAQ,CAAC,GAClC,CACA,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,GAC9B,CACA,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC1B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,CAAC"}

package/dist/view/derive-current-view.d.ts

@@ -1,49 +1,51 @@
 /**
- * View derivation — the meta.view half of the player pipeline.
+ * The view derivation — the meta.view half of the player pipeline.
  *
- * Kept beside src/routing/ so player-actor.ts holds only the actor itself:
- * signals, hooks, and lifecycle. The active-branch walk is shared with route
- * derivation so a parallel machine's view always belongs to the region its
- * URL points at.
+ * This file is beside src/routing/, so that player-actor.ts holds the actor
+ * itself only: the signals, the hooks, and the lifecycle. The walk over the active
+ * branch is shared with the route derivation. Therefore the view of a parallel
+ * machine always belongs to the region of its URL.
  */
 import type { AnyMachineSnapshot } from "xstate";
 import { type PlaySpec } from "@xmachines/play-actor";
 /**
- * Derive the actor's current view from state metadata.
- *
- * Always returns a **fresh** `PlaySpec` object so a genuine view change is never
- * suppressed by `Signal.State`'s `Object.is` equality check. Whether that fresh
- * object is actually emitted is decided by `PlayerActor.validateAndCacheView`,
- * which compares against the last emitted spec (reusing the composed `state`
- * reference when the projection is value-unchanged) and skips emission when the
- * rendered view is unchanged — preventing downstream providers from remounting
- * the UI on every event.
- *
- * ### Context projection
- *
- * The machine's context is projected into the derived spec's `state` under the
- * read-only `/context` subtree: `state: { ...meta.view.state, context: slice }`.
- * The emitted spec is therefore **self-consistent** — its `state` honestly
- * describes the store contents — so `repeat.statePath: "/context/tasks"`,
- * `visible: { $state: "/context/…" }`, and `{ $state: "/context/…" }` props all
- * resolve through the ordinary state grammar, and tools like `validateSpec`
- * pass on derived views with no special-casing (validate the derived view, not
- * the raw `meta.view`).
- *
- * The whole context is always projected; the authored `meta.view` object is
- * never mutated.
- *
- * ### viewKey
- *
- * The derived spec carries `viewKey` — the meta record key (state node id) of
- * the entry this derivation actually selected. Providers key their store
- * lifecycle on it: changed → reseed, unchanged → refresh `/context` in place.
- * It is taken from the selected entry rather than "the active state id"
- * because for parallel machines the walked branch and the flat `getMeta()`
- * fallback can select a view from a different region than the branch leaf.
- *
- * @param snapshot - Current XState machine snapshot.
- * @returns Derived `PlaySpec`, or `null` if the current state has no view metadata.
+ * Derives the current view of the actor from the state metadata.
+ *
+ * The function always returns a **fresh** `PlaySpec` object. The `Object.is`
+ * equality test of `Signal.State` therefore stops no real change of the view.
+ * `PlayerActor.validateAndCacheView` decides if the actor emits that fresh object:
+ * it compares the object with the last spec of an emission, it reuses the reference
+ * of the composed `state` field when the value of the projection did not change, and
+ * it emits nothing when the view on the screen is the same. A provider below the
+ * actor therefore mounts the UI again not on every event.
+ *
+ * ### The context projection
+ *
+ * The function projects the context of the machine into the `state` field of the
+ * derived spec, under the read-only `/context` subtree:
+ * `state: { ...meta.view.state, context: slice }`. The spec of the emission is
+ * therefore **consistent with itself**, and its `state` field describes the contents
+ * of the store correctly. `repeat.statePath: "/context/tasks"`,
+ * `visible: { $state: "/context/…" }`, and a `{ $state: "/context/…" }` prop all
+ * resolve through the ordinary state grammar. A tool such as `validateSpec` also
+ * passes on a derived view, with no special case. Validate the derived view, and not
+ * the raw `meta.view`.
+ *
+ * The store always holds the complete context. The function changes the authored
+ * `meta.view` object never.
+ *
+ * ### The viewKey
+ *
+ * The derived spec carries a `viewKey` field. Its value is the key of the meta
+ * record, which is the id of the state node, of the entry that this derivation
+ * selected. A provider uses it as the key of its store lifecycle: a new key seeds
+ * the store again, and the same key refreshes `/context` in place. The value comes
+ * from the selected entry, and not from "the id of the active state", because for a
+ * parallel machine the branch of the walk and the flat `getMeta()` fallback can
+ * select a view of a different region than the leaf of the branch.
+ *
+ * @param snapshot - The current snapshot of the XState machine.
+ * @returns The derived `PlaySpec`, or `null` when the current state has no view metadata.
  */
 export declare const deriveCurrentView: (snapshot: AnyMachineSnapshot) => PlaySpec | null;
 //# sourceMappingURL=derive-current-view.d.ts.map

package/dist/view/derive-current-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-current-view.d.ts","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAiC,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAsDrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IA4C3E,CAAC"}
+{"version":3,"file":"derive-current-view.d.ts","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAiC,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAwDrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IA4C3E,CAAC"}