@xmachines/play-xstate 3.0.0 → 5.0.0

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":"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"}
+{"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,40 +1,6 @@
 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;
+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.
  *
@@ -46,7 +12,7 @@ export declare const activeStateMeta: (snapshot: AnyMachineSnapshot) => Record<s
  * - 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
@@ -54,7 +20,15 @@ export declare const activeStateMeta: (snapshot: AnyMachineSnapshot) => Record<s
  * 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;AAOjD;;;;;;;;;;;;;;;;;;;;;;;;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;AAEF;;;;;;;;;;;;;;;;;;;;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

@@ -1,82 +1,8 @@
 import { MissingRouteParamError } from "../errors.js";
 import { deriveRoute } from "./derive-route.js";
 import { buildRouteUrl } from "./build-url.js";
-/**
- * Collects the `meta` object of the active state nodes of a SINGLE branch, from the
- * root to a leaf. The key of each entry is the state id, and the order is the
- * ancestors first. {@link deriveRoute} folds this shape.
- *
- * `snapshot.getMeta()` returns a FLAT record of the meta object of every active
- * state. For a machine that is not parallel, that record is one chain of ancestors
- * already. For a PARALLEL machine, it mixes the entries of every active region. A
- * blind fold therefore joins a relative route of one region to an absolute route of
- * a sibling region, and the URL belongs to the tree of neither region. The flat
- * record also cannot go back into a hierarchy: when a state declares an explicit
- * `id`, for example a child with `id: "dashboard-overview"` under `id: "dashboard"`,
- * the meta keys are those ids, and they carry no information about the ancestry.
- *
- * Therefore this function walks `snapshot.value`, which holds the real hierarchy of
- * the active states by the state key, against the node tree of the machine. It
- * follows the FIRST active child at each level. This gives one deterministic branch,
- * which matches the historical behavior of "the first that it finds" for a parallel
- * machine. It also works with an explicit id, because each node carries its own `id`
- * and its own `meta`.
- *
- * The function returns `null` when the snapshot exposes no machine and no value to
- * walk. This is a defensive measure, because a real XState snapshot always exposes
- * them. The caller then uses `getMeta()`, as before.
- */
-export const firstActiveBranchMeta = (snapshot) => {
-    const root = snapshot.machine?.root;
-    if (!root)
-        return null;
-    const ordered = {};
-    let node = root;
-    let value = snapshot.value;
-    while (node) {
-        if (node.meta && typeof node.meta === "object") {
-            ordered[node.id] = node.meta; // nosemgrep: gitlab.eslint.detect-object-injection
-        }
-        // Find the key of the active child at this level. A string value is the name of an
-        // atomic active leaf. An object value is a compound node, with one key, or a
-        // parallel node, with many keys: take the first key, for one deterministic
-        // branch.
-        let key;
-        if (typeof value === "string") {
-            key = value;
-        }
-        else if (value && typeof value === "object") {
-            key = Object.keys(value)[0];
-        }
-        if (key === undefined)
-            break;
-        const child = node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection
-        if (!child)
-            break;
-        value =
-            typeof value === "object" && value !== null
-                ? value[key] // nosemgrep: gitlab.eslint.detect-object-injection
-                : {};
-        node = child;
-    }
-    return ordered;
-};
-/**
- * Resolves the meta record that the route derivation and the view derivation fold:
- * the single active branch that {@link firstActiveBranchMeta} walks, which is
- * correct for a parallel machine and for an explicit id, or the flat `getMeta()`
- * record when the snapshot has no machine tree to walk. `deriveCurrentRoute` and
- * `deriveCurrentView` share this function. Therefore the two sides cannot move apart
- * on the selection of the branch, and they cannot move apart on their tolerance of a
- * degenerate snapshot.
- */
-export const activeStateMeta = (snapshot) => {
-    if (!snapshot || typeof snapshot.getMeta !== "function") {
-        return null;
-    }
-    const meta = firstActiveBranchMeta(snapshot) ?? snapshot.getMeta();
-    return meta && typeof meta === "object" ? meta : null;
-};
+import { activeStateMeta } from "../state-meta.js";
+export { activeStateMeta, firstActiveBranchMeta } from "../state-meta.js";
 /**
  * Derives the current URL of the actor from the state metadata and the context.
  *
@@ -88,7 +14,7 @@ export const activeStateMeta = (snapshot) => {
  * - 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
@@ -96,9 +22,17 @@ export const activeStateMeta = (snapshot) => {
  * 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;
@@ -108,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
@@ -117,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":"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"}
+{"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,IAavF,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);
@@ -52,6 +52,17 @@ export const deriveInitialRoute = (machine, input) => {
         // that snapshot also has no route metadata. Report "no initial route to derive".
         return null;
     }
-    return deriveCurrentRoute(initialSnapshot);
+    // The SAME failure, reported the other way. XState 5.32 threw out of
+    // `initialTransition` for a context factory that throws, and 5.33 returns an
+    // error-status snapshot instead, with the reason on `snapshot.error`. The catch above
+    // therefore stopped firing, and a machine whose context never built derived the route
+    // of its initial state — `/login` for a factory that threw — which a bridge then took
+    // as the place of the actor.
+    //
+    // Both shapes mean the same thing, so both answer the same way. The status is the
+    // question, and it holds whichever way a later release reports the failure.
+    if (initialSnapshot.status === "error")
+        return null;
+    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,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/derive-route.d.ts

@@ -1,3 +1,4 @@
+import type { PlayRouteEvent, RouteData } from "@xmachines/play-router";
 import type { RouteMetadata } from "./types.js";
 /**
  * Derives the route from the metadata of an XState state
@@ -18,7 +19,7 @@ import type { RouteMetadata } from "./types.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({
@@ -101,6 +102,84 @@ export declare const deriveRoute: (stateMeta: Record<string, unknown>) => string
  * @throws {InvalidRouteMetadataError} When the form of the route is invalid
  */
 export declare const normalizeRoute: (route: RouteMetadata, source?: string) => string;
+/**
+ * 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 declare const routeReenter: (route: RouteMetadata | undefined) => boolean;
+/**
+ * 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 declare const routeData: (route: RouteMetadata | undefined, args: {
+    context: unknown;
+    event: PlayRouteEvent;
+}) => RouteData | undefined;
+/**
+ * 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 declare const routeHandler: (route: RouteMetadata | undefined, source?: string) => "root" | "local" | "both";
 /**
  * Tells you if the route path is absolute
  *
@@ -113,7 +192,7 @@ export declare const normalizeRoute: (route: RouteMetadata, source?: string) =>
  *
  * @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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,GAAG,IAuBzE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,aAAa,EAAE,eAAsB,KAAG,MAW7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAE9C,CAAC"}
+{"version":3,"file":"derive-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,GAAG,IAuBzE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,aAAa,EAAE,eAAsB,KAAG,MAW7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,aAAa,GAAG,SAAS,KAAG,OACuB,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS,GACrB,OAAO,aAAa,GAAG,SAAS,EAChC,MAAM;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,KAC/C,SAAS,GAAG,SAOd,CAAC;AAKF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GACxB,OAAO,aAAa,GAAG,SAAS,EAChC,eAAqC,KACnC,MAAM,GAAG,OAAO,GAAG,MAUrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAE9C,CAAC"}