@xmachines/play-xstate 4.0.0 → 5.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @xmachines/play-xstate
 
-> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with signal-driven reactivity and a router integration.
+> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with atom-driven reactivity and a router integration.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
@@ -13,10 +13,24 @@
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-xstate xstate
+pnpm add @xmachines/play-xstate @xmachines/play @xmachines/play-atom xstate
 ```
 
-`xstate ^5.33.0` is a peer dependency. Install it with this package.
+**Peer dependencies.** Install them with the package:
+
+- [`@xmachines/play`](../play/README.md) — the core protocol. This package reads `shallowEqualExcept` and `DISPOSE` from it.
+- [`@xmachines/play-atom`](../play-atom/README.md) — the atom primitives. `PlayerActor` holds `currentView` and `currentRoute` as atoms.
+- `xstate` ^5.33.0 — the XState v5 runtime.
+
+**Optional peers.** Each capability subpath carries one. Install it when you read that subpath, and not before:
+
+```bash
+pnpm add @xmachines/play-router   # @xmachines/play-xstate/routing
+pnpm add @xmachines/play-view     # @xmachines/play-xstate/view
+```
+
+- [`@xmachines/play-router`](../play-router/README.md) — the routing capability reads `Routable`, `PlayRouteEvent` and `RouteData` from it.
+- [`@xmachines/play-view`](../play-view/README.md) — the view capability reads `composePlayState`, `PlaySpec` and `Viewable` from it.
 
 ---
 
@@ -43,7 +57,7 @@ const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRou
 const actor = createPlayer();
 actor.start();
 
-// 4. Observe TC39 Signal-based reactive state
+// 4. Observe atom-based reactive state
 console.log(actor.currentRoute.get()); // "/"
 console.log(actor.state.get().value); // "idle"
 
@@ -132,13 +146,13 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-This concrete actor class is an XState v5 actor that exposes reactive TC39 Signals. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
+This concrete actor class is an XState v5 actor that exposes reactive atoms. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
 
-#### Signals
+#### Atoms
 
-| Signal  | Type                                   | Description                                                                  |
-| ------- | -------------------------------------- | ---------------------------------------------------------------------------- |
-| `state` | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+| Atom    | Type                           | Description                                                                  |
+| ------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `state` | `Atom<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
 
 ### The capabilities
 
@@ -154,12 +168,12 @@ pnpm add @xmachines/play-view     # for @xmachines/play-xstate/view
 The main entry point of this package names neither. `@xmachines/play-xstate/routing` also
 carries the route utilities — `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
 `formatPlayRouteTransitions` and the route types — because each one names
-`@xmachines/play-router` in its own types.
+[`@xmachines/play-router`](../play-router/README.md) in its own types.
 
-| Capability | Entry point                      | Adds                           | Interface                              |
-| ---------- | -------------------------------- | ------------------------------ | -------------------------------------- |
-| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of `@xmachines/play-router` |
-| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of `@xmachines/play-view`   |
+| Capability | Entry point                      | Adds                           | Interface                                                          |
+| ---------- | -------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of [`@xmachines/play-router`](../play-router/README.md) |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of [`@xmachines/play-view`](../play-view/README.md)     |
 
 `compose` applies each capability from left to right:
 
@@ -181,7 +195,7 @@ const createRouted = definePlayer({ machine, actor: compose(PlayerActor, withRou
 const createBare = definePlayer({ machine });
 ```
 
-**Compose `withView` after `withRouting`.** An override calls `super.onSnapshot()` first, so the composition order decides the derivation order: the route holds its new value before the view derives from the same transition. A router bridge therefore sees a guard redirect before a renderer sees the view of the state that the guard refused.
+**The composition ORDER decides nothing.** `currentRoute` and `currentView` are computed atoms over `state`, and neither reads the other, so one write for each transition reaches both and the engine evaluates them in topological order. A router bridge therefore sees a guard redirect and a renderer sees the view of the same snapshot, whatever order `compose` applied. A release before this one wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there.
 
 **A lifecycle hook receives the bare actor.** `PlayerOptions` is typed before the class is composed, so it cannot name the capabilities, and a narrower hook parameter is refused under `strictFunctionTypes`. A hook that reads `currentRoute` or `currentView` reads them through a binding of the composed type:
 
@@ -196,11 +210,27 @@ const actor = definePlayer({
 composed = actor;
 ```
 
-| Signal         | Type                              | Capability | Description                                                                                                                              |
-| -------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `currentRoute` | `Signal.Computed<string \| null>` | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
-| `initialRoute` | `readonly string \| null`         | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
-| `currentView`  | `Signal.State<PlaySpec \| null>`  | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
+| Atom           | Type                             | Capability | Description                                                                                                                              |
+| -------------- | -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentRoute` | `ReadonlyAtom<string \| null>`   | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
+| `initialRoute` | `readonly string \| null`        | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
+| `currentView`  | `ReadonlyAtom<PlaySpec \| null>` | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
+
+`state` is the ONE atom that the actor writes. `currentRoute` and `currentView` are
+COMPUTED over it, so one write for each transition reaches both in one propagation and no
+observer reads the new state beside an old derivation. Each derivation reports a failure
+through the `onError` option and keeps its last good value; it throws never, because it
+runs inside the write.
+
+**`currentRoute` notifies on every transition, and `currentView` notifies on a change of
+the view alone.** The two atoms answer two different questions. A router bridge needs the
+answer of the actor to each event that it proposed, and a guard that refuses an inbound
+location and holds the machine where it was derives the SAME path — so `currentRoute`
+compares "different" always, and the bridge learns that the address bar must go back.
+`currentView` gates its emission on the value, and a snapshot that changes no view on the
+screen keeps the previous reference, so a provider below it mounts the UI again not on
+every event. Debounce your own `watchAtom(actor.currentRoute, ...)` callback, or compare
+the path yourself, when you run work that belongs to a change of the route alone.
 
 #### Methods
 
@@ -213,19 +243,19 @@ composed = actor;
 | `getSnapshot()` | Returns the current XState snapshot                                       |
 | `[DISPOSE]()`   | Stops the actor at the end of a `using` scope. The release is `stop()`    |
 
-#### Signal usage example
+#### Atom usage example
 
 ```typescript
-import { Signal } from "@xmachines/play-signals";
+import { watchAtom } from "@xmachines/play-atom";
 
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		console.log("Route changed:", actor.currentRoute.get());
-	});
+const stop = watchAtom(actor.currentRoute, (route) => {
+	console.log("Route changed:", route);
 });
 
-watcher.watch(actor.currentRoute);
 actor.start();
+
+// Later, on teardown
+stop();
 ```
 
 ---
@@ -371,7 +401,7 @@ import type {
 ```
 
 `RouteObject`, `RouteMetadata`, `RouteData`, and `RouteDataResolver` have one
-definition, and it lives in `@xmachines/play-router`. `@xmachines/play-xstate/routing`
+definition, and it lives in [`@xmachines/play-router`](../play-router/README.md). `@xmachines/play-xstate/routing`
 re-exports them, so either import path gives you the same type. The MAIN entry point of
 this package re-exports them no longer: it would name an optional peer in the types of
 every consumer, including one that composes no routing.
@@ -435,6 +465,7 @@ The `@xmachines/play-xstate/errors` subpath exports the error classes. The main
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
+	InvalidRouteParamError, // A :param carries a dot segment, which a URL resolves away
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
@@ -444,7 +475,7 @@ import {
 } from "@xmachines/play-xstate/errors";
 ```
 
-Every error class extends `PlayError` from `@xmachines/play/errors`. Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
+Every error class extends `PlayError` from [`@xmachines/play/errors`](../play/README.md). Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
 
 ---
 

package/dist/capabilities.d.ts

@@ -7,9 +7,10 @@
  * and an application that declares no route loads no routing code.
  *
  * {@link compose} applies each capability from left to right, so the LAST one is the
- * outermost class. That is also the order in which `onSnapshot` derives: an override calls
- * `super.onSnapshot()` first, so `compose(PlayerActor, withRouting, withView)` gives the
- * route its new value before the view reads it.
+ * outermost class. The ORDER decides no value: a capability that publishes one derives it
+ * with a computed atom over `state`, and the engine evaluates every derivation from the
+ * one write of a transition, in topological order. `onSnapshot` remains for a capability
+ * that must run an EFFECT, and an override of it still calls `super.onSnapshot()` first.
  *
  * ## Why the types read this way
  *

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAC5B,QAAQ,SAAS,eAAe,EAChC,aAAa,SAAS,MAAM,GAAG,MAAM,IAClC,KACH,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAChC,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,gBAAgB,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,KACjD,WAAW,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,eAAe,EAAE,MAAM,SAAS,MAAM,IAAI,CACjF,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,KAC7B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EACvD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAC/B,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAC3E,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACpC,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAC/F,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;AAC1C,wBAAgB,OAAO,CACtB,QAAQ,SAAS,eAAe,EAChC,GAAG,SAAS,MAAM,EAClB,GAAG,SAAS,MAAM,EAClB,GAAG,SAAS,MAAM,EAElB,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAC5B,QAAQ,SAAS,eAAe,EAChC,aAAa,SAAS,MAAM,GAAG,MAAM,IAClC,KACH,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAChC,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,gBAAgB,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,KACjD,WAAW,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,eAAe,EAAE,MAAM,SAAS,MAAM,IAAI,CACjF,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,KAC7B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EACvD,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAC/B,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAC3E,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACpC,wBAAgB,OAAO,CAAC,QAAQ,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAC/F,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;AAC1C,wBAAgB,OAAO,CACtB,QAAQ,SAAS,eAAe,EAChC,GAAG,SAAS,MAAM,EAClB,GAAG,SAAS,MAAM,EAClB,GAAG,SAAS,MAAM,EAElB,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC7B,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,GAC3B,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC"}

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AA4HA,MAAM,UAAU,OAAO,CACtB,IAAiC,EACjC,GAAG,YAEF;IAED,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AA6HA,MAAM,UAAU,OAAO,CACtB,IAAiC,EACjC,GAAG,YAEF;IAED,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC"}

package/dist/errors.d.ts

@@ -35,6 +35,44 @@ export declare class MissingRouteParamError extends PlayError {
     readonly template: string;
     constructor(param: string, template: string);
 }
+/**
+ * `buildRouteUrl()` throws this error when a route parameter carries a value that no path
+ * can hold, so the template matches the built URL back never.
+ *
+ * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
+ * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
+ * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
+ * address bar shows `/`, and the two stay out of step for the rest of the session.
+ *
+ * Give the param a value that names a segment. Machine state that can carry a path from a
+ * user belongs behind a check of its own, in the same way that a base path checks the
+ * values of its `:param` segments.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
+ *
+ * @example
+ * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+ * import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
+ * } catch (err) {
+ *   if (err instanceof InvalidRouteParamError) {
+ *     console.error(`"${err.value}" cannot stand in "${err.param}"`);
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidRouteParamError extends PlayError {
+    /** The name of the route parameter that carries the value, for example `"name"`. */
+    readonly param: string;
+    /** The value that no path can hold, for example `".."`. */
+    readonly value: string;
+    /** The route template that declares the parameter, for example `"/files/:name"`. */
+    readonly template: string;
+    constructor(param: string, value: string, template: string);
+}
 /**
  * `formatPlayRouteTransitions()` throws this error when a state node declares a
  * `meta.route` field but no explicit `id` field.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAsBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAqBD;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,OAAO,EAAE,MAAM,SAA+B;CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAsBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAW1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAqBD;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,OAAO,EAAE,MAAM,SAA+B;CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}

package/dist/errors.js

@@ -61,6 +61,50 @@ export class MissingRouteParamError extends PlayError {
         this.template = template;
     }
 }
+/**
+ * `buildRouteUrl()` throws this error when a route parameter carries a value that no path
+ * can hold, so the template matches the built URL back never.
+ *
+ * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
+ * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
+ * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
+ * address bar shows `/`, and the two stay out of step for the rest of the session.
+ *
+ * Give the param a value that names a segment. Machine state that can carry a path from a
+ * user belongs behind a check of its own, in the same way that a base path checks the
+ * values of its `:param` segments.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
+ *
+ * @example
+ * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+ * import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
+ * } catch (err) {
+ *   if (err instanceof InvalidRouteParamError) {
+ *     console.error(`"${err.value}" cannot stand in "${err.param}"`);
+ *   }
+ * }
+ * ```
+ */
+export class InvalidRouteParamError extends PlayError {
+    /** The name of the route parameter that carries the value, for example `"name"`. */
+    param;
+    /** The value that no path can hold, for example `".."`. */
+    value;
+    /** The route template that declares the parameter, for example `"/files/:name"`. */
+    template;
+    constructor(param, value, template) {
+        super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_INVALID", `Route parameter '${param}' of template '${template}' carries the value '${value}', which resolves away in a URL.`);
+        this.name = "InvalidRouteParamError";
+        this.param = param;
+        this.value = value;
+        this.template = template;
+    }
+}
 /**
  * `formatPlayRouteTransitions()` throws this error when a state node declares a
  * `meta.route` field but no explicit `id` field.

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -2,11 +2,11 @@
  * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
  * This package gives you the definePlayer() API. That function binds an XState state
- * machine to the actor base, with the signal lifecycle and the DevTools
+ * machine to the actor base, with the atom lifecycle and the DevTools
  * integration.
  *
  * The Play RFC gives this package as the adapter of the logic layer. It converts a
- * declarative machine definition into a live actor with a signal-driven
+ * declarative machine definition into a live actor with an atom-driven
  * reactivity.
  *
  * @packageDocumentation

package/dist/index.js

@@ -2,11 +2,11 @@
  * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
  * This package gives you the definePlayer() API. That function binds an XState state
- * machine to the actor base, with the signal lifecycle and the DevTools
+ * machine to the actor base, with the atom lifecycle and the DevTools
  * integration.
  *
  * The Play RFC gives this package as the adapter of the logic layer. It converts a
- * declarative machine definition into a live actor with a signal-driven
+ * declarative machine definition into a live actor with an atom-driven
  * reactivity.
  *
  * @packageDocumentation

package/dist/player-actor.d.ts

@@ -1,7 +1,7 @@
 import { Actor, type AnyStateMachine, type AnyMachineSnapshot, type InputFrom, type ActorOptions, type Observer, type Snapshot, type SnapshotFrom, type Subscription, type EventFromLogic } from "xstate";
 import type { PlayActor } from "@xmachines/play-actor";
 import { DISPOSE } from "@xmachines/play";
-import { Signal } from "@xmachines/play-signals";
+import type { Atom } from "@xmachines/play-atom";
 import type { PlayerOptions } from "./types.js";
 /**
  * Normalizes a failure of the actor for `onError`.
@@ -16,7 +16,7 @@ import type { PlayerOptions } from "./types.js";
  */
 export declare const toError: (value: unknown) => Error;
 /**
- * The concrete XState actor. It implements the signal protocol of the Play Architecture
+ * The concrete XState actor. It implements the atom protocol of the Play Architecture
  *
  * The class extends the `Actor` class of XState directly, and it implements
  * {@link @xmachines/play-actor!PlayActor}. It gives you the XState v5 integration, and it keeps the
@@ -24,7 +24,7 @@ export declare const toError: (value: unknown) => Error;
  * The constructor of the base class receives the machine. Therefore a `PlayerActor`
  * **is** the XState actor, and it is no wrapper around one: every member of the
  * XState `Actor` class works on the state of this instance, and this class adds the
- * reactive state on the TC39 Signals for the observation by the infrastructure.
+ * reactive state on the atoms for the observation by the infrastructure.
  *
  * **Capabilities:** the class implements both the
  * {@link @xmachines/play-router!index.Routable} interface and the
@@ -33,7 +33,7 @@ export declare const toError: (value: unknown) => Error;
  *
  * **Architectural context:** the class implements **Actor Authority (INV-01)**,
  * because the guards of the XState machine control every decision of the
- * navigation. The infrastructure observes the signals of the actor (`state`,
+ * navigation. The infrastructure observes the atoms of the actor (`state`,
  * `currentRoute`, and `currentView`), but it changes no state directly: every
  * change goes through the event handlers of the state machine.
  *
@@ -65,31 +65,29 @@ export declare const toError: (value: unknown) => Error;
  * const actor = createPlayer();
  * actor.start();
  *
- * // Observe the signals
+ * // Observe the atoms
  * console.log(actor.currentRoute.get());          // '/'
  * console.log(actor.currentView.get()?.root);     // 'home'
  * ```
  *
  * @example
- * The signal lifecycle with a watcher
+ * The atom lifecycle with a watch
  * ```typescript
- * import { Signal } from "@xmachines/play-signals";
+ * import { watchAtom } from "@xmachines/play-atom";
  *
- * const watcher = new Signal.subtle.Watcher(() => {
- *   queueMicrotask(() => {
- *     const pending = watcher.getPending();
- *     console.log('State changed:', actor.state.get());
- *   });
+ * const stop = watchAtom(actor.state, (snapshot) => {
+ *   console.log('State changed:', snapshot.value);
  * });
  *
- * watcher.watch(actor.state);
  * actor.send({ type: 'play.route', to: '#about' });
- * // The watcher schedules its own notification in a microtask
+ * // watchAtom delivers the new value from a microtask
+ *
+ * stop();
  * ```
  *
  * @see [Play RFC](../../docs/rfc/play.md)
  * @see {@link definePlayer} for the creation through a factory
- * @see {@link @xmachines/play-actor!PlayActor} for the signal protocol
+ * @see {@link @xmachines/play-actor!PlayActor} for the atom protocol
  * @see {@link @xmachines/play-router!index.Routable} for the routing capability
  * @see {@link @xmachines/play-view!index.Viewable} for the view rendering capability
  *
@@ -99,10 +97,11 @@ export declare const toError: (value: unknown) => Error;
  * `meta.route`, which is the Stately pattern, for a URL template, and it substitutes
  * each parameter.
  *
- * **The pattern of the view signal:** the `currentView` signal is a direct
- * `Signal.State`, and not a `Signal.Computed`. The propagation to a watcher in
- * PlayRenderer is therefore correct. The class derives each view at the entry of a
- * state and keeps it, and it computes no view on a read.
+ * **The pattern of the view atom:** `withView` of `@xmachines/play-xstate/view` adds
+ * `currentView`, and that atom is a COMPUTED atom over `state`. One write for each
+ * transition — `state.set(snapshot)` — therefore reaches the view and the route in one
+ * flush, and no subscriber reads the new state beside an old derivation. The atom
+ * memoizes the result, so a repeated read computes no view again.
  */
 export declare class PlayerActor<TMachine extends AnyStateMachine> extends Actor<TMachine> implements PlayActor<ReturnType<TMachine["transition"]>, EventFromLogic<TMachine>> {
     private playerOptions?;
@@ -162,12 +161,12 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Actor
      * times.
      */
     private nextOnlySubscriptions?;
-    state: Signal.State<ReturnType<TMachine["transition"]>>;
+    state: Atom<ReturnType<TMachine["transition"]>>;
     /**
      * Tells you if the current state of the actor accepts the given event.
      *
      * The type is the event union of the machine. An unknown event type is therefore a
-     * compile error. The method evaluates the event against the snapshot signal.
+     * compile error. The method evaluates the event against the snapshot atom.
      *
      * @example
      * ```typescript
@@ -248,17 +247,19 @@ export declare class PlayerActor<TMachine extends AnyStateMachine> extends Actor
      */
     getPersistedSnapshot(options?: unknown): Snapshot<unknown>;
     /**
-     * The point where a capability derives its own signals from a new snapshot.
+     * The point where a capability derives its own atoms from a new snapshot.
      *
      * The base derives nothing: `PlayActor` asks for `state` and `send`, and this class
-     * gives exactly those. A capability is a mixin that overrides this method, calls
-     * `super.onSnapshot(snapshot)` FIRST, and then writes its own signal.
+     * gives exactly those.
+     *
+     * A capability that PUBLISHES a value overrides this method NOT. It derives the value
+     * with a computed atom over `state`, as `withRouting` and `withView` both do, and the
+     * engine then evaluates every derivation from the one write of a transition, in
+     * topological order. The composition order therefore decides no value.
      *
-     * That one rule fixes the order, and the order is load-bearing. The view of a state
-     * reads the route and the state that the same transition produced, and a router bridge
-     * must see a guard redirect synchronously. `compose(PlayerActor, withRouting, withView)`
-     * therefore derives the route before the view, because `withView` wraps the class that
-     * `withRouting` returned.
+     * This method remains for a capability that must run an EFFECT on a transition. Such a
+     * mixin overrides it and calls `super.onSnapshot(snapshot)` FIRST, so that every
+     * capability composed before it runs its own effect first.
      *
      * The method runs after `state` holds the new snapshot and before the `onStateChange`
      * hook of the options.

package/dist/player-actor.d.ts.map

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