@xmachines/play-xstate 3.0.0 → 4.0.0

package/dist/state-meta.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The read of the `meta` of the active states, which BOTH capabilities share.
+ *
+ * `deriveCurrentRoute` folds this record into a URL, and `deriveCurrentView` folds the
+ * same record into a view spec. The two therefore cannot move apart on the selection of
+ * the branch, and they cannot move apart on their tolerance of a degenerate snapshot.
+ *
+ * It lives in its own module, and no longer beside the route derivation, because it
+ * belongs to neither capability. `@xmachines/play-xstate/view` imported it from
+ * `routing/derive-current-route.ts`, and that module reads `deriveRoute`, which names
+ * `@xmachines/play-router`. A view-only application therefore loaded the whole route
+ * derivation, and the OPTIONAL peer of the routing reached the runtime graph of the view
+ * entry point.
+ */
+import type { AnyMachineSnapshot } from "xstate";
+/**
+ * Collects the `meta` object of the active state nodes of a SINGLE branch, from the
+ * root to a leaf. The key of each entry is the state id, and the order is the
+ * ancestors first. {@link deriveRoute} folds this shape.
+ *
+ * `snapshot.getMeta()` returns a FLAT record of the meta object of every active
+ * state. For a machine that is not parallel, that record is one chain of ancestors
+ * already. For a PARALLEL machine, it mixes the entries of every active region. A
+ * blind fold therefore joins a relative route of one region to an absolute route of
+ * a sibling region, and the URL belongs to the tree of neither region. The flat
+ * record also cannot go back into a hierarchy: when a state declares an explicit
+ * `id`, for example a child with `id: "dashboard-overview"` under `id: "dashboard"`,
+ * the meta keys are those ids, and they carry no information about the ancestry.
+ *
+ * Therefore this function walks `snapshot.value`, which holds the real hierarchy of
+ * the active states by the state key, against the node tree of the machine. It
+ * follows the FIRST active child at each level. This gives one deterministic branch,
+ * which matches the historical behavior of "the first that it finds" for a parallel
+ * machine. It also works with an explicit id, because each node carries its own `id`
+ * and its own `meta`.
+ *
+ * The function returns `null` when the snapshot exposes no machine and no value to
+ * walk. This is a defensive measure, because a real XState snapshot always exposes
+ * them. The caller then uses `getMeta()`, as before.
+ */
+export declare const firstActiveBranchMeta: (snapshot: AnyMachineSnapshot) => Record<string, unknown> | null;
+/**
+ * Resolves the meta record that the route derivation and the view derivation fold:
+ * the single active branch that {@link firstActiveBranchMeta} walks, which is
+ * correct for a parallel machine and for an explicit id, or the flat `getMeta()`
+ * record when the snapshot has no machine tree to walk. `deriveCurrentRoute` and
+ * `deriveCurrentView` share this function. Therefore the two sides cannot move apart
+ * on the selection of the branch, and they cannot move apart on their tolerance of a
+ * degenerate snapshot.
+ */
+export declare const activeStateMeta: (snapshot: AnyMachineSnapshot) => Record<string, unknown> | null;
+//# sourceMappingURL=state-meta.d.ts.map

package/dist/state-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-meta.d.ts","sourceRoot":"","sources":["../src/state-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,qBAAqB,GACjC,UAAU,kBAAkB,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAqC5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAMxF,CAAC"}

package/dist/state-meta.js

@@ -0,0 +1,77 @@
+/**
+ * Collects the `meta` object of the active state nodes of a SINGLE branch, from the
+ * root to a leaf. The key of each entry is the state id, and the order is the
+ * ancestors first. {@link deriveRoute} folds this shape.
+ *
+ * `snapshot.getMeta()` returns a FLAT record of the meta object of every active
+ * state. For a machine that is not parallel, that record is one chain of ancestors
+ * already. For a PARALLEL machine, it mixes the entries of every active region. A
+ * blind fold therefore joins a relative route of one region to an absolute route of
+ * a sibling region, and the URL belongs to the tree of neither region. The flat
+ * record also cannot go back into a hierarchy: when a state declares an explicit
+ * `id`, for example a child with `id: "dashboard-overview"` under `id: "dashboard"`,
+ * the meta keys are those ids, and they carry no information about the ancestry.
+ *
+ * Therefore this function walks `snapshot.value`, which holds the real hierarchy of
+ * the active states by the state key, against the node tree of the machine. It
+ * follows the FIRST active child at each level. This gives one deterministic branch,
+ * which matches the historical behavior of "the first that it finds" for a parallel
+ * machine. It also works with an explicit id, because each node carries its own `id`
+ * and its own `meta`.
+ *
+ * The function returns `null` when the snapshot exposes no machine and no value to
+ * walk. This is a defensive measure, because a real XState snapshot always exposes
+ * them. The caller then uses `getMeta()`, as before.
+ */
+export const firstActiveBranchMeta = (snapshot) => {
+    const root = snapshot.machine?.root;
+    if (!root)
+        return null;
+    const ordered = {};
+    let node = root;
+    let value = snapshot.value;
+    while (node) {
+        if (node.meta && typeof node.meta === "object") {
+            ordered[node.id] = node.meta; // nosemgrep: gitlab.eslint.detect-object-injection
+        }
+        // Find the key of the active child at this level. A string value is the name of an
+        // atomic active leaf. An object value is a compound node, with one key, or a
+        // parallel node, with many keys: take the first key, for one deterministic
+        // branch.
+        let key;
+        if (typeof value === "string") {
+            key = value;
+        }
+        else if (value && typeof value === "object") {
+            key = Object.keys(value)[0];
+        }
+        if (key === undefined)
+            break;
+        const child = node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        if (!child)
+            break;
+        value =
+            typeof value === "object" && value !== null
+                ? value[key] // nosemgrep: gitlab.eslint.detect-object-injection
+                : {};
+        node = child;
+    }
+    return ordered;
+};
+/**
+ * Resolves the meta record that the route derivation and the view derivation fold:
+ * the single active branch that {@link firstActiveBranchMeta} walks, which is
+ * correct for a parallel machine and for an explicit id, or the flat `getMeta()`
+ * record when the snapshot has no machine tree to walk. `deriveCurrentRoute` and
+ * `deriveCurrentView` share this function. Therefore the two sides cannot move apart
+ * on the selection of the branch, and they cannot move apart on their tolerance of a
+ * degenerate snapshot.
+ */
+export const activeStateMeta = (snapshot) => {
+    if (!snapshot || typeof snapshot.getMeta !== "function") {
+        return null;
+    }
+    const meta = firstActiveBranchMeta(snapshot) ?? snapshot.getMeta();
+    return meta && typeof meta === "object" ? meta : null;
+};
+//# sourceMappingURL=state-meta.js.map

package/dist/state-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-meta.js","sourceRoot":"","sources":["../src/state-meta.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACpC,QAA4B,EACK,EAAE;IACnC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,IAEnB,CAAC;IACb,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,IAAI,KAAK,GAAY,QAAQ,CAAC,KAAK,CAAC;IAEpC,OAAO,IAAI,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,mDAAmD;QAClF,CAAC;QAED,mFAAmF;QACnF,6EAA6E;QAC7E,2EAA2E;QAC3E,UAAU;QACV,IAAI,GAAuB,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,GAAG,GAAG,KAAK,CAAC;QACb,CAAC;aAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/C,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM;QAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAA4B,CAAC,CAAC,mDAAmD;QAChH,IAAI,CAAC,KAAK;YAAE,MAAM;QAClB,KAAK;YACJ,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC1C,CAAC,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,mDAAmD;gBAC7F,CAAC,CAAC,EAAE,CAAC;QACP,IAAI,GAAG,KAAK,CAAC;IACd,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAA4B,EAAkC,EAAE;IAC/F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnE,OAAO,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAgC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC,CAAC"}

package/dist/types.d.ts

@@ -1,13 +1,28 @@
 import type { ActorOptions, AnyStateMachine, InputFrom, SnapshotFrom } from "xstate";
 import type { PlayerActor as PlayerActorClass } from "./player-actor.js";
+import type { PlayerConstructor } from "./capabilities.js";
 /**
  * The configuration of definePlayer()
  */
-export interface PlayerConfig<TMachine extends AnyStateMachine> {
+export interface PlayerConfig<TMachine extends AnyStateMachine, TCapabilities extends object = object> {
     /** The XState v5 state machine */
     machine: TMachine;
     /** The lifecycle hooks and the configuration */
     options?: PlayerOptions<TMachine>;
+    /**
+     * The actor class to build, which decides which CAPABILITIES the actor carries.
+     *
+     * `PlayerActor` is the default, and it holds `state` and `send` alone. Compose a class
+     * to add a capability, and the factory then answers an actor with it:
+     *
+     * ```typescript
+     * definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
+     * ```
+     *
+     * An application that declares no route, and renders no view, passes nothing and loads
+     * neither body of code.
+     */
+    actor?: PlayerConstructor<TMachine, TCapabilities>;
 }
 /**
  * The lifecycle hooks of the player — the observability surface around the actor.
@@ -21,7 +36,7 @@ export interface PlayerOptions<TMachine extends AnyStateMachine> {
     onStart?: (actor: PlayerActorClass<TMachine>) => void;
     /**
      * 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 down. A second `stop()` call, and a stop of an
      * actor that never started fire the hook not.
      */
     onStop?: (actor: PlayerActorClass<TMachine>) => void;
@@ -118,5 +133,5 @@ export interface PlayerFactoryResumeOptions<TMachine extends AnyStateMachine> {
  * 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>;
+export type PlayerFactory<TMachine extends AnyStateMachine, TCapabilities extends object = object> = undefined extends InputFrom<TMachine> ? (input?: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine> & TCapabilities : (input: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine> & TCapabilities;
 //# 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,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"}
+{"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;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,YAAY,CAC5B,QAAQ,SAAS,eAAe,EAChC,aAAa,SAAS,MAAM,GAAG,MAAM;IAErC,kCAAkC;IAClC,OAAO,EAAE,QAAQ,CAAC;IAElB,gDAAgD;IAChD,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAElC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;CACnD;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,EAAE,aAAa,SAAS,MAAM,GAAG,MAAM,IAChG,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,GAAG,aAAa,GAC9C,CACA,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC1B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC"}

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

@@ -7,7 +7,7 @@
  * machine always belongs to the region of its URL.
  */
 import type { AnyMachineSnapshot } from "xstate";
-import { type PlaySpec } from "@xmachines/play-actor";
+import { type PlaySpec } from "@xmachines/play-view";
 /**
  * Derives the current view of the actor from the state metadata.
  *

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;AAyErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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,sBAAsB,CAAC;AAyEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IA4C3E,CAAC"}

package/dist/view/derive-current-view.js

@@ -1,5 +1,5 @@
-import { composePlayState, toAtomState } from "@xmachines/play-actor";
-import { activeStateMeta } from "../routing/index.js";
+import { composePlayState, toAtomState } from "@xmachines/play-view";
+import { activeStateMeta } from "../state-meta.js";
 /**
  * The migration warning of the `contextProps` field, which 1.x removed. The code
  * writes it one time for each spec. A meta.view object from a person passes around

package/dist/view/derive-current-view.js.map

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

package/dist/with-routing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The routing capability of an XState actor, as a mixin.
+ *
+ * `PlayerActor` holds `state` and `send`, and nothing about a route. This module adds
+ * `currentRoute` and `initialRoute`, which is what `Routable` of `@xmachines/play-router`
+ * asks for and what every router bridge reads.
+ *
+ * It is a SEPARATE entry point, `@xmachines/play-xstate/routing`, and the core imports it
+ * never. `@xmachines/play-router` is an OPTIONAL peer of this package for the same reason:
+ * an application that declares no route installs neither that package nor the route map
+ * and the bridge that it carries.
+ *
+ * @example
+ * ```typescript
+ * import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+ * import { withRouting } from "@xmachines/play-xstate/routing";
+ *
+ * const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+ * const actor = createPlayer();
+ * actor.currentRoute.get(); // "/profile/alice"
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AnyStateMachine } from "xstate";
+import type { Routable } from "@xmachines/play-router";
+import type { PlayerConstructor } from "./capabilities.js";
+/**
+ * Adds the routing capability to an actor class.
+ *
+ * The result satisfies `Routable`, so a router bridge accepts it. A class without this
+ * mixin exposes no `currentRoute`, and a bridge therefore refuses it when it compiles,
+ * rather than at the first navigation.
+ *
+ * The mixin declares NO constructor, and that is deliberate: TypeScript demands the
+ * signature `...args: any[]` from a mixin over a generic base (TS2545), and this
+ * workspace writes no `any`. A field initializer of a subclass runs after `super()`
+ * instead, and it reads the inputs that `PlayerActor` keeps for a capability.
+ *
+ * @param Base - The actor class to extend, normally `PlayerActor`.
+ */
+export declare function withRouting<TMachine extends AnyStateMachine>(Base: PlayerConstructor<TMachine>): PlayerConstructor<TMachine, Routable>;
+export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
+export type { RouteMachineConfig, RouteStateNode, RouteContext, RouteObject, RouteMetadata, RouteData, RouteDataResolver, } from "./routing/index.js";
+//# sourceMappingURL=with-routing.d.ts.map

package/dist/with-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-routing.d.ts","sourceRoot":"","sources":["../src/with-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,QAAQ,SAAS,eAAe,EAC3D,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAoDvC;AAcD,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,iBAAiB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/with-routing.js

@@ -0,0 +1,78 @@
+import { Signal } from "@xmachines/play-signals";
+import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
+/**
+ * Adds the routing capability to an actor class.
+ *
+ * The result satisfies `Routable`, so a router bridge accepts it. A class without this
+ * mixin exposes no `currentRoute`, and a bridge therefore refuses it when it compiles,
+ * rather than at the first navigation.
+ *
+ * The mixin declares NO constructor, and that is deliberate: TypeScript demands the
+ * signature `...args: any[]` from a mixin over a generic base (TS2545), and this
+ * workspace writes no `any`. A field initializer of a subclass runs after `super()`
+ * instead, and it reads the inputs that `PlayerActor` keeps for a capability.
+ *
+ * @param Base - The actor class to extend, normally `PlayerActor`.
+ */
+export function withRouting(Base) {
+    class RoutableActor extends Base {
+        /**
+         * A TC39 `Signal.Computed`. It derives the current URL path from the `meta.route`
+         * template of the active machine state and from the context of the actor.
+         *
+         * It returns `null` when the current state has no `meta.route` field, and also when
+         * a necessary `:param` has no value in the context. The second case is normally
+         * temporary during a transition, and the signal computes the value again on the next
+         * snapshot.
+         *
+         * @example
+         * ```typescript
+         * // It returns "/profile/alice" when context.params.userId === "alice",
+         * // and null while the param is still absent.
+         * const route = actor.currentRoute.get();
+         * ```
+         */
+        currentRoute = new Signal.Computed(() => deriveCurrentRoute(this.state.get()));
+        /**
+         * The route of the initial state of the machine. The construction fixes it, and it
+         * never changes, also when the code restores the actor from a snapshot.
+         *
+         * A router bridge compares it with the browser URL, and it therefore separates a
+         * deep link (a URL that is not the initial one → the router wins) from a restore
+         * (the initial URL, and the actor at a different route from the restore → the actor
+         * wins).
+         *
+         * `deriveInitialRoute` derives the value statically from the machine definition,
+         * with the pure `initialTransition` helper of XState: the chain of the initial states
+         * and their `meta.route` templates are fixed at the moment of the machine
+         * definition, and the substitution of a `:param` uses the real initial context of
+         * the machine for the `input` of this actor. The code makes no second actor, and a
+         * snapshot of a restore changes the value never: it is always the **default**
+         * initial route of the machine.
+         *
+         * Without a snapshot of a restore, the pre-start snapshot of this actor IS that
+         * default initial state, so the code derives the route from it directly. A restore
+         * alone needs `initialTransition`, whose inert actor scope runs the initial
+         * transition two more times, one of them with an undefined `input`. That is a quirk
+         * of XState, and it costs too much for every other case.
+         */
+        initialRoute = this.playerRestoredSnapshot === undefined
+            ? deriveCurrentRoute(this.getSnapshot())
+            : deriveInitialRoute(this.playerMachine, this.playerInput);
+    }
+    return RoutableActor;
+}
+// The utilities of the route derivation and of the URL construction.
+//
+// They belong HERE, and no longer on the main entry. Each one names
+// `@xmachines/play-router` in its own `.d.ts` — `PlayRouteEvent`, `RouteData`,
+// `RouteObject` and `RouteMetadata` all have their single definition there. That
+// package is an OPTIONAL peer, so a main entry that reached them gave every consumer
+// of `definePlayer` a type graph that names a package their node_modules does not
+// hold. `skipLibCheck` hides the fault and does not remove it: the types resolve to
+// nothing.
+//
+// The view half exposes nothing on the main entry, for the same reason. The two
+// capabilities hold one shape.
+export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
+//# sourceMappingURL=with-routing.js.map

package/dist/with-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-routing.js","sourceRoot":"","sources":["../src/with-routing.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAC1B,IAAiC;IAEjC,MAAM,aAAc,SAAQ,IAAI;QAC/B;;;;;;;;;;;;;;;WAeG;QACa,YAAY,GAAmC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CACvF,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CACpC,CAAC;QAEF;;;;;;;;;;;;;;;;;;;;;;WAsBG;QACa,YAAY,GAC3B,IAAI,CAAC,sBAAsB,KAAK,SAAS;YACxC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACxC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;KAC7D;IAED,OAAO,aAAa,CAAC;AACtB,CAAC;AAED,qEAAqE;AACrE,EAAE;AACF,oEAAoE;AACpE,+EAA+E;AAC/E,iFAAiF;AACjF,qFAAqF;AACrF,kFAAkF;AAClF,oFAAoF;AACpF,WAAW;AACX,EAAE;AACF,gFAAgF;AAChF,+BAA+B;AAC/B,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC"}

package/dist/with-view.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The view capability of an XState actor, as a mixin.
+ *
+ * `PlayerActor` holds `state` and `send`, and nothing about a view. This module adds
+ * `currentView`, which is what `Viewable` of `@xmachines/play-view` asks for and what
+ * every renderer reads.
+ *
+ * It is a SEPARATE entry point, `@xmachines/play-xstate/view`, and the core imports it
+ * never. `@xmachines/play-view` is an OPTIONAL peer of this package for the same reason:
+ * an application that renders no view installs neither that package nor the json-render
+ * types that it names.
+ *
+ * @example
+ * ```typescript
+ * import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+ * import { withRouting } from "@xmachines/play-xstate/routing";
+ * import { withView } from "@xmachines/play-xstate/view";
+ *
+ * const createPlayer = definePlayer({
+ *   machine,
+ *   actor: compose(PlayerActor, withRouting, withView),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AnyStateMachine } from "xstate";
+import { type Viewable } from "@xmachines/play-view";
+import type { PlayerConstructor } from "./capabilities.js";
+/**
+ * Adds the view capability to an actor class.
+ *
+ * Compose it AFTER the routing capability. An override calls `super.onSnapshot()` first,
+ * so `compose(PlayerActor, withRouting, withView)` gives the route its new value before
+ * the view derives from the same transition. A router bridge therefore sees a guard
+ * redirect before a renderer sees the view of the state that the guard refused.
+ *
+ * @param Base - The actor class to extend, normally `PlayerActor` or the result of
+ *   another capability.
+ */
+export declare function withView<TMachine extends AnyStateMachine>(Base: PlayerConstructor<TMachine>): PlayerConstructor<TMachine, Viewable>;
+//# sourceMappingURL=with-view.d.ts.map

package/dist/with-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-view.d.ts","sourceRoot":"","sources":["../src/with-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAsB,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGlE,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAsD3D;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAS,eAAe,EACxD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAgFvC"}

package/dist/with-view.js

@@ -0,0 +1,150 @@
+import { Signal } from "@xmachines/play-signals";
+import { shallowEqualExcept } from "@xmachines/play";
+import { reuseComposedState } from "@xmachines/play-view";
+import { toError } from "./player-actor.js";
+import { deriveCurrentView } from "./view/derive-current-view.js";
+/**
+ * The structural equality of two derived view specs, with a limit on its depth.
+ *
+ * The function walks exactly the shape that `deriveCurrentView` builds: the spec
+ * fields, then `elements`, then the `props` object of each element. It compares
+ * each leaf with `Object.is`. It never enters the VALUE of a prop: a new reference
+ * therefore emits the view again, also when the contents are equal. This design
+ * keeps two things correct: a prop of a container (a Map, a Set, or an instance of a
+ * class, which a structural comparison cannot see), and a cyclic value, which gives
+ * a structural comparison a recursion without an end.
+ */
+const viewSpecsEquivalent = (a, b) => {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (!shallowEqualExcept(a, b, "elements"))
+        return false;
+    const aElements = a.elements ?? {};
+    const bElements = b.elements ?? {};
+    // A derived spec spreads the same static meta.view. Therefore the elements
+    // usually have the same reference, and the walk over each element is then not
+    // necessary.
+    if (aElements === bElements)
+        return true;
+    const elementKeys = Object.keys(aElements);
+    if (elementKeys.length !== Object.keys(bElements).length)
+        return false;
+    for (const key of elementKeys) {
+        const aElement = aElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        const bElement = bElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        if (aElement === bElement)
+            continue;
+        if (!aElement || !bElement)
+            return false;
+        if (!shallowEqualExcept(aElement, bElement, "props"))
+            return false;
+        if (!shallowEqualExcept(aElement.props ?? {}, bElement.props ?? {}))
+            return false;
+    }
+    return true;
+};
+/**
+ * The last snapshot that the view pipeline of each actor read.
+ *
+ * A WeakMap at the module level, and not a field of the class: a `private` or a `#` field
+ * makes a class type NOMINAL, so the compiler then compares the mixin class with no other
+ * type and the return of this function needs `as unknown as`. The map holds the same state
+ * with no member, and it releases each entry with its actor.
+ *
+ * XState notifies each observer on EVERY event that it processes, and an event that it
+ * ignores delivers the identical snapshot again. `deriveCurrentView` is pure in the
+ * snapshot, so an identical reference can change no result. An actor that the map does not
+ * hold has read no snapshot yet, which is correct for the first derivation: the snapshot of
+ * the construction has the same reference as the snapshot that `start()` replays.
+ */
+const lastViewSnapshots = new WeakMap();
+/**
+ * Adds the view capability to an actor class.
+ *
+ * Compose it AFTER the routing capability. An override calls `super.onSnapshot()` first,
+ * so `compose(PlayerActor, withRouting, withView)` gives the route its new value before
+ * the view derives from the same transition. A router bridge therefore sees a guard
+ * redirect before a renderer sees the view of the state that the guard refused.
+ *
+ * @param Base - The actor class to extend, normally `PlayerActor` or the result of
+ *   another capability.
+ */
+export function withView(Base) {
+    class ViewableActor extends Base {
+        /**
+         * The reactive signal of the current view spec. The signal derives the spec from the
+         * `meta.view` metadata of the active state.
+         *
+         * It emits a **new object reference** on each real change of the view on the screen:
+         * the view of a different state, or a change of a param or of the context that changes
+         * the resolved spec. A re-entry with `reenter: true` and new params also changes the
+         * spec. A snapshot that changes no view on the screen, such as an assign of the
+         * context alone, keeps the previous reference. A provider below the signal therefore
+         * mounts the UI again not on every event.
+         *
+         * The `PlaySpec` of the emission carries the context of the machine in its composed
+         * `state` field, under the read-only `/context` subtree. A spec therefore reads the
+         * context, and also each URL param, through the ordinary state grammar
+         * (`{ $state: "/context/params/section" }`). The context-projection module of
+         * `@xmachines/play-view` holds the complete contract.
+         *
+         * The signal returns `null` when the current state has no `meta.view` metadata.
+         *
+         * Two states can declare two separate `meta.view` literals with an identical
+         * structure. A transition between those two states then emits two different
+         * references, and a provider mounts the UI again. Move the shared literal into one
+         * `typedSpec` constant, and the identity then removes the duplicate.
+         */
+        currentView = new Signal.State(null);
+        onSnapshot(snapshot) {
+            // FIRST, so that every capability composed before this one holds its new value.
+            super.onSnapshot(snapshot);
+            this.validateAndCacheView(snapshot);
+        }
+        /**
+         * Derives the view at the entry of a state, and keeps it. This happens one time for
+         * each transition. The signal holds the view, and the code computes it not on each
+         * read.
+         *
+         * @param snapshot - The current XState snapshot
+         */
+        validateAndCacheView(snapshot) {
+            if (snapshot === lastViewSnapshots.get(this)) {
+                return;
+            }
+            lastViewSnapshots.set(this, snapshot);
+            try {
+                const view = deriveCurrentView(snapshot);
+                // Emit only after a real change of the view on the screen: deriveCurrentView
+                // returns a fresh object on each call, and the identity of the reference therefore
+                // tells nothing. A new reference for a snapshot that changes the view not, for
+                // example a context-only assign, makes a provider below mount the UI again, and
+                // that removes the state of the view. A deep equality test is deliberately NOT
+                // here: it sees nothing inside a Map or a Set, and it therefore stops a real
+                // change, and it recurses without an end on a cyclic prop. The last spec of an
+                // emission IS the current value of the signal. Read it without a track, so that
+                // the gate registers currentView never as a dependency of a computation around it.
+                const lastEmittedView = Signal.subtle.untrack(() => this.currentView.get());
+                // Use the reference of the previous composed state again when the value of the
+                // /context projection did not change. A context-only assign that changes no
+                // projected value therefore changes the identity of the state not.
+                const nextView = reuseComposedState(lastEmittedView, view);
+                if (viewSpecsEquivalent(lastEmittedView, nextView)) {
+                    return;
+                }
+                this.currentView.set(nextView);
+            }
+            catch (error) {
+                const onError = this.hooks.onError;
+                if (onError) {
+                    onError(this, toError(error));
+                }
+                // On an error: keep the last valid view, and clear it not
+            }
+        }
+    }
+    return ViewableActor;
+}
+//# sourceMappingURL=with-view.js.map

package/dist/with-view.js.map

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