@xmachines/play-router 2.0.0 → 2.1.0

package/dist/errors.d.ts

@@ -1,9 +1,10 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown when `RouterBridgeBase.syncActorFromRouter()` fails to process a router
- * location change and send the corresponding `play.route` event to the actor.
+ * The bridge throws this error when `RouterBridgeBase.syncActorFromRouter()`
+ * cannot process a location change of the router and send the `play.route` event to
+ * the actor.
  *
- * The `cause` property wraps the original error.
+ * The `cause` property holds the original error.
  *
  * **Error code:** `PLAY_ROUTER_SYNC_FAILED`
  *
@@ -24,17 +25,17 @@ export declare class RouterSyncError extends PlayError {
     constructor(message: string, options?: ErrorOptions);
 }
 /**
- * Thrown by `RouterBridgeBase.connect()` when a second bridge tries to connect
- * to an actor that already has an active bridge connection.
+ * `RouterBridgeBase.connect()` throws this error when a second bridge connects to an
+ * actor with an active bridge connection.
  *
- * One actor may only be connected to one router bridge at a time. Two bridges
- * sharing the same actor would both receive and process every router navigation
- * event, sending duplicate `play.route` events to the actor and producing
- * conflicting echo-suppression state via `lastSyncedPath`.
+ * One actor can hold one router bridge at a time. Two bridges of the same actor both
+ * receive and process every navigation event of the router. They therefore send two
+ * `play.route` events to the actor, and their `lastSyncedPath` values of the echo
+ * suppression contradict each other.
  *
- * **How to fix:** Call `bridge.disconnect()` on the first bridge before
- * connecting a second one, or ensure only one `connectRouter()` call is active
- * per actor at any given time.
+ * **The remedy:** call `bridge.disconnect()` on the first bridge before you connect
+ * the second one. You can also permit one active `connectRouter()` call for each
+ * actor at a time.
  *
  * **Error code:** `PLAY_ROUTER_DUPLICATE_BRIDGE`
  *
@@ -55,20 +56,20 @@ export declare class DuplicateBridgeError extends PlayError {
     constructor();
 }
 /**
- * Thrown by the `RouteMap` constructor when a parameterized route is registered but
- * the `URLPattern` API is not available in the current runtime environment and no
- * polyfill has been loaded.
+ * The `RouteMap` constructor throws this error when the caller registers a
+ * parameterized route, the current runtime has no `URLPattern` API, and no polyfill
+ * is loaded.
  *
- * **How to fix:** Load `urlpattern-polyfill` at your application entry point, before
- * any import of `@xmachines/play-router`:
+ * **The remedy:** load `urlpattern-polyfill` at the entry point of your application,
+ * before each import of `@xmachines/play-router`:
  *
  * ```typescript
- * // app entry point — must run first
+ * // the entry point of the application — it must run first
  * import "urlpattern-polyfill";
  * ```
  *
- * URLPattern is natively available on Node.js ≥ 24 and modern browsers
- * (Chrome 95+, Firefox 117+, Safari 16.4+). Use the polyfill on older targets.
+ * URLPattern is native in Node.js ≥ 24 and in a modern browser (Chrome 95+,
+ * Firefox 117+, Safari 16.4+). Use the polyfill for an older target.
  *
  * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
  */
@@ -76,58 +77,59 @@ export declare class URLPatternUnavailableError extends PlayError {
     constructor();
 }
 /**
- * Thrown by `validateRouteFormat()` when a state declares `meta.route` with an
- * empty string path.
+ * `validateRouteFormat()` throws this error when a state declares a `meta.route`
+ * field with an empty string as its path.
  *
  * **Error code:** `PLAY_ROUTE_EMPTY_PATH`
  */
 export declare class EmptyRoutePathError extends PlayError {
-    /** The state ID whose route path is empty. */
+    /** The state ID with the empty route path. */
     readonly stateId: string;
     constructor(stateId: string);
 }
 /**
- * Thrown by `validateStateExists()` when a route references a state ID that does
- * not exist in the machine graph.
+ * `validateStateExists()` throws this error when a route names a state ID that the
+ * machine graph does not hold.
  *
  * **Error code:** `PLAY_ROUTE_INVALID_STATE_ID`
  */
 export declare class InvalidStateIdError extends PlayError {
-    /** The state ID that was referenced but not found. */
+    /** The state ID of the reference. The graph does not hold it. */
     readonly stateId: string;
     constructor(stateId: string);
 }
 /**
- * Thrown by `detectDuplicateRoutes()` when two or more states share the same URL path.
+ * `detectDuplicateRoutes()` throws this error when two states or more hold the same
+ * URL path.
  *
  * **Error code:** `PLAY_ROUTE_DUPLICATE_PATH`
  */
 export declare class DuplicateRoutePathError extends PlayError {
-    /** Human-readable list of conflicting path → state-ID mappings. */
+    /** The list of the path → state-ID mappings of the conflict, for a person to read. */
     readonly duplicates: string[];
     constructor(duplicates: string[]);
 }
 /**
- * Thrown by `machineToGraph()` when an XState state node has an unrecognised
- * `.type` value.
+ * `machineToGraph()` throws this error when an XState state node has a `.type` value
+ * that the package does not know.
  *
  * **Error code:** `PLAY_ROUTE_UNKNOWN_STATE_TYPE`
  */
 export declare class UnknownStateTypeError extends PlayError {
-    /** The unrecognised state type string. */
+    /** The string of the state type that the package does not know. */
     readonly stateType: string;
     /** The ID of the state node with the unknown type. */
     readonly nodeId: string;
     constructor(stateType: string, nodeId: string, validTypes: string[]);
 }
 /**
- * Thrown by the `RouteMap` constructor when a route pattern string cannot be compiled
- * by `URLPattern`. The `pattern` field contains the rejected string; `cause` wraps the
- * original `URLPattern` constructor error.
+ * The `RouteMap` constructor throws this error when `URLPattern` cannot compile the
+ * string of a route pattern. The `pattern` field holds the string in question, and
+ * `cause` holds the original error of the `URLPattern` constructor.
  *
- * Common causes:
- * - Unmatched parentheses or brackets in the pattern string
- * - Characters that are invalid in a URL pathname pattern
+ * The common causes:
+ * - A parenthesis or a bracket without its pair in the string of the pattern
+ * - A character that a URL pathname pattern does not permit
  *
  * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
  *
@@ -145,7 +147,7 @@ export declare class UnknownStateTypeError extends PlayError {
  * ```
  */
 export declare class InvalidRoutePatternError extends PlayError {
-    /** The route pattern string that could not be compiled by URLPattern. */
+    /** The string of the route pattern. URLPattern could not compile it. */
     readonly pattern: string;
     constructor(pattern: string, options?: ErrorOptions);
 }

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAUnD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAUnD"}

package/dist/errors.js

@@ -1,9 +1,10 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown when `RouterBridgeBase.syncActorFromRouter()` fails to process a router
- * location change and send the corresponding `play.route` event to the actor.
+ * The bridge throws this error when `RouterBridgeBase.syncActorFromRouter()`
+ * cannot process a location change of the router and send the `play.route` event to
+ * the actor.
  *
- * The `cause` property wraps the original error.
+ * The `cause` property holds the original error.
  *
  * **Error code:** `PLAY_ROUTER_SYNC_FAILED`
  *
@@ -27,17 +28,17 @@ export class RouterSyncError extends PlayError {
     }
 }
 /**
- * Thrown by `RouterBridgeBase.connect()` when a second bridge tries to connect
- * to an actor that already has an active bridge connection.
+ * `RouterBridgeBase.connect()` throws this error when a second bridge connects to an
+ * actor with an active bridge connection.
  *
- * One actor may only be connected to one router bridge at a time. Two bridges
- * sharing the same actor would both receive and process every router navigation
- * event, sending duplicate `play.route` events to the actor and producing
- * conflicting echo-suppression state via `lastSyncedPath`.
+ * One actor can hold one router bridge at a time. Two bridges of the same actor both
+ * receive and process every navigation event of the router. They therefore send two
+ * `play.route` events to the actor, and their `lastSyncedPath` values of the echo
+ * suppression contradict each other.
  *
- * **How to fix:** Call `bridge.disconnect()` on the first bridge before
- * connecting a second one, or ensure only one `connectRouter()` call is active
- * per actor at any given time.
+ * **The remedy:** call `bridge.disconnect()` on the first bridge before you connect
+ * the second one. You can also permit one active `connectRouter()` call for each
+ * actor at a time.
  *
  * **Error code:** `PLAY_ROUTER_DUPLICATE_BRIDGE`
  *
@@ -62,20 +63,20 @@ export class DuplicateBridgeError extends PlayError {
     }
 }
 /**
- * Thrown by the `RouteMap` constructor when a parameterized route is registered but
- * the `URLPattern` API is not available in the current runtime environment and no
- * polyfill has been loaded.
+ * The `RouteMap` constructor throws this error when the caller registers a
+ * parameterized route, the current runtime has no `URLPattern` API, and no polyfill
+ * is loaded.
  *
- * **How to fix:** Load `urlpattern-polyfill` at your application entry point, before
- * any import of `@xmachines/play-router`:
+ * **The remedy:** load `urlpattern-polyfill` at the entry point of your application,
+ * before each import of `@xmachines/play-router`:
  *
  * ```typescript
- * // app entry point — must run first
+ * // the entry point of the application — it must run first
  * import "urlpattern-polyfill";
  * ```
  *
- * URLPattern is natively available on Node.js ≥ 24 and modern browsers
- * (Chrome 95+, Firefox 117+, Safari 16.4+). Use the polyfill on older targets.
+ * URLPattern is native in Node.js ≥ 24 and in a modern browser (Chrome 95+,
+ * Firefox 117+, Safari 16.4+). Use the polyfill for an older target.
  *
  * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
  */
@@ -86,13 +87,13 @@ export class URLPatternUnavailableError extends PlayError {
     }
 }
 /**
- * Thrown by `validateRouteFormat()` when a state declares `meta.route` with an
- * empty string path.
+ * `validateRouteFormat()` throws this error when a state declares a `meta.route`
+ * field with an empty string as its path.
  *
  * **Error code:** `PLAY_ROUTE_EMPTY_PATH`
  */
 export class EmptyRoutePathError extends PlayError {
-    /** The state ID whose route path is empty. */
+    /** The state ID with the empty route path. */
     stateId;
     constructor(stateId) {
         super("RouteMap", "PLAY_ROUTE_EMPTY_PATH", `Empty route path in state "${stateId}": routes must have a non-empty path`);
@@ -101,13 +102,13 @@ export class EmptyRoutePathError extends PlayError {
     }
 }
 /**
- * Thrown by `validateStateExists()` when a route references a state ID that does
- * not exist in the machine graph.
+ * `validateStateExists()` throws this error when a route names a state ID that the
+ * machine graph does not hold.
  *
  * **Error code:** `PLAY_ROUTE_INVALID_STATE_ID`
  */
 export class InvalidStateIdError extends PlayError {
-    /** The state ID that was referenced but not found. */
+    /** The state ID of the reference. The graph does not hold it. */
     stateId;
     constructor(stateId) {
         super("RouteMap", "PLAY_ROUTE_INVALID_STATE_ID", `Route references non-existent state ID: ${stateId}`);
@@ -116,12 +117,13 @@ export class InvalidStateIdError extends PlayError {
     }
 }
 /**
- * Thrown by `detectDuplicateRoutes()` when two or more states share the same URL path.
+ * `detectDuplicateRoutes()` throws this error when two states or more hold the same
+ * URL path.
  *
  * **Error code:** `PLAY_ROUTE_DUPLICATE_PATH`
  */
 export class DuplicateRoutePathError extends PlayError {
-    /** Human-readable list of conflicting path → state-ID mappings. */
+    /** The list of the path → state-ID mappings of the conflict, for a person to read. */
     duplicates;
     constructor(duplicates) {
         super("RouteMap", "PLAY_ROUTE_DUPLICATE_PATH", `Duplicate route paths detected:\n${duplicates.join("\n")}\n\n` +
@@ -132,13 +134,13 @@ export class DuplicateRoutePathError extends PlayError {
     }
 }
 /**
- * Thrown by `machineToGraph()` when an XState state node has an unrecognised
- * `.type` value.
+ * `machineToGraph()` throws this error when an XState state node has a `.type` value
+ * that the package does not know.
  *
  * **Error code:** `PLAY_ROUTE_UNKNOWN_STATE_TYPE`
  */
 export class UnknownStateTypeError extends PlayError {
-    /** The unrecognised state type string. */
+    /** The string of the state type that the package does not know. */
     stateType;
     /** The ID of the state node with the unknown type. */
     nodeId;
@@ -151,13 +153,13 @@ export class UnknownStateTypeError extends PlayError {
     }
 }
 /**
- * Thrown by the `RouteMap` constructor when a route pattern string cannot be compiled
- * by `URLPattern`. The `pattern` field contains the rejected string; `cause` wraps the
- * original `URLPattern` constructor error.
+ * The `RouteMap` constructor throws this error when `URLPattern` cannot compile the
+ * string of a route pattern. The `pattern` field holds the string in question, and
+ * `cause` holds the original error of the `URLPattern` constructor.
  *
- * Common causes:
- * - Unmatched parentheses or brackets in the pattern string
- * - Characters that are invalid in a URL pathname pattern
+ * The common causes:
+ * - A parenthesis or a bracket without its pair in the string of the pattern
+ * - A character that a URL pathname pattern does not permit
  *
  * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
  *
@@ -175,7 +177,7 @@ export class UnknownStateTypeError extends PlayError {
  * ```
  */
 export class InvalidRoutePatternError extends PlayError {
-    /** The route pattern string that could not be compiled by URLPattern. */
+    /** The string of the route pattern. URLPattern could not compile it. */
     pattern;
     constructor(pattern, options) {
         super("RouteMap", "PLAY_ROUTE_MAP_INVALID_PATTERN", `Invalid route pattern: "${pattern}"`, options);

package/dist/errors.js.map

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

package/dist/extract-routes.d.ts

@@ -1,15 +1,16 @@
 import type { AnyStateMachine } from "xstate";
 import type { RouteTree } from "./types.js";
 /**
- * Extract complete route tree from state machine graph
+ * Reads the complete route tree from the graph of a state machine
  *
- * Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
- * then walks graph nodes to extract route metadata, validate route references,
- * and build a hierarchical RouteTree. The graph is attached to the returned
- * RouteTree for downstream transition-aware queries.
+ * The function converts the XState machine into a Graph of @statelyai/graph, with
+ * machineToGraph(). It then walks the graph nodes: it reads the route metadata of
+ * each node, it checks each route reference, and it builds a hierarchical RouteTree.
+ * The RouteTree of the return value also holds the graph, for a later query that
+ * needs the transitions.
  *
- * @param machine - XState v5 state machine
- * @returns Route tree with root, byStateId map, byPath map, and graph
+ * @param machine - The XState v5 state machine
+ * @returns The route tree, with its root, its byStateId map, its byPath map, and its graph
  */
 export declare const extractMachineRoutes: (machine: AnyStateMachine) => RouteTree;
 //# sourceMappingURL=extract-routes.d.ts.map

package/dist/extract-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-routes.d.ts","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,YAAY,CAAC;AA2EvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,eAAe,KAAG,SAmB/D,CAAC"}
+{"version":3,"file":"extract-routes.d.ts","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,YAAY,CAAC;AA6EvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,eAAe,KAAG,SAoB/D,CAAC"}

package/dist/extract-routes.js

@@ -2,14 +2,16 @@ import { machineToGraph } from "./machine-to-graph.js";
 import { validateRouteFormat, validateStateExists } from "./validate-routes.js";
 import { buildRouteTree } from "./build-tree.js";
 /**
- * Build statePath for a graph node by walking the parentId chain.
+ * Builds the statePath of a graph node, and it walks the chain of the parentId
+ * values.
  *
- * Produces an array of stateId segments from root to this node (excluding root),
- * matching the format expected by buildRouteTree's parent lookup.
+ * The function makes an array of the stateId segments, from the root to this node,
+ * and the array holds no root. This is the format of the parent lookup in
+ * buildRouteTree.
  *
- * @param graphNode - The node to build a path for
- * @param graphNodeMap - Map from node id to GraphNode for O(1) parent lookup
- * @returns Array of stateId segments (e.g. ["dashboard", "overview"])
+ * @param graphNode - The node of the path
+ * @param graphNodeMap - The map from a node id to a GraphNode, for a parent lookup in O(1)
+ * @returns The array of the stateId segments, for example ["dashboard", "overview"]
  */
 const buildStatePath = (graphNode, graphNodeMap) => {
     const path = [];
@@ -21,22 +23,22 @@ const buildStatePath = (graphNode, graphNodeMap) => {
     return path;
 };
 /**
- * Extract route info from a graph node's MachineNodeData.
- * Returns null if the node has no route (not routable).
+ * Reads the route information of the MachineNodeData object of a graph node.
+ * The function returns null when the node has no route.
  */
 const extractRouteFromNode = (graphNode, stateIds, graphNodeMap) => {
     const { stateId, route, meta } = graphNode.data;
-    // Node has no route — not routable
+    // The node has no route
     if (!route)
         return null;
-    // Validate format (must start with /)
+    // Check the format. The path must start with /
     validateRouteFormat(route, stateId);
-    // Validate state exists in graph (redundant but guards against corruption)
+    // Check that the graph holds the state. This test is redundant, and it guards against a corruption
     validateStateExists(stateId, stateIds);
-    // Build statePath from parentId chain (works for both explicit IDs and auto-generated)
+    // Build the statePath from the chain of the parentId values. This works for an explicit ID and also for a generated one
     const statePath = buildStatePath(graphNode, graphNodeMap);
     const pattern = route.includes(":") ? route : undefined;
-    // Reconstruct original metadata shape from graph data
+    // Build the original shape of the metadata again, from the data of the graph
     const metadata = meta && typeof meta === "object" && "route" in meta
         ? meta["route"]
         : route;
@@ -53,30 +55,32 @@ const extractRouteFromNode = (graphNode, stateIds, graphNodeMap) => {
     return result;
 };
 /**
- * Extract complete route tree from state machine graph
+ * Reads the complete route tree from the graph of a state machine
  *
- * Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
- * then walks graph nodes to extract route metadata, validate route references,
- * and build a hierarchical RouteTree. The graph is attached to the returned
- * RouteTree for downstream transition-aware queries.
+ * The function converts the XState machine into a Graph of @statelyai/graph, with
+ * machineToGraph(). It then walks the graph nodes: it reads the route metadata of
+ * each node, it checks each route reference, and it builds a hierarchical RouteTree.
+ * The RouteTree of the return value also holds the graph, for a later query that
+ * needs the transitions.
  *
- * @param machine - XState v5 state machine
- * @returns Route tree with root, byStateId map, byPath map, and graph
+ * @param machine - The XState v5 state machine
+ * @returns The route tree, with its root, its byStateId map, its byPath map, and its graph
  */
 export const extractMachineRoutes = (machine) => {
-    // 1. Convert machine to graph
+    // 1. Convert the machine into a graph
     const graph = machineToGraph(machine);
-    // 2. Build state ID set for validation and node map for O(1) parent lookup
+    // 2. Build the set of the state IDs, for the check, and the node map, for a parent lookup in O(1)
     const stateIds = new Set(graph.nodes.map((n) => n.data.stateId));
     const graphNodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
-    // 3. Extract routes from graph nodes
+    // 3. Read the routes of the graph nodes
     const routes = graph.nodes
         .map((node) => extractRouteFromNode(node, stateIds, graphNodeMap))
         .filter((r) => r !== null);
-    // 4. Build hierarchical tree and attach graph.
-    // Duplicate-route detection happens inside buildRouteTree, AFTER relative
-    // routes are resolved to full paths — raw route strings are not comparable
-    // (two relative "settings" routes under different parents are distinct).
+    // 4. Build the hierarchical tree, and attach the graph.
+    // buildRouteTree finds each duplicate route, AFTER it resolved each relative route
+    // to a complete path. The raw route strings are not comparable, because two
+    // relative "settings" routes below two different parents are two different
+    // routes.
     const tree = buildRouteTree(routes);
     return { ...tree, graph };
 };

package/dist/extract-routes.js.map

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

package/dist/find-route.d.ts

@@ -1,13 +1,14 @@
 import type { RouteTree, RouteNode } from "./types.js";
 /**
- * Find route node by state ID
+ * Finds a route node by its state ID
  *
- * Looks up route node using the state's ID property. Used to get URL path
- * from state ID for browser URL sync after play.route transitions.
+ * The function looks the route node up by the ID property of the state. It gives you
+ * the URL path of a state ID, for the update of the browser URL after a `play.route`
+ * transition.
  *
- * @param tree - Route tree from extractMachineRoutes
- * @param id - State ID (e.g., 'dashboard', 'settings.profile')
- * @returns Route node if found, undefined otherwise
+ * @param tree - The route tree, from extractMachineRoutes
+ * @param id - The state ID, for example 'dashboard' or 'settings.profile'
+ * @returns The route node, or undefined when the function finds none
  *
  * @example
  * ```typescript
@@ -20,19 +21,21 @@ import type { RouteTree, RouteNode } from "./types.js";
  */
 export declare const findRouteById: (tree: RouteTree, id: string) => RouteNode | undefined;
 /**
- * Find route node by URL path
+ * Finds a route node by its URL path
  *
- * Looks up route node using the URL path. Used to get state ID from browser
- * URL for sending play.route events on navigation.
+ * The function looks the route node up by the URL path. It gives you the state ID of
+ * a browser URL, for the `play.route` event of a navigation.
  *
- * When multiple states share the same path (e.g., root and a state both at "/"),
- * prefers routable nodes (with meta.route) over non-routable nodes.
+ * When more than one state holds the same path, for example the root and a second
+ * state both at "/", the function prefers a node with a route, which means a node
+ * with a `meta.route` field, over a node without one.
  *
- * Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
+ * The function also matches a pattern of a dynamic route, for example
+ * '/settings/:section?'.
  *
- * @param tree - Route tree from extractMachineRoutes
- * @param path - URL path (e.g., '/dashboard', '/settings/profile')
- * @returns Route node if found, undefined otherwise
+ * @param tree - The route tree, from extractMachineRoutes
+ * @param path - The URL path, for example '/dashboard' or '/settings/profile'
+ * @returns The route node, or undefined when the function finds none
  *
  * @example
  * ```typescript

package/dist/find-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqCvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}
+{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAsCvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}