@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L61) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,11 +2,11 @@
 
 # Interface: RouteMatch
 
-Defined in: [router-sync.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-sync.ts#L9)
+Defined in: [router-sync.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-sync.ts#L9)
 
 ## Properties
 
 | Property                               | Type                              | Defined in                                                                                                                        |
 | -------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-sync.ts#L11) |
-| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-sync.ts#L10) |
+| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-sync.ts#L11) |
+| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-sync.ts#L10) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMatcher
 
-Defined in: [create-route-matcher.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-matcher.ts#L20)
+Defined in: [create-route-matcher.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-matcher.ts#L20)
 
 URL route matcher interface returned by `createRouteMatcher()`.
 
@@ -23,7 +23,7 @@ events into `play.route` actor events.
 match(path): object;
 ```
 
-Defined in: [create-route-matcher.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-matcher.ts#L37)
+Defined in: [create-route-matcher.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-matcher.ts#L37)
 
 Match 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-matcher.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-matcher.ts#L39) |
-| `to`     | `string` \| `null`             | [create-route-matcher.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-matcher.ts#L38) |
+| `params` | `Record`\<`string`, `string`\> | [create-route-matcher.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-matcher.ts#L39) |
+| `to`     | `string` \| `null`             | [create-route-matcher.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-matcher.ts#L38) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteNode
 
-Defined in: [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L77)
+Defined in: [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L77)
 
 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:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L101) |
-| <a id="property-fullpath"></a> `fullPath` | `string`                                            | The fully resolved absolute path from the root (e.g. `"/dashboard/overview"`). Always use `fullPath` for browser URL matching and route map construction. `createRouteMapFromTree` and `createRouteMap` both use this field. | [types.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L90)   |
-| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                                                                                                                                                 | [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L79)   |
-| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                                                                                                                                                 | [types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L105) |
-| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                                                                                                                                                 | [types.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L103) |
-| <a id="property-path"></a> `path`         | `string`                                            | The raw route path segment as declared in `meta.route` — may be relative (e.g. `"overview"`) or absolute (e.g. `"/dashboard"`). Do not use this for URL matching; use `fullPath` instead.                                    | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L84)   |
-| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                                                                                                                                               | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L92)   |
-| <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:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L99)   |
-| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                                                                                                                                           | [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L94)   |
+| <a id="property-children"></a> `children` | `RouteNode`[]                                       | Child routes                                                                                                                                                                                                                 | [types.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L101) |
+| <a id="property-fullpath"></a> `fullPath` | `string`                                            | The fully resolved absolute path from the root (e.g. `"/dashboard/overview"`). Always use `fullPath` for browser URL matching and route map construction. `createRouteMapFromTree` and `createRouteMap` both use this field. | [types.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L90)   |
+| <a id="property-id"></a> `id`             | `string`                                            | Unique identifier (state ID)                                                                                                                                                                                                 | [types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L79)   |
+| <a id="property-metadata"></a> `metadata` | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original meta.route metadata                                                                                                                                                                                                 | [types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L105) |
+| <a id="property-parent"></a> `parent`     | `RouteNode` \| `null`                               | Parent route (null for root)                                                                                                                                                                                                 | [types.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L103) |
+| <a id="property-path"></a> `path`         | `string`                                            | The raw route path segment as declared in `meta.route` — may be relative (e.g. `"overview"`) or absolute (e.g. `"/dashboard"`). Do not use this for URL matching; use `fullPath` instead.                                    | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L84)   |
+| <a id="property-pattern"></a> `pattern?`  | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if path contains params                                                                                                                                               | [types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L92)   |
+| <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:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L99)   |
+| <a id="property-stateid"></a> `stateId`   | `string`                                            | XState state ID this route maps to                                                                                                                                                                                           | [types.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L94)   |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteObject
 
-Defined in: [types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L39)
+Defined in: [types.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L39)
 
 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:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L41) |
+| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L41) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteTree
 
-Defined in: [types.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L115)
+Defined in: [types.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L115)
 
 Complete route tree with lookup maps
 
@@ -15,7 +15,7 @@ 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:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L127) |
-| <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:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L122) |
-| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | Graph representation of the state machine for advanced queries. Populated by extractMachineRoutes() — use for hierarchy queries, reachability checks, and transition-aware navigation via @statelyai/graph algorithms. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L139) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | Root route node                                                                                                                                                                                                                                                                                                                                                  | [types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L117) |
+| <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:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L127) |
+| <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:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L122) |
+| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | Graph representation of the state machine for advanced queries. Populated by extractMachineRoutes() — use for hierarchy queries, reachability checks, and transition-aware navigation via @statelyai/graph algorithms. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L139) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | Root route node                                                                                                                                                                                                                                                                                                                                                  | [types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L117) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteWatcherHandle
 
-Defined in: [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-bridge-base.ts#L71)
+Defined in: [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-bridge-base.ts#L71)
 
 Narrow interface for the TC39 Signal watcher used by `RouterBridgeBase` to
 monitor `actor.currentRoute` changes.
@@ -24,7 +24,7 @@ created and managed internally by `RouterBridgeBase`.
 unwatch(): void;
 ```
 
-Defined in: [router-bridge-base.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-bridge-base.ts#L75)
+Defined in: [router-bridge-base.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-bridge-base.ts#L75)
 
 Stop observing and release the watcher.
 
@@ -40,7 +40,7 @@ Stop observing and release the watcher.
 watch(signal): void;
 ```
 
-Defined in: [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/router-bridge-base.ts#L73)
+Defined in: [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/router-bridge-base.ts#L73)
 
 Arm the watcher to observe the given signal.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L271)
+Defined in: [types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L287)
+Defined in: [types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L303)
+Defined in: [types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -2,7 +2,7 @@
 
 # Interface: WindowLike
 
-Defined in: [types.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L324)
+Defined in: [types.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L324)
 
 Minimal window interface required by adapters that subscribe to DOM events
 (e.g. `hashchange`). Injectable for SSR and testing — pass a mock instead of
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L325)
+Defined in: [types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L325)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L326)
+Defined in: [types.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L326)
 
 #### Parameters
 

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

@@ -6,7 +6,7 @@
 type MachineGraph = Graph<MachineNodeData, MachineEdgeData>;
 ```
 
-Defined in: [machine-to-graph.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/machine-to-graph.ts#L18)
+Defined in: [machine-to-graph.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/machine-to-graph.ts#L18)
 
 Typed @statelyai/graph Graph representing a state machine.
 Provides hierarchy queries, traversal algorithms, and reachability checks.

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

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

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

@@ -1,18 +1,12 @@
 [API](../../README.md) / @xmachines/play-signals
 
-# @xmachines/play-signals
-
-**Canonical Signals substrate for XMachines with Stage 1 API isolation**
+<!-- generated-by: gsd-doc-writer -->
 
-`@xmachines/play-signals` re-exports `Signal` from `signal-polyfill` as the single import boundary for XMachines packages.
-
-## Why This Package Exists
+# @xmachines/play-signals
 
-- Keep the raw `Signal` API as the canonical substrate surface.
-- Isolate Stage 1 proposal churn behind one package boundary.
-- Preserve Play invariants: Signal-only reactivity, passive infrastructure, and event-only mutation paths.
+TC39 Signals polyfill for XMachines — fine-grained reactive state primitives that enable glitch-free, subscription-free state propagation in the Play Architecture.
 
-This package does not add business behavior to signals. Adapters and renderers observe signals and forward events; they do not mutate business state directly.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
@@ -20,13 +14,27 @@ This package does not add business behavior to signals. Adapters and renderers o
 npm install @xmachines/play-signals
 ```
 
-## Current Exports
+## Overview
+
+This package wraps the [`signal-polyfill`](https://github.com/nicolo-ribaudo/tc39-proposal-signals-polyfill) reference implementation of the [TC39 Signals proposal](https://github.com/tc39/proposal-signals) (Stage 1). It re-exports the full `Signal` namespace and adds a memory-safe `watchSignal` utility, isolating the rest of the codebase from potential Stage 1 API churn.
+
+**All signal imports in the XMachines ecosystem should come from this package**, not directly from `signal-polyfill`, so that polyfill version bumps or API adaptations can be made in one place.
+
+## Usage
+
+### `Signal.State` — writable reactive state
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
 
-- `Signal` (re-export from `signal-polyfill`)
-- `watchSignal(signal, onValue)`
-- Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
+console.log(count.get()); // 0
+count.set(5);
+console.log(count.get()); // 5
+```
 
-## Quick Start
+### `Signal.Computed` — lazy memoized derived values
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -34,96 +42,120 @@ import { Signal } from "@xmachines/play-signals";
 const count = new Signal.State(0);
 const doubled = new Signal.Computed(() => count.get() * 2);
 
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const pending = watcher.getPending();
-		for (const signal of pending) {
-			signal.get();
-		}
-		watcher.watch(...pending);
-	});
-});
+console.log(doubled.get()); // 0  (computed on first access)
+count.set(5);
+console.log(doubled.get()); // 10 (recomputed because dependency changed)
+console.log(doubled.get()); // 10 (memoized — no recomputation)
+```
 
-watcher.watch(doubled);
-doubled.get();
+Computations automatically track every signal accessed inside them. Dynamic branching is fully supported — only signals read in the _current_ execution path are tracked as dependencies.
 
-count.set(2);
+### `watchSignal` — memory-safe one-shot effect
 
-const dispose = () => {
-	watcher.unwatch(doubled);
-};
+Use `watchSignal` to subscribe to a `Signal.State` or `Signal.Computed` and receive its value after each change. Updates are coalesced into a single microtask per synchronous batch.
+
+```typescript
+import { Signal, watchSignal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
 
-void dispose;
+const cleanup = watchSignal(count, (value) => {
+	console.log("count changed:", value);
+});
+
+count.set(1); // → logs "count changed: 1" (via microtask)
+count.set(2); // coalesced with any rapid synchronous changes
+count.set(3); // → logs "count changed: 3" once
+
+// Stop watching
+cleanup();
 ```
 
-### `watchSignal()` helper
+The returned cleanup function is idempotent — calling it multiple times is safe and will not throw.
+
+### `Signal.subtle.Watcher` — low-level multi-signal observation
 
-For the common case of subscribing to one signal with deterministic cleanup, use `watchSignal()`:
+For advanced use cases such as framework integrations, the full `Signal.subtle.Watcher` API is available:
 
 ```typescript
-import { watchSignal } from "@xmachines/play-signals";
+import { Signal } from "@xmachines/play-signals";
 
-const stopWatching = watchSignal(actor.currentRoute, (route) => {
-	console.log("Route changed:", route);
+const count = new Signal.State(0);
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		console.log("signals changed:", pending.length);
+		watcher.watch(...pending); // re-arm for future changes
+	});
 });
 
-stopWatching();
+watcher.watch(count);
+watcher.watch(doubled);
+
+count.set(5); // schedules microtask notification
 ```
 
-`watchSignal()` is memory-safe:
+### Custom equality
 
-- Calling the returned cleanup before a pending microtask fires will **not** invoke the callback — a `disposed` flag prevents use-after-free when components unmount with in-flight updates.
-- Rapid synchronous signal changes coalesce to **one** microtask (`needsEnqueue` guard) — the callback receives the latest value only.
-- Calling the cleanup multiple times is idempotent (no throw).
+Both `Signal.State` and `Signal.Computed` accept an `equals` option to control when dependents are notified:
 
-`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.
+```typescript
+import { Signal } from "@xmachines/play-signals";
+import type { SignalOptions } from "@xmachines/play-signals";
 
-## Canonical Watcher Lifecycle
+const options: SignalOptions<{ name: string; age: number }> = {
+	equals: (a, b) => a.name === b.name && a.age === b.age,
+};
 
-Use one lifecycle pattern everywhere (React, Vue, Solid, router bridges, helper wrappers):
+const person = new Signal.State({ name: "Alice", age: 30 }, options);
+// Setting structurally identical value will not notify dependents
+person.set({ name: "Alice", age: 30 });
+```
 
-1. `notify` callback runs.
-2. Schedule work with `queueMicrotask`.
-3. Drain `watcher.getPending()`.
-4. Perform reads/effects.
-5. Re-arm watcher with `watch()` or `watch(...signals)`.
+## API Summary
 
-Watcher notifications are one-shot. If you do not re-arm, you will miss future updates.
+| Export                         | Kind      | Description                                                                                            |
+| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
+| `Signal`                       | namespace | Full TC39 Signals namespace (`State`, `Computed`, `subtle.Watcher`) re-exported from `signal-polyfill` |
+| `watchSignal(signal, onValue)` | function  | Memory-safe subscription helper; returns a cleanup function                                            |
+| `SignalState<T>`               | interface | Shape of `Signal.State<T>` (`.get()`, `.set()`)                                                        |
+| `SignalComputed<T>`            | interface | Shape of `Signal.Computed<T>` (`.get()`)                                                               |
+| `SignalWatcher`                | interface | Shape of `Signal.subtle.Watcher` (`.watch()`, `.unwatch()`, `.getPending()`)                           |
+| `SignalOptions<T>`             | interface | Options bag for `Signal.State` constructor (`equals?`)                                                 |
+| `ComputedOptions<T>`           | interface | Options bag for `Signal.Computed` constructor (`equals?`)                                              |
+| `WatcherNotify`                | type      | Callback signature for `Signal.subtle.Watcher` notify function                                         |
 
-## Cleanup Contract
+## Testing
 
-Always dispose explicitly. Do not rely on GC-only cleanup guidance.
+Run tests for this package in isolation:
 
-- If you called `watch(...)`, call `unwatch(...)` in teardown.
-- Framework lifecycles (`useEffect` cleanup, `onUnmounted`, `onCleanup`) must unwatch.
-- Bridge lifecycles (`disconnect`, `dispose`) must unwatch and unsubscribe.
+```bash
+# From this package directory
+npm test
 
-## API Surface
+# Watch mode
+npm test -- --watch
 
-- `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
+# With coverage (lines ≥ 90 %, functions ≥ 90 %, branches ≥ 85 %, statements ≥ 90 %)
+npm run test:coverage
+```
 
-## Architecture Notes
+From the monorepo root:
 
-- **Signal-Only Reactivity (INV-05):** Signals are the reactive substrate.
-- **Passive Infrastructure (INV-04):** Adapters and frameworks only observe/forward.
-- **Actor Authority (INV-01):** Business validity and transitions stay in actors.
-- **Event-only mutation path:** Signals are not a business mutation channel.
+```bash
+npm test -w @xmachines/play-signals
+```
 
-## Resources
+## Requirements
 
-- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
-- [signal-polyfill](https://github.com/proposal-signals/signal-polyfill)
-- [Play RFC](../../../rfc/play.md)
+- **Node.js** `>= 22.0.0`
+- **TypeScript** `5.7+` (for consumers using TypeScript)
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE).
 
 TC39 Signals Polyfill for XMachines Play Architecture
 

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

@@ -6,7 +6,7 @@
 function watchSignal<T>(signal, onValue): () => void;
 ```
 
-Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-signals/src/watch-signal.ts#L21)
+Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-signals/src/watch-signal.ts#L21)
 
 Subscribe to a single signal using the canonical one-shot watcher lifecycle.
 

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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/packages/play-signals/src/types.ts#L66)
 
 Write new value and notify watchers if changed