@xmachines/play-xstate 6.1.0 → 7.0.0

package/dist/with-routing.js

@@ -1,140 +1,98 @@
-import { createAtom } from "@xmachines/play-atom";
-import { deriveCurrentRoute, deriveInitialRoute } from "./routing/index.js";
 import { toError } from "./player-actor.js";
+import { deriveRoute, isAbsoluteRoute } from "./routing/derive-route.js";
+import { buildRouteUrl } from "./routing/build-url.js";
+import { deriveCurrentRoute } from "./routing/derive-current-route.js";
+import { deriveInitialRoute } from "./routing/derive-initial-route.js";
+import { formatPlayRouteTransitions } from "./routing/format-play-route-transitions.js";
+import { createAtom } from "@xmachines/play-atom";
+//#region packages/play-xstate/src/with-routing.ts
 /**
- * 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;
+* 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`.
+*/
+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) {
+				const onError = this.hooks.onError;
+				if (onError) {
+					const reported = toError(error);
+					queueMicrotask(() => {
+						onError(this, reported);
+					});
+				}
+				return previous ?? null;
+			}
+		}, { 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 === void 0 ? 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";
+//#endregion
+export { buildRouteUrl, deriveRoute, formatPlayRouteTransitions, isAbsoluteRoute, withRouting };
+
 //# sourceMappingURL=with-routing.js.map

package/dist/with-routing.js.map

@@ -1 +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"}
+{"version":3,"file":"with-routing.js","names":[],"sources":["../src/with-routing.ts"],"sourcesContent":["/**\n * The routing capability of an XState actor, as a mixin.\n *\n * `PlayerActor` holds `state` and `send`, and nothing about a route. This module adds\n * `currentRoute` and `initialRoute`, which is what `Routable` of `@xmachines/play-router`\n * asks for and what every router bridge reads.\n *\n * It is a SEPARATE entry point, `@xmachines/play-xstate/routing`, and the core imports it\n * never. `@xmachines/play-router` is an OPTIONAL peer of this package for the same reason:\n * an application that declares no route installs neither that package nor the route map\n * and the bridge that it carries.\n *\n * @example\n * ```typescript\n * import { definePlayer, PlayerActor, compose } from \"@xmachines/play-xstate\";\n * import { withRouting } from \"@xmachines/play-xstate/routing\";\n *\n * const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });\n * const actor = createPlayer();\n * actor.currentRoute.get(); // \"/profile/alice\"\n * ```\n *\n * @packageDocumentation\n */\nimport type { AnyStateMachine } from \"xstate\";\nimport { createAtom } from \"@xmachines/play-atom\";\nimport type { ReadonlyAtom } from \"@xmachines/play-atom\";\nimport type { Routable } from \"@xmachines/play-router\";\n\nimport type { PlayerConstructor } from \"./capabilities.js\";\nimport { deriveCurrentRoute, deriveInitialRoute } from \"./routing/index.js\";\nimport { toError } from \"./player-actor.js\";\n\n/**\n * Adds the routing capability to an actor class.\n *\n * The result satisfies `Routable`, so a router bridge accepts it. A class without this\n * mixin exposes no `currentRoute`, and a bridge therefore refuses it when it compiles,\n * rather than at the first navigation.\n *\n * The mixin declares NO constructor, and that is deliberate: TypeScript demands the\n * signature `...args: any[]` from a mixin over a generic base (TS2545), and this\n * workspace writes no `any`. A field initializer of a subclass runs after `super()`\n * instead, and it reads the inputs that `PlayerActor` keeps for a capability.\n *\n * @param Base - The actor class to extend, normally `PlayerActor`.\n */\nexport function withRouting<TMachine extends AnyStateMachine>(\n\tBase: PlayerConstructor<TMachine>,\n): PlayerConstructor<TMachine, Routable> {\n\tclass RoutableActor extends Base implements Routable {\n\t\t/**\n\t\t * A computed atom. It derives the current URL path from the `meta.route`\n\t\t * template of the active machine state and from the context of the actor.\n\t\t *\n\t\t * It returns `null` when the current state has no `meta.route` field, and also when\n\t\t * a necessary `:param` has no value in the context. The second case is normally\n\t\t * temporary during a transition, and the atom computes the value again on the next\n\t\t * snapshot.\n\t\t *\n\t\t * It THROWS never. A derivation of this architecture reports a failure through\n\t\t * `onError` and keeps its last good value, and `currentView` of\n\t\t * `@xmachines/play-xstate/view` follows the same rule.\n\t\t *\n\t\t * The reason is the propagation. A subscriber makes this atom eager, so the\n\t\t * derivation runs inside the `set` of `state`, which runs inside the XState\n\t\t * subscription. A throw that left this function would unwind into `actor.send` and\n\t\t * break the transition for EVERY other observer of the actor.\n\t\t *\n\t\t * The containment therefore belongs to the derivation, and not to each subscriber:\n\t\t * a consumer that writes its own `watchAtom(actor.currentRoute, ...)` is protected\n\t\t * by the same rule that protects a router bridge.\n\t\t *\n\t\t * @example\n\t\t * ```typescript\n\t\t * // It returns \"/profile/alice\" when context.params.userId === \"alice\",\n\t\t * // and null while the param is still absent.\n\t\t * const route = actor.currentRoute.get();\n\t\t * ```\n\t\t */\n\t\tpublic readonly currentRoute: ReadonlyAtom<string | null> = createAtom(\n\t\t\t(previous): string | null => {\n\t\t\t\ttry {\n\t\t\t\t\treturn deriveCurrentRoute(this.state.get());\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// `deriveCurrentRoute` answers the EXPECTED failure itself: a missing `:param`\n\t\t\t\t\t// returns `null`, and the next snapshot resolves it. Whatever reaches this line\n\t\t\t\t\t// is unexpected — a `URIError` of `encodeURIComponent` for a lone surrogate,\n\t\t\t\t\t// for example. Report it, and keep the last route: a caller that reads `null`\n\t\t\t\t\t// or a stale route navigates nowhere, which the bridge handles already.\n\t\t\t\t\t// The derivation runs inside the `set` of `state`, and the engine TRACKS every\n\t\t\t\t\t// atom that this function reads — the handler of the host included. A report\n\t\t\t\t\t// from HERE therefore made whatever that handler reads a dependency of this\n\t\t\t\t\t// atom, and an unrelated write of it re-derived and reported again: three\n\t\t\t\t\t// reports for one failure. The microtask leaves the evaluation, so the handler\n\t\t\t\t\t// reads what it likes and this atom depends on none of it.\n\t\t\t\t\t//\n\t\t\t\t\t// It leaves the `set` as well, which is what the comment below already needed:\n\t\t\t\t\t// a throw from the handler lands on the global handler of the runtime, and it\n\t\t\t\t\t// breaks the transition for no other observer of the actor.\n\t\t\t\t\tconst onError = this.hooks.onError;\n\t\t\t\t\tif (onError) {\n\t\t\t\t\t\tconst reported = toError(error);\n\t\t\t\t\t\tqueueMicrotask(() => {\n\t\t\t\t\t\t\tonError(this, reported);\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\treturn previous ?? null;\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\t// Every WRITE of `state` reaches an observer of this atom, and not the writes\n\t\t\t\t// that change the route alone.\n\t\t\t\t//\n\t\t\t\t// The default `Object.is` stops a notification for a value that the atom holds\n\t\t\t\t// already, and a route is a STRING: a guard that refuses an inbound location and\n\t\t\t\t// moves the actor back to the state it came from derives the same string, so no\n\t\t\t\t// observer heard the answer. `RouterBridgeBase` waits for exactly that answer —\n\t\t\t\t// `syncActorFromRouter` clears `lastActorRoute` before it sends, so the push\n\t\t\t\t// that puts the address bar back on the route of the machine is owed to this\n\t\t\t\t// notification — and the address bar kept the location that the guard refused.\n\t\t\t\t//\n\t\t\t\t// The bridge is written against a notification for each change of the SNAPSHOT,\n\t\t\t\t// and not for each change of the derived string, so the comparison has to answer\n\t\t\t\t// \"different\" always. A consumer that reads the value pays nothing for it: the\n\t\t\t\t// derivation still runs one time for each transition, and `state` itself compares\n\t\t\t\t// with `Object.is`, so an event that XState ignores delivers the identical\n\t\t\t\t// snapshot and propagates nothing.\n\t\t\t\tcompare: () => false,\n\t\t\t},\n\t\t);\n\n\t\t/**\n\t\t * The route of the initial state of the machine. The construction fixes it, and it\n\t\t * never changes, also when the code restores the actor from a snapshot.\n\t\t *\n\t\t * A router bridge compares it with the browser URL, and it therefore separates a\n\t\t * deep link (a URL that is not the initial one → the router wins) from a restore\n\t\t * (the initial URL, and the actor at a different route from the restore → the actor\n\t\t * wins).\n\t\t *\n\t\t * `deriveInitialRoute` derives the value statically from the machine definition,\n\t\t * with the pure `initialTransition` helper of XState: the chain of the initial states\n\t\t * and their `meta.route` templates are fixed at the moment of the machine\n\t\t * definition, and the substitution of a `:param` uses the real initial context of\n\t\t * the machine for the `input` of this actor. The code makes no second actor, and a\n\t\t * snapshot of a restore changes the value never: it is always the **default**\n\t\t * initial route of the machine.\n\t\t *\n\t\t * Without a snapshot of a restore, the pre-start snapshot of this actor IS that\n\t\t * default initial state, so the code derives the route from it directly. A restore\n\t\t * alone needs `initialTransition`, whose inert actor scope runs the initial\n\t\t * transition two more times, one of them with an undefined `input`. That is a quirk\n\t\t * of XState, and it costs too much for every other case.\n\t\t */\n\t\tpublic readonly initialRoute: string | null =\n\t\t\tthis.playerRestoredSnapshot === undefined\n\t\t\t\t? deriveCurrentRoute(this.getSnapshot())\n\t\t\t\t: deriveInitialRoute(this.playerMachine, this.playerInput);\n\t}\n\n\treturn RoutableActor;\n}\n\n// The utilities of the route derivation and of the URL construction.\n//\n// They belong HERE, and no longer on the main entry. Each one names\n// `@xmachines/play-router` in its own `.d.ts` — `PlayRouteEvent`, `RouteData`,\n// `RouteObject` and `RouteMetadata` all have their single definition there. That\n// package is an OPTIONAL peer, so a main entry that reached them gave every consumer\n// of `definePlayer` a type graph that names a package their node_modules does not\n// hold. `skipLibCheck` hides the fault and does not remove it: the types resolve to\n// nothing.\n//\n// The view half exposes nothing on the main entry, for the same reason. The two\n// capabilities hold one shape.\nexport {\n\tderiveRoute,\n\tisAbsoluteRoute,\n\tbuildRouteUrl,\n\tformatPlayRouteTransitions,\n} from \"./routing/index.js\";\nexport type {\n\tRouteMachineConfig,\n\tRouteStateNode,\n\tRouteContext,\n\tRouteObject,\n\tRouteMetadata,\n\tRouteData,\n\tRouteDataResolver,\n} from \"./routing/index.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,YACf,MACwC;CACxC,MAAM,sBAAsB,KAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BpD,eAA4D,YAC1D,aAA4B;GAC5B,IAAI;IACH,OAAO,mBAAmB,KAAK,MAAM,IAAI,CAAC;GAC3C,SAAS,OAAO;IAgBf,MAAM,UAAU,KAAK,MAAM;IAC3B,IAAI,SAAS;KACZ,MAAM,WAAW,QAAQ,KAAK;KAC9B,qBAAqB;MACpB,QAAQ,MAAM,QAAQ;KACvB,CAAC;IACF;IACA,OAAO,YAAY;GACpB;EACD,GACA,EAkBC,eAAe,MAChB,CACD;;;;;;;;;;;;;;;;;;;;;;;;EAyBA,eACC,KAAK,2BAA2B,KAAA,IAC7B,mBAAmB,KAAK,YAAY,CAAC,IACrC,mBAAmB,KAAK,eAAe,KAAK,WAAW;CAC5D;CAEA,OAAO;AACR"}

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

@@ -1 +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;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAS,eAAe,EACxD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAyFvC"}
+{"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;AAG9C,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAS,eAAe,EACxD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAuFvC"}

package/dist/with-view.js

@@ -1,158 +1,88 @@
-import { createAtom } from "@xmachines/play-atom";
-import { shallowEqualExcept } from "@xmachines/core/utils";
-import { reuseComposedState } from "@xmachines/play-view";
 import { toError } from "./player-actor.js";
 import { deriveCurrentView } from "./view/derive-current-view.js";
+import { createAtom } from "@xmachines/play-atom";
+import { reuseComposedState } from "@xmachines/play-view";
+//#region packages/play-xstate/src/with-view.ts
 /**
- * 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;
-};
-/**
- * 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.
- */
+* 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.
- *
- * @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 atom of the current view spec. The atom 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 snapshot that changes no view on the screen, such as an
-         * assign of the context alone, keeps the previous reference. A provider below the
-         * atom 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 atom returns `null` when the current state has no `meta.view` metadata.
-         *
-         * Two states that each declare a `meta.view` emit two different `viewKey` values,
-         * also when the two specs are one `typedSpec` constant: the key is the id of the
-         * state node that declares the view. A transition between those two states therefore
-         * emits again, and a provider seeds a new store, which removes the ephemeral state.
-         * The ephemeral state survives a move between the children when the parent holds
-         * the key: declare the view on the parent and none on the children, or declare
-         * `outlets` on the parent, which keeps its id as the `viewKey` of the composed view.
-         *
-         * It is a COMPUTED atom over `state`, and not a written one. One write for each
-         * transition therefore reaches the whole actor — `state.set(snapshot)` — and the
-         * engine evaluates this atom and `currentRoute` in one propagation, in topological
-         * order. A second write would flush a second time, and an observer that reads two
-         * atoms would see the new state beside the old view in between.
-         */
-        currentView = createAtom((previous) => {
-            // `previous` is the value that this atom holds already. The engine hands it in,
-            // so the gate below reads it without a `get()`, and it therefore registers
-            // `currentView` as a dependency of nothing.
-            const lastEmittedView = previous ?? null;
-            try {
-                const view = deriveCurrentView(this.state.get());
-                // 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.
-                //
-                // A return of `lastEmittedView` compares equal under `Object.is`, so the atom
-                // notifies no subscriber and the propagation stops here.
-                const nextView = reuseComposedState(lastEmittedView, view);
-                return viewSpecsEquivalent(lastEmittedView, nextView)
-                    ? lastEmittedView
-                    : nextView;
-            }
-            catch (error) {
-                // The derivation runs inside the `set` of `state`, which runs inside the XState
-                // subscription. A throw that leaves this function therefore leaves that `set`
-                // and breaks the transition for every other observer of the actor. Report it,
-                // and keep the last valid view.
-                //
-                // 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 lastEmittedView;
-            }
-        });
-    }
-    return ViewableActor;
+* 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.
+*
+* @param Base - The actor class to extend, normally `PlayerActor` or the result of
+*   another capability.
+*/
+function withView(Base) {
+	class ViewableActor extends Base {
+		/**
+		* The reactive atom of the current view spec. The atom derives the spec from the
+		* `meta.view` metadata of the active state.
+		*
+		* It emits a **new object reference** for the view of a different state, and for a
+		* change of a value of the context, which the spec reads under `/context`. A snapshot
+		* that changes neither keeps the previous reference: an event that the machine
+		* ignores, a transition inside a region that no outlet shows, or an assign that
+		* writes the same values again. The viewKey of a new emission tells a provider
+		* whether to seed its store again or to refresh `/context` in place, so the UI
+		* mounts again only for a new viewKey.
+		*
+		* 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 atom returns `null` when the current state has no `meta.view` metadata.
+		*
+		* Two states that each declare a `meta.view` emit two different `viewKey` values,
+		* also when the two specs are one `typedSpec` constant: the key is the id of the
+		* state node that declares the view. A transition between those two states therefore
+		* emits again, and a provider seeds a new store, which removes the ephemeral state.
+		* The ephemeral state survives a move between the children when the parent holds
+		* the key: declare the view on the parent and none on the children, or declare
+		* `outlets` on the parent, which keeps its id as the `viewKey` of the composed view.
+		*
+		* It is a COMPUTED atom over `state`, and not a written one. One write for each
+		* transition therefore reaches the whole actor — `state.set(snapshot)` — and the
+		* engine evaluates this atom and `currentRoute` in one propagation, in topological
+		* order. A second write would flush a second time, and an observer that reads two
+		* atoms would see the new state beside the old view in between.
+		*/
+		currentView = createAtom((previous) => {
+			const lastEmittedView = previous ?? null;
+			try {
+				const view = deriveCurrentView(this.state.get());
+				return reuseComposedState(lastEmittedView, view);
+			} catch (error) {
+				const onError = this.hooks.onError;
+				if (onError) {
+					const reported = toError(error);
+					queueMicrotask(() => {
+						onError(this, reported);
+					});
+				}
+				return lastEmittedView;
+			}
+		});
+	}
+	return ViewableActor;
 }
+//#endregion
+export { withView };
+
 //# sourceMappingURL=with-view.js.map

package/dist/with-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-view.js","sourceRoot":"","sources":["../src/with-view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"with-view.js","names":[],"sources":["../src/with-view.ts"],"sourcesContent":["/**\n * The view capability of an XState actor, as a mixin.\n *\n * `PlayerActor` holds `state` and `send`, and nothing about a view. This module adds\n * `currentView`, which is what `Viewable` of `@xmachines/play-view` asks for and what\n * every renderer reads.\n *\n * It is a SEPARATE entry point, `@xmachines/play-xstate/view`, and the core imports it\n * never. `@xmachines/play-view` is an OPTIONAL peer of this package for the same reason:\n * an application that renders no view installs neither that package nor the json-render\n * types that it names.\n *\n * @example\n * ```typescript\n * import { definePlayer, PlayerActor, compose } from \"@xmachines/play-xstate\";\n * import { withRouting } from \"@xmachines/play-xstate/routing\";\n * import { withView } from \"@xmachines/play-xstate/view\";\n *\n * const createPlayer = definePlayer({\n *   machine,\n *   actor: compose(PlayerActor, withRouting, withView),\n * });\n * ```\n *\n * @packageDocumentation\n */\nimport type { AnyStateMachine } from \"xstate\";\nimport { createAtom } from \"@xmachines/play-atom\";\nimport type { ReadonlyAtom } from \"@xmachines/play-atom\";\nimport { reuseComposedState, type PlaySpec, type Viewable } from \"@xmachines/play-view\";\n\nimport { toError } from \"./player-actor.js\";\nimport type { PlayerConstructor } from \"./capabilities.js\";\nimport { deriveCurrentView } from \"./view/derive-current-view.js\";\n\n/**\n * Two WeakMaps stood here, and the derivation below needs neither.\n *\n * `lastViewSnapshots` skipped the derivation for a snapshot that the pipeline read\n * already, because XState notifies each observer on EVERY event that it processes and an\n * event that it ignores delivers the identical snapshot again. A computed atom answers\n * that by itself: `state.set(snapshot)` compares with `Object.is`, an identical reference\n * therefore propagates nothing, and this atom stays valid.\n *\n * `lastEmittedViews` held the previous emission for the equality gate, because a read of\n * `currentView` would have registered it as a dependency of the computation around the\n * call and `@xstate/store` exports no `untrack`. The `previous` parameter of a computed\n * atom is that same value, and the engine hands it in rather than tracking a read.\n */\n\n/**\n * Adds the view capability to an actor class.\n *\n * The ORDER of the composition does not matter. `currentView` and `currentRoute` are two\n * computed atoms over `state`, and neither reads the other, so the engine evaluates both\n * from one write in topological order.\n *\n * @param Base - The actor class to extend, normally `PlayerActor` or the result of\n *   another capability.\n */\nexport function withView<TMachine extends AnyStateMachine>(\n\tBase: PlayerConstructor<TMachine>,\n): PlayerConstructor<TMachine, Viewable> {\n\tclass ViewableActor extends Base implements Viewable {\n\t\t/**\n\t\t * The reactive atom of the current view spec. The atom derives the spec from the\n\t\t * `meta.view` metadata of the active state.\n\t\t *\n\t\t * It emits a **new object reference** for the view of a different state, and for a\n\t\t * change of a value of the context, which the spec reads under `/context`. A snapshot\n\t\t * that changes neither keeps the previous reference: an event that the machine\n\t\t * ignores, a transition inside a region that no outlet shows, or an assign that\n\t\t * writes the same values again. The viewKey of a new emission tells a provider\n\t\t * whether to seed its store again or to refresh `/context` in place, so the UI\n\t\t * mounts again only for a new viewKey.\n\t\t *\n\t\t * The `PlaySpec` of the emission carries the context of the machine in its composed\n\t\t * `state` field, under the read-only `/context` subtree. A spec therefore reads the\n\t\t * context, and also each URL param, through the ordinary state grammar\n\t\t * (`{ $state: \"/context/params/section\" }`). The context-projection module of\n\t\t * `@xmachines/play-view` holds the complete contract.\n\t\t *\n\t\t * The atom returns `null` when the current state has no `meta.view` metadata.\n\t\t *\n\t\t * Two states that each declare a `meta.view` emit two different `viewKey` values,\n\t\t * also when the two specs are one `typedSpec` constant: the key is the id of the\n\t\t * state node that declares the view. A transition between those two states therefore\n\t\t * emits again, and a provider seeds a new store, which removes the ephemeral state.\n\t\t * The ephemeral state survives a move between the children when the parent holds\n\t\t * the key: declare the view on the parent and none on the children, or declare\n\t\t * `outlets` on the parent, which keeps its id as the `viewKey` of the composed view.\n\t\t *\n\t\t * It is a COMPUTED atom over `state`, and not a written one. One write for each\n\t\t * transition therefore reaches the whole actor — `state.set(snapshot)` — and the\n\t\t * engine evaluates this atom and `currentRoute` in one propagation, in topological\n\t\t * order. A second write would flush a second time, and an observer that reads two\n\t\t * atoms would see the new state beside the old view in between.\n\t\t */\n\t\tpublic readonly currentView: ReadonlyAtom<PlaySpec | null> = createAtom(\n\t\t\t(previous): PlaySpec | null => {\n\t\t\t\t// `previous` is the value that this atom holds already. The engine hands it in,\n\t\t\t\t// so the gate below reads it without a `get()`, and it therefore registers\n\t\t\t\t// `currentView` as a dependency of nothing.\n\t\t\t\tconst lastEmittedView = previous ?? null;\n\n\t\t\t\ttry {\n\t\t\t\t\tconst view = deriveCurrentView(this.state.get());\n\n\t\t\t\t\t// Emit only after a real change: deriveCurrentView returns a fresh object on\n\t\t\t\t\t// each call, and the identity of the reference therefore tells nothing. The\n\t\t\t\t\t// derivation keeps `elements` and `viewParts` for one tree of views, so the\n\t\t\t\t\t// gate compares the top-level fields and the context one level deep. A deep\n\t\t\t\t\t// equality test is deliberately NOT here: it sees nothing inside a Map or a\n\t\t\t\t\t// Set, and it therefore stops a real change, and it recurses without an end\n\t\t\t\t\t// on a cyclic prop.\n\t\t\t\t\t//\n\t\t\t\t\t// A return of `lastEmittedView` compares equal under `Object.is`, so the atom\n\t\t\t\t\t// notifies no subscriber and the propagation stops here.\n\t\t\t\t\treturn reuseComposedState(lastEmittedView, view);\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// The derivation runs inside the `set` of `state`, which runs inside the XState\n\t\t\t\t\t// subscription. A throw that leaves this function therefore leaves that `set`\n\t\t\t\t\t// and breaks the transition for every other observer of the actor. Report it,\n\t\t\t\t\t// and keep the last valid view.\n\t\t\t\t\t//\n\t\t\t\t\t// The derivation runs inside the `set` of `state`, and the engine TRACKS every\n\t\t\t\t\t// atom that this function reads — the handler of the host included. A report\n\t\t\t\t\t// from HERE therefore made whatever that handler reads a dependency of this\n\t\t\t\t\t// atom, and an unrelated write of it re-derived and reported again: three\n\t\t\t\t\t// reports for one failure. The microtask leaves the evaluation, so the handler\n\t\t\t\t\t// reads what it likes and this atom depends on none of it.\n\t\t\t\t\t//\n\t\t\t\t\t// It leaves the `set` as well, which is what the comment below already needed:\n\t\t\t\t\t// a throw from the handler lands on the global handler of the runtime, and it\n\t\t\t\t\t// breaks the transition for no other observer of the actor.\n\t\t\t\t\tconst onError = this.hooks.onError;\n\t\t\t\t\tif (onError) {\n\t\t\t\t\t\tconst reported = toError(error);\n\t\t\t\t\t\tqueueMicrotask(() => {\n\t\t\t\t\t\t\tonError(this, reported);\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\treturn lastEmittedView;\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\t}\n\n\treturn ViewableActor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,SACf,MACwC;CACxC,MAAM,sBAAsB,KAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCpD,cAA6D,YAC3D,aAA8B;GAI9B,MAAM,kBAAkB,YAAY;GAEpC,IAAI;IACH,MAAM,OAAO,kBAAkB,KAAK,MAAM,IAAI,CAAC;IAY/C,OAAO,mBAAmB,iBAAiB,IAAI;GAChD,SAAS,OAAO;IAgBf,MAAM,UAAU,KAAK,MAAM;IAC3B,IAAI,SAAS;KACZ,MAAM,WAAW,QAAQ,KAAK;KAC9B,qBAAqB;MACpB,QAAQ,MAAM,QAAQ;KACvB,CAAC;IACF;IACA,OAAO;GACR;EACD,CACD;CACD;CAEA,OAAO;AACR"}