@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.18

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [types.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L190)
+Defined in: [types.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L190)
 
 Enhanced routing event with parameter and query support
 
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L195) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L193) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:194](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L194) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L192) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L191) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L195) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L193) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:194](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L194) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L192) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L191) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteInfo
 
-Defined in: [types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L40)
+Defined in: [types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L40)
 
 Extracted route information from a state node
 
@@ -10,10 +10,10 @@ Extracted route information from a state node
 
 | Property                                      | Type                                                | Description                                                                                          | Defined in                                                                                                            |
 | --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L50) |
-| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L57) |
-| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L48) |
-| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L55) |
-| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L46) |
-| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L42) |
-| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L44) |
+| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L50) |
+| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L57) |
+| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L48) |
+| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L55) |
+| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L46) |
+| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L42) |
+| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L44) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMap
 
-Defined in: [create-route-map.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-route-map.ts#L27)
+Defined in: [create-route-map.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-route-map.ts#L28)
 
 Bidirectional route resolution interface returned by `createRouteMap()`.
 
@@ -23,7 +23,7 @@ events into `play.route` actor events.
 resolve(path): object;
 ```
 
-Defined in: [create-route-map.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-route-map.ts#L44)
+Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-route-map.ts#L45)
 
 Resolve a URL path to a state ID and params.
 
@@ -52,5 +52,5 @@ if (to) {
 
 | Name     | Type                           | Defined in                                                                                                                                  |
 | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-route-map.ts#L46) |
-| `to`     | `string` \| `null`             | [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-route-map.ts#L45) |
+| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-route-map.ts#L47) |
+| `to`     | `string` \| `null`             | [create-route-map.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-route-map.ts#L46) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteNode
 
-Defined in: [types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L63)
+Defined in: [types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L63)
 
 Node in the route tree representing a single route
 
@@ -10,12 +10,12 @@ Node in the route tree representing a single route
 
 | Property                                  | Type                  | Description                                                                                          | Defined in                                                                                                            |
 | ----------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children` | `RouteNode`[]         | Child routes                                                                                         | [types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L80) |
-| <a id="property-fullpath"></a> `fullPath` | `string`              | Full resolved path from root                                                                         | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L69) |
-| <a id="property-id"></a> `id`             | `string`              | Unique identifier (state ID)                                                                         | [types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L65) |
-| <a id="property-metadata"></a> `metadata` | `unknown`             | Original meta.route metadata                                                                         | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L84) |
-| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null` | Parent route (null for root)                                                                         | [types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L82) |
-| <a id="property-path"></a> `path`         | `string`              | Route path segment (relative or absolute)                                                            | [types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L67) |
-| <a id="property-pattern"></a> `pattern?`  | `string`              | Route pattern with parameters (e.g., /profile/:userId) if path contains params                       | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L71) |
-| <a id="property-routable"></a> `routable` | `boolean`             | Whether this state is routable (has meta.route) States with meta.route can receive play.route events | [types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L78) |
-| <a id="property-stateid"></a> `stateId`   | `string`              | XState state ID this route maps to                                                                   | [types.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L73) |
+| <a id="property-children"></a> `children` | `RouteNode`[]         | Child routes                                                                                         | [types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L80) |
+| <a id="property-fullpath"></a> `fullPath` | `string`              | Full resolved path from root                                                                         | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L69) |
+| <a id="property-id"></a> `id`             | `string`              | Unique identifier (state ID)                                                                         | [types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L65) |
+| <a id="property-metadata"></a> `metadata` | `unknown`             | Original meta.route metadata                                                                         | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L84) |
+| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null` | Parent route (null for root)                                                                         | [types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L82) |
+| <a id="property-path"></a> `path`         | `string`              | Route path segment (relative or absolute)                                                            | [types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L67) |
+| <a id="property-pattern"></a> `pattern?`  | `string`              | Route pattern with parameters (e.g., /profile/:userId) if path contains params                       | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L71) |
+| <a id="property-routable"></a> `routable` | `boolean`             | Whether this state is routable (has meta.route) States with meta.route can receive play.route events | [types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L78) |
+| <a id="property-stateid"></a> `stateId`   | `string`              | XState state ID this route maps to                                                                   | [types.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L73) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteObject
 
-Defined in: [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L13)
+Defined in: [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L13)
 
 Route object with additional metadata.
 
@@ -18,4 +18,4 @@ Additional route metadata (title, breadcrumb, etc.)
 
 | Property                          | Type     | Description                             | Defined in                                                                                                            |
 | --------------------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L15) |
+| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L15) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteTree
 
-Defined in: [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L94)
+Defined in: [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L94)
 
 Complete route tree with lookup maps
 
@@ -15,6 +15,6 @@ Provides bidirectional mapping between state IDs and URL paths:
 
 | Property                                    | Type                                           | Description                                                                                       | Defined in                                                                                                              |
 | ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map full path -> route node Used to look up state ID from URL path for play.route event targeting | [types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L106) |
-| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map state ID -> route node Used to look up URL path from state ID for browser URL sync            | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L101) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                    | Root route node                                                                                   | [types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L96)   |
+| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map full path -> route node Used to look up state ID from URL path for play.route event targeting | [types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L106) |
+| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\> | Map state ID -> route node Used to look up URL path from state ID for browser URL sync            | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L101) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                    | Root route node                                                                                   | [types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L96)   |

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

@@ -0,0 +1,55 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteWatcherHandle
+
+# Interface: RouteWatcherHandle
+
+Defined in: [router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/router-bridge-base.ts#L68)
+
+Narrow interface for the TC39 Signal watcher used by `RouterBridgeBase` to
+monitor `actor.currentRoute` changes.
+
+This interface hides the full `Signal.subtle.Watcher` surface and exposes only
+the two operations that `RouterBridgeBase` actually needs:
+
+- `watch(signal)` — arm the watcher on a specific signal
+- `unwatch()` — stop watching and release resources
+
+Framework adapter subclasses never interact with this handle directly; it is
+created and managed internally by `RouterBridgeBase`.
+
+## Methods
+
+### unwatch()
+
+```ts
+unwatch(): void;
+```
+
+Defined in: [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/router-bridge-base.ts#L72)
+
+Stop observing and release the watcher.
+
+#### Returns
+
+`void`
+
+---
+
+### watch()
+
+```ts
+watch(signal): void;
+```
+
+Defined in: [router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/router-bridge-base.ts#L70)
+
+Arm the watcher to observe the given signal.
+
+#### Parameters
+
+| Parameter | Type                                                                          |
+| --------- | ----------------------------------------------------------------------------- |
+| `signal`  | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\> |
+
+#### Returns
+
+`void`

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L238)
+Defined in: [types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L238)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L254)
+Defined in: [types.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L254)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L270)
+Defined in: [types.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L270)
 
 Disconnect the router bridge from the Actor
 

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

@@ -2,7 +2,7 @@
 
 # Interface: StateVisit
 
-Defined in: [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L28)
+Defined in: [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L28)
 
 Represents a visit to a state node during graph crawling
 
@@ -10,6 +10,6 @@ Represents a visit to a state node during graph crawling
 
 | Property                              | Type                                                                                                                                                                                                                     | Description                                                    | Defined in                                                                                                            |
 | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-node"></a> `node`     | [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)                                                                                                                                                            | The state node being visited                                   | [types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L30) |
-| <a id="property-parent"></a> `parent` | \| [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)\<[`MachineContext`](https://www.jsdocs.io/package/xstate#MachineContext), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> \| `null` | Parent state node (null for root)                              | [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L34) |
-| <a id="property-path"></a> `path`     | `string`[]                                                                                                                                                                                                               | Path from root to this state (e.g., ['dashboard', 'overview']) | [types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L32) |
+| <a id="property-node"></a> `node`     | [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)                                                                                                                                                            | The state node being visited                                   | [types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L30) |
+| <a id="property-parent"></a> `parent` | \| [`StateNode`](https://www.jsdocs.io/package/xstate#StateNode)\<[`MachineContext`](https://www.jsdocs.io/package/xstate#MachineContext), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> \| `null` | Parent state node (null for root)                              | [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L34) |
+| <a id="property-path"></a> `path`     | `string`[]                                                                                                                                                                                                               | Path from root to this state (e.g., ['dashboard', 'overview']) | [types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L32) |

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

@@ -2,14 +2,14 @@
 
 # Interface: VanillaRouter
 
-Defined in: [create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-router.ts#L4)
+Defined in: [create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-router.ts#L4)
 
 ## Properties
 
 | Property                                    | Modifier   | Type                                  | Description                          | Defined in                                                                                                                            |
 | ------------------------------------------- | ---------- | ------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md) | History instance                     | [create-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-router.ts#L8)   |
-| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](RouteTree.md)           | Route tree (for structure reference) | [create-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-router.ts#L13) |
+| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md) | History instance                     | [create-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-router.ts#L8)   |
+| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](RouteTree.md)           | Route tree (for structure reference) | [create-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-router.ts#L13) |
 
 ## Methods
 
@@ -19,7 +19,7 @@ Defined in: [create-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/bl
 destroy(): void;
 ```
 
-Defined in: [create-router.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/create-router.ts#L18)
+Defined in: [create-router.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/create-router.ts#L18)
 
 Cleanup
 

package/api/@xmachines/play-router/type-aliases/RouteMetadata.md

@@ -6,6 +6,6 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/types.ts#L23)
+Defined in: [types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/types.ts#L23)
 
 Route metadata from state machine `meta.route` field.

package/api/@xmachines/play-signals/README.md

@@ -23,6 +23,7 @@ npm install @xmachines/play-signals
 ## Current Exports
 
 - `Signal` (re-export from `signal-polyfill`)
+- `watchSignal(signal, onValue)`
 - Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
 
 ## Quick Start
@@ -55,6 +56,22 @@ const dispose = () => {
 void dispose;
 ```
 
+### `watchSignal()` helper
+
+For the common case of subscribing to one signal with deterministic cleanup, use `watchSignal()`:
+
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
+
+const stopWatching = watchSignal(actor.currentRoute, (route) => {
+	console.log("Route changed:", route);
+});
+
+stopWatching();
+```
+
+`watchSignal()` preserves the same canonical watcher lifecycle described below. It is an optional helper for adapter and renderer code; raw `Signal` APIs remain the base substrate.
+
 ## Canonical Watcher Lifecycle
 
 Use one lifecycle pattern everywhere (React, Vue, Solid, router bridges, helper wrappers):
@@ -75,21 +92,12 @@ Always dispose explicitly. Do not rely on GC-only cleanup guidance.
 - Framework lifecycles (`useEffect` cleanup, `onUnmounted`, `onCleanup`) must unwatch.
 - Bridge lifecycles (`disconnect`, `dispose`) must unwatch and unsubscribe.
 
-## Optional Helper Direction
-
-Raw `Signal` remains canonical. Helper APIs are optional, additive guidance for consistency:
-
-- `watchSignals(signals, onChange, options)`
-- `createSignalEffect(effect, options)`
-- `toSubscribable(signal, options)`
-
-These helpers are intended to codify lifecycle-safe watcher scheduling and deterministic teardown. They do not replace direct `Signal` usage.
-
 ## API Surface
 
 - `Signal.State<T>`: writable signal state (`get`, `set`)
 - `Signal.Computed<T>`: lazy memoized derivations
 - `Signal.subtle.Watcher`: low-level watcher (`watch`, `unwatch`, `getPending`)
+- `watchSignal(signal, onValue)`: lifecycle-safe single-signal subscription helper
 
 ## Architecture Notes
 
@@ -174,3 +182,7 @@ consuming packages. This architectural decision protects against Stage 1 API chu
 ## Type Aliases
 
 - [WatcherNotify](type-aliases/WatcherNotify.md)
+
+## Functions
+
+- [watchSignal](functions/watchSignal.md)

package/api/@xmachines/play-signals/functions/watchSignal.md

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / watchSignal
+
+# Function: watchSignal()
+
+```ts
+function watchSignal<T>(signal, onValue): () => void;
+```
+
+Defined in: [packages/play-signals/src/watch-signal.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/watch-signal.ts#L15)
+
+Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+
+The callback runs from a queued microtask after pending notifications are
+drained, then the watcher re-arms itself so future updates are not missed.
+The returned cleanup keeps teardown idempotent by tolerating already-detached
+watchers.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter | Type                                                                                                                        | Description                                             |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `signal`  | \| [`State`](../namespaces/Signal/classes/State.md)\<`T`\> \| [`Computed`](../namespaces/Signal/classes/Computed.md)\<`T`\> | A `Signal.State` or `Signal.Computed` to subscribe to.  |
+| `onValue` | (`value`) => `void`                                                                                                         | Called with the current signal value after each change. |
+
+## Returns
+
+A cleanup function that unregisters the watcher.
+
+() => `void`

package/api/@xmachines/play-signals/interfaces/ComputedOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ComputedOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L84)
+Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L84)
 
 Options for creating Signal.Computed
 
@@ -31,4 +31,4 @@ const options: ComputedOptions<string> = {
 
 | Property                               | Type                    | Description                              | Defined in                                                                                                                                       |
 | -------------------------------------- | ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for memoization | [packages/play-signals/src/types.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L88) |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for memoization | [packages/play-signals/src/types.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L88) |

package/api/@xmachines/play-signals/interfaces/SignalComputed.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalComputed\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L111)
+Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L111)
 
 Lazily-evaluated, memoized computed signal
 
@@ -38,7 +38,7 @@ console.log(doubled.get()); // 10 (memoized, not recomputed)
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L117)
+Defined in: [packages/play-signals/src/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L117)
 
 Read computed value (recalculates only if dependencies changed)
 

package/api/@xmachines/play-signals/interfaces/SignalOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L26)
+Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L26)
 
 Options for creating Signal.State
 
@@ -32,4 +32,4 @@ const count = new Signal.State(0, options);
 
 | Property                               | Type                    | Description                                               | Defined in                                                                                                                                       |
 | -------------------------------------- | ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for determining if value changed | [packages/play-signals/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L33) |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for determining if value changed | [packages/play-signals/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L33) |

package/api/@xmachines/play-signals/interfaces/SignalState.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalState\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L53)
+Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L53)
 
 Writable state signal holding a single reactive value
 
@@ -35,7 +35,7 @@ console.log(name.get()); // 'Bob'
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L59)
+Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L59)
 
 Read current value and track as dependency
 
@@ -53,7 +53,7 @@ Current value of the signal
 set(value): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L66)
+Defined in: [packages/play-signals/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L66)
 
 Write new value and notify watchers if changed
 

package/api/@xmachines/play-signals/interfaces/SignalWatcher.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalWatcher
 
-Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L167)
+Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L167)
 
 Watcher for observing signal changes and scheduling effects
 
@@ -40,7 +40,7 @@ getPending(): (
   | SignalComputed<unknown>)[];
 ```
 
-Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L187)
+Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L187)
 
 Get signals that changed since last check
 
@@ -60,7 +60,7 @@ Array of signals that have pending updates
 unwatch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L180)
+Defined in: [packages/play-signals/src/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L180)
 
 Stop watching a signal
 
@@ -82,7 +82,7 @@ Stop watching a signal
 watch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L173)
+Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L173)
 
 Start watching a signal for changes
 

package/api/@xmachines/play-signals/type-aliases/WatcherNotify.md

@@ -6,7 +6,7 @@
 type WatcherNotify = () => void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L139)
+Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-signals/src/types.ts#L139)
 
 Notification callback for Signal.subtle.Watcher