@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,9 +2,9 @@
 
 # Interface: RouteObject
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L60)
+Defined in: [types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L45)
 
-Route object with additional metadata.
+A route object, with more metadata.
 
 ## Indexable
 
@@ -12,10 +12,10 @@ Route object with additional metadata.
 [key: string]: unknown
 ```
 
-Additional route metadata (title, breadcrumb, etc.)
+The additional metadata of the route: a title, a breadcrumb, and so on
 
 ## Properties
 
-| Property                          | Type     | Description                             | Defined in                                                                                                            |
-| --------------------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | Route path template (e.g., '/user/:id') | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L62) |
+| Property                          | Type     | Description                                             | Defined in                                                                                                    |
+| --------------------------------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `string` | The template of the route path, for example '/user/:id' | [types.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L47) |

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

@@ -2,20 +2,20 @@
 
 # Interface: RouteTree
 
-Defined in: [types.ts:136](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L136)
+Defined in: [types.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L122)
 
-Complete route tree with lookup maps
+The complete route tree, with its lookup maps
 
-Provides bidirectional mapping between state IDs and URL paths:
+It gives you the map between a state ID and a URL path, in both directions:
 
-- byStateId: Maps state IDs to route nodes (for play.route event targeting)
-- byPath: Maps URL paths to route nodes (for browser navigation)
+- byStateId: it maps each state ID to its route node, for the target of a play.route event
+- byPath: it maps each URL path to its route node, for the browser navigation
 
 ## Properties
 
-| 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:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L148) |
-| <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:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L143) |
-| <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:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L160) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | Root route node                                                                                                                                                                                                                                                                                                                                                  | [types.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L138) |
+| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                      |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a complete path to its route node. It gives you the state ID of a URL path, for the target of a play.route event                                                                                                                                                                                                                                                                       | [types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L134) |
+| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a state ID to its route node. It gives you the URL path of a state ID, for the update of the browser URL                                                                                                                                                                                                                                                                               | [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L129) |
+| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | The graph of the state machine, for an advanced query. extractMachineRoutes() fills it. Use it for a query of the hierarchy, for a test of the reachability, and for a navigation that knows the transitions, through the algorithms of @statelyai/graph. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L147) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | The root node of the routes                                                                                                                                                                                                                                                                                                                                                                         | [types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L124) |

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

@@ -2,19 +2,19 @@
 
 # Interface: RouteWatcherHandle
 
-Defined in: [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L71)
+Defined in: [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L72)
 
-Narrow interface for the TC39 Signal watcher used by `RouterBridgeBase` to
-monitor `actor.currentRoute` changes.
+The narrow interface of the TC39 Signal watcher. `RouterBridgeBase` uses it to
+observe each change of `actor.currentRoute`.
 
-This interface hides the full `Signal.subtle.Watcher` surface and exposes only
-the two operations that `RouterBridgeBase` actually needs:
+The interface hides the complete `Signal.subtle.Watcher` surface. It exposes the
+two operations that `RouterBridgeBase` needs:
 
-- `watch(signal)` — arm the watcher on a specific signal
-- `unwatch()` — stop watching and release resources
+- `watch(signal)` — it arms the watcher on one signal
+- `unwatch()` — it stops the watch and frees the resources
 
-Framework adapter subclasses never interact with this handle directly; it is
-created and managed internally by `RouterBridgeBase`.
+A framework adapter subclass touches this handle never. `RouterBridgeBase` makes
+it and manages it internally.
 
 ## Methods
 
@@ -24,9 +24,9 @@ created and managed internally by `RouterBridgeBase`.
 unwatch(): void;
 ```
 
-Defined in: [router-bridge-base.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L75)
+Defined in: [router-bridge-base.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L76)
 
-Stop observing and release the watcher.
+Stops the observation and frees the watcher.
 
 #### Returns
 
@@ -40,9 +40,9 @@ Stop observing and release the watcher.
 watch(signal): void;
 ```
 
-Defined in: [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/router-bridge-base.ts#L73)
+Defined in: [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L74)
 
-Arm the watcher to observe the given signal.
+Arms the watcher on the given signal.
 
 #### Parameters
 

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

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [types.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L360)
+Defined in: [types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L358)
 
-RouterBridge interface for runtime infrastructure adapters
+The RouterBridge interface of a runtime infrastructure adapter
 
-Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
-the Actor. Infrastructure "bridges" to the Actor by observing its signals and
-managing its own lifecycle accordingly.
+The interface defines the connection of the lifecycle between the infrastructure,
+for example a framework router, and the Actor. The infrastructure builds a "bridge"
+to the Actor: it observes the signals of the Actor, and it manages its own
+lifecycle accordingly.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
-a unidirectional observation pattern. Infrastructure connects to observe Actor signals
-(currentRoute, currentView, state) and reflects changes without making state decisions.
+**Architectural context:** the interface implements **Passive Infrastructure
+(INV-04)**, because it gives an observation in one direction. The infrastructure
+connects to observe the signals of the Actor (currentRoute, currentView, and
+state), and it reflects each change. It makes no decision about the state.
 
 ## Example
 
-Framework router bridge implementation
+The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
@@ -26,7 +28,7 @@ class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
-		// Start observing actor.currentRoute signal
+		// Start the observation of the actor.currentRoute signal
 		this.watcher = new Signal.subtle.Watcher(() => {
 			const route = actor.currentRoute.get();
 			if (route) router.navigate(route);
@@ -35,7 +37,7 @@ class MyRouterBridge implements RouterBridge {
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop observing, cleanup watchers
+		// Stop the observation, and clean the watchers up
 		this.watcher?.unwatch(actor.currentRoute);
 		this.watcher = null;
 	}
@@ -44,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -54,25 +56,26 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
+Defined in: [types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L375)
 
-Connect the router bridge to the Actor
+Connects the router bridge to the Actor
 
-Called when Infrastructure should begin observing Actor signals and
-synchronizing its state (e.g., browser URL) with Actor state.
+The infrastructure calls it when it must start the observation of the Actor
+signals, and when it must bring its own state, for example the browser URL, in line
+with the Actor state.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when connection is established, or void for synchronous connection
+The promise that resolves after the connection, or void for a synchronous connection
 
 #### Example
 
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// Bridge now observing actor.currentRoute signal
+// The bridge observes the actor.currentRoute signal now
 ```
 
 ---
@@ -83,22 +86,22 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
+Defined in: [types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L391)
 
-Disconnect the router bridge from the Actor
+Disconnects the router bridge from the Actor
 
-Called when Infrastructure should stop observing and clean up resources
-(e.g., signal watchers, event listeners).
+The infrastructure calls it when it must stop the observation and free its
+resources, for example a signal watcher and an event listener.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when disconnection is complete, or void for synchronous disconnection
+The promise that resolves after the disconnection, or void for a synchronous disconnection
 
 #### Example
 
 ```typescript
 await bridge.disconnect();
-// Bridge stopped observing, resources cleaned up
+// The bridge stopped its observation, and it freed its resources
 ```

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

@@ -2,22 +2,22 @@
 
 # Interface: WindowLike
 
-Defined in: [types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L413)
+Defined in: [types.ts:412](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L412)
 
-Minimal window interface required by adapters that subscribe to DOM events
-(e.g. `hashchange`). Injectable for SSR and testing — pass a mock instead of
-the global `window` when the DOM is unavailable.
+The minimal window interface of an adapter that subscribes to a DOM event, for
+example to `hashchange`. You can inject it for SSR and for a test: give a mock in
+place of the global `window` when no DOM is available.
 
-Defined structurally (no `Window` reference) so this package compiles without
-the DOM lib.
+The definition is structural, and it holds no reference to `Window`. This package
+therefore compiles without the DOM lib.
 
 ## Example
 
 ```typescript
-// Normal usage — global window (default)
+// The normal use — the global window, which is the default
 connectRouter({ actor, routeMap });
 
-// SSR / test — injected mock
+// SSR or a test — an injected mock
 const mockWin: WindowLike = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
 connectRouter({ actor, routeMap, window: mockWin });
 ```
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L414)
+Defined in: [types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L413)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L415)
+Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L414)
 
 #### Parameters
 

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMapping
+
+# ~~Type Alias: BaseRouteMapping~~
+
+```ts
+type BaseRouteMapping = RouteMapping;
+```
+
+Defined in: [index.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/index.ts#L61)
+
+## Deprecated
+
+Use [RouteMapping](../interfaces/RouteMapping.md). Will be removed in the next major.

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

@@ -6,10 +6,11 @@
 type MachineGraph = Graph<MachineNodeData, MachineEdgeData>;
 ```
 
-Defined in: [machine-to-graph.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/machine-to-graph.ts#L18)
+Defined in: [machine-to-graph.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/machine-to-graph.ts#L19)
 
-Typed @statelyai/graph Graph representing a state machine.
-Provides hierarchy queries, traversal algorithms, and reachability checks.
+The typed Graph of @statelyai/graph that represents a state machine.
+It gives you the queries of the hierarchy, the algorithms of a walk, and the tests
+of the reachability.
 
 ## Example
 

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

@@ -6,6 +6,6 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L70)
+Defined in: [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L55)
 
-Route metadata from state machine `meta.route` field.
+The route metadata of the `meta.route` field of a state machine.

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

@@ -1,12 +1,10 @@
 [API](../../README.md) / @xmachines/play-signals
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-signals
 
-TC39 Signals polyfill for XMachines — fine-grained reactive state primitives that enable glitch-free, subscription-free state propagation in the Play Architecture.
+TC39 Signals polyfill for XMachines. It gives the Play Architecture fine-grained reactive state primitives. The primitives propagate state without a glitch and without a subscription.
 
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
 
 ## Installation
 
@@ -16,9 +14,9 @@ pnpm add @xmachines/play-signals
 
 ## 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.
+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 complete `Signal` namespace, and it adds the memory-safe `watchSignal` utility. The wrapper keeps the rest of the code away from a Stage 1 API that can still change.
 
-**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.
+**Import every signal in the XMachines ecosystem from this package**, not from `signal-polyfill`. One import point keeps each polyfill update and each API change in one place.
 
 ## Usage
 
@@ -48,11 +46,11 @@ console.log(doubled.get()); // 10 (recomputed because dependency changed)
 console.log(doubled.get()); // 10 (memoized — no recomputation)
 ```
 
-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.
+A computation tracks each signal that it reads. A dynamic branch is safe: the computation keeps only the signals of the _current_ execution path as its dependencies.
 
 ### `watchSignal` — memory-safe one-shot effect
 
-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.
+Use `watchSignal` to subscribe to a `Signal.State` or to a `Signal.Computed`. The callback receives the value after each change. `watchSignal` groups the updates of one synchronous batch into a single microtask.
 
 ```typescript
 import { Signal, watchSignal } from "@xmachines/play-signals";
@@ -71,11 +69,11 @@ count.set(3); // → logs "count changed: 3" once
 cleanup();
 ```
 
-The returned cleanup function is idempotent — calling it multiple times is safe and will not throw.
+The cleanup function is idempotent. A second call is safe, and it does not throw.
 
 ### `Signal.subtle.Watcher` — low-level multi-signal observation
 
-For advanced use cases such as framework integrations, the full `Signal.subtle.Watcher` API is available:
+Advanced code, such as a framework integration, can use the complete `Signal.subtle.Watcher` API:
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -99,7 +97,7 @@ count.set(5); // schedules microtask notification
 
 ### Custom equality
 
-Both `Signal.State` and `Signal.Computed` accept an `equals` option to control when dependents are notified:
+Both `Signal.State` and `Signal.Computed` accept an `equals` option. The option controls when a signal notifies its dependents:
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -110,7 +108,7 @@ const options: SignalOptions<{ name: string; age: number }> = {
 };
 
 const person = new Signal.State({ name: "Alice", age: 30 }, options);
-// Setting structurally identical value will not notify dependents
+// A structurally identical value does not notify the dependents
 person.set({ name: "Alice", age: 30 });
 ```
 
@@ -119,13 +117,13 @@ person.set({ name: "Alice", age: 30 });
 | 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                                            |
+| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It 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                                         |
+| `SignalOptions<T>`             | interface | The options object for the `Signal.State` constructor (`equals?`)                                      |
+| `ComputedOptions<T>`           | interface | The options object for the `Signal.Computed` constructor (`equals?`)                                   |
+| `WatcherNotify`                | type      | The callback signature of the `Signal.subtle.Watcher` notify function                                  |
 
 ## Testing
 
@@ -152,36 +150,38 @@ pnpm run test:coverage
 ## Requirements
 
 - **Node.js** `>= 22.0.0`
-- **TypeScript** `5.7+` (for consumers using TypeScript)
+- **TypeScript** `5.7+` (for a consumer that uses TypeScript)
 
 ## License
 
 MIT — see [LICENSE](LICENSE).
 
-TC39 Signals Polyfill for XMachines Play Architecture
+The TC39 Signals polyfill of the XMachines Play Architecture
 
-Provides fine-grained reactive state primitives based on the TC39 Signals proposal (Stage 1).
-This package isolates the TC39 polyfill to protect the codebase from Stage 1 API changes.
+This package gives you the fine-grained reactive state primitives of the TC39
+Signals proposal (Stage 1). It keeps the TC39 polyfill in one place, and it
+therefore protects the code from a change of the Stage 1 API.
 
-**Architectural Context:** Implements **Signal-Only Reactivity (INV-05)** by providing
-the reactive primitives that enable Actor-to-Infrastructure communication without
-subscriptions or event emitters. All state propagation in Play Architecture uses
-TC39 Signals for automatic dependency tracking and glitch-free updates.
+**Architectural context:** the package implements **Signal-Only Reactivity
+(INV-05)**. It gives the reactive primitives that carry the communication from
+the Actor to the infrastructure, without a subscription and without an event
+emitter. Every propagation of state in the Play Architecture uses a TC39 Signal,
+which tracks each dependency and updates without a glitch.
 
 ## Example
 
-Basic Signal usage
+The basic use of a signal
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
 
-// Create state signal
+// Create a state signal
 const count = new Signal.State(0);
 
-// Create computed signal
+// Create a computed signal
 const doubled = new Signal.Computed(() => count.get() * 2);
 
-// Observe changes
+// Observe the changes
 const watcher = new Signal.subtle.Watcher(() => {
 	console.log("Count:", count.get(), "Doubled:", doubled.get());
 });
@@ -192,19 +192,21 @@ count.set(5); // Logs: Count: 5 Doubled: 10
 
 ## See
 
-- [Play RFC](../../../rfc/play.md) - Invariant INV-05
+- [Play RFC](../../../rfc/play.md) - invariant INV-05
 - [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
 
 ## Remarks
 
-**Stage 1 Status:** TC39 Signals is currently Stage 1 in the TC39 process. This package
-uses the official `signal-polyfill` reference implementation to isolate the codebase
-from potential API changes as the proposal evolves. All signal imports should go through
-this package to maintain isolation.
+**Stage 1 status:** TC39 Signals is at Stage 1 in the TC39 process now. This
+package uses the official `signal-polyfill` reference implementation. The code
+therefore stays separate from an API that can change while the proposal
+develops. Import every signal through this package, and the separation stays
+complete.
 
-**Why Isolation:** By re-exporting the polyfill through this dedicated package, we can
-update the polyfill version or adapt to API changes in one place without touching
-consuming packages. This architectural decision protects against Stage 1 API churn.
+**The reason for the separation:** this dedicated package re-exports the
+polyfill. Therefore one place holds each new polyfill version and each change of
+the API, and no consuming package changes. This architectural decision protects
+the code from a change of the Stage 1 API.
 
 ## Namespaces
 

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

@@ -6,21 +6,21 @@
 function watchSignal<T>(signal, onValue): () => void;
 ```
 
-Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/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/v2.1.0/packages/play-signals/src/watch-signal.ts#L21)
 
-Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+Subscribes to one signal, with 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.
+The callback runs from a microtask in the queue, after the watcher drains the
+notifications that wait. The watcher then arms itself again, so that it misses no
+later update. The cleanup function is idempotent, because it accepts a watcher
+that is detached already.
 
 **Memory safety (Phase 29):**
 
-- `disposed` flag prevents post-cleanup callback execution: if cleanup is
-  called before a pending microtask fires, the microtask returns early.
-- `needsEnqueue` guard dedups rapid synchronous signal changes: only one
-  microtask is ever queued per batch of synchronous mutations.
+- The `disposed` flag stops a callback after the cleanup: the microtask returns at
+  once when the cleanup runs before the microtask fires.
+- The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
+  changes: one batch of synchronous changes queues one microtask only.
 
 ## Type Parameters
 
@@ -30,13 +30,13 @@ watchers.
 
 ## 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. |
+| Parameter | Type                                                                                                                        | Description                                                           |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `signal`  | \| [`State`](../namespaces/Signal/classes/State.md)\<`T`\> \| [`Computed`](../namespaces/Signal/classes/Computed.md)\<`T`\> | The `Signal.State` or `Signal.Computed` to subscribe to.              |
+| `onValue` | (`value`) => `void`                                                                                                         | The watcher calls it with the current signal value after each change. |
 
 ## Returns
 
-A cleanup function that unregisters the watcher.
+The cleanup function. It removes the watcher.
 
 () => `void`

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

@@ -2,15 +2,15 @@
 
 # Interface: ComputedOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-signals/src/types.ts#L84)
+Defined in: [packages/play-signals/src/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L85)
 
-Options for creating Signal.Computed
+The options of a Signal.Computed
 
 ## Param
 
 **equals**
 
-Optional custom equality function for memoization
+The optional equality function of your own, for the memoization
 
 ## Example
 
@@ -31,6 +31,6 @@ const options: ComputedOptions<string> = {
 
 ## Properties
 
-| 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/v2.0.0-alpha.1/packages/play-signals/src/types.ts#L88) |
+| Property                               | Type                    | Description                                            | Defined in                                                                                                                               |
+| -------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own, for the memoization | [packages/play-signals/src/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L89) |