@xmachines/play-xstate 3.0.0 → 5.0.0

package/README.md

@@ -1,24 +1,36 @@
 # @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-3.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)
 
 ---
 
 > **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`. Vite 8 resolves its default
-> `baseline-widely-available` target to Firefox 114, which is below it — raise
-> `build.target` when you bundle for the browser. The root README carries the table.
+> `TypeError: ... is not a function`. The root README carries the table.
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-xstate xstate
+pnpm add @xmachines/play-xstate @xmachines/play @xmachines/play-atom xstate
 ```
 
-`xstate ^5.31.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.
 
 ---
 
@@ -26,7 +38,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({
@@ -38,13 +51,13 @@ 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();
 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"
 
@@ -133,16 +146,91 @@ 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 atoms. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
+
+#### Atoms
+
+| Atom    | Type                           | Description                                                                  |
+| ------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `state` | `Atom<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`](../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`](../play-router/README.md) |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of [`@xmachines/play-view`](../play-view/README.md)     |
 
-#### Signals
+`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 });
+```
+
+**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:
+
+```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                                   | 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 |
+| 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
 
@@ -153,59 +241,45 @@ 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()`. Deprecated — call `stop()`, or write `using`       |
 | `[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();
 ```
 
 ---
 
-### Guard utilities
-
-> **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.
+### Guards
 
-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",
 		},
 	},
@@ -213,6 +287,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
@@ -225,7 +303,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",
@@ -309,17 +387,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`](../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.
+
+### 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
@@ -329,31 +465,17 @@ 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
+	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
 	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`](../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

@@ -0,0 +1,93 @@
+/**
+ * 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. 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
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -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":"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/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"}