@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/player-actor.js.map

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

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

@@ -1,24 +1,27 @@
 import type { RouteContext } from "./types.js";
 /**
- * Build a full URL from a route template and the actor's context.
+ * Builds a complete URL from a route template and the context of the actor.
  *
- * Substitutes `:param` and `:param?` placeholders from `context.params`,
- * then appends query params and hash fragments.
+ * The function replaces each `:param` placeholder and each `:param?` placeholder
+ * with a value of `context.params`. It then appends the query params and the hash
+ * fragment.
  *
- * All parameter values must be in `context.params`. Flat context fields are not
- * inspected — this is intentional so misspelled placeholders produce a compile-time
- * error rather than silently resolving to `undefined`.
+ * Every parameter value must be in `context.params`. The function reads no flat
+ * context field, and this is deliberate: a placeholder with a spelling error
+ * therefore gives a compile-time error, and it does not resolve to `undefined` in
+ * silence.
  *
- * @param routeTemplate - Route path template, e.g. `"/profile/:userId"` or
- *   `"/settings/:section?"`.
- * @param context - Actor context object. Route parameters must be in `context.params`;
- *   flat context fields are not inspected. A missing `query` field builds a
- *   query-less URL, exactly like `query: {}`.
- * @returns The fully resolved URL string.
+ * @param routeTemplate - The template of the route path, for example
+ *   `"/profile/:userId"` or `"/settings/:section?"`.
+ * @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: {}`.
+ * @returns The complete URL string.
  *
- * @throws {MissingRouteParamError} When a **required** `:param` placeholder has no
- *   matching value in context. Optional parameters (`:param?`) are silently omitted
- *   when missing. Import the class from `@xmachines/play-xstate/errors`.
+ * @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`.
  *
  * @example
  * ```typescript
@@ -26,7 +29,7 @@ import type { RouteContext } from "./types.js";
  * // → "/user/123?tab=profile#top"
  *
  * buildRouteUrl("/settings/:section?", { params: {}, query: {} });
- * // → "/settings"  (optional param omitted, no query string)
+ * // → "/settings"  (the optional param is absent, and there is no query string)
  * ```
  */
 export declare const buildRouteUrl: (routeTemplate: string, context?: RouteContext) => string;

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

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

package/dist/routing/build-url.js

@@ -1,25 +1,28 @@
 import { isAbsoluteRoute } from "./derive-route.js";
 import { MissingRouteParamError } from "../errors.js";
 /**
- * Build a full URL from a route template and the actor's context.
+ * Builds a complete URL from a route template and the context of the actor.
  *
- * Substitutes `:param` and `:param?` placeholders from `context.params`,
- * then appends query params and hash fragments.
+ * The function replaces each `:param` placeholder and each `:param?` placeholder
+ * with a value of `context.params`. It then appends the query params and the hash
+ * fragment.
  *
- * All parameter values must be in `context.params`. Flat context fields are not
- * inspected — this is intentional so misspelled placeholders produce a compile-time
- * error rather than silently resolving to `undefined`.
+ * Every parameter value must be in `context.params`. The function reads no flat
+ * context field, and this is deliberate: a placeholder with a spelling error
+ * therefore gives a compile-time error, and it does not resolve to `undefined` in
+ * silence.
  *
- * @param routeTemplate - Route path template, e.g. `"/profile/:userId"` or
- *   `"/settings/:section?"`.
- * @param context - Actor context object. Route parameters must be in `context.params`;
- *   flat context fields are not inspected. A missing `query` field builds a
- *   query-less URL, exactly like `query: {}`.
- * @returns The fully resolved URL string.
+ * @param routeTemplate - The template of the route path, for example
+ *   `"/profile/:userId"` or `"/settings/:section?"`.
+ * @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: {}`.
+ * @returns The complete URL string.
  *
- * @throws {MissingRouteParamError} When a **required** `:param` placeholder has no
- *   matching value in context. Optional parameters (`:param?`) are silently omitted
- *   when missing. Import the class from `@xmachines/play-xstate/errors`.
+ * @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`.
  *
  * @example
  * ```typescript
@@ -27,26 +30,26 @@ import { MissingRouteParamError } from "../errors.js";
  * // → "/user/123?tab=profile#top"
  *
  * buildRouteUrl("/settings/:section?", { params: {}, query: {} });
- * // → "/settings"  (optional param omitted, no query string)
+ * // → "/settings"  (the optional param is absent, and there is no query string)
  * ```
  */
 export const buildRouteUrl = (routeTemplate, context = { query: {} }) => {
-    // A context without a `query` field builds a query-less URL, the same way a
-    // missing context does. The generated play.route transitions assign `query`
-    // on every navigation regardless of the initial context shape, so there is
-    // no query-loss here for a throw to prevent — machines that handle
-    // play.route by hand and want query forwarding must assign event.query to
-    // context themselves.
-    // Handle relative vs absolute paths
+    // 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.
+    // Therefore no query goes away here, and a throw prevents nothing. A machine that
+    // handles play.route itself and wants the query must assign event.query to its
+    // context itself.
+    // Handle a relative path and an absolute path
     const basePath = context.basePath || "";
     const isAbsolute = isAbsoluteRoute(routeTemplate);
-    // Build base URL
+    // Build the base URL
     let url = isAbsolute ? routeTemplate : joinPaths(basePath, routeTemplate);
-    // Replace :param with context values
+    // Replace each :param with a context value
     url = substituteParams(url, context);
-    // Append query params from context. The ubiquitous empty `query: {}` gets
-    // the key check so the per-recompute URLSearchParams allocation is only
-    // paid when there is something to serialize.
+    // 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.
     if (context.query && typeof context.query === "object") {
         const queryEntries = Object.entries(context.query);
         if (queryEntries.length > 0) {
@@ -57,75 +60,75 @@ export const buildRouteUrl = (routeTemplate, context = { query: {} }) => {
             }
         }
     }
-    // Append hash from context
+    // Append the hash of the context
     if (context.hash && typeof context.hash === "string") {
         url += `#${context.hash}`;
     }
     return url;
 };
 /**
- * Substitute `:param` placeholders with `encodeURIComponent`-escaped context
- * values.
+ * Replaces each `:param` placeholder with a context value, and it escapes that
+ * value with `encodeURIComponent`.
  *
- * Supports optional parameters with :param? syntax.
- * - Optional parameters without values are removed entirely (including the /)
- * - Required parameters without values log warnings
+ * 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
  *
- * Parameter lookup:
- * - Reads from context.params[param] exclusively. Flat context fields are not inspected.
+ * The lookup of a parameter:
+ * - The function reads context.params[param] only. It reads no flat context field.
  *
- * @param template - URL template with :param or :param? syntax
- * @param context - Context with parameter values (may have params field)
- * @returns URL with parameters substituted and double slashes cleaned
- * @throws {MissingRouteParamError} When a required route parameter is missing
+ * @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 parameters, handling optional syntax
+    // 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
-        // Parameter has a non-empty value - substitute it
-        // For optional params, treat empty string as "no value"
+        // 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));
         }
-        // Optional parameter without value (or empty string) - remove the segment
+        // An optional parameter without a value, or with an empty string: remove the segment
         if (optional === "?") {
             hasOptionalRemoval = true;
-            return ""; // Will leave // in path, cleaned up below
+            return ""; // This leaves // in the path. The code below removes it
         }
         throw new MissingRouteParamError(param, template);
     });
-    // Clean up double slashes
+    // Remove each double slash
     let cleaned = result.replace(/\/+/g, "/");
-    // Only remove trailing slash if we removed optional parameters
-    // (preserves trailing slash for required params, which indicates an error)
+    // 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);
     }
-    // Never return an empty path: a root-level template of only optional params
-    // (e.g. "/:section?") collapses to "" after the trailing-slash trim, which
-    // would produce invalid URLs like "" or "?tab=x". Normalize to "/".
+    // 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;
 };
 /**
- * Join base path and relative path
+ * Joins a base path and a relative path
  *
- * Ensures single slash between paths
+ * The function puts one slash between the two paths
  *
- * @param base - Base path
- * @param relative - Relative path
- * @returns Joined path
+ * @param base - The base path
+ * @param relative - The relative path
+ * @returns The joined path
  */
 const joinPaths = (base, relative) => {
-    // Remove trailing slash from base
+    // Remove the trailing slash of the base
     const normalizedBase = base.replace(/\/$/, "");
-    // Remove leading slash from relative
+    // Remove the first slash of the relative path
     const normalizedRelative = relative.replace(/^\//, "");
-    // Join with single slash
+    // Join the two paths with one slash
     return normalizedBase ? `${normalizedBase}/${normalizedRelative}` : `/${normalizedRelative}`;
 };
 //# sourceMappingURL=build-url.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,aAAqB,EACrB,UAAwB,EAAE,KAAK,EAAE,EAAE,EAAE,EAC5B,EAAE;IACX,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,mEAAmE;IACnE,0EAA0E;IAC1E,sBAAsB;IAEtB,oCAAoC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,UAAU,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;IAElD,iBAAiB;IACjB,IAAI,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE1E,qCAAqC;IACrC,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAErC,0EAA0E;IAC1E,wEAAwE;IACxE,6CAA6C;IAC7C,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,eAAe,CACjC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAqB,CAAC,CAChE,CAAC;YACF,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,WAAW,EAAE,CAAC;gBACjB,GAAG,IAAI,IAAI,WAAW,EAAE,CAAC;YAC1B,CAAC;QACF,CAAC;IACF,CAAC;IAED,2BAA2B;IAC3B,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtD,GAAG,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GAAG,CAAC,QAAgB,EAAE,OAAqB,EAAU,EAAE;IAC5E,+CAA+C;IAC/C,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAC/B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,mDAAmD;QAE1F,kDAAkD;QAClD,wDAAwD;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YAC3D,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,0EAA0E;QAC1E,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACtB,kBAAkB,GAAG,IAAI,CAAC;YAC1B,OAAO,EAAE,CAAC,CAAC,0CAA0C;QACtD,CAAC;QAED,MAAM,IAAI,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,0BAA0B;IAC1B,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE1C,+DAA+D;IAC/D,2EAA2E;IAC3E,IAAI,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,4EAA4E;IAC5E,2EAA2E;IAC3E,oEAAoE;IACpE,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,GAAG,GAAG,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;IAC5D,kCAAkC;IAClC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE/C,qCAAqC;IACrC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEvD,yBAAyB;IACzB,OAAO,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,kBAAkB,EAAE,CAAC;AAC9F,CAAC,CAAC"}
+{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"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"}

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

@@ -1,54 +1,60 @@
 import type { AnyMachineSnapshot } from "xstate";
 /**
- * Collect the `meta` of the active state nodes along a SINGLE root-to-leaf branch,
- * keyed by state id and ordered ancestors-first — the shape {@link deriveRoute} folds.
+ * 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 every active state's meta. For a
- * non-parallel machine that record is already a single ancestor chain, but for a
- * PARALLEL machine it interleaves entries from every active region, so folding it
- * blindly would concatenate a relative route from one region onto an absolute route
- * from a sibling region (a URL belonging to neither region's tree). The flat record
- * also cannot be re-ordered back into a hierarchy: when states declare an explicit
- * `id` (e.g. a child `id: "dashboard-overview"` under `id: "dashboard"`), the meta
- * keys are those ids and carry no ancestry information.
+ * `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.
  *
- * We therefore walk `snapshot.value` (which encodes the true active-state hierarchy
- * by state key) against the machine's node tree, following the FIRST active child at
- * each level. This yields one deterministic branch — matching the historical
- * first-found behaviour for parallel machines — and works regardless of explicit ids
- * because each node carries its own `id` and `meta`.
+ * 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`.
  *
- * Falls back to `null` when the snapshot does not expose a navigable machine/value
- * (defensive — real XState snapshots always do); callers then use `getMeta()` as before.
+ * 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;
 /**
- * Resolve the meta record route and view derivation fold: the single active
- * branch {@link firstActiveBranchMeta} walks (correct for parallel machines
- * and explicit ids), or the flat `getMeta()` record when the snapshot lacks a
- * navigable machine tree. Shared by `deriveCurrentRoute` and
- * `deriveCurrentView` so the two sides cannot drift apart on branch selection
- * or on tolerating degenerate snapshots.
+ * 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;
 /**
- * Derive the actor's current URL from state metadata and context.
+ * Derives the current URL of the actor from the state metadata and the context.
  *
- * Resolves the route template from the current state's `meta.route` and substitutes
- * any `:param` placeholders from `context.params` (preferred) or flat `context`.
+ * The function resolves the route template from the `meta.route` field of the
+ * current state. It then replaces each `:param` placeholder with a value of
+ * `context.params`, which it prefers, or of the flat `context` object.
  *
- * Returns `null` — rather than throwing — when:
- * - The snapshot has no route metadata (non-routable state)
- * - A required route parameter is absent from context (`MissingRouteParamError`)
+ * The function returns `null`, and it throws no error, in two cases:
+ * - 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` return on missing params is intentional: it keeps the computed signal
- * stable during transient states (e.g. mid-transition before context is fully updated,
- * or after logout when `context.username` is `null` but the router bridge has not yet
- * synced to the new state). The router bridge and URL bar are updated on the next
- * stable snapshot once context is complete.
+ * The `null` value for an absent param is deliberate: the computed signal 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
+ * and the URL bar receive the new value on the next stable snapshot, when the
+ * context is complete.
  *
- * @param snapshot - Current XState machine snapshot.
- * @returns Resolved URL string, or `null` if the route cannot be resolved.
+ * @param snapshot - The current snapshot of the XState machine.
+ * @returns The resolved URL string, or `null` when the function cannot resolve the route.
  */
 export declare const deriveCurrentRoute: (snapshot: AnyMachineSnapshot) => 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,qBAAqB,GACjC,UAAU,kBAAkB,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAoC5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAMxF,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,kBAAkB,KAAG,MAAM,GAAG,IA6B1E,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;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"}

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

@@ -2,26 +2,29 @@ import { MissingRouteParamError } from "../errors.js";
 import { deriveRoute } from "./derive-route.js";
 import { buildRouteUrl } from "./build-url.js";
 /**
- * Collect the `meta` of the active state nodes along a SINGLE root-to-leaf branch,
- * keyed by state id and ordered ancestors-first — the shape {@link deriveRoute} folds.
+ * 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 every active state's meta. For a
- * non-parallel machine that record is already a single ancestor chain, but for a
- * PARALLEL machine it interleaves entries from every active region, so folding it
- * blindly would concatenate a relative route from one region onto an absolute route
- * from a sibling region (a URL belonging to neither region's tree). The flat record
- * also cannot be re-ordered back into a hierarchy: when states declare an explicit
- * `id` (e.g. a child `id: "dashboard-overview"` under `id: "dashboard"`), the meta
- * keys are those ids and carry no ancestry information.
+ * `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.
  *
- * We therefore walk `snapshot.value` (which encodes the true active-state hierarchy
- * by state key) against the machine's node tree, following the FIRST active child at
- * each level. This yields one deterministic branch — matching the historical
- * first-found behaviour for parallel machines — and works regardless of explicit ids
- * because each node carries its own `id` and `meta`.
+ * 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`.
  *
- * Falls back to `null` when the snapshot does not expose a navigable machine/value
- * (defensive — real XState snapshots always do); callers then use `getMeta()` as before.
+ * 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;
@@ -34,9 +37,10 @@ export const firstActiveBranchMeta = (snapshot) => {
         if (node.meta && typeof node.meta === "object") {
             ordered[node.id] = node.meta; // nosemgrep: gitlab.eslint.detect-object-injection
         }
-        // Determine the active child key at this level. A string value is an atomic
-        // active leaf name; an object value is a compound (one key) or parallel (many
-        // keys) node — take the first key for a single deterministic branch.
+        // 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;
@@ -58,12 +62,13 @@ export const firstActiveBranchMeta = (snapshot) => {
     return ordered;
 };
 /**
- * Resolve the meta record route and view derivation fold: the single active
- * branch {@link firstActiveBranchMeta} walks (correct for parallel machines
- * and explicit ids), or the flat `getMeta()` record when the snapshot lacks a
- * navigable machine tree. Shared by `deriveCurrentRoute` and
- * `deriveCurrentView` so the two sides cannot drift apart on branch selection
- * or on tolerating degenerate snapshots.
+ * 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") {
@@ -73,23 +78,25 @@ export const activeStateMeta = (snapshot) => {
     return meta && typeof meta === "object" ? meta : null;
 };
 /**
- * Derive the actor's current URL from state metadata and context.
+ * Derives the current URL of the actor from the state metadata and the context.
  *
- * Resolves the route template from the current state's `meta.route` and substitutes
- * any `:param` placeholders from `context.params` (preferred) or flat `context`.
+ * The function resolves the route template from the `meta.route` field of the
+ * current state. It then replaces each `:param` placeholder with a value of
+ * `context.params`, which it prefers, or of the flat `context` object.
  *
- * Returns `null` — rather than throwing — when:
- * - The snapshot has no route metadata (non-routable state)
- * - A required route parameter is absent from context (`MissingRouteParamError`)
+ * The function returns `null`, and it throws no error, in two cases:
+ * - 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` return on missing params is intentional: it keeps the computed signal
- * stable during transient states (e.g. mid-transition before context is fully updated,
- * or after logout when `context.username` is `null` but the router bridge has not yet
- * synced to the new state). The router bridge and URL bar are updated on the next
- * stable snapshot once context is complete.
+ * The `null` value for an absent param is deliberate: the computed signal 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
+ * and the URL bar receive the new value on the next stable snapshot, when the
+ * context is complete.
  *
- * @param snapshot - Current XState machine snapshot.
- * @returns Resolved URL string, or `null` if the route cannot be resolved.
+ * @param snapshot - The current snapshot of the XState machine.
+ * @returns The resolved URL string, or `null` when the function cannot resolve the route.
  */
 export const deriveCurrentRoute = (snapshot) => {
     const meta = activeStateMeta(snapshot);
@@ -104,19 +111,20 @@ export const deriveCurrentRoute = (snapshot) => {
         return buildRouteUrl(routeTemplate, (snapshot.context ?? {}));
     }
     catch (error) {
-        // MissingRouteParamError: transient and self-resolving — a required `:param` is absent
-        // from context during a mid-transition state (e.g. actor in profile state before the
-        // first play.route event populates context.params, or after logout before the bridge
-        // redirects). Returning null is correct:
-        //   - Router bridges handle null by skipping navigation (syncRouterFromActor line 242)
-        //   - The signal recomputes automatically on the next snapshot when params are populated
-        //   - Throwing would propagate into signal watchers as an unhandled exception for a
-        //     state that resolves itself — worse than a one-tick null.
-        // Do NOT convert this to a throw.
+        // MissingRouteParamError: the condition is temporary, and it resolves itself. A
+        // necessary `:param` is absent from the context during a state of a transition, for
+        // example an actor in the profile state before the first play.route event fills
+        // 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.
+        // Do NOT convert this into a throw.
         if (error instanceof MissingRouteParamError) {
             return null;
         }
-        // Unexpected errors re-throw unchanged.
+        // Each unexpected error goes to the caller without a change.
         throw error;
     }
 };