@xmachines/docs 2.0.0 → 2.1.0

package/api/@xmachines/play-router/functions/isRouteReachable.md

@@ -6,26 +6,27 @@
 function isRouteReachable(graph, fromStateId, toStateId): boolean;
 ```
 
-Defined in: [query.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/query.ts#L181)
+Defined in: [query.ts:186](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/query.ts#L186)
 
-Check if a route is reachable from current state via transitions
+Tells you if a transition from the current state can reach a route
 
-Uses @statelyai/graph path-finding to determine if there exists
-a chain of transition edges from the source state to the target state.
+The function uses the path search of @statelyai/graph. It decides if a chain of
+transition edges is present from the state of the origin to the state of the
+target.
 
 ## Parameters
 
-| Parameter     | Type                                                                                                                    | Description                        |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| `graph`       | `Graph`\<[`MachineNodeData`](../interfaces/MachineNodeData.md), [`MachineEdgeData`](../interfaces/MachineEdgeData.md)\> | Machine graph from RouteTree.graph |
-| `fromStateId` | `string`                                                                                                                | Source state ID                    |
-| `toStateId`   | `string`                                                                                                                | Target state ID                    |
+| Parameter     | Type                                                                                                                    | Description                             |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `graph`       | `Graph`\<[`MachineNodeData`](../interfaces/MachineNodeData.md), [`MachineEdgeData`](../interfaces/MachineEdgeData.md)\> | The machine graph, from RouteTree.graph |
+| `fromStateId` | `string`                                                                                                                | The ID of the state of the origin       |
+| `toStateId`   | `string`                                                                                                                | The ID of the state of the target       |
 
 ## Returns
 
 `boolean`
 
-true if a transition path exists, false otherwise
+true when a transition path is present. In every other case, false
 
 ## Example
 
@@ -33,6 +34,6 @@ true if a transition path exists, false otherwise
 const tree = extractMachineRoutes(machine);
 if (tree.graph) {
 	const canReach = isRouteReachable(tree.graph, "auth.login", "auth.dashboard");
-	// true if login → dashboard transition path exists
+	// it is true when a transition path from login to dashboard is present
 }
 ```

package/api/@xmachines/play-router/functions/machineToGraph.md

@@ -6,7 +6,7 @@
 function machineToGraph(machine): MachineGraph;
 ```
 
-Defined in: [machine-to-graph.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/machine-to-graph.ts#L71)
+Defined in: [machine-to-graph.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/machine-to-graph.ts#L73)
 
 ## Parameters
 

package/api/@xmachines/play-router/functions/routeExists.md

@@ -6,21 +6,21 @@
 function routeExists(tree, path): boolean;
 ```
 
-Defined in: [query.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/query.ts#L125)
+Defined in: [query.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/query.ts#L128)
 
-Validate route path exists in tree
+Tells you if a route path is in the tree
 
-Checks if path has corresponding state with meta.route.
+The function tests if the path has a state with a `meta.route` field.
 
 ## Parameters
 
-| Parameter | Type                                      | Description                                   |
-| --------- | ----------------------------------------- | --------------------------------------------- |
-| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | Route tree from extractMachineRoutes()        |
-| `path`    | `string`                                  | Full route path (e.g., '/dashboard/settings') |
+| Parameter | Type                                      | Description                                                |
+| --------- | ----------------------------------------- | ---------------------------------------------------------- |
+| `tree`    | [`RouteTree`](../interfaces/RouteTree.md) | The route tree, from extractMachineRoutes()                |
+| `path`    | `string`                                  | The complete route path, for example '/dashboard/settings' |
 
 ## Returns
 
 `boolean`
 
-true if path exists, false otherwise
+true when the tree holds the path. In every other case, false

package/api/@xmachines/play-router/functions/sanitizePathname.md

@@ -6,29 +6,31 @@
 function sanitizePathname(pathname): string | null;
 ```
 
-Defined in: [router-sync.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L72)
+Defined in: [router-sync.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L74)
 
-Normalize a pathname before route-map lookup.
+Normalizes a pathname before a lookup in the route map.
 
-This strips query/hash fragments, collapses duplicate slashes, and rejects
-implausibly long paths that should never enter route resolution.
+The function removes a query fragment and a hash fragment, it joins each duplicate
+slash into one, and it refuses a path of an improbable length, because such a path
+must never enter the route resolution.
 
-Returns `null` for paths exceeding 2048 characters (malformed/adversarial input).
-Adapters that bypass `RouterBridgeBase.syncActorFromRouter()` (e.g. `VueRouterBridge`)
-must call this function directly and return early on `null` to apply the same
-defense-in-depth security guarantee as the shared base class.
+It returns `null` for a path of more than 2048 characters, which is malformed or
+hostile input. An adapter that passes around
+`RouterBridgeBase.syncActorFromRouter()`, for example `VueRouterBridge`, must call
+this function itself, and it must return at once on a `null` value. That adapter
+then gives the same guarantee of the defense in depth as the shared base class.
 
 ## Parameters
 
-| Parameter  | Type     | Description                                   |
-| ---------- | -------- | --------------------------------------------- |
-| `pathname` | `string` | Raw path string from router navigation event. |
+| Parameter  | Type     | Description                                              |
+| ---------- | -------- | -------------------------------------------------------- |
+| `pathname` | `string` | The raw path string of a navigation event of the router. |
 
 ## Returns
 
 `string` \| `null`
 
-Normalized path string, or `null` if the path is malformed/too long.
+The normalized path string, or `null` when the path is malformed or too long.
 
 ## Example
 
@@ -36,5 +38,5 @@ Normalized path string, or `null` if the path is malformed/too long.
 import { sanitizePathname } from "@xmachines/play-router";
 
 const clean = sanitizePathname(to.path);
-if (clean === null) return; // reject malformed path
+if (clean === null) return; // refuse a malformed path
 ```

package/api/@xmachines/play-router/functions/validateRouteFormat.md

@@ -6,20 +6,20 @@
 function validateRouteFormat(routePath, stateId): void;
 ```
 
-Defined in: [validate-routes.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L27)
+Defined in: [validate-routes.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L27)
 
-Validate route path format
+Checks the format of a route path
 
-Ensures route paths are non-empty strings. Both absolute paths ("/foo")
-and relative paths ("foo", "child/nested") are accepted. Relative routes
-inherit their parent state's path prefix when the tree is built.
+The function requires a string that is not empty. It accepts an absolute path
+("/foo") and also a relative path ("foo" or "child/nested"). A relative route
+receives the path prefix of its parent state during the construction of the tree.
 
 ## Parameters
 
-| Parameter   | Type     | Description                                   |
-| ----------- | -------- | --------------------------------------------- |
-| `routePath` | `string` | Route path to validate (absolute or relative) |
-| `stateId`   | `string` | State identifier for error messages           |
+| Parameter   | Type     | Description                                        |
+| ----------- | -------- | -------------------------------------------------- |
+| `routePath` | `string` | The route path to check: absolute or relative      |
+| `stateId`   | `string` | The identifier of the state, for the error message |
 
 ## Returns
 
@@ -27,4 +27,4 @@ inherit their parent state's path prefix when the tree is built.
 
 ## Throws
 
-If route path is empty
+When the route path is empty

package/api/@xmachines/play-router/functions/validateStateExists.md

@@ -6,19 +6,19 @@
 function validateStateExists(stateId, stateIds): void;
 ```
 
-Defined in: [validate-routes.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L43)
+Defined in: [validate-routes.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L43)
 
-Validate state exists in state ID set
+Checks that the set of the state IDs holds a state
 
-Ensures referenced state IDs exist in the machine graph.
-Build-time validation prevents broken route references.
+The function requires each state ID of a reference in the machine graph. This
+check at the build time therefore stops a broken route reference.
 
 ## Parameters
 
-| Parameter  | Type              | Description                                       |
-| ---------- | ----------------- | ------------------------------------------------- |
-| `stateId`  | `string`          | State identifier to validate                      |
-| `stateIds` | `Set`\<`string`\> | Set of all known state IDs from the machine graph |
+| Parameter  | Type              | Description                                          |
+| ---------- | ----------------- | ---------------------------------------------------- |
+| `stateId`  | `string`          | The identifier of the state to check                 |
+| `stateIds` | `Set`\<`string`\> | The set of every known state ID of the machine graph |
 
 ## Returns
 
@@ -26,4 +26,4 @@ Build-time validation prevents broken route references.
 
 ## Throws
 
-If state ID doesn't exist in set
+When the set does not hold the state ID

package/api/@xmachines/play-router/interfaces/BuildPlayRouteEventOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: BuildPlayRouteEventOptions
 
-Defined in: [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L17)
+Defined in: [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L17)
 
 ## Properties
 
 | Property                                  | Type                                                   | Defined in                                                                                                                |
 | ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match`       | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L20) |
-| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L18) |
-| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-sync.ts#L19) |
+| <a id="property-match"></a> `match`       | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L20) |
+| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L18) |
+| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-sync.ts#L19) |

package/api/@xmachines/play-router/interfaces/LocationLike.md

@@ -2,19 +2,19 @@
 
 # Interface: LocationLike
 
-Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L414)
+Defined in: [types.ts:432](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L432)
 
-Minimal location interface required by adapters that read the current URL at
-`connect()` time. Injectable for SSR and testing — pass a mock instead of the
-global `location` when the DOM is unavailable.
+The minimal location interface of an adapter that reads the current URL at the
+moment of `connect()`. You can inject it for SSR and for a test: give a mock in
+place of the global `location` when no DOM is available.
 
-Defined structurally (no `Location` reference) so this package compiles without
-the DOM lib.
+The definition is structural, and it holds no reference to `Location`. This package
+therefore compiles without the DOM lib.
 
 ## Example
 
 ```typescript
-// SSR / test — injected mock
+// SSR or a test — an injected mock
 const mockLoc: LocationLike = { pathname: "/dashboard", search: "?tab=posts" };
 connectRouter({ actor, routeMap, location: mockLoc });
 ```
@@ -23,5 +23,5 @@ connectRouter({ actor, routeMap, location: mockLoc });
 
 | Property                                  | Modifier   | Type     | Defined in                                                                                                      |
 | ----------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L415) |
-| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L416) |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:433](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L433) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:434](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L434) |

package/api/@xmachines/play-router/interfaces/MachineEdgeData.md

@@ -2,14 +2,14 @@
 
 # Interface: MachineEdgeData
 
-Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L24)
+Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L24)
 
-Data attached to each edge in the machine graph representation.
-Captures transition event and guard information.
+The data on each edge of the graph that represents the machine.
+It holds the event of the transition and the information of its guard.
 
 ## Properties
 
-| Property                                     | Type     | Description                                  | Defined in                                                                                                    |
-| -------------------------------------------- | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L26) |
-| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L28) |
+| Property                                         | Type     | Description                                                                                      | Defined in                                                                                                    |
+| ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-eventtype"></a> `eventType`      | `string` | The event type that starts this transition                                                       | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L26) |
+| <a id="property-guardtype"></a> ~~`guardType?`~~ | `string` | The guard as a string, when a guard is present **Deprecated** Will be removed in the next major. | [types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L32) |

package/api/@xmachines/play-router/interfaces/MachineNodeData.md

@@ -2,16 +2,16 @@
 
 # Interface: MachineNodeData
 
-Defined in: [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L9)
+Defined in: [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L9)
 
-Data attached to each node in the machine graph representation.
-Captures the essential state metadata needed for route extraction and queries.
+The data on each node of the graph that represents the machine.
+It holds the state metadata that the route extraction and the queries need.
 
 ## Properties
 
-| Property                                | Type                                                                   | Description                                        | Defined in                                                                                                    |
-| --------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L15) |
-| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L17) |
-| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L11) |
-| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | State type from XState                             | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L13) |
+| Property                                | Type                                                                   | Description                                                | Defined in                                                                                                    |
+| --------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | The original meta object of the state                      | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L15) |
+| <a id="property-route"></a> `route?`    | `string`                                                               | The route path of meta.route, in its string form           | [types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L17) |
+| <a id="property-stateid"></a> `stateId` | `string`                                                               | The XState state ID, for example "test.dashboard.overview" | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L11) |
+| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | The state type of XState                                   | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L13) |

package/api/@xmachines/play-router/interfaces/PlayActor.md

@@ -2,22 +2,24 @@
 
 # Interface: PlayActor
 
-Defined in: [types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L297)
+Defined in: [types.ts:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L312)
 
-Full actor shape used by `PlayRouterProvider` components across all framework
-adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
-adapters built on the shared framework-router bridge bases).
+The complete actor shape of the `PlayRouterProvider` component of each framework
+adapter: `play-solid-router`, `play-vue-router`, `play-react-router`, and each
+adapter on the shared framework router bridge bases.
 
-Extends `RoutableActor` with `currentView` — the provider renders the current
-view spec in addition to synchronizing routes, so it needs both capabilities.
+The shape extends `RoutableActor` with `currentView`, because the provider renders
+the current view spec and also keeps the routes in step. It therefore needs both
+capabilities.
 
-- Use `RoutableActor` when only routing is needed (e.g. `RouterBridgeBase` subclasses,
-  `connectRouter`).
-- Use `PlayActor` when the component also renders the current view spec
-  (e.g. `PlayRouterProvider` renderer callback parameter, `PlayRenderer`).
+- Use `RoutableActor` when you need the routing alone, for example in a
+  `RouterBridgeBase` subclass, or in `connectRouter`.
+- Use `PlayActor` when the component also renders the current view spec, for
+  example for the renderer callback parameter of `PlayRouterProvider`, and in
+  `PlayRenderer`.
 
-All `AbstractActor` subclasses that implement both `Routable` and `Viewable`
-satisfy this interface structurally.
+Every `AbstractActor` subclass that implements both `Routable` and `Viewable`
+satisfies this interface structurally.
 
 ## Example
 
@@ -25,7 +27,7 @@ satisfy this interface structurally.
 import type { PlayActor } from "@xmachines/play-router";
 
 function MyRouterProvider({ actor }: { actor: PlayActor }) {
-	// access actor.currentRoute (routing) and actor.currentView (rendering)
+	// it reads actor.currentRoute for the routing, and actor.currentView for the render
 }
 ```
 
@@ -35,11 +37,11 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                               | Defined in                                                                                                      |
-| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](RoutableActor.md).[`currentRoute`](RoutableActor.md#property-currentroute) | [types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L261) |
-| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                            | [types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L299) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](RoutableActor.md).[`initialRoute`](RoutableActor.md#property-initialroute) | [types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L267) |
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                                              | Inherited from                                                                               | Defined in                                                                                                      |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | The TC39 Signal of the current URL path of the actor, or of its state ID.                                                                                                                                                                | [`RoutableActor`](RoutableActor.md).[`currentRoute`](RoutableActor.md#property-currentroute) | [types.ts:274](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L274) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | The TC39 Signal of the current view spec of the actor, or `null` when no view is active.                                                                                                                                                 | -                                                                                            | [types.ts:314](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L314) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route of the initial state of the machine. The constructor fixes it. A router bridge compares it with the browser URL. It therefore separates a deep link, where the router wins, from a restore of a session, where the actor wins. | [`RoutableActor`](RoutableActor.md).[`initialRoute`](RoutableActor.md#property-initialroute) | [types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L280) |
 
 ## Methods
 
@@ -49,9 +51,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L269)
+Defined in: [types.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L282)
 
-Send a route navigation event to the actor.
+Sends a route navigation event to the actor.
 
 #### Parameters
 

package/api/@xmachines/play-router/interfaces/PlayRouteEvent.md

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L225)
+Defined in: [types.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L237)
 
-Enhanced routing event with parameter and query support
+The routing event, with its parameters and its query
 
-Unified routing event used throughout the Play architecture. Supports parameter-aware
-navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+This is the one routing event of the complete Play architecture. It supports a
+navigation that knows the parameters, for example `/profile/:userId`, for a dynamic
+route segment.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
-user navigation intent that the Actor evaluates through guards. Infrastructure proposes
-via `play.route` events, Actor decides via state machine transitions.
+**Architectural context:** the event implements **Passive Infrastructure
+(INV-04)**, because it holds the navigation intent of the user, and the Actor then
+evaluates that intent with its guards. The infrastructure makes a request with a
+`play.route` event, and the Actor decides with a transition of its state machine.
 
-**Browser Navigation Flow:**
+**The flow of a browser navigation:**
 
-1. Browser fires `popstate`
-2. Router adapter resolves URL to route target
-3. Adapter sends `PlayRouteEvent` to Actor
-4. Actor validates transition via state machine guards
+1. The browser fires `popstate`
+2. The router adapter resolves the URL to a route target
+3. The adapter sends a `PlayRouteEvent` to the Actor
+4. The Actor checks the transition with the guards of its state machine
 
 ## Param
 
 **type**
 
-Event discriminator (always "play.route")
+The discriminator of the event. It is always "play.route"
 
 ## Param
 
 **to**
 
-Target state ID with # prefix (e.g., '#home', '#profile')
+The target state ID, with a # prefix, for example '#home' or '#profile'
 
 ## Param
 
 **params**
 
-Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+The route parameters of the path only, from the URL path, for
+example `{ userId: '123' }` of `/profile/123`. The `query` field holds the query
+parameters separately.
 
 ## Param
 
 **query**
 
-Query parameters only (isolated from path params)
+The query parameters only. They stay separate from the params of the path
 
 ## Param
 
 **match**
 
-Full URLPattern match result for debugging/observability (optional)
+The complete match result of URLPattern, for the debug work and for
+the observability. It is optional
 
 ## Examples
 
-Combining base and routing events
+The base event and the routing event together
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
@@ -61,7 +66,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 type AppEvent = PlayEvent | PlayRouteEvent;
 ```
 
-Basic navigation to a route
+A basic navigation to a route
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -73,7 +78,7 @@ const event: PlayRouteEvent = {
 actor.send(event);
 ```
 
-Navigation with route parameters
+A navigation with route parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -84,10 +89,10 @@ const event: PlayRouteEvent = {
 	params: { userId: "123" },
 };
 actor.send(event);
-// Resolves to route: /profile/123
+// It resolves to the route /profile/123
 ```
 
-Navigation with query parameters
+A navigation with query parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -95,11 +100,11 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Path-only route parameter
-	query: { tab: "security" }, // Query-only
+	params: { section: "profile" }, // a route parameter of the path only
+	query: { tab: "security" }, // the query only
 };
 actor.send(event);
-// Resolves to route: /settings/profile?tab=security
+// It resolves to the route /settings/profile?tab=security
 ```
 
 ## See
@@ -108,9 +113,10 @@ actor.send(event);
 
 ## Remarks
 
-Use `play.route` when you need parameter-aware navigation with the `route: {}`
-config pattern on your state machine nodes. The `match` field exposes the full
-URLPatternResult for advanced use cases (debugging, pattern analysis).
+Use `play.route` when you need a navigation that knows the parameters, with the
+`route: {}` config pattern on the nodes of your state machine. The `match` field
+gives you the complete URLPatternResult, for an advanced use such as a debug or an
+analysis of the pattern.
 
 ## Indexable
 
@@ -122,8 +128,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                      |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L230) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L228) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L229) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L227) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L242) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L240) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L241) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L239) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L238) |

package/api/@xmachines/play-router/interfaces/ResolvedRoutePath.md

@@ -2,16 +2,16 @@
 
 # Interface: ResolvedRoutePath
 
-Defined in: [validate-routes.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L9)
+Defined in: [validate-routes.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L9)
 
-A route entry with its RESOLVED full path — the path after relative routes have
-been prefixed with their parent's full path during tree construction.
+A route entry with its RESOLVED complete path, which is the path after the tree
+construction put the path of the parent before each relative route.
 
 `RouteNode` satisfies this shape structurally.
 
 ## Properties
 
-| Property                                  | Type     | Description                                                          | Defined in                                                                                                                        |
-| ----------------------------------------- | -------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-fullpath"></a> `fullPath` | `string` | Resolved absolute route path (e.g. `"/dashboard/settings"`).         | [validate-routes.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L13) |
-| <a id="property-stateid"></a> `stateId`   | `string` | State identifier owning the route (e.g. `"app.dashboard.settings"`). | [validate-routes.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/validate-routes.ts#L11) |
+| Property                                  | Type     | Description                                                                              | Defined in                                                                                                                        |
+| ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-fullpath"></a> `fullPath` | `string` | The resolved absolute route path, for example `"/dashboard/settings"`.                   | [validate-routes.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L13) |
+| <a id="property-stateid"></a> `stateId`   | `string` | The identifier of the state that owns the route, for example `"app.dashboard.settings"`. | [validate-routes.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/validate-routes.ts#L11) |