@xmachines/play-xstate 4.0.0 → 5.0.0

package/dist/player-actor.js

@@ -1,6 +1,6 @@
 import { Actor, } from "xstate";
 import { DISPOSE } from "@xmachines/play";
-import { Signal } from "@xmachines/play-signals";
+import { createWritableAtom } from "@xmachines/play-atom";
 import { ActorThrewNonErrorError, InvalidEventError, InvalidMachineError } from "./errors.js";
 /**
  * Tells you if a value is an `Error`, by its identity or by its brand: `instanceof`
@@ -44,15 +44,15 @@ export const toError = (value) => {
     return new ActorThrewNonErrorError(value);
 };
 /**
- * Tells you if a snapshot is worth a propagation to the signals: an active
+ * Tells you if a snapshot is worth a propagation to the atoms: an active
  * snapshot, or a "done" snapshot, which means that the machine reached a final state
  * at the top level. The code skips an error snapshot and a stopped snapshot.
- * Therefore the signals keep the last observable state, and they show no artifact of
+ * Therefore the atoms keep the last observable state, and they show no artifact of
  * a teardown or of an error.
  */
 const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snapshot.status === "done";
 /**
- * The concrete XState actor. It implements the signal protocol of the Play Architecture
+ * The concrete XState actor. It implements the atom protocol of the Play Architecture
  *
  * The class extends the `Actor` class of XState directly, and it implements
  * {@link @xmachines/play-actor!PlayActor}. It gives you the XState v5 integration, and it keeps the
@@ -60,7 +60,7 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  * The constructor of the base class receives the machine. Therefore a `PlayerActor`
  * **is** the XState actor, and it is no wrapper around one: every member of the
  * XState `Actor` class works on the state of this instance, and this class adds the
- * reactive state on the TC39 Signals for the observation by the infrastructure.
+ * reactive state on the atoms for the observation by the infrastructure.
  *
  * **Capabilities:** the class implements both the
  * {@link @xmachines/play-router!index.Routable} interface and the
@@ -69,7 +69,7 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  *
  * **Architectural context:** the class implements **Actor Authority (INV-01)**,
  * because the guards of the XState machine control every decision of the
- * navigation. The infrastructure observes the signals of the actor (`state`,
+ * navigation. The infrastructure observes the atoms of the actor (`state`,
  * `currentRoute`, and `currentView`), but it changes no state directly: every
  * change goes through the event handlers of the state machine.
  *
@@ -101,31 +101,29 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  * const actor = createPlayer();
  * actor.start();
  *
- * // Observe the signals
+ * // Observe the atoms
  * console.log(actor.currentRoute.get());          // '/'
  * console.log(actor.currentView.get()?.root);     // 'home'
  * ```
  *
  * @example
- * The signal lifecycle with a watcher
+ * The atom lifecycle with a watch
  * ```typescript
- * import { Signal } from "@xmachines/play-signals";
+ * import { watchAtom } from "@xmachines/play-atom";
  *
- * const watcher = new Signal.subtle.Watcher(() => {
- *   queueMicrotask(() => {
- *     const pending = watcher.getPending();
- *     console.log('State changed:', actor.state.get());
- *   });
+ * const stop = watchAtom(actor.state, (snapshot) => {
+ *   console.log('State changed:', snapshot.value);
  * });
  *
- * watcher.watch(actor.state);
  * actor.send({ type: 'play.route', to: '#about' });
- * // The watcher schedules its own notification in a microtask
+ * // watchAtom delivers the new value from a microtask
+ *
+ * stop();
  * ```
  *
  * @see [Play RFC](../../docs/rfc/play.md)
  * @see {@link definePlayer} for the creation through a factory
- * @see {@link @xmachines/play-actor!PlayActor} for the signal protocol
+ * @see {@link @xmachines/play-actor!PlayActor} for the atom protocol
  * @see {@link @xmachines/play-router!index.Routable} for the routing capability
  * @see {@link @xmachines/play-view!index.Viewable} for the view rendering capability
  *
@@ -135,10 +133,11 @@ const isObservableSnapshot = (snapshot) => snapshot.status === "active" || snaps
  * `meta.route`, which is the Stately pattern, for a URL template, and it substitutes
  * each parameter.
  *
- * **The pattern of the view signal:** the `currentView` signal is a direct
- * `Signal.State`, and not a `Signal.Computed`. The propagation to a watcher in
- * PlayRenderer is therefore correct. The class derives each view at the entry of a
- * state and keeps it, and it computes no view on a read.
+ * **The pattern of the view atom:** `withView` of `@xmachines/play-xstate/view` adds
+ * `currentView`, and that atom is a COMPUTED atom over `state`. One write for each
+ * transition — `state.set(snapshot)` — therefore reaches the view and the route in one
+ * flush, and no subscriber reads the new state beside an old derivation. The atom
+ * memoizes the result, so a repeated read computes no view again.
  */
 export class PlayerActor extends Actor {
     playerOptions;
@@ -180,7 +179,7 @@ export class PlayerActor extends Actor {
      * Tells you if the current state of the actor accepts the given event.
      *
      * The type is the event union of the machine. An unknown event type is therefore a
-     * compile error. The method evaluates the event against the snapshot signal.
+     * compile error. The method evaluates the event against the snapshot atom.
      *
      * @example
      * ```typescript
@@ -188,7 +187,7 @@ export class PlayerActor extends Actor {
      * ```
      */
     can(event) {
-        // A read of the signal keeps can() reactive: a Signal.Computed over the signal
+        // A read of the atom keeps can() reactive: a computed atom over the atom
         // computes its value again on each transition.
         const snapshot = this.state?.get();
         // The STATUS decides first, and the presence of the method decides second.
@@ -201,7 +200,7 @@ export class PlayerActor extends Actor {
         // `done` actor answers `false` for the same reason.
         //
         // A STOPPED actor is the exception, and it is deliberate: the subscription below
-        // updates this signal on a stable state alone, so the signal keeps the last ACTIVE
+        // updates this atom on a stable state alone, so the atom keeps the last ACTIVE
         // snapshot after a teardown rather than freezing on an artifact of it. `can()`
         // therefore answers for the last live state of a stopped actor.
         if (snapshot?.status !== "active")
@@ -235,11 +234,15 @@ export class PlayerActor extends Actor {
         this.playerInput = input;
         this.playerRestoredSnapshot = restoredSnapshot;
         this.playerOptions = options || {};
-        // Initialize the state signal. Each update is synchronous, with no batching in a
+        // Initialize the state atom. Each update is synchronous, with no batching in a
         // microtask: XState groups the transitions of one send() call into one
         // subscription callback already, and a synchronous update shows each guard
         // redirect to a router bridge at once.
-        this.state = new Signal.State(this.getSnapshot());
+        // `createWritableAtom`, and not `createAtom`. The overload pair of `createAtom` reads
+        // a function argument as a computed atom, and `ReturnType<TMachine["transition"]>` is
+        // an unresolved conditional type here, so TypeScript cannot rule a function out. It
+        // picks the computed signature, which returns a `ReadonlyAtom` that carries no `set`.
+        this.state = createWritableAtom(this.getSnapshot());
         // Observe the transitions of this actor. The code uses `super`, and not `this`, so
         // that the bookkeeping of the next-only subscriptions in the subscribe override
         // stays about the subscriptions of the user code.
@@ -247,16 +250,21 @@ export class PlayerActor extends Actor {
             next: (snapshot) => {
                 // Update on a stable state only: an active snapshot, and the "done" snapshot of a
                 // final state at the top level. The code skips an error snapshot and a stopped
-                // snapshot. Therefore a signal never freezes on an artifact of a teardown.
+                // snapshot. Therefore an atom never freezes on an artifact of a teardown.
                 if (isObservableSnapshot(snapshot)) {
                     // Each state update is synchronous. Therefore a router bridge sees a guard redirect at once.
                     this.state.set(snapshot);
-                    // Every capability derives here, and the ORDER is the composition order:
-                    // `compose(PlayerActor, withRouting, withView)` makes `withView` the outermost
-                    // class, so its override runs `super.onSnapshot()` first and the routing
-                    // capability therefore holds its new value before the view derives from it.
+                    // ONE write for each transition, and the line above is it. `currentRoute` and
+                    // `currentView` are computed atoms over `state`, so that write propagates to
+                    // both in ONE flush, in topological order. No observer therefore reads the new
+                    // state beside an old derivation, and the composition order of the capabilities
+                    // decides nothing.
+                    //
+                    // `onSnapshot` remains for a capability that must run an EFFECT on a
+                    // transition. A capability that publishes a value derives it instead.
+                    //
                     // The whole order of one transition:
-                    // 1. state receives its new value, and each Computed over it follows
+                    // 1. state receives its new value, and every computed atom over it follows
                     // 2. onSnapshot runs each capability, in the composition order
                     // 3. the onStateChange hook runs
                     // 4. send() then calls onTransition
@@ -332,7 +340,7 @@ export class PlayerActor extends Actor {
         // A call that reaches in through the construction window, for example a context
         // factory that stops its own `self`, marks the actor as stopped before the code
         // registers its internal subscription. XState drops each observer of a stopped
-        // actor. The signals therefore move never again. There is nothing to tear down
+        // actor. The atoms therefore move never again. There is nothing to tear down
         // during the construction, and the code ignores such a call.
         if (!this.constructed) {
             return this;
@@ -436,17 +444,19 @@ export class PlayerActor extends Actor {
         return forward.call(this, options);
     }
     /**
-     * The point where a capability derives its own signals from a new snapshot.
+     * The point where a capability derives its own atoms from a new snapshot.
      *
      * The base derives nothing: `PlayActor` asks for `state` and `send`, and this class
-     * gives exactly those. A capability is a mixin that overrides this method, calls
-     * `super.onSnapshot(snapshot)` FIRST, and then writes its own signal.
+     * gives exactly those.
+     *
+     * A capability that PUBLISHES a value overrides this method NOT. It derives the value
+     * with a computed atom over `state`, as `withRouting` and `withView` both do, and the
+     * engine then evaluates every derivation from the one write of a transition, in
+     * topological order. The composition order therefore decides no value.
      *
-     * That one rule fixes the order, and the order is load-bearing. The view of a state
-     * reads the route and the state that the same transition produced, and a router bridge
-     * must see a guard redirect synchronously. `compose(PlayerActor, withRouting, withView)`
-     * therefore derives the route before the view, because `withView` wraps the class that
-     * `withRouting` returned.
+     * This method remains for a capability that must run an EFFECT on a transition. Such a
+     * mixin overrides it and calls `super.onSnapshot(snapshot)` FIRST, so that every
+     * capability composed before it runs its own effect first.
      *
      * The method runs after `state` holds the new snapshot and before the `onStateChange`
      * hook of the options.

package/dist/player-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"player-actor.js","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,GAWL,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAG9F;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG,CAAC,KAAc,EAAkB,EAAE;IACtD,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,OAAO,GAAI,KAA0D,CAAC,OAAO,CAAC;IACpF,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,gBAAgB,CAAC;AACnE,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAS,EAAE;IAChD,IAAI,CAAC;QACJ,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,6EAA6E;QAC7E,kFAAkF;QAClF,aAAa;IACd,CAAC;IACD,OAAO,IAAI,uBAAuB,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,oBAAoB,GAAG,CAAC,QAA4B,EAAW,EAAE,CACtE,QAAQ,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAM,OAAO,WACZ,SAAQ,KAAe;IAGf,aAAa,CAA2B;IAChD;;;;;;;OAOG;IACgB,aAAa,CAAW;IAC3C,iCAAiC;IACd,WAAW,CAAkC;IAChE,iCAAiC;IACd,sBAAsB,CAAiD;IAW1F;;;;;;;;;;;;;;;OAeG;IACH,IAAc,KAAK;QAClB,OAAO,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;IACjC,CAAC;IAiBD,6CAA6C;IACtC,KAAK,CAAmD;IAE/D;;;;;;;;;;OAUG;IACI,GAAG,CAAC,KAA+B;QACzC,+EAA+E;QAC/E,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QACnC,2EAA2E;QAC3E,EAAE;QACF,gFAAgF;QAChF,qFAAqF;QACrF,iFAAiF;QACjF,oFAAoF;QACpF,mFAAmF;QACnF,oDAAoD;QACpD,EAAE;QACF,iFAAiF;QACjF,mFAAmF;QACnF,+EAA+E;QAC/E,gEAAgE;QAChE,IAAI,QAAQ,EAAE,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChD,OAAO,OAAO,QAAQ,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACzE,CAAC;IAED,YACC,OAAiB,EACjB,OAAgC,EAChC,KAA2B,EAC3B,gBAAqD;QAErD,+EAA+E;QAC/E,mFAAmF;QACnF,SAAS;QACT,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC7C,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACjC,CAAC;QAED,kFAAkF;QAClF,4EAA4E;QAC5E,6EAA6E;QAC7E,iEAAiE;QACjE,EAAE;QACF,kFAAkF;QAClF,2EAA2E;QAC3E,kFAAkF;QAClF,iFAAiF;QACjF,uBAAuB;QACvB,0FAA0F;QAC1F,KAAK,CAAC,OAAO,EAAE;YACd,KAAK;YACL,QAAQ,EAAE,gBAAgB;YAC1B,OAAO,EAAE,OAAO,EAAE,OAAO;SACM,CAAC,CAAC;QAElC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,sBAAsB,GAAG,gBAAgB,CAAC;QAC/C,IAAI,CAAC,aAAa,GAAG,OAAO,IAAI,EAAE,CAAC;QAEnC,iFAAiF;QACjF,uEAAuE;QACvE,2EAA2E;QAC3E,uCAAuC;QACvC,IAAI,CAAC,KAAK,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAElD,mFAAmF;QACnF,gFAAgF;QAChF,kDAAkD;QAClD,KAAK,CAAC,SAAS,CAAC;YACf,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE;gBAClB,kFAAkF;gBAClF,+EAA+E;gBAC/E,2EAA2E;gBAC3E,IAAI,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACpC,6FAA6F;oBAC7F,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAEzB,yEAAyE;oBACzE,+EAA+E;oBAC/E,yEAAyE;oBACzE,4EAA4E;oBAC5E,qCAAqC;oBACrC,qEAAqE;oBACrE,+DAA+D;oBAC/D,iCAAiC;oBACjC,oCAAoC;oBACpC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;oBAE1B,8BAA8B;oBAC9B,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC;oBAC/C,IAAI,aAAa,EAAE,CAAC;wBACnB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;oBAC/B,CAAC;gBACF,CAAC;YACF,CAAC;YACD,iFAAiF;YACjF,+EAA+E;YAC/E,kFAAkF;YAClF,+DAA+D;YAC/D,mFAAmF;YACnF,+EAA+E;YAC/E,qDAAqD;YACrD,KAAK,EAAE,CAAC,KAAc,EAAE,EAAE;gBACzB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;gBACnC,IAAI,OAAO,EAAE,CAAC;oBACb,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;oBAC9B,OAAO;gBACR,CAAC;gBACD,8EAA8E;gBAC9E,8DAA8D;gBAC9D,IAAI,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC3C,OAAO;gBACR,CAAC;gBACD,MAAM,KAAK,CAAC;YACb,CAAC;SACD,CAAC,CAAC;QAEH,oFAAoF;QACpF,kCAAkC;QAClC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACM,KAAK;QACb,mFAAmF;QACnF,wBAAwB;QACxB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,KAAK,CAAC,KAAK,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YACnC,IAAI,OAAO,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,CAAC;YACf,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;OASG;IACM,IAAI;QACZ,gFAAgF;QAChF,gFAAgF;QAChF,+EAA+E;QAC/E,+EAA+E;QAC/E,6DAA6D;QAC7D,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,KAAK,CAAC,IAAI,EAAE,CAAC;QAEb,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QACjC,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACM,IAAI,CAAC,KAA+B;QAC5C,kEAAkE;QAClE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACzC,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,gFAAgF;QAChF,2CAA2C;QAC3C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACvC,OAAO;QACR,CAAC;QAED,+EAA+E;QAC/E,6EAA6E;QAC7E,+EAA+E;QAC/E,yEAAyE;QACzE,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAExC,sCAAsC;QACtC,0CAA0C;QAC1C,yEAAyE;QACzE,kFAAkF;QAClF,mFAAmF;QACnF,kFAAkF;QAClF,iBAAiB;QACjB,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAEvC,6BAA6B;QAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;QAC7C,IAAI,YAAY,EAAE,CAAC;YAClB,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACxC,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;QAChD,CAAC;IACF,CAAC;IA2CQ,SAAS,CACjB,sBAEmC,EACnC,aAAwC,EACxC,gBAA6B;QAE7B,mFAAmF;QACnF,+EAA+E;QAC/E,MAAM,YAAY,GAAG,KAAK,CAAC,SAAS,CACnC,sBAAoE,EACpE,aAAa,EACb,gBAAgB,CAChB,CAAC;QAEF,mFAAmF;QACnF,mFAAmF;QACnF,mFAAmF;QACnF,gEAAgE;QAChE,MAAM,gBAAgB,GACrB,OAAO,sBAAsB,KAAK,QAAQ,IAAI,sBAAsB,KAAK,IAAI;YAC5E,CAAC,CAAC,OAAO,sBAAsB,CAAC,KAAK,KAAK,UAAU;YACpD,CAAC,CAAC,OAAO,aAAa,KAAK,UAAU,CAAC;QACxC,IAAI,gBAAgB,EAAE,CAAC;YACtB,OAAO,YAAY,CAAC;QACrB,CAAC;QAED,IAAI,CAAC,qBAAqB,GAAG,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACnE,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,OAAO;YACN,WAAW,EAAE,GAAG,EAAE;gBACjB,IAAI,OAAO,EAAE,CAAC;oBACb,OAAO,GAAG,KAAK,CAAC;oBAChB,IAAI,CAAC,qBAAqB,GAAG,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBACpE,CAAC;gBACD,YAAY,CAAC,WAAW,EAAE,CAAC;YAC5B,CAAC;SACD,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACM,oBAAoB,CAAC,OAAiB;QAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,oBAAgE,CAAC;QACvF,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IACD;;;;;;;;;;;;;;;;;OAiBG;IACO,UAAU,CAAC,QAA4B;QAChD,qEAAqE;QACrE,KAAK,QAAQ,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,CAAC,OAAO,CAAC;QACR,IAAI,CAAC,IAAI,EAAE,CAAC;IACb,CAAC;CACD"}
+{"version":3,"file":"player-actor.js","sourceRoot":"","sources":["../src/player-actor.ts"],"names":[],"mappings":"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"}

package/dist/routing/build-url.d.ts

@@ -1,3 +1,4 @@
+import type { ParseOptions } from "@xmachines/play-pattern";
 import type { RouteContext } from "./types.js";
 /**
  * Builds a complete URL from a route template and the context of the actor.
@@ -16,12 +17,18 @@ import type { RouteContext } from "./types.js";
  * @param context - The context object of the actor. Each route parameter must be in
  *   `context.params`, because the function reads no flat context field. An absent
  *   `query` field builds a URL without a query, exactly like `query: {}`.
+ * @param options - The caches to read, as {@link ParseOptions}. The default is the cache
+ *   that `@xmachines/play-pattern` shares with every caller of the process. A parse is
+ *   deterministic, so this changes how often the parser runs and it changes no answer.
  * @returns The complete URL string.
  *
  * @throws {MissingRouteParamError} When a **necessary** `:param` placeholder has no
  *   value in the context. The function omits an optional parameter (`:param?`) in
  *   silence when its value is absent. Import the class from
  *   `@xmachines/play-xstate/errors`.
+ * @throws {InvalidRouteParamError} When a `:param` placeholder carries a dot segment,
+ *   which a URL resolves away. The template matches the built URL back never, so the
+ *   actor and the address bar would stay out of step.
  *
  * @example
  * ```typescript
@@ -32,5 +39,5 @@ import type { RouteContext } from "./types.js";
  * // → "/settings"  (the optional param is absent, and there is no query string)
  * ```
  */
-export declare const buildRouteUrl: (routeTemplate: string, context?: RouteContext) => string;
+export declare const buildRouteUrl: (routeTemplate: string, context?: RouteContext, options?: ParseOptions) => string;
 //# sourceMappingURL=build-url.d.ts.map

package/dist/routing/build-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-url.d.ts","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,GACzB,eAAe,MAAM,EACrB,UAAS,YAA4B,KACnC,MAwCF,CAAC"}
+{"version":3,"file":"build-url.d.ts","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,aAAa,GACzB,eAAe,MAAM,EACrB,UAAS,YAA4B,EACrC,UAAU,YAAY,KACpB,MAgEF,CAAC"}

package/dist/routing/build-url.js

@@ -1,5 +1,6 @@
+import { buildPath } from "@xmachines/play-pattern";
 import { isAbsoluteRoute } from "./derive-route.js";
-import { MissingRouteParamError } from "../errors.js";
+import { InvalidRouteParamError, MissingRouteParamError } from "../errors.js";
 /**
  * Builds a complete URL from a route template and the context of the actor.
  *
@@ -17,12 +18,18 @@ import { MissingRouteParamError } from "../errors.js";
  * @param context - The context object of the actor. Each route parameter must be in
  *   `context.params`, because the function reads no flat context field. An absent
  *   `query` field builds a URL without a query, exactly like `query: {}`.
+ * @param options - The caches to read, as {@link ParseOptions}. The default is the cache
+ *   that `@xmachines/play-pattern` shares with every caller of the process. A parse is
+ *   deterministic, so this changes how often the parser runs and it changes no answer.
  * @returns The complete URL string.
  *
  * @throws {MissingRouteParamError} When a **necessary** `:param` placeholder has no
  *   value in the context. The function omits an optional parameter (`:param?`) in
  *   silence when its value is absent. Import the class from
  *   `@xmachines/play-xstate/errors`.
+ * @throws {InvalidRouteParamError} When a `:param` placeholder carries a dot segment,
+ *   which a URL resolves away. The template matches the built URL back never, so the
+ *   actor and the address bar would stay out of step.
  *
  * @example
  * ```typescript
@@ -33,7 +40,7 @@ import { MissingRouteParamError } from "../errors.js";
  * // → "/settings"  (the optional param is absent, and there is no query string)
  * ```
  */
-export const buildRouteUrl = (routeTemplate, context = { query: {} }) => {
+export const buildRouteUrl = (routeTemplate, context = { query: {} }, options) => {
     // A context without a `query` field builds a URL without a query, in the same way
     // as an absent context. The generated play.route transitions assign `query` on
     // every navigation, and the shape of the initial context has no effect on that.
@@ -43,10 +50,31 @@ export const buildRouteUrl = (routeTemplate, context = { query: {} }) => {
     // Handle a relative path and an absolute path
     const basePath = context.basePath || "";
     const isAbsolute = isAbsoluteRoute(routeTemplate);
-    // Build the base URL
-    let url = isAbsolute ? routeTemplate : joinPaths(basePath, routeTemplate);
-    // Replace each :param with a context value
-    url = substituteParams(url, context);
+    // Build the base URL. Join every run of separators into one, exactly as
+    // `buildRouteTree` of `@xmachines/play-router` does for the `fullPath` that the route
+    // map holds: `deriveRoute` writes `${parent}/${child}`, so a parent route that ends
+    // with a `/` gives `/app//sub` while the map holds `/app/sub`. A bridge pushed that
+    // location, the router reported `/app/sub` back — `sanitizePathname` collapses it —
+    // and the echo test then read its OWN push as a move of the user and sent a
+    // `play.route` for the state the actor was in already.
+    //
+    // The collapse runs on the TEMPLATE, and not on the built path, so a `:path*` value
+    // keeps every separator that it carries.
+    let url = (isAbsolute ? routeTemplate : joinPaths(basePath, routeTemplate)).replace(/\/+/g, "/");
+    // Replace each param with a context value. `buildPath` of `@xmachines/play-pattern`
+    // reads the WHOLE pattern grammar, which is the same parse that the match reads, so a
+    // route that the router matches derives a URL that the router matches back. That
+    // package carries the language alone: no URLPattern, and no polyfill for it.
+    const built = buildPath(url, context.params ?? {}, options);
+    if (!built.ok) {
+        if (built.reason === "unresolvable") {
+            throw new InvalidRouteParamError(built.param, built.value, routeTemplate);
+        }
+        throw new MissingRouteParamError(built.missing, routeTemplate);
+    }
+    // A template of the root level with optional params only, for example `/:section?`,
+    // builds `""`. That value makes an invalid URL, such as `""` or `"?tab=x"`.
+    url = built.path === "" ? "/" : built.path;
     // Append the query params of the context. The frequent empty `query: {}` passes the
     // key check first. Therefore each recomputation allocates a URLSearchParams object
     // only when it has something to write.
@@ -66,54 +94,6 @@ export const buildRouteUrl = (routeTemplate, context = { query: {} }) => {
     }
     return url;
 };
-/**
- * Replaces each `:param` placeholder with a context value, and it escapes that
- * value with `encodeURIComponent`.
- *
- * The function supports an optional parameter, in the form :param?.
- * - It removes an optional parameter without a value completely, and it also removes the /
- * - It writes a warning for a necessary parameter without a value
- *
- * The lookup of a parameter:
- * - The function reads context.params[param] only. It reads no flat context field.
- *
- * @param template - The URL template, with the :param or :param? syntax
- * @param context - The context with the parameter values. It can have a params field
- * @returns The URL with the parameters in place, and without a double slash
- * @throws {MissingRouteParamError} When a necessary route parameter is absent
- */
-const substituteParams = (template, context) => {
-    // Replace each parameter, and handle the optional syntax
-    let hasOptionalRemoval = false;
-    const result = template.replace(/:(\w+)(\?)?/g, (_match, param, optional) => {
-        const value = context.params?.[param]; // nosemgrep: gitlab.eslint.detect-object-injection
-        // The parameter has a value that is not empty: put it in place.
-        // For an optional param, an empty string means "no value".
-        if (value !== undefined && value !== null && value !== "") {
-            return encodeURIComponent(String(value));
-        }
-        // An optional parameter without a value, or with an empty string: remove the segment
-        if (optional === "?") {
-            hasOptionalRemoval = true;
-            return ""; // This leaves // in the path. The code below removes it
-        }
-        throw new MissingRouteParamError(param, template);
-    });
-    // Remove each double slash
-    let cleaned = result.replace(/\/+/g, "/");
-    // Remove a trailing slash only after the code removed an optional parameter.
-    // A trailing slash of a necessary param stays, because it shows an error.
-    if (hasOptionalRemoval && cleaned.endsWith("/")) {
-        cleaned = cleaned.slice(0, -1);
-    }
-    // Return an empty path never: a template of the root level with optional params
-    // only, for example "/:section?", becomes "" after the trim of the trailing slash.
-    // That value makes an invalid URL, such as "" or "?tab=x". Normalize it to "/".
-    if (cleaned === "") {
-        cleaned = "/";
-    }
-    return cleaned;
-};
 /**
  * Joins a base path and a relative path
  *

package/dist/routing/build-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,aAAqB,EACrB,UAAwB,EAAE,KAAK,EAAE,EAAE,EAAE,EAC5B,EAAE;IACX,kFAAkF;IAClF,+EAA+E;IAC/E,gFAAgF;IAChF,kFAAkF;IAClF,+EAA+E;IAC/E,kBAAkB;IAElB,8CAA8C;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,UAAU,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;IAElD,qBAAqB;IACrB,IAAI,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE1E,2CAA2C;IAC3C,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAErC,oFAAoF;IACpF,mFAAmF;IACnF,uCAAuC;IACvC,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,eAAe,CACjC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAqB,CAAC,CAChE,CAAC;YACF,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,WAAW,EAAE,CAAC;gBACjB,GAAG,IAAI,IAAI,WAAW,EAAE,CAAC;YAC1B,CAAC;QACF,CAAC;IACF,CAAC;IAED,iCAAiC;IACjC,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtD,GAAG,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GAAG,CAAC,QAAgB,EAAE,OAAqB,EAAU,EAAE;IAC5E,yDAAyD;IACzD,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAC/B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,mDAAmD;QAE1F,gEAAgE;QAChE,2DAA2D;QAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YAC3D,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,qFAAqF;QACrF,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACtB,kBAAkB,GAAG,IAAI,CAAC;YAC1B,OAAO,EAAE,CAAC,CAAC,wDAAwD;QACpE,CAAC;QAED,MAAM,IAAI,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE1C,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,gFAAgF;IAChF,mFAAmF;IACnF,gFAAgF;IAChF,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,GAAG,GAAG,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;IAC5D,wCAAwC;IACxC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE/C,8CAA8C;IAC9C,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEvD,oCAAoC;IACpC,OAAO,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,kBAAkB,EAAE,CAAC;AAC9F,CAAC,CAAC"}
+{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"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"}

package/dist/routing/derive-current-route.d.ts

@@ -1,4 +1,5 @@
 import type { AnyMachineSnapshot } from "xstate";
+import type { ParseOptions } from "@xmachines/play-pattern";
 export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
 /**
  * Derives the current URL of the actor from the state metadata and the context.
@@ -11,7 +12,7 @@ export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
  * - The snapshot has no route metadata, which means a state without a route
  * - The context does not hold a necessary route parameter (`MissingRouteParamError`)
  *
- * The `null` value for an absent param is deliberate: the computed signal therefore
+ * The `null` value for an absent param is deliberate: the computed atom therefore
  * stays stable during a temporary state. Such a state appears during a transition,
  * before the context is complete, and also after a logout, when `context.username`
  * is `null` and the router bridge did not reach the new state yet. The router bridge
@@ -19,7 +20,15 @@ export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
  * context is complete.
  *
  * @param snapshot - The current snapshot of the XState machine.
+ * @param options - The caches that the parse of the route TEMPLATE reads. The default is
+ *   the cache that `@xmachines/play-pattern` shares with every caller of the process.
+ *
+ *   `withRouting` calls this function with no options, and that is deliberate: it parses
+ *   the `meta.route` template of a state, and a machine declares a small and static set of
+ *   those. The unbounded key space that a cache of the caller answers is the one of
+ *   `RouterBridgeBase`, which parses a CONCRETE location — one for each value that an
+ *   application puts in a param — and a bridge takes its caches already.
  * @returns The resolved URL string, or `null` when the function cannot resolve the route.
  */
-export declare const deriveCurrentRoute: (snapshot: AnyMachineSnapshot) => string | null;
+export declare const deriveCurrentRoute: (snapshot: AnyMachineSnapshot, options?: ParseOptions) => string | null;
 //# sourceMappingURL=derive-current-route.d.ts.map

package/dist/routing/derive-current-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-current-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-current-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAQjD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,kBAAkB,KAAG,MAAM,GAAG,IA8B1E,CAAC"}
+{"version":3,"file":"derive-current-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-current-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAMjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,GAC9B,UAAU,kBAAkB,EAC5B,UAAU,YAAY,KACpB,MAAM,GAAG,IAsCX,CAAC"}

package/dist/routing/derive-current-route.js

@@ -14,7 +14,7 @@ export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
  * - The snapshot has no route metadata, which means a state without a route
  * - The context does not hold a necessary route parameter (`MissingRouteParamError`)
  *
- * The `null` value for an absent param is deliberate: the computed signal therefore
+ * The `null` value for an absent param is deliberate: the computed atom therefore
  * stays stable during a temporary state. Such a state appears during a transition,
  * before the context is complete, and also after a logout, when `context.username`
  * is `null` and the router bridge did not reach the new state yet. The router bridge
@@ -22,9 +22,17 @@ export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
  * context is complete.
  *
  * @param snapshot - The current snapshot of the XState machine.
+ * @param options - The caches that the parse of the route TEMPLATE reads. The default is
+ *   the cache that `@xmachines/play-pattern` shares with every caller of the process.
+ *
+ *   `withRouting` calls this function with no options, and that is deliberate: it parses
+ *   the `meta.route` template of a state, and a machine declares a small and static set of
+ *   those. The unbounded key space that a cache of the caller answers is the one of
+ *   `RouterBridgeBase`, which parses a CONCRETE location — one for each value that an
+ *   application puts in a param — and a bridge takes its caches already.
  * @returns The resolved URL string, or `null` when the function cannot resolve the route.
  */
-export const deriveCurrentRoute = (snapshot) => {
+export const deriveCurrentRoute = (snapshot, options) => {
     const meta = activeStateMeta(snapshot);
     if (!meta) {
         return null;
@@ -34,7 +42,7 @@ export const deriveCurrentRoute = (snapshot) => {
         return null;
     }
     try {
-        return buildRouteUrl(routeTemplate, (snapshot.context ?? {}));
+        return buildRouteUrl(routeTemplate, (snapshot.context ?? {}), options);
     }
     catch (error) {
         // MissingRouteParamError: the condition is temporary, and it resolves itself. A
@@ -43,14 +51,22 @@ export const deriveCurrentRoute = (snapshot) => {
         // context.params, and also after a logout, before the bridge redirects. A `null`
         // value is correct here:
         //   - a router bridge reads null and skips the navigation (syncRouterFromActor, line 242)
-        //   - the signal computes its value again on the next snapshot, when the params arrive
-        //   - a throw goes to each signal watcher as an unhandled exception, for a state
-        //     that resolves itself. That is worse than a null value for one tick.
+        //   - the atom computes its value again on the next snapshot, when the params arrive
+        //   - a report of a condition that resolves itself is worse than a null value for
+        //     one tick.
         // Do NOT convert this into a throw.
         if (error instanceof MissingRouteParamError) {
             return null;
         }
         // Each unexpected error goes to the caller without a change.
+        //
+        // This function is PURE, and it stays that way: it has no actor, so it holds no
+        // error channel and no previous value. The CALLER decides what an unexpected error
+        // means. `currentRoute` of `with-routing.ts` is that caller for the reactive path —
+        // it reports through `onError` of the actor and keeps the last route, because a
+        // throw from there would unwind into the transition. `initialRoute` is the other
+        // caller, and a throw from it fails the construction, which is where a developer
+        // wants to see a route template that cannot be built.
         throw error;
     }
 };

package/dist/routing/derive-current-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-current-route.js","sourceRoot":"","sources":["../../src/routing/derive-current-route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAA4B,EAAiB,EAAE;IACjF,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,CAAC;QACJ,OAAO,aAAa,CAAC,aAAa,EAAE,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAiB,CAAC,CAAC;IAC/E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,gFAAgF;QAChF,oFAAoF;QACpF,gFAAgF;QAChF,iFAAiF;QACjF,yBAAyB;QACzB,0FAA0F;QAC1F,uFAAuF;QACvF,iFAAiF;QACjF,0EAA0E;QAC1E,oCAAoC;QACpC,IAAI,KAAK,YAAY,sBAAsB,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC;QACb,CAAC;QACD,6DAA6D;QAC7D,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC,CAAC"}
+{"version":3,"file":"derive-current-route.js","sourceRoot":"","sources":["../../src/routing/derive-current-route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CACjC,QAA4B,EAC5B,OAAsB,EACN,EAAE;IAClB,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,CAAC;QACJ,OAAO,aAAa,CAAC,aAAa,EAAE,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAiB,EAAE,OAAO,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,gFAAgF;QAChF,oFAAoF;QACpF,gFAAgF;QAChF,iFAAiF;QACjF,yBAAyB;QACzB,0FAA0F;QAC1F,qFAAqF;QACrF,kFAAkF;QAClF,gBAAgB;QAChB,oCAAoC;QACpC,IAAI,KAAK,YAAY,sBAAsB,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC;QACb,CAAC;QACD,6DAA6D;QAC7D,EAAE;QACF,gFAAgF;QAChF,mFAAmF;QACnF,oFAAoF;QACpF,gFAAgF;QAChF,iFAAiF;QACjF,iFAAiF;QACjF,sDAAsD;QACtD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC,CAAC"}

package/dist/routing/derive-initial-route.d.ts

@@ -1,4 +1,5 @@
 import { type AnyStateMachine } from "xstate";
+import type { ParseOptions } from "@xmachines/play-pattern";
 /**
  * Derives the initial route of the machine directly from the machine definition.
  *
@@ -39,5 +40,5 @@ import { type AnyStateMachine } from "xstate";
  * deriveInitialRoute(machine, { username: "alice" }); // "/profile/alice"
  * ```
  */
-export declare const deriveInitialRoute: (machine: AnyStateMachine, input?: unknown) => string | null;
+export declare const deriveInitialRoute: (machine: AnyStateMachine, input?: unknown, options?: ParseOptions) => string | null;
 //# sourceMappingURL=derive-initial-route.d.ts.map

package/dist/routing/derive-initial-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-initial-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-initial-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,QAAQ,CAAC;AAI1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,eAAe,EAAE,QAAQ,OAAO,KAAG,MAAM,GAAG,IAwBvF,CAAC"}
+{"version":3,"file":"derive-initial-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-initial-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,QAAQ,CAAC;AAG1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,eAAe,EACxB,QAAQ,OAAO,EACf,UAAU,YAAY,KACpB,MAAM,GAAG,IAwBX,CAAC"}

package/dist/routing/derive-initial-route.js

@@ -40,7 +40,7 @@ import { deriveCurrentRoute } from "./derive-current-route.js";
  * deriveInitialRoute(machine, { username: "alice" }); // "/profile/alice"
  * ```
  */
-export const deriveInitialRoute = (machine, input) => {
+export const deriveInitialRoute = (machine, input, options) => {
     let initialSnapshot;
     try {
         [initialSnapshot] = initialTransition(machine, input);
@@ -63,6 +63,6 @@ export const deriveInitialRoute = (machine, input) => {
     // question, and it holds whichever way a later release reports the failure.
     if (initialSnapshot.status === "error")
         return null;
-    return deriveCurrentRoute(initialSnapshot);
+    return deriveCurrentRoute(initialSnapshot, options);
 };
 //# sourceMappingURL=derive-initial-route.js.map

package/dist/routing/derive-initial-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-initial-route.js","sourceRoot":"","sources":["../../src/routing/derive-initial-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAiD,MAAM,QAAQ,CAAC;AAE1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAwB,EAAE,KAAe,EAAiB,EAAE;IAC9F,IAAI,eAAmC,CAAC;IACxC,IAAI,CAAC;QACJ,CAAC,eAAe,CAAC,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACR,gFAAgF;QAChF,oFAAoF;QACpF,qFAAqF;QACrF,iFAAiF;QACjF,OAAO,IAAI,CAAC;IACb,CAAC;IAED,qEAAqE;IACrE,6EAA6E;IAC7E,sFAAsF;IACtF,sFAAsF;IACtF,sFAAsF;IACtF,6BAA6B;IAC7B,EAAE;IACF,kFAAkF;IAClF,4EAA4E;IAC5E,IAAI,eAAe,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAEpD,OAAO,kBAAkB,CAAC,eAAe,CAAC,CAAC;AAC5C,CAAC,CAAC"}
+{"version":3,"file":"derive-initial-route.js","sourceRoot":"","sources":["../../src/routing/derive-initial-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAiD,MAAM,QAAQ,CAAC;AAE1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CACjC,OAAwB,EACxB,KAAe,EACf,OAAsB,EACN,EAAE;IAClB,IAAI,eAAmC,CAAC;IACxC,IAAI,CAAC;QACJ,CAAC,eAAe,CAAC,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACR,gFAAgF;QAChF,oFAAoF;QACpF,qFAAqF;QACrF,iFAAiF;QACjF,OAAO,IAAI,CAAC;IACb,CAAC;IAED,qEAAqE;IACrE,6EAA6E;IAC7E,sFAAsF;IACtF,sFAAsF;IACtF,sFAAsF;IACtF,6BAA6B;IAC7B,EAAE;IACF,kFAAkF;IAClF,4EAA4E;IAC5E,IAAI,eAAe,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAEpD,OAAO,kBAAkB,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AACrD,CAAC,CAAC"}

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

@@ -28,6 +28,13 @@ const asTransitionArray = (value) => value === undefined ? [] : Array.isArray(va
  * event: the declaration of a state is static.
  */
 const declaresRouteData = (route) => typeof route === "object" && route !== null && route.data !== undefined;
+/**
+ * The `params` and the `query` of the event, each beside the container that the context
+ * holds already. Neither one reads the metadata of the route, so both stand here rather
+ * than inside the factory, where a call rebuilt them for every generated transition.
+ */
+const assignParams = ({ context, event }) => keepEqualContainer(context.params, event.params || {});
+const assignQuery = ({ context, event }) => keepEqualContainer(context.query, event.query || {});
 /**
  * Builds the assign action of a generated `play.route` transition.
  *
@@ -41,13 +48,11 @@ const declaresRouteData = (route) => typeof route === "object" && route !== null
  * received one with no value, and the `/context` projection of every view carried it.
  */
 const makeRouteAssign = (routeMeta) => {
-    const params = ({ context, event }) => keepEqualContainer(context.params, event.params || {});
-    const query = ({ context, event }) => keepEqualContainer(context.query, event.query || {});
     if (!declaresRouteData(routeMeta))
-        return assign({ params, query });
+        return assign({ params: assignParams, query: assignQuery });
     return assign({
-        params,
-        query,
+        params: assignParams,
+        query: assignQuery,
         // A resolver that answers `undefined` leaves the field of the context as it stands,
         // and it therefore writes `undefined` over the data of an earlier route never.
         data: ({ context, event }) => {