@xmachines/play-xstate 3.0.0 → 5.0.0

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;
@@ -32,7 +47,7 @@ export interface PlayerOptions<TMachine extends AnyStateMachine> {
      * you.
      */
     onTransition?: (actor: PlayerActorClass<TMachine>, prevState: SnapshotFrom<TMachine>, nextState: SnapshotFrom<TMachine>) => void;
-    /** The actor calls it when the state signal changes */
+    /** The actor calls it when the state atom changes */
     onStateChange?: (actor: PlayerActorClass<TMachine>, state: SnapshotFrom<TMachine>) => void;
     /**
      * The actor calls it on an actor error: a snapshot restore that fails at `start()`,
@@ -77,7 +92,7 @@ export interface PlayerOptions<TMachine extends AnyStateMachine> {
      * 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.
+     * reference, and read the atoms from a later event, or outside the observer.
      *
      * @example
      * ```typescript
@@ -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,qDAAqD;IACrD,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

@@ -2,22 +2,23 @@
  * 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
+ * itself only: the atoms, 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";
+import { type PlaySpec } from "@xmachines/play-view";
 /**
  * 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:
+ * equality test of the atom therefore stops no real change of the view.
+ * The `currentView` atom of `withView` 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.
+ * it returns the previous spec when the view on the screen is the same — which the
+ * `Object.is` compare of the atom reads as no change, so it notifies no subscriber. A
+ * provider below the actor therefore mounts the UI again not on every event.
  *
  * ### The context projection
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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
@@ -59,12 +59,13 @@ const resolveViewMeta = (meta) => {
  * 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:
+ * equality test of the atom therefore stops no real change of the view.
+ * The `currentView` atom of `withView` 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.
+ * it returns the previous spec when the view on the screen is the same — which the
+ * `Object.is` compare of the atom reads as no change, so it notifies no subscriber. A
+ * provider below the actor therefore mounts the UI again not on every event.
  *
  * ### The context projection
  *

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;AAG9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,QAAQ,SAAS,eAAe,EAC3D,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAiHvC;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,140 @@
+import { createAtom } from "@xmachines/play-atom";
+import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
+import { toError } from "./player-actor.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 computed atom. 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 atom computes the value again on the next
+         * snapshot.
+         *
+         * It THROWS never. A derivation of this architecture reports a failure through
+         * `onError` and keeps its last good value, and `currentView` of
+         * `@xmachines/play-xstate/view` follows the same rule.
+         *
+         * The reason is the propagation. A subscriber makes this atom eager, so the
+         * derivation runs inside the `set` of `state`, which runs inside the XState
+         * subscription. A throw that left this function would unwind into `actor.send` and
+         * break the transition for EVERY other observer of the actor.
+         *
+         * The containment therefore belongs to the derivation, and not to each subscriber:
+         * a consumer that writes its own `watchAtom(actor.currentRoute, ...)` is protected
+         * by the same rule that protects a router bridge.
+         *
+         * @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 = createAtom((previous) => {
+            try {
+                return deriveCurrentRoute(this.state.get());
+            }
+            catch (error) {
+                // `deriveCurrentRoute` answers the EXPECTED failure itself: a missing `:param`
+                // returns `null`, and the next snapshot resolves it. Whatever reaches this line
+                // is unexpected — a `URIError` of `encodeURIComponent` for a lone surrogate,
+                // for example. Report it, and keep the last route: a caller that reads `null`
+                // or a stale route navigates nowhere, which the bridge handles already.
+                // The derivation runs inside the `set` of `state`, and the engine TRACKS every
+                // atom that this function reads — the handler of the host included. A report
+                // from HERE therefore made whatever that handler reads a dependency of this
+                // atom, and an unrelated write of it re-derived and reported again: three
+                // reports for one failure. The microtask leaves the evaluation, so the handler
+                // reads what it likes and this atom depends on none of it.
+                //
+                // It leaves the `set` as well, which is what the comment below already needed:
+                // a throw from the handler lands on the global handler of the runtime, and it
+                // breaks the transition for no other observer of the actor.
+                const onError = this.hooks.onError;
+                if (onError) {
+                    const reported = toError(error);
+                    queueMicrotask(() => {
+                        onError(this, reported);
+                    });
+                }
+                return previous ?? null;
+            }
+        }, {
+            // Every WRITE of `state` reaches an observer of this atom, and not the writes
+            // that change the route alone.
+            //
+            // The default `Object.is` stops a notification for a value that the atom holds
+            // already, and a route is a STRING: a guard that refuses an inbound location and
+            // moves the actor back to the state it came from derives the same string, so no
+            // observer heard the answer. `RouterBridgeBase` waits for exactly that answer —
+            // `syncActorFromRouter` clears `lastActorRoute` before it sends, so the push
+            // that puts the address bar back on the route of the machine is owed to this
+            // notification — and the address bar kept the location that the guard refused.
+            //
+            // The bridge is written against a notification for each change of the SNAPSHOT,
+            // and not for each change of the derived string, so the comparison has to answer
+            // "different" always. A consumer that reads the value pays nothing for it: the
+            // derivation still runs one time for each transition, and `state` itself compares
+            // with `Object.is`, so an event that XState ignores delivers the identical
+            // snapshot and propagates nothing.
+            compare: () => false,
+        });
+        /**
+         * 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,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKlD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAC1B,IAAiC;IAEjC,MAAM,aAAc,SAAQ,IAAI;QAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;QACa,YAAY,GAAgC,UAAU,CACrE,CAAC,QAAQ,EAAiB,EAAE;YAC3B,IAAI,CAAC;gBACJ,OAAO,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,+EAA+E;gBAC/E,gFAAgF;gBAChF,6EAA6E;gBAC7E,8EAA8E;gBAC9E,wEAAwE;gBACxE,+EAA+E;gBAC/E,6EAA6E;gBAC7E,4EAA4E;gBAC5E,0EAA0E;gBAC1E,+EAA+E;gBAC/E,2DAA2D;gBAC3D,EAAE;gBACF,+EAA+E;gBAC/E,8EAA8E;gBAC9E,4DAA4D;gBAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;gBACnC,IAAI,OAAO,EAAE,CAAC;oBACb,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;oBAChC,cAAc,CAAC,GAAG,EAAE;wBACnB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;oBACzB,CAAC,CAAC,CAAC;gBACJ,CAAC;gBACD,OAAO,QAAQ,IAAI,IAAI,CAAC;YACzB,CAAC;QACF,CAAC,EACD;YACC,8EAA8E;YAC9E,+BAA+B;YAC/B,EAAE;YACF,+EAA+E;YAC/E,iFAAiF;YACjF,gFAAgF;YAChF,gFAAgF;YAChF,6EAA6E;YAC7E,6EAA6E;YAC7E,+EAA+E;YAC/E,EAAE;YACF,gFAAgF;YAChF,iFAAiF;YACjF,+EAA+E;YAC/E,kFAAkF;YAClF,2EAA2E;YAC3E,mCAAmC;YACnC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK;SACpB,CACD,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,57 @@
+/**
+ * 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";
+/**
+ * Two WeakMaps stood here, and the derivation below needs neither.
+ *
+ * `lastViewSnapshots` skipped the derivation for a snapshot that the pipeline read
+ * already, because XState notifies each observer on EVERY event that it processes and an
+ * event that it ignores delivers the identical snapshot again. A computed atom answers
+ * that by itself: `state.set(snapshot)` compares with `Object.is`, an identical reference
+ * therefore propagates nothing, and this atom stays valid.
+ *
+ * `lastEmittedViews` held the previous emission for the equality gate, because a read of
+ * `currentView` would have registered it as a dependency of the computation around the
+ * call and `@xstate/store` exports no `untrack`. The `previous` parameter of a computed
+ * atom is that same value, and the engine hands it in rather than tracking a read.
+ */
+/**
+ * Adds the view capability to an actor class.
+ *
+ * The ORDER of the composition does not matter. `currentView` and `currentRoute` are two
+ * computed atoms over `state`, and neither reads the other, so the engine evaluates both
+ * from one write in topological order. An earlier release wrote `currentView` from an
+ * `onSnapshot` override, and the order then decided which capability held its new value
+ * first.
+ *
+ * @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,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAI9C,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAsC3D;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAS,eAAe,EACxD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAuFvC"}