@xmachines/play-xstate 3.0.0 → 5.0.0

package/dist/routing/derive-route.js

@@ -1,4 +1,4 @@
-import { InvalidRouteMetadataError } from "../errors.js";
+import { InvalidRouteHandlerError, InvalidRouteMetadataError } from "../errors.js";
 /**
  * Derives the route from the metadata of an XState state
  *
@@ -18,7 +18,7 @@ import { InvalidRouteMetadataError } from "../errors.js";
  * @example
  * The basic read of a route
  * ```typescript
- * import { deriveRoute } from "@xmachines/play-xstate";
+ * import { deriveRoute } from "@xmachines/play-xstate/routing";
  * import { setup } from "xstate";
  *
  * const machine = setup({}).createMachine({
@@ -135,6 +135,100 @@ export const normalizeRoute = (route, source = "deriveRoute") => {
     }
     throw new InvalidRouteMetadataError(route, source);
 };
+/**
+ * Reads the `reenter` flag of the route metadata.
+ *
+ * The string form of the metadata declares no flag, and the object form declares the
+ * flag only when it wants one. Both therefore give `false`, which is the default of
+ * XState for a transition. A state without a route gives `false` too, so the caller
+ * needs no test of its own for that case.
+ *
+ * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+ * every call site and throws `InvalidRouteMetadataError` on a malformed value.
+ *
+ * @param route - The route metadata: a string, an object with a `path` property, or
+ *   `undefined` for a state that declares no route
+ * @returns The declared flag, or `false` where the metadata declares none
+ *
+ * @example
+ * ```typescript
+ * routeReenter("/dashboard");                       // false
+ * routeReenter({ path: "/dashboard" });             // false
+ * routeReenter({ path: "/dashboard", reenter: true }); // true
+ * routeReenter(undefined);                          // false
+ * ```
+ */
+export const routeReenter = (route) => typeof route === "object" && route !== null && route.reenter === true;
+/**
+ * Reads the extra data that a route declares, resolved for one event.
+ *
+ * The field holds a literal value or a function of `{ context, event }`, which is the
+ * `WithDynamicParams` shape of XState. This function collapses the two into the value.
+ *
+ * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+ * every call site and throws `InvalidRouteMetadataError` on a malformed value.
+ *
+ * @param route - The route metadata: a string, an object with a `path` property, or
+ *   `undefined` for a state that declares no route
+ * @param args - The context of the machine and the `play.route` event that asks for the
+ *   route. The resolver reads them.
+ * @returns The data, or `undefined` where the route declares none
+ *
+ * @example
+ * ```typescript
+ * routeData({ path: "/a", data: { titleKey: "a" } }, args);        // { titleKey: "a" }
+ * routeData({ path: "/a", data: ({ event }) => ({ to: event.to }) }, args);
+ * routeData("/a", args);                                          // undefined
+ * ```
+ */
+export const routeData = (route, args) => {
+    if (typeof route !== "object" || route === null)
+        return undefined;
+    const data = route.data;
+    if (data === undefined)
+        return undefined;
+    return typeof data === "function" ? data(args) : data;
+};
+/** The placements that a `meta.route` object can declare. */
+const ROUTE_HANDLERS = new Set(["root", "local", "both"]);
+/**
+ * Reads the placement of the generated `play.route` transition.
+ *
+ * `"root"` is the default, and it is the placement of XState: every route transition
+ * sits on the root of the machine. `"local"` moves the transition to the parent of the
+ * state, and `"both"` puts one transition in each place.
+ *
+ * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+ * every call site and throws `InvalidRouteMetadataError` on a malformed value.
+ *
+ * @param route - The route metadata: a string, an object with a `path` property, or
+ *   `undefined` for a state that declares no route
+ * @param source - The `PlayError.scope` value to report for an unknown placement
+ * @returns The declared placement, and `"root"` where the metadata declares none
+ * @throws {InvalidRouteHandlerError} When the object declares a `handler` that is not
+ *   `"root"`, `"local"`, or `"both"`. A typo would otherwise fall back to a placement
+ *   that the author did not ask for, and it would change which states a route reaches.
+ *
+ * @example
+ * ```typescript
+ * routeHandler("/dashboard");                             // "root"
+ * routeHandler({ path: "/dashboard" });                   // "root"
+ * routeHandler({ path: "/dashboard", handler: "local" }); // "local"
+ * routeHandler({ path: "/dashboard", handler: "both" });  // "both"
+ * routeHandler({ path: "/dashboard", handler: "locale" }); // throws
+ * ```
+ */
+export const routeHandler = (route, source = "formatPlayRouteTransitions") => {
+    if (typeof route !== "object" || route === null)
+        return "root";
+    const handler = route.handler;
+    if (handler === undefined)
+        return "root";
+    if (typeof handler !== "string" || !ROUTE_HANDLERS.has(handler)) {
+        throw new InvalidRouteHandlerError(handler, source);
+    }
+    return handler;
+};
 /**
  * Tells you if the route path is absolute
  *
@@ -147,7 +241,7 @@ export const normalizeRoute = (route, source = "deriveRoute") => {
  *
  * @example
  * ```typescript
- * import { isAbsoluteRoute } from "@xmachines/play-xstate";
+ * import { isAbsoluteRoute } from "@xmachines/play-xstate/routing";
  *
  * console.log(isAbsoluteRoute("/dashboard")); // true
  * console.log(isAbsoluteRoute("settings"));   // false

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

@@ -1 +1 @@
-{"version":3,"file":"derive-route.js","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAkC,EAAiB,EAAE;IAChF,kFAAkF;IAClF,+EAA+E;IAC/E,8EAA8E;IAC9E,iFAAiF;IACjF,kFAAkF;IAClF,qBAAqB;IACrB,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QACxD,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,SAAS;QAEhD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAsB,CAAC,CAAC;QAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QACxD,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,QAAQ,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,GAAW,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC3E,QAAQ,GAAG,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC;QAC/B,CAAC;IACF,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAoB,EAAE,MAAM,GAAG,aAAa,EAAU,EAAE;IACtF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IAED,uCAAuC;IACvC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3D,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,MAAM,IAAI,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAW,EAAE;IACxD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC,CAAC"}
+{"version":3,"file":"derive-route.js","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"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"}

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

@@ -16,13 +16,19 @@ export type RouteStateNode = {
     meta?: {
         /**
          * The template of the URL path: the string form, for example
-         * `"/profile/:username"`, or the object form (`{ path, title }`). Both match
-         * {@link RouteMetadata}.
+         * `"/profile/:username"`, or the object form (`{ path, reenter, title }`). Both
+         * match {@link RouteMetadata}. The object form declares the `reenter` flag of the
+         * generated transition, and that flag defaults to `false`.
          */
         route?: RouteMetadata;
     };
     /** The nested child states. The function walks them for each further route declaration. */
     states?: Record<string, RouteStateNode>;
+    /**
+     * The event handlers of this state. The function reads them where a child asks for a
+     * local `play.route` handler, so that the transitions of the user survive the merge.
+     */
+    on?: Record<string, unknown> | undefined;
     [key: string]: unknown;
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE;QACN;;;;WAIG;QACH,KAAK,CAAC,EAAE,aAAa,CAAC;KACtB,CAAC;IACF,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAaF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,kBAAkB,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAwH5F"}
+{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAgB7D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE;QACN;;;;;WAKG;QACH,KAAK,CAAC,EAAE,aAAa,CAAC;KACtB,CAAC;IACF,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAiHF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,kBAAkB,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CA2L5F"}

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

@@ -1,7 +1,7 @@
 import { assign } from "xstate";
-import { shallowEqualExcept } from "@xmachines/play-actor";
+import { shallowEqualExcept } from "@xmachines/play";
 import { MissingStateIdError } from "../errors.js";
-import { normalizeRoute } from "./derive-route.js";
+import { normalizeRoute, routeData, routeHandler, routeReenter } from "./derive-route.js";
 /**
  * Reuses the previous container of the params and of the query when the new
  * container is equal to it in a shallow comparison.
@@ -13,7 +13,78 @@ import { normalizeRoute } from "./derive-route.js";
  * values, such as a popstate event to the current URL or a second send from the
  * code, emits the view again for nothing.
  */
-const keepEqualContainer = (prev, next) => (prev !== undefined && shallowEqualExcept(prev, next) ? prev : next);
+const keepEqualContainer = (prev, next) => prev !== undefined && shallowEqualExcept(prev, next) ? prev : next;
+/**
+ * Normalizes the `play.route` entry of an `on` record into an array.
+ *
+ * A user writes one transition or an array of them, and XState accepts both forms.
+ * The merge therefore needs one form.
+ */
+const asTransitionArray = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+/**
+ * True when the route declares a `data` field.
+ *
+ * The assigner below reads this ONE time, when it builds the action, and not on every
+ * 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.
+ *
+ * Every generated transition gets its OWN action object, from this one factory. The
+ * root transition and the local transition of the same state therefore hold no shared
+ * object, and the body of the assign lives in one place.
+ *
+ * A route that declares no `data` gets an assign with no `data` KEY. A key that writes
+ * the previous value back is not the same thing: `assign` puts an own property on the
+ * context for each key that it carries, so a machine that declares no `data` field
+ * received one with no value, and the `/context` projection of every view carried it.
+ */
+const makeRouteAssign = (routeMeta) => {
+    if (!declaresRouteData(routeMeta))
+        return assign({ params: assignParams, query: assignQuery });
+    return assign({
+        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 }) => {
+            const previous = context.data;
+            const next = routeData(routeMeta, { context, event });
+            return next === undefined ? previous : keepEqualContainer(previous, next);
+        },
+    });
+};
+/**
+ * Rebuilds one state node with its local `play.route` transitions in place.
+ *
+ * The transitions of the user stay, and they come AFTER the generated ones: XState
+ * reads the candidates in their order, so a generated guard wins when it matches, and
+ * the transitions of the user are the fallback. This is the rule that the root of the
+ * machine follows too.
+ *
+ * The function writes into NO object of the caller. It returns a new node.
+ */
+const withLocalTransitions = (node, states, transitions) => {
+    if (transitions.length === 0)
+        return { ...node, states };
+    const existingOn = node.on ?? {};
+    return {
+        ...node,
+        states,
+        on: {
+            ...existingOn,
+            "play.route": [...transitions, ...asTransitionArray(existingOn["play.route"])],
+        },
+    };
+};
 /**
  * Makes the play.route transitions from the declarative route configs
  *
@@ -49,7 +120,14 @@ const keepEqualContainer = (prev, next) => (prev !== undefined && shallowEqualEx
 export function formatPlayRouteTransitions(machineConfig) {
     const routeTransitions = [];
     const collectRoutes = (states, parentPath = "") => {
-        Object.entries(states).forEach(([key, stateConfig]) => {
+        const localTransitions = [];
+        let changed = false;
+        // The walk collects PAIRS, and `Object.fromEntries` builds the record at the end.
+        // A write through `nextStates[key]` would reach the `__proto__` setter of
+        // `Object.prototype` for a state whose key is `"__proto__"`, and it would set the
+        // prototype of the record instead of adding a state to it. `fromEntries` defines
+        // an own property for every key, so no key of a config is special.
+        const nextEntries = Object.entries(states).map(([key, stateConfig]) => {
             const node = stateConfig;
             // Build the complete path of the keys, from the root, for the target of the
             // transition. An XState target uses the hierarchy of the state keys, and not the
@@ -59,80 +137,134 @@ export function formatPlayRouteTransitions(machineConfig) {
             // InvalidRouteMetadataError. It then normalizes the value into the string of the
             // path. An empty path marks the state as a state without a route, in the string form
             // ("") and also in the object form ({ path: "" }).
-            const routePath = node.meta?.route === undefined
+            const routeMeta = node.meta?.route;
+            const routePath = routeMeta === undefined
                 ? ""
-                : normalizeRoute(node.meta.route, "formatPlayRouteTransitions");
+                : normalizeRoute(routeMeta, "formatPlayRouteTransitions");
+            // Check the placement for EVERY declared route, and not only for one that
+            // produces a transition. A state with an empty path generates none, and a typo
+            // in its `handler` would otherwise wait silently until somebody gives the state
+            // a path.
+            const placement = routeHandler(routeMeta);
             if (routePath && !node.id) {
                 throw new MissingStateIdError(key, routePath);
             }
             if (routePath && node.id) {
-                const transition = {
-                    target: `.${statePath}`,
-                    guard: ({ event }) => event.to === `#${node.id}`,
-                    reenter: true,
-                    actions: assign({
-                        params: ({ context, event }) => keepEqualContainer(context.params, event.params || {}),
-                        query: ({ context, event }) => keepEqualContainer(context.query, event.query || {}),
-                    }),
-                };
-                routeTransitions.push(transition);
+                // The declaration of the state decides the flag, and the default is `false`,
+                // which is the default of XState. The flag spares the DOMAIN of the
+                // transition: under the root placement it spares the root alone, and each
+                // ancestor between the root and the target still runs its exit and its entry
+                // actions. `handler` is the field that spares those.
+                const reenter = routeReenter(routeMeta);
+                // A parent path of "" means that the parent IS the root. The root transition of
+                // such a state already targets `.${key}`, so it IS the local transition, and
+                // every placement therefore collapses to the root transition.
+                const parentIsRoot = parentPath === "";
+                const wantsRoot = parentIsRoot || placement === "root" || placement === "both";
+                const wantsLocal = !parentIsRoot && (placement === "local" || placement === "both");
+                // The ROOT transition. XState installs every route transition on the root, and
+                // this function keeps that placement as its default: a route from ANY state
+                // therefore reaches this state.
+                if (wantsRoot) {
+                    routeTransitions.push({
+                        target: `.${statePath}`,
+                        guard: ({ event }) => event.to === `#${node.id}`,
+                        reenter,
+                        actions: makeRouteAssign(routeMeta),
+                    });
+                }
+                // The LOCAL transition. It sits on the PARENT of this state, and it targets
+                // this state relatively. XState offers the transitions of the deepest active
+                // state node first, so this transition answers the event while the parent is
+                // active, and the parent therefore runs its exit and its entry actions NOT
+                // again.
+                //
+                // Under `"local"` this is the ONLY transition of the state, so a route that
+                // arrives while the parent is inactive matches nothing and the actor does not
+                // move. That is the declared intent of `"local"`: it scopes the route.
+                if (wantsLocal) {
+                    localTransitions.push({
+                        target: `.${key}`,
+                        guard: ({ event }) => event.to === `#${node.id}`,
+                        reenter,
+                        actions: makeRouteAssign(routeMeta),
+                    });
+                }
             }
+            let nextNode = stateConfig;
             if (node.states) {
-                collectRoutes(node.states, statePath);
+                const child = collectRoutes(node.states, statePath);
+                if (child.changed || child.localTransitions.length > 0) {
+                    // Rebuild this node, and do NOT write into the config of the caller. The
+                    // function returns a new config, and the original must stay untouched.
+                    nextNode = withLocalTransitions(node, child.states, child.localTransitions);
+                    changed = true;
+                }
             }
+            return [key, nextNode];
         });
+        return { states: Object.fromEntries(nextEntries), localTransitions, changed };
     };
     const machineStates = machineConfig.states;
-    if (machineStates) {
-        collectRoutes(machineStates);
-    }
+    // `states` comes back rebuilt where a descendant asked for a local handler, and it
+    // comes back as the original record where none did. The walk returns no local
+    // transition for the top level: the parent of a top-level state IS the root, and the
+    // root transition of such a state is already local to its parent.
+    const walk = machineStates ? collectRoutes(machineStates) : undefined;
     // The ROOT of the machine can declare a route of its own, which a chart does when
     // its whole document owns a path prefix, for example `/doc` with `/doc/a` under it.
     // `collectRoutes` walks `states` only, so the root got no transition, and a URL for
     // the root moved the machine nowhere: a press on BACK to `/doc` left the actor on
     // the child it already held, and the URL and the actor diverged.
     //
-    // The transition targets the root by its id, and it re-enters. XState therefore
-    // enters the `initial` child of the root, which is the state that a URL for the
-    // root means.
+    // The transition targets the root by its ID. XState enters the `initial` child of
+    // an ID target, which is the state that a URL for the root means. The `reenter`
+    // flag does NOT decide that: a route to the root lands on the initial child of the
+    // root under `false` and under `true`. The flag decides only whether the root runs
+    // its own `exit` and `entry` actions again. The root therefore reads the flag from
+    // its `meta.route` like every other state, and it defaults to `false`.
     const rootNode = machineConfig;
-    const rootRoutePath = rootNode.meta?.route === undefined
+    const rootRouteMeta = rootNode.meta?.route;
+    const rootRoutePath = rootRouteMeta === undefined
         ? ""
-        : normalizeRoute(rootNode.meta.route, "formatPlayRouteTransitions");
+        : normalizeRoute(rootRouteMeta, "formatPlayRouteTransitions");
+    // The placement of the ROOT has no meaning, because the root has no parent to hold a
+    // local transition. A value that the routing layer does not know must still fail
+    // here, so that one typo behaves the same wherever an author writes it.
+    routeHandler(rootRouteMeta);
     if (rootRoutePath) {
         if (!rootNode.id)
             throw new MissingStateIdError("(the root of the machine)", rootRoutePath);
         routeTransitions.push({
             target: `#${rootNode.id}`,
             guard: ({ event }) => event.to === `#${rootNode.id}`,
-            reenter: true,
-            actions: assign({
-                params: ({ context, event }) => keepEqualContainer(context.params, event.params || {}),
-                query: ({ context, event }) => keepEqualContainer(context.query, event.query || {}),
-            }),
+            reenter: routeReenter(rootRouteMeta),
+            actions: makeRouteAssign(rootRouteMeta),
         });
     }
+    const rebuiltStates = walk?.changed === true;
+    // A machine whose every routable state declares `handler: "local"` produces NO root
+    // transition, and its transitions live on the rebuilt states alone. The rebuilt
+    // states must therefore survive on their own, and not only beside a root
+    // transition.
+    if (routeTransitions.length === 0 && !rebuiltStates) {
+        return machineConfig;
+    }
+    const next = {
+        ...machineConfig,
+        ...(rebuiltStates ? { states: walk?.states } : {}),
+    };
     if (routeTransitions.length > 0) {
         const existingOn = machineConfig.on || {};
         // Keep each play.route transition of the user, for example a 404 fallback that a
         // person wrote, and append those transitions AFTER the generated ones: XState
         // evaluates the candidate transitions in their order. Therefore a generated guard
         // wins when it matches, and the transitions of the user are the fallback.
-        const userRouteTransitions = existingOn["play.route"];
-        const normalizedUserTransitions = userRouteTransitions === undefined
-            ? []
-            : Array.isArray(userRouteTransitions)
-                ? userRouteTransitions
-                : [userRouteTransitions];
-        const updatedOn = {
+        next["on"] = {
             ...existingOn,
-            "play.route": [...routeTransitions, ...normalizedUserTransitions],
-        };
-        return {
-            ...machineConfig,
-            on: updatedOn,
+            "play.route": [...routeTransitions, ...asTransitionArray(existingOn["play.route"])],
         };
     }
-    return machineConfig;
+    return next;
 }
 //# sourceMappingURL=format-play-route-transitions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"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"}

package/dist/routing/index.d.ts

@@ -12,5 +12,5 @@ export { deriveInitialRoute } from "./derive-initial-route.js";
 export { buildRouteUrl } from "./build-url.js";
 export { formatPlayRouteTransitions } from "./format-play-route-transitions.js";
 export type { RouteMachineConfig, RouteStateNode } from "./format-play-route-transitions.js";
-export type { RouteContext, RouteObject, RouteMetadata } from "./types.js";
+export type { RouteContext, RouteObject, RouteMetadata, RouteData, RouteDataResolver, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/routing/types.d.ts

@@ -1,8 +1,12 @@
-export interface RouteObject {
-    path: string;
-    [key: string]: unknown;
-}
-export type RouteMetadata = string | RouteObject;
+/**
+ * `RouteObject` and `RouteMetadata` have ONE definition, and it lives in
+ * `@xmachines/play-router`. That package owns the routing protocol, and this package
+ * consumes it. A second definition here would be a copy that drifts: a field added to
+ * one of them would leave the other behind, and nothing would fail.
+ *
+ * The re-export keeps the import path of every consumer of this package unchanged.
+ */
+export type { RouteObject, RouteMetadata, RouteData, RouteDataResolver, } from "@xmachines/play-router";
 /**
  * The context of the route construction, from the machine context.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EACX,WAAW,EACX,aAAa,EACb,SAAS,EACT,iBAAiB,GACjB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd"}

package/dist/state-meta.d.ts

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

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

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