@xmachines/play-xstate 2.2.0 → 4.0.0

package/README.md

@@ -2,17 +2,21 @@
 
 > 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.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
+> **Browser floor: Chrome 110, Firefox 115, Safari 16.4.** This package calls the ES2023
+> change-by-copy array methods, so a browser below that floor throws
+> `TypeError: ... is not a function`. The root README carries the table.
+
 ## Installation
 
 ```bash
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency. Install it with this package.
+`xstate ^5.33.0` is a peer dependency. Install it with this package.
 
 ---
 
@@ -20,7 +24,8 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
 // 1. Define your XState v5 machine
 const machine = setup({}).createMachine({
@@ -32,7 +37,7 @@ const machine = setup({}).createMachine({
 });
 
 // 2. Create a player factory
-const createPlayer = definePlayer({ machine });
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
 
 // 3. Instantiate and start an actor
 const actor = createPlayer();
@@ -127,16 +132,75 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-This concrete actor class is an XState v5 actor that also exposes reactive TC39 Signals. It implements both the `Routable` interface and the `Viewable` interface from `@xmachines/play-actor`.
+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`.
 
 #### Signals
 
-| Signal         | Type                                   | Description                                                                                                                             |
-| -------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition                                                            |
-| `currentRoute` | `Signal.Computed<string \| null>`      | The URL that comes from the `meta.route` template of the active state and from the context                                              |
-| `currentView`  | `Signal.State<PlaySpec \| null>`       | The view spec from the `meta.view` metadata of the active state, with the context params added                                          |
-| `initialRoute` | `readonly string \| null`              | The route of the initial state of the machine. The constructor fixes it, and a router bridge uses it to detect a deep link or a restore |
+| Signal  | Type                                   | Description                                                                  |
+| ------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `state` | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+
+### The capabilities
+
+Routing and the view are OPTIONAL, and each one is a mixin behind its own entry point. An application that declares no route loads no routing code, and an application that renders no view loads no view code and installs no json-render.
+
+Each capability package is an OPTIONAL peer dependency. Install the one that you compose:
+
+```bash
+pnpm add @xmachines/play-router   # for @xmachines/play-xstate/routing
+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.
+
+| 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`   |
+
+`compose` applies each capability from left to right:
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+// Both capabilities
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+
+// Routing alone: `currentView` is a compile error on this actor
+const createRouted = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+
+// Neither: `state` and `send`
+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.
+
+**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:
+
+```typescript
+let composed: PlayerActor<typeof machine> & Routable & Viewable;
+
+const actor = definePlayer({
+	machine,
+	options: { onStateChange: () => console.log(composed.currentRoute.get()) },
+	actor: compose(PlayerActor, withRouting, withView),
+})();
+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                                           |
 
 #### Methods
 
@@ -147,7 +211,7 @@ This concrete actor class is an XState v5 actor that also exposes reactive TC39
 | `send(event)`   | Sends a typed event to the machine and calls the `onTransition` hook      |
 | `can(event)`    | Returns `true` when the current state accepts the given event             |
 | `getSnapshot()` | Returns the current XState snapshot                                       |
-| `dispose()`     | The alias of `stop()`                                                     |
+| `[DISPOSE]()`   | Stops the actor at the end of a `using` scope. The release is `stop()`    |
 
 #### Signal usage example
 
@@ -166,39 +230,26 @@ actor.start();
 
 ---
 
-### Guard utilities
+### Guards
 
-> **Deprecated:** these guard helpers wrap the `and()`, `or()`, and `not()`
-> combinators of XState, but they do not compose with a guard slot that
-> `setup()` types. Use the combinators of XState directly. The next major
-> version removes this module.
-
-These composable guard helpers wrap the `and()`, `or()`, and `not()` functions of XState. Use them in a machine `setup({ guards })` definition.
+This package gives no guard utility. Compose a guard with the `and()`, `or()` and `not()` combinators of XState:
 
 ```typescript
-import { setup } from "xstate";
-import {
-	composeGuards, // AND logic: all guards must pass
-	composeGuardsOr, // OR logic:  at least one guard must pass
-	negateGuard, // NOT logic: inverts a guard
-	hasContext, // guard: context field is present and non-null
-	eventMatches, // guard: event type matches a string
-	contextFieldMatches, // guard: context field equals a value
-} from "@xmachines/play-xstate";
+import { and, not, setup } from "xstate";
 
 const machine = setup({
 	guards: {
-		isLoggedIn: ({ context }) => !!context.userId,
+		isLoggedIn: ({ context }) => context.userId !== "",
 		hasAdminRole: ({ context }) => context.role === "admin",
 	},
 }).createMachine({
 	on: {
 		accessAdmin: {
-			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
+			guard: and(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
 		accessLogin: {
-			guard: negateGuard("isLoggedIn"),
+			guard: not("isLoggedIn"),
 			target: "login",
 		},
 	},
@@ -206,6 +257,10 @@ const machine = setup({
 });
 ```
 
+A combinator resolves each name against the `guards` of `setup()`. A name that the map does not hold therefore fails to compile, and it names the fault: `Type '"typoGuardName"' is not assignable to type '"isLoggedIn"'`.
+
+`composeGuards`, `composeGuardsOr`, `negateGuard`, `hasContext`, `eventMatches` and `contextFieldMatches` stood here before. They closed two gaps of the types of XState 5.28. The peer floor of this package is `^5.33.0`, and 5.33 holds neither gap. The helpers also fitted a guard slot that `setup()` types never: the example of this package reached them through an `as never` cast. Write the combinator instead, and write a plain predicate in place of each helper.
+
 ---
 
 ### Routing utilities
@@ -218,7 +273,7 @@ This function reads each machine state that has a `meta.route` field. It then ge
 
 ```typescript
 import { setup } from "xstate";
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
@@ -249,6 +304,12 @@ const machine = setup({}).createMachine(config);
 | `isAbsoluteRoute(route)`           | Returns `true` when the route string is an absolute URL path                |
 | `buildRouteUrl(template, context)` | Replaces each `:param` placeholder of a route template with a context value |
 
+#### The release protocol
+
+`DISPOSE` comes from [`@xmachines/play`](../play/README.md), and this package re-exports
+it, because `PlayerActor` carries `[DISPOSE]`: a scope releases an actor with `using` and
+writes no teardown.
+
 ---
 
 ## Inspection
@@ -296,17 +357,75 @@ import type {
 	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // deprecated with the guard utilities — removed in the next major
-	GuardArray, // deprecated with the guard utilities — removed in the next major
-	ComposedGuard, // deprecated with the guard utilities — removed in the next major
+} from "@xmachines/play-xstate";
+
+import type {
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
-	RouteObject, // Route metadata object shape: { path: string }
+	RouteObject, // Route metadata object shape: { path, reenter?, handler?, data? }
 	RouteMetadata, // Union: string | RouteObject
-} from "@xmachines/play-xstate";
+	RouteData, // The resolved extra data of a route: Record<string, unknown>
+	RouteDataResolver, // The function form of RouteObject.data
+} from "@xmachines/play-xstate/routing";
+```
+
+`RouteObject`, `RouteMetadata`, `RouteData`, and `RouteDataResolver` have one
+definition, and it lives in `@xmachines/play-router`. `@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.
+
+### The object form of `meta.route`
+
+The string form declares the path only. The object form declares the path and the
+behaviour of the generated `play.route` transition:
+
+```typescript
+meta: {
+	route: {
+		path: "/doc/:docId",
+		// Where the generated transition sits. The default is "root", which is what
+		// XState does: every route transition sits on the root of the machine.
+		//   "root"  — one transition on the root. A route from any state arrives.
+		//   "local" — one transition on the PARENT. The parent keeps its entry action,
+		//             and a route from outside the parent arrives NOWHERE.
+		//   "both"  — one in each place. The parent keeps its entry action, and a route
+		//             from outside the parent still arrives.
+		handler: "both",
+		// Whether the transition re-enters its OWN DOMAIN. The default is false, which
+		// is the default of XState. Under `handler: "root"` the domain is the root of
+		// the machine, so `false` spares the root alone: each ancestor between the root
+		// and the target still runs its exit and its entry actions. `handler` is the
+		// field that spares those intermediate ancestors.
+		reenter: false,
+		// The extra data of the route. The generated transition assigns it to
+		// `context.data`. A literal value, or a function of { context, event }.
+		data: { titleKey: "doc.view" },
+	},
+}
 ```
 
+An unknown `handler` value throws `InvalidRouteHandlerError` at the format time.
+
+> **Upgrading from 3.x: the `reenter` default changed, and a machine that relies on it
+> goes quiet.** An earlier release wrote `reenter: true` on EVERY generated transition,
+> so every routed state re-entered its own domain on each navigation and ran its `entry`
+> actions again. The flag is now what `meta.route` declares, and the default is `false` —
+> which is the default of XState. A state whose `entry` action must run on each
+> navigation has to declare `reenter: true` for itself. Nothing throws, and the action
+> simply stops running.
+
+The `data` field follows the `WithDynamicParams` shape of XState, so the function form
+reads the context and the event:
+
+```typescript
+data: ({ context, event }) => ({ title: `Document ${event.params?.docId}` });
+```
+
+A function does not survive `JSON.stringify`. Use the literal form for a machine that
+Stately Studio reads, or that a process sends over a wire.
+
 ---
 
 ## Error Classes
@@ -316,31 +435,16 @@ The `@xmachines/play-xstate/errors` subpath exports the error classes. The main
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // deprecated: no longer thrown
 	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
 	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
-	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
+	InvalidRouteHandlerError, // meta.route.handler is not "root", "local", or "both"
 } from "@xmachines/play-xstate/errors";
 ```
 
-Every error class extends `PlayError` from `@xmachines/play`. Each class also carries typed detail fields, such as `param`, `template`, and `combinator`. Your code therefore reads the details of an error, and it does not parse the message.
-
----
-
-## Testing
-
-```bash
-# Run tests for this package in isolation
-pnpm --filter @xmachines/play-xstate test
-
-# Watch mode
-pnpm --filter @xmachines/play-xstate run test:watch
-```
-
-The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/test/`.
+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.
 
 ---
 

package/dist/capabilities.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The composition of the optional capabilities of an actor.
+ *
+ * `PlayerActor` gives the protocol of `PlayActor` and nothing else: `state` and
+ * `send`. Routing and the view are capabilities, each one a MIXIN in a module that the
+ * core imports never. An application that renders no view therefore loads no view code,
+ * 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.
+ *
+ * ## Why the types read this way
+ *
+ * A capability is typed by the INSTANCE that it extends, and not by a type parameter for
+ * the class. That one decision removes three problems at once:
+ *
+ * - A class that extends a TYPE PARAMETER must constrain it to `new (...args: any[])`, and
+ *   TypeScript reports TS2545 for every other spelling. A concrete constructor type needs
+ *   no `any`.
+ * - A mixin that INFERS its return type emits no declaration: `Actor` of XState carries
+ *   private members such as `_actorScope`, and an anonymous class that holds one is not
+ *   nameable (TS4094).
+ * - A conditional return type cannot be checked against the class that a mixin builds, so
+ *   it forces `as unknown as` at the return. Nothing here asserts anything.
+ *
+ * `TCapabilities` carries what the base already added, so a composed constructor names
+ * every capability on its instance. {@link compose} is what accumulates them:
+ * `compose(PlayerActor, withRouting, withView)` answers an actor that is `Routable` AND
+ * `Viewable`. Each capability declares a FIXED return type, so the nested form
+ * `withView(withRouting(PlayerActor))` answers `Viewable` alone.
+ */
+import type { ActorOptions, AnyStateMachine, InputFrom } from "xstate";
+import type { PlayerActor } from "./player-actor.js";
+import type { PlayerOptions } from "./types.js";
+/**
+ * The constructor of a `PlayerActor`, with every capability that it carries already.
+ *
+ * The argument list is the one that `PlayerActor` declares, so `definePlayer` builds an
+ * actor with the arguments checked, whatever the composition added to the instance.
+ *
+ * @typeParam TMachine - The machine of the actor.
+ * @typeParam TCapabilities - What the capabilities added, for example `Routable & Viewable`.
+ */
+export type PlayerConstructor<TMachine extends AnyStateMachine, TCapabilities extends object = object> = new (machine: TMachine, options: PlayerOptions<TMachine>, input?: InputFrom<TMachine>, restoredSnapshot?: ActorOptions<TMachine>["snapshot"]) => PlayerActor<TMachine> & TCapabilities;
+/**
+ * One capability of an actor: a function that takes an actor class and answers the same
+ * class with `TAdded` on the instance.
+ *
+ * `withRouting` of `@xmachines/play-xstate/routing` and `withView` of
+ * `@xmachines/play-xstate/view` are the two that this package ships. Write your own with
+ * the same shape, and {@link compose} takes it beside them.
+ *
+ * @typeParam TMachine - The machine of the actor.
+ * @typeParam TAdded - What the capability adds to the instance, for example `Routable`.
+ */
+export type Capability<TMachine extends AnyStateMachine, TAdded extends object> = (Base: PlayerConstructor<TMachine>) => PlayerConstructor<TMachine, TAdded>;
+/**
+ * Builds an actor class from a base and a list of capabilities.
+ *
+ * It applies each capability from left to right, so the LAST one is the outermost class,
+ * and the return type accumulates what each one adds:
+ * `compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.
+ *
+ * Use this form, and not the nested one. Each capability declares a FIXED return type, so
+ * `withView(withRouting(PlayerActor))` builds the same class at run time and answers
+ * `Viewable` alone at the type level — a router bridge then refuses the actor with
+ * TS2739. The overloads below are what carries `Routable` through.
+ *
+ * @example
+ * ```typescript
+ * import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+ * import { withRouting } from "@xmachines/play-xstate/routing";
+ * import { withView } from "@xmachines/play-xstate/view";
+ *
+ * const createPlayer = definePlayer({
+ *   machine,
+ *   actor: compose(PlayerActor, withRouting, withView),
+ * });
+ * ```
+ *
+ * Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it
+ * applies them from left to right.
+ *
+ * @param Base - The actor class to build on, normally `PlayerActor`.
+ */
+export declare function compose<TMachine extends AnyStateMachine>(Base: PlayerConstructor<TMachine>): PlayerConstructor<TMachine>;
+export declare function compose<TMachine extends AnyStateMachine, TC1 extends object>(Base: PlayerConstructor<TMachine>, c1: Capability<TMachine, TC1>): PlayerConstructor<TMachine, TC1>;
+export declare function compose<TMachine extends AnyStateMachine, TC1 extends object, TC2 extends object>(Base: PlayerConstructor<TMachine>, c1: Capability<TMachine, TC1>, c2: Capability<TMachine, TC2>): PlayerConstructor<TMachine, TC1 & TC2>;
+export declare function compose<TMachine extends AnyStateMachine, TC1 extends object, TC2 extends object, TC3 extends object>(Base: PlayerConstructor<TMachine>, c1: Capability<TMachine, TC1>, c2: Capability<TMachine, TC2>, c3: Capability<TMachine, TC3>): PlayerConstructor<TMachine, TC1 & TC2 & TC3>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +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"}

package/dist/capabilities.js

@@ -0,0 +1,4 @@
+export function compose(Base, ...capabilities) {
+    return capabilities.reduce((actor, capability) => capability(actor), Base);
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +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"}

package/dist/define-player.d.ts

@@ -1,5 +1,6 @@
 import type { AnyStateMachine } from "xstate";
 import type { PlayerConfig, PlayerFactory } from "./types.js";
+import type { PlayerConstructor } from "./capabilities.js";
 /**
  * Creates a player factory from an XState machine
  *
@@ -56,5 +57,10 @@ import type { PlayerConfig, PlayerFactory } from "./types.js";
  * @see {@link PlayerConfig} for the configuration options
  * @see {@link PlayerFactory} for the signature of the factory function
  */
-export declare const definePlayer: <TMachine extends AnyStateMachine>(config: PlayerConfig<TMachine>) => PlayerFactory<TMachine>;
+export declare function definePlayer<TMachine extends AnyStateMachine>(config: PlayerConfig<TMachine> & {
+    actor?: undefined;
+}): PlayerFactory<TMachine>;
+export declare function definePlayer<TMachine extends AnyStateMachine, TCapabilities extends object>(config: PlayerConfig<TMachine, TCapabilities> & {
+    actor: PlayerConstructor<TMachine, TCapabilities>;
+}): PlayerFactory<TMachine, TCapabilities>;
 //# sourceMappingURL=define-player.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"define-player.d.ts","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAA8B,MAAM,YAAY,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,eAAe,EAC5D,QAAQ,YAAY,CAAC,QAAQ,CAAC,KAC5B,aAAa,CAAC,QAAQ,CAKxB,CAAC"}
+{"version":3,"file":"define-player.d.ts","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAA8B,MAAM,YAAY,CAAC;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS,eAAe,EAC5D,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACpD,aAAa,CAAC,QAAQ,CAAC,CAAC;AAC3B,wBAAgB,YAAY,CAAC,QAAQ,SAAS,eAAe,EAAE,aAAa,SAAS,MAAM,EAC1F,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG;IAC/C,KAAK,EAAE,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;CAClD,GACC,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC"}

package/dist/define-player.js

@@ -1,62 +1,11 @@
 import { PlayerActor } from "./player-actor.js";
-/**
- * Creates a player factory from an XState machine
- *
- * This factory function accepts an XState v5 machine. It returns a function that
- * makes {@link PlayerActor} instances. One configuration can therefore make more
- * than one actor instance, and this helps with a test, with an application of
- * several instances, and with a render on the server.
- *
- * @typeParam TMachine - The type of the XState v5 state machine
- *
- * @param config - The configuration object of the player
- * @param config.machine - The XState v5 state machine
- * @param config.options - The optional lifecycle hooks: onStart, onTransition, and the others
- *
- * @returns The factory function. It makes an actor instance, with an optional input context
- *
- * @example
- * A basic player factory
- * ```typescript
- * import { setup } from "xstate";
- * import { definePlayer } from "@xmachines/play-xstate";
- *
- * const machine = setup({}).createMachine({
- *   initial: 'idle',
- *   states: {
- *     idle: { meta: { route: '/' } },
- *     active: { meta: { route: '/active' } }
- *   }
- * });
- *
- * const createPlayer = definePlayer({ machine });
- * const actor = createPlayer();
- * actor.start();
- * ```
- *
- * @example
- * More than one actor instance from one factory
- * ```typescript
- * const createPlayer = definePlayer({ machine });
- *
- * // Create an actor for each user
- * const alice = createPlayer({ userId: 'alice' });
- * const bob = createPlayer({ userId: 'bob' });
- *
- * alice.start();
- * bob.start();
- *
- * // The two state machines are independent
- * console.log(alice.state.get() !== bob.state.get());
- * ```
- *
- * @see [Play RFC](../../docs/rfc/play.md)
- * @see {@link PlayerActor} for the concrete actor implementation
- * @see {@link PlayerConfig} for the configuration options
- * @see {@link PlayerFactory} for the signature of the factory function
- */
-export const definePlayer = (config) => {
-    const { machine, options } = config;
-    return (input, restore) => new PlayerActor(machine, options ?? {}, input, restore?.snapshot);
-};
+export function definePlayer(config) {
+    const { machine, options, actor } = config;
+    // `PlayerActor` is the default, and it carries no capability. A consumer that routes or
+    // renders passes a composed class, and this module imports neither capability. The two
+    // overloads above are what keeps the answer exact: the default one answers a bare
+    // player, and the other answers the player with everything that the composition added.
+    const ActorClass = actor ?? PlayerActor;
+    return (input, restore) => new ActorClass(machine, options ?? {}, input, restore?.snapshot);
+}
 //# sourceMappingURL=define-player.js.map

package/dist/define-player.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-player.js","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC3B,MAA8B,EACJ,EAAE;IAC5B,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAEpC,OAAO,CAAC,KAA2B,EAAE,OAA8C,EAAE,EAAE,CACtF,IAAI,WAAW,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACpE,CAAC,CAAC"}
+{"version":3,"file":"define-player.js","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkEhD,MAAM,UAAU,YAAY,CAC3B,MAA6C;IAE7C,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC3C,wFAAwF;IACxF,uFAAuF;IACvF,kFAAkF;IAClF,uFAAuF;IACvF,MAAM,UAAU,GAAG,KAAK,IAAI,WAAW,CAAC;IAExC,OAAO,CAAC,KAA2B,EAAE,OAA8C,EAAE,EAAE,CACtF,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC"}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 /**
  * `buildRouteUrl()` throws this error when the context of the actor does not hold a
  * necessary route parameter.
@@ -14,7 +14,7 @@ import { PlayError } from "@xmachines/play";
  *
  * @example
  * ```typescript
- * import { buildRouteUrl } from "@xmachines/play-xstate";
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
  * try {
@@ -35,23 +35,6 @@ export declare class MissingRouteParamError extends PlayError {
     readonly template: string;
     constructor(param: string, template: string);
 }
-/**
- * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
- * field as `query: {}`. The generated `play.route` transitions assign `query` on
- * every navigation, and the loss that this error guarded against therefore cannot
- * happen through the route derivation. A machine that handles `play.route` itself
- * and wants the query must assign `event.query` to its context itself. This class
- * stays in the exports, so that an `instanceof` handler that exists now still
- * compiles. Remove such a handler when you have the time.
- *
- * `buildRouteUrl()` threw this error before, when the context had a `params` field,
- * which means a context that knows the routing, but no `query` field.
- *
- * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- */
-export declare class MissingQueryContextError extends PlayError {
-    constructor();
-}
 /**
  * `formatPlayRouteTransitions()` throws this error when a state node declares a
  * `meta.route` field but no explicit `id` field.
@@ -112,15 +95,35 @@ export declare class InvalidRouteMetadataError extends PlayError {
     constructor(route: unknown, source?: string);
 }
 /**
- * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
- * guards. A composition of zero guards has no meaning.
+ * `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
+ * `handler` field holds a value that the routing layer does not know.
  *
- * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
+ * The field decides WHERE the generated `play.route` transition sits, and each value
+ * produces a different reachability. `"local"` in particular makes a state reachable
+ * only while its parent is active. A typo such as `"locale"` would therefore fall back
+ * to a placement that the author did not ask for, and the route would behave correctly
+ * in the test that the author wrote and wrongly everywhere else. The error refuses the
+ * value instead.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidRouteHandlerError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   formatPlayRouteTransitions(config);
+ * } catch (error) {
+ *   if (error instanceof InvalidRouteHandlerError) {
+ *     console.error(error.handler); // the value that the config declared
+ *   }
+ * }
+ * ```
  */
-export declare class EmptyGuardArrayError extends PlayError {
-    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
-    readonly combinator: "and" | "or";
-    constructor(combinator: "and" | "or");
+export declare class InvalidRouteHandlerError extends PlayError {
+    /** The value that the config declared, as a string, for the debug work. */
+    readonly handler: string;
+    constructor(handler: unknown, source?: string);
 }
 /**
  * `PlayerActor.send()` throws this error when the event argument is not a plain

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,iBAAiB,CAAC;AAsB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;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;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}