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

package/dist/routing/format-play-route-transitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,iHAAiH;IACjH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,IAAI,CAAC,EAAE;QACN;;;WAGG;QACH,KAAK,CAAC,EAAE,aAAa,CAAC;KACtB,CAAC;IACF,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AA4BF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,kBAAkB,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAyH5F"}
+{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE;QACN;;;;WAIG;QACH,KAAK,CAAC,EAAE,aAAa,CAAC;KACtB,CAAC;IACF,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAaF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,kBAAkB,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAmF5F"}

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

@@ -1,18 +1,28 @@
+import { assign } from "xstate";
+import { shallowEqualExcept } from "@xmachines/play-actor";
 import { MissingStateIdError } from "../errors.js";
 import { normalizeRoute } from "./derive-route.js";
 /**
- * Formats play.route routing from declarative route configs.
+ * Reuses the previous container of the params and of the query when the new
+ * container is equal to it in a shallow comparison.
  *
- * Crawls machine states looking for states with `meta.route` and wires them to
- * XState v6's **native routing machinery**:
+ * 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);
+/**
+ * Makes the play.route transitions from the declarative route configs
  *
- * - every routed state gets a native `route: {}` config (unless it already
- *   declares its own `route`), making it targetable via the built-in
- *   `{ type: "xstate.route", to: "#id" }` event (Stately tooling interop and
- *   statically-known graph edges), and
- * - one root-level `play.route` forwarder performs the navigation for those
- *   targets as ONE atomic transition: target + re-entry + a shallow
- *   `params`/`query` context patch.
+ * 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.
+ *
+ * The internal formatRouteTransitions function of XState was the model for this
+ * function (stateUtils.ts, line 391).
  *
  * @example
  * ```typescript
@@ -27,142 +37,76 @@ import { normalizeRoute } from "./derive-route.js";
  * const machine = createMachine(formatPlayRouteTransitions(machineConfig));
  * ```
  *
- * Because the injected `route` configs are static (object form), the machine's
- * route transitions keep **statically-known targets** — `toDirectedGraph()` /
- * `machineToGraph()` edges point at the actual routed states, so graph
- * reachability queries work. (Function-form transition candidates would have
- * dynamic targets, opaque to static analysis.)
- *
- * The `play.route` public API and its v5 semantics are preserved:
- * - `send({ type: "play.route", to: "#home", params, query })` navigates and
- *   patches `context.params`/`context.query` in the SAME transition — exit
- *   actions of the departing state observe the OLD params, entry actions of
- *   the target observe the NEW ones, `always` transitions never see a
- *   half-navigated intermediate state, and entry/exit actions receive the
- *   original `play.route` event;
- * - user-defined `play.route` transitions (e.g. a hand-written 404 fallback)
- *   are preserved AFTER the forwarder: for unknown targets the forwarder
- *   returns `undefined`, so evaluation falls through to them;
- * - `params`/`query` are only patched when the forwarder navigates — unknown
- *   and blocked targets leave context untouched.
+ * 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
  *
- * When a state declares its OWN `route` config (which wins over the injected
- * default), the forwarder re-raises the event as `xstate.route` instead of
- * navigating, so the user's resolver decides — including blocking. The
- * forwarder does NOT patch `params`/`query` for such targets (a blocking
- * resolver would otherwise leave context describing a route that was never
- * entered); the user's function-form resolver owns any context patch, and
- * that navigation microstep runs under the `xstate.route` event.
- *
- * Native `xstate.route` events also work directly (Stately ecosystem tooling),
- * but bypass the forwarder — no `params`/`query` context patch is applied, so
- * stale values from earlier `play.route` events linger in context (and a
- * router bridge deriving the URL from context would interpolate those stale
- * params).
- *
- * @param machineConfig - XState machine config (before createMachine). Must extend `RouteMachineConfig`.
- * @returns The machine config with native `route` configs and the `play.route` forwarder 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) {
-    /**
-     * Routing table: `#id` -> the state's key path (e.g. `.dashboard.stats`)
-     * for targets whose `route` config was injected by this transform, or
-     * `null` for targets with a USER-declared `route` config (the user's
-     * resolver decides those — the forwarder re-raises instead of navigating).
-     */
-    const routeTargets = new Map();
-    /**
-     * Rebuild the states tree, injecting a native `route` config into routed
-     * nodes. The input config is never mutated — every node is shallow-copied.
-     */
-    const injectRoutes = (states, parentPath = "") => {
-        const next = {};
-        for (const [key, stateConfig] of Object.entries(states)) {
-            const node = { ...stateConfig };
+    const routeTransitions = [];
+    const collectRoutes = (states, parentPath = "") => {
+        Object.entries(states).forEach(([key, stateConfig]) => {
+            const node = stateConfig;
+            // 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");
             if (routePath && !node.id) {
                 throw new MissingStateIdError(key, routePath);
             }
-            if (node.states) {
-                node.states = injectRoutes(node.states, statePath);
-            }
             if (routePath && node.id) {
-                if (node.route === undefined) {
-                    // Native object-form route config: statically-targeted transition,
-                    // visible to graph tooling. The play.route forwarder navigates these
-                    // targets DIRECTLY (atomically); the native config exists for
-                    // xstate.route interop (Stately tooling, devtools).
-                    node.route = {};
-                    routeTargets.set(`#${node.id}`, `.${statePath}`);
-                }
-                else {
-                    // A user-declared route config wins: the forwarder re-raises
-                    // xstate.route so the user's resolver decides (and owns any
-                    // context patch).
-                    routeTargets.set(`#${node.id}`, null);
-                }
+                const transition = {
+                    target: `.${statePath}`,
+                    guard: ({ event }) => event.to === `#${node.id}`,
+                    reenter: true,
+                    actions: assign({
+                        params: ({ context, event }) => keepEqualContainer(context.params, event.params || {}),
+                        query: ({ context, event }) => keepEqualContainer(context.query, event.query || {}),
+                    }),
+                };
+                routeTransitions.push(transition);
             }
-            next[key] = node;
-        }
-        return next;
+            if (node.states) {
+                collectRoutes(node.states, statePath);
+            }
+        });
     };
     const machineStates = machineConfig.states;
-    const injectedStates = machineStates ? injectRoutes(machineStates) : machineStates;
-    if (routeTargets.size === 0) {
-        return machineConfig;
+    if (machineStates) {
+        collectRoutes(machineStates);
     }
-    // Root play.route forwarder. For injected-route targets it returns ONE
-    // atomic transition (target + reenter + params/query patch): exit actions
-    // see the OLD params, `always` transitions never observe a half-navigated
-    // intermediate state, and entry/exit actions receive the original
-    // play.route event. For user-routed targets it re-raises xstate.route
-    // WITHOUT patching (the user's resolver owns the patch — otherwise a
-    // blocking resolver would leave context describing a route that was never
-    // entered). Unknown targets return undefined so user fallback candidates
-    // below are evaluated.
-    const forwarder = ({ event }, enq) => {
-        const target = routeTargets.get(event.to);
-        if (target === undefined)
-            return undefined;
-        if (target === null) {
-            enq.raise({ ...event, type: "xstate.route" });
-            return {};
-        }
+    if (routeTransitions.length > 0) {
+        const existingOn = machineConfig.on || {};
+        // 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
+            ? []
+            : Array.isArray(userRouteTransitions)
+                ? userRouteTransitions
+                : [userRouteTransitions];
+        const updatedOn = {
+            ...existingOn,
+            "play.route": [...routeTransitions, ...normalizedUserTransitions],
+        };
         return {
-            target,
-            reenter: true,
-            // Shallow context patch — v6's replacement for assign().
-            context: {
-                params: event.params || {},
-                query: event.query || {},
-            },
+            ...machineConfig,
+            on: updatedOn,
         };
-    };
-    // Preserve user-defined play.route transitions (e.g. a hand-written 404
-    // fallback) by appending them AFTER the forwarder: XState evaluates
-    // candidate transitions in order, so the forwarder wins for known targets
-    // and the user's transitions act as fallbacks otherwise.
-    const existingOn = machineConfig.on || {};
-    const userRouteTransitions = existingOn["play.route"];
-    const normalizedUserTransitions = userRouteTransitions === undefined
-        ? []
-        : Array.isArray(userRouteTransitions)
-            ? userRouteTransitions
-            : [userRouteTransitions];
-    return {
-        ...machineConfig,
-        states: injectedStates,
-        on: {
-            ...existingOn,
-            "play.route": [forwarder, ...normalizedUserTransitions],
-        },
-    };
+    }
+    return machineConfig;
 }
 //# sourceMappingURL=format-play-route-transitions.js.map

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,20 +1,16 @@
 /**
- * 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
  */
 export { deriveRoute, isAbsoluteRoute } from "./derive-route.js";
-export { deriveCurrentRoute } from "./derive-current-route.js";
+export { activeStateMeta, deriveCurrentRoute, firstActiveBranchMeta, } from "./derive-current-route.js";
 export { deriveInitialRoute } from "./derive-initial-route.js";
 export { buildRouteUrl } from "./build-url.js";
 export { formatPlayRouteTransitions } from "./format-play-route-transitions.js";
-export { playMetaSchema, playRouteEventSchema } from "./schemas.js";
-export type { PlayRoutePayload, WithOptional } from "./schemas.js";
-export type { SetupLike } from "./create-routed-machine.js";
-export { createRoutedMachine } from "./create-routed-machine.js";
 export type { RouteMachineConfig, RouteStateNode } from "./format-play-route-transitions.js";
 export type { RouteContext, RouteObject, RouteMetadata } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACnE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACN,eAAe,EACf,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/routing/index.js

@@ -1,16 +1,14 @@
 /**
- * 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
  */
 export { deriveRoute, isAbsoluteRoute } from "./derive-route.js";
-export { deriveCurrentRoute } from "./derive-current-route.js";
+export { activeStateMeta, deriveCurrentRoute, firstActiveBranchMeta, } from "./derive-current-route.js";
 export { deriveInitialRoute } from "./derive-initial-route.js";
 export { buildRouteUrl } from "./build-url.js";
 export { formatPlayRouteTransitions } from "./format-play-route-transitions.js";
-export { playMetaSchema, playRouteEventSchema } from "./schemas.js";
-export { createRoutedMachine } from "./create-routed-machine.js";
 //# sourceMappingURL=index.js.map

package/dist/routing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACN,eAAe,EACf,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC"}

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,45 +1,122 @@
-import type { AnyStateMachine, InputFrom, SnapshotFrom } from "xstate";
+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 v6 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
- *
- * Per CONTEXT.md: Rich set of hooks for observability
+ * The lifecycle hooks of the player — the observability surface around the actor.
  */
 export interface PlayerOptions<TMachine extends AnyStateMachine> {
-    /** Called when actor starts */
+    /**
+     * 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 when actor stops */
+    /**
+     * 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 on every state transition */
+    /**
+     * 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 */
+    /**
+     * 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.
+     *
+     * 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 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`, 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.
+     *
+     * 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;
+    /**
+     * The inspection observer. The factory gives it to `createActor` of XState without
+     * a change.
+     *
+     * 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 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.
+     *
+     * 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
+     * import { createBrowserInspector } from "@statelyai/inspect";
+     *
+     * const { inspect } = createBrowserInspector();
+     * const createPlayer = definePlayer({ machine, options: { inspect } });
+     * ```
+     *
+     * 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. */
-    snapshot?: SnapshotFrom<TMachine>;
+    /**
+     * The persisted XState snapshot. The factory restores the actor state from it.
+     *
+     * 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()
+ * The factory function that definePlayer() returns. Each call makes an independent
+ * actor instance from the same configuration.
  *
- * Per CONTEXT.md: Factory supports creating multiple actor instances
+ * 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> = (input?: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine>;
+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,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACvE,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;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,eAAe;IAC9D,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEtD,8BAA8B;IAC9B,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAErD,uCAAuC;IACvC,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,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,eAAe;IAC3E,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,eAAe,IAAI,CAC7D,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,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

@@ -0,0 +1,51 @@
+/**
+ * The view derivation — the meta.view half of the player pipeline.
+ *
+ * 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";
+/**
+ * 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

@@ -0,0 +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;AAwDrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IA4C3E,CAAC"}