@xmachines/play-actor 3.0.0 → 4.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @xmachines/play-actor
 
-Abstract Actor base class for XMachines Play Architecture.
+The actor contract of the XMachines Play Architecture. It names no state machine library.
 
-[![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-actor)
+[![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-actor)
 
 ## Installation
 
@@ -13,227 +13,108 @@ pnpm add @xmachines/play-actor
 **Peer dependencies.** Install them with the package:
 
 ```bash
-pnpm add xstate @xmachines/play @xmachines/play-signals @xmachines/json-render-core
+pnpm add @xmachines/play-signals
 ```
 
 ## Overview
 
-`@xmachines/play-actor` gives you `AbstractActor`, a minimal base class. The class extends the XState `Actor` class, and it enforces the **signal protocol** of the Play Architecture (RFC section 5.3). It exposes reactive TC39 Signals for the infrastructure layer. It also keeps the complete compatibility with the XState ecosystem, which includes the devtools and the inspection.
+`@xmachines/play-actor` gives you `PlayActor`, the contract that every layer above reads.
+An actor of XMachines holds exactly two things:
 
-The core protocol is small on purpose:
+| Member  | Type                      | Description                                |
+| ------- | ------------------------- | ------------------------------------------ |
+| `state` | `Signal.State<TSnapshot>` | The reactive snapshot of the current state |
+| `send`  | `(event: TEvent) => void` | The typed event dispatch                   |
 
-| Property | Type                      | Description                              |
-| -------- | ------------------------- | ---------------------------------------- |
-| `state`  | `Signal.State<unknown>`   | Reactive snapshot of current actor state |
-| `send`   | `(event: TEvent) => void` | Event dispatch method                    |
+**It is an interface, and no base class.** A state machine library is the concern of an
+adapter, and [`@xmachines/play-xstate`](../play-xstate/README.md) is the adapter of XState
+v5. This package therefore names `xstate` nowhere.
 
-Separate interfaces declare the optional capabilities. A concrete actor implements only the interfaces that it needs:
+The contract was an abstract CLASS that extended `Actor` of `xstate`, and the class carried
+no implementation at all: both of its members were abstract. Its whole effect was to force
+the inheritance of XState on every consumer of the contract, including
+[`@xmachines/play-view`](../play-view/README.md) and
+[`@xmachines/play-router`](../play-router/README.md), which read `currentView`,
+`currentRoute` and `send`, and no other member.
 
-| Interface  | Property                                        | Description                           |
-| ---------- | ----------------------------------------------- | ------------------------------------- |
-| `Routable` | `currentRoute: Signal.Computed<string \| null>` | Current route path derived from state |
-| `Routable` | `initialRoute: string \| null`                  | The route where the actor starts      |
-| `Viewable` | `currentView: Signal.State<PlaySpec \| null>`   | Current JSON-render view spec         |
+### The capabilities are optional, and separate
 
-An adapter, such as [`@xmachines/play-xstate`](../play-xstate/README.md), makes the concrete implementations.
+A capability lives with the package that holds its shared machinery. Neither one implies
+the other, and neither one names an engine.
 
-## API Summary
+| Capability | Interface  | Package                                              | Adds                           |
+| ---------- | ---------- | ---------------------------------------------------- | ------------------------------ |
+| Routing    | `Routable` | [`@xmachines/play-router`](../play-router/README.md) | `currentRoute`, `initialRoute` |
+| View       | `Viewable` | [`@xmachines/play-view`](../play-view/README.md)     | `currentView`                  |
 
-### `AbstractActor<TLogic, TEvent>`
+## API Summary
 
-The abstract base class extends the XState `Actor<TLogic>` class.
+### `PlayActor<TSnapshot, TEvent>`
 
-A subclass **is** the actor. Give the logic and its options to `super()`, so that one
-instance holds the running machine. Reach the `send` method of XState through the
-prototype. This class declares `send` as abstract for one reason only: to narrow the
-event type. TypeScript forbids a `super` call to an abstract member.
+Both type parameters carry their real type through, and neither one erases it.
 
 ```ts
-import { AbstractActor } from "@xmachines/play-actor";
+import type { PlayActor } from "@xmachines/play-actor";
 import { Signal } from "@xmachines/play-signals";
-import { Actor, type ActorOptions, type AnyActorLogic } from "xstate";
-
-class MyActor extends AbstractActor<AnyActorLogic> {
-	// Required: reactive state signal
-	state: Signal.State<unknown>;
 
-	constructor(logic: AnyActorLogic, options?: ActorOptions<AnyActorLogic>) {
-		super(logic, options);
-		this.state = new Signal.State(this.getSnapshot());
-		super.subscribe((snapshot) => this.state.set(snapshot));
-	}
-
-	// Required: typed event dispatch
-	override send(event: { type: string }): void {
-		Actor.prototype.send.call(this, event);
-	}
-}
-```
-
-With a typed event union:
-
-```ts
-// imports as in the previous example
-type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+type Snapshot = { readonly value: string };
+type AuthEvent =
+	{ readonly type: "auth.login"; readonly username: string } | { readonly type: "auth.logout" };
 
-class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
-	state = new Signal.State({ isAuthenticated: false, username: null });
+class AuthActor implements PlayActor<Snapshot, AuthEvent> {
+	readonly state = new Signal.State<Snapshot>({ value: "guest" });
 
-	override send(event: AuthEvent): void {
-		Actor.prototype.send.call(this, event);
+	send(event: AuthEvent): void {
+		if (event.type === "auth.login") this.state.set({ value: "authenticated" });
 	}
 }
-```
-
-### `typedSpec(spec)`
-
-This identity helper gives a view-spec literal the type `PlaySpec` at the definition site. The
-XState `meta` field has the type `Record<string, unknown>`. Therefore this helper is the place
-where the spec shape receives the compile-time check and the IDE autocomplete. The helper has no
-cost at run time.
 
-```ts
-import { typedSpec } from "@xmachines/play-actor";
-
-// In an XState machine meta block:
-meta: {
-  view: typedSpec({
-    root: "root",
-    elements: {
-      root: {
-        type: "Dashboard",
-        props: { username: { $state: "/context/username" } },
-        children: [],
-      },
-    },
-  }),
-}
+// The snapshot type reaches the reader, and it is no `unknown`:
+const actor: PlayActor<Snapshot, AuthEvent> = new AuthActor();
+const value: string = actor.state.get().value;
 ```
 
-### `PlaySpec`
-
-This type extends the `Spec` type of `@xmachines/json-render-core`. Each derived view receives
-the complete machine context in its state store, under the read-only **`/context` subtree**. A
-spec therefore reads the context through the ordinary `{ $state: "/context/…" }` grammar: in a
-prop, in a `visible` condition, and in `repeat.statePath`.
-
-`/context` is read-only by design. Nothing can write to it. The machine context changes through
-an event only. A `$bindState` write or a `setState` write under `/context` throws an error, and
-the error names the event to send. This is the model: the bindable ephemeral state is at the
-root of the store, from `spec.state`; the domain state is in the machine, and it changes through
-events that are meaningful and easy to inspect.
-
-The path shows the origin of each value. `/context/params/username` comes from the URL.
-`/context/username` belongs to the machine. One value can never hide the other.
-
-The model projects everything, and this has two consequences. The first consequence is
-**exposure**. The complete context is visible to the client in the view store, which includes a
-debug panel, an inspector, and a validator. The context is a client-side value in each case, so
-keep a secret out of it.
-
-The second consequence is **emission granularity**. The emit gate compares the context field by
-field, at the top level only. Therefore an event that changes any field emits the view again
-with the same `viewKey`. A provider refreshes `/context` in the live store, and it does not seed
-the store again. The component does not remount, and the ephemeral view state and the focus
-stay. However, a new emission is still a render pass in the framework layer. Keep
-high-frequency ephemeral data, such as a draft for each keystroke or a timer, in the view store
-(`spec.state` with `$bindState`) or in a child actor. The domain state belongs in the context. A
-keystroke does not.
+A plain object satisfies the contract as well. Nothing here asks for a class.
 
 ```ts
-import type { PlaySpec } from "@xmachines/play-actor";
-
-const spec: PlaySpec = {
-	root: "root",
-	elements: {
-		root: {
-			type: "Profile",
-			props: { username: { $state: "/context/username" } },
-			children: [],
-		},
-	},
+const actor: PlayActor<Snapshot, AuthEvent> = {
+	state: new Signal.State<Snapshot>({ value: "guest" }),
+	send: () => {},
 };
 ```
 
-> Historical note: an earlier version had a `contextProps` field. At first the field drove an
-> implicit prop-enrichment pass. That pass merged the allowlisted context fields and the URL
-> params into the props of every element. We removed it, because it put values into components
-> that never asked for them, and it let URL data from the user hide machine-owned state. The
-> field was then a projection filter for a short time. We removed that filter too, because a
-> limit on what a view can read added machinery without a real problem to solve. Always
-> validate the **derived** view (`actor.currentView.get()`), not the raw `meta.view`. The
-> `state` of the derived spec carries the projection, so a tool such as `validateSpec` sees a
-> spec that is consistent with itself.
+### `ActorEvent`
 
-### `Routable`
+The minimal shape of an event that an actor receives: `{ readonly type: string }`. It is
+the constraint of `TEvent`, and it is the base of `PlayEvent` of
+[`@xmachines/play`](../play/README.md).
 
-Interface for actors that support routing.
+### An actor with a capability
 
-```ts
-import { AbstractActor, type Routable } from "@xmachines/play-actor";
-import { Signal } from "@xmachines/play-signals";
-import type { AnyActorLogic, EventObject } from "xstate";
-
-// Implement in a concrete actor (note: RoutableActor interface is exported from @xmachines/play-router):
-class MyRoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
-	state = new Signal.State<{ path?: string }>({});
-	currentRoute = new Signal.Computed<string | null>(() => this.state.get().path ?? null);
-	initialRoute = "/";
-	override send(event: EventObject): void {
-		/* dispatch */
-	}
-}
-```
-
-### `Viewable`
-
-Interface for actors that expose a renderable view signal.
+A concrete actor implements the contract and the capabilities that it needs. It extends the
+actor class of its own engine, and the contract stays out of the inheritance.
 
 ```ts
-import type { Viewable } from "@xmachines/play-actor";
-import type { PlaySpec } from "@xmachines/play-actor";
+import type { PlayActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
-
-// currentView carries PlaySpec | null
-const signal = new Signal.State<PlaySpec | null>(null);
-const viewable: Viewable = { currentView: signal };
-```
-
-### `BaseActorProviderProps<TRegistry>`
-
-The framework-agnostic base props. Every `ActorProvider` implementation shares them: React, Vue, Solid, and Svelte. Each framework renderer package extends this interface.
-
-```ts
-import type { BaseActorProviderProps } from "@xmachines/play-actor";
-import type { DefineRegistryResult } from "@xmachines/json-render-react";
-
-interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
-	fallback?: React.ReactNode;
-	children: React.ReactNode;
+import { Actor, type AnyActorLogic } from "xstate";
+
+class MyRoutableActor
+	extends Actor<AnyActorLogic>
+	implements PlayActor<unknown, { readonly type: string }>, Routable
+{
+	readonly state = new Signal.State<unknown>({});
+	readonly currentRoute = new Signal.Computed<string | null>(() => null);
+	readonly initialRoute = "/";
 }
 ```
 
-### `BaseViewContextValue<TRegistry>`
-
-The framework-agnostic base of the `ViewContextValue` type in each framework. It holds the `spec`, `handlers`, `registry`, and `store` fields. These fields are identical in React, Vue, Solid, and Svelte.
-
-## Testing
-
-Run the test suite for this package in isolation:
-
-```bash
-# From the package directory
-pnpm test
-
-# From the monorepo root (workspace-scoped)
-pnpm --filter @xmachines/play-actor test
-
-# Watch mode
-pnpm --filter @xmachines/play-actor run test:watch
-```
+[`@xmachines/play-xstate`](../play-xstate/README.md) does exactly this, and it composes
+each capability with `compose(PlayerActor, withRouting, withView)`.
 
 ## Requirements
 
-- **Node.js** `>=22.0.0`
+- **Node.js** `>=24.0.0`
 - **TypeScript** `>=5.7` (strict mode)
 - **ESM only** — `"type": "module"`

package/dist/index.d.ts

@@ -1,27 +1,22 @@
 /**
- * @xmachines/play-actor - the abstract Actor base class of the Play Architecture
+ * @xmachines/play-actor - the actor contract of the Play Architecture
  *
- * This package gives you AbstractActor, a minimal base class. It extends the XState
- * Actor class, and it enforces the signal protocol of the Play Architecture (RFC
- * section 5.3).
+ * The contract is minimal, and it names no engine: `state` and `send`. A state machine
+ * library is the concern of an adapter, and `@xmachines/play-xstate` is the adapter of
+ * XState v5.
  *
- * The core protocol is minimal: state and send. Two interfaces give the optional
- * capabilities:
- * - Routable: for an actor with a routing support
- * - Viewable: for an actor with a view rendering
+ * A capability is optional, and each one lives with the package that holds its shared
+ * machinery:
+ * - `Routable`, for an actor with a routing support, is in `@xmachines/play-router`, with
+ *   the bridge that reads it
+ * - `Viewable`, for an actor with a view rendering, is in `@xmachines/play-view`, with the
+ *   view store lifecycle, the context projection and the provider guards
  *
- * The class keeps the compatibility with the XState ecosystem, such as the
- * inspection and the devtools. It also exposes the reactive signals of the
- * communication with the infrastructure layer.
+ * A consumer that needs one capability installs one package, and a consumer that needs
+ * neither installs neither. Neither capability implies the other.
  *
  * @packageDocumentation
  * @see [Play RFC](../../docs/rfc/play.md)
  */
-export { AbstractActor, typedSpec, type Routable, type Viewable, type PlaySpec, type BaseActorProviderProps, type BaseViewContextValue, } from "./abstract-actor.js";
-export { toAtomState, attachRenderErrorHandler } from "./provider-guards.js";
-export { CONTEXT_STATE_KEY, guardContextWrites, refreshContextSubtree, composePlayState, shallowEqualExcept, reuseComposedState, } from "./context-projection.js";
-export { createViewStoreLifecycle } from "./view-store-lifecycle.js";
-export { createFailureLatch, createReportGuard, sameViewInputs } from "./failure-latch.js";
-export type { FailureLatch, ReportGuard, ReportGuardMessages, ViewInputs, } from "./failure-latch.js";
-export type { ViewStoreLifecycle, ViewStoreResolution, ResolveViewStoreOptions, } from "./view-store-lifecycle.js";
+export type { PlayActor, ActorEvent } from "./play-actor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC3F,YAAY,EACX,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,UAAU,GACV,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,GACvB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,25 +1,22 @@
 /**
- * @xmachines/play-actor - the abstract Actor base class of the Play Architecture
+ * @xmachines/play-actor - the actor contract of the Play Architecture
  *
- * This package gives you AbstractActor, a minimal base class. It extends the XState
- * Actor class, and it enforces the signal protocol of the Play Architecture (RFC
- * section 5.3).
+ * The contract is minimal, and it names no engine: `state` and `send`. A state machine
+ * library is the concern of an adapter, and `@xmachines/play-xstate` is the adapter of
+ * XState v5.
  *
- * The core protocol is minimal: state and send. Two interfaces give the optional
- * capabilities:
- * - Routable: for an actor with a routing support
- * - Viewable: for an actor with a view rendering
+ * A capability is optional, and each one lives with the package that holds its shared
+ * machinery:
+ * - `Routable`, for an actor with a routing support, is in `@xmachines/play-router`, with
+ *   the bridge that reads it
+ * - `Viewable`, for an actor with a view rendering, is in `@xmachines/play-view`, with the
+ *   view store lifecycle, the context projection and the provider guards
  *
- * The class keeps the compatibility with the XState ecosystem, such as the
- * inspection and the devtools. It also exposes the reactive signals of the
- * communication with the infrastructure layer.
+ * A consumer that needs one capability installs one package, and a consumer that needs
+ * neither installs neither. Neither capability implies the other.
  *
  * @packageDocumentation
  * @see [Play RFC](../../docs/rfc/play.md)
  */
-export { AbstractActor, typedSpec, } from "./abstract-actor.js";
-export { toAtomState, attachRenderErrorHandler } from "./provider-guards.js";
-export { CONTEXT_STATE_KEY, guardContextWrites, refreshContextSubtree, composePlayState, shallowEqualExcept, reuseComposedState, } from "./context-projection.js";
-export { createViewStoreLifecycle } from "./view-store-lifecycle.js";
-export { createFailureLatch, createReportGuard, sameViewInputs } from "./failure-latch.js";
+export {};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,aAAa,EACb,SAAS,GAMT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/play-actor.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The actor contract of the Play Architecture.
+ *
+ * An actor of XMachines holds exactly two things, and this file names both:
+ *
+ * - `state`: the reactive snapshot, as a TC39 Signal
+ * - `send`: the typed event dispatch
+ *
+ * It names NO engine. A state machine library is the concern of an adapter, and
+ * `@xmachines/play-xstate` is the adapter of XState v5.
+ *
+ * The contract was an abstract CLASS that extended `Actor` of `xstate`, and the class
+ * carried no implementation at all: both members were abstract, and `instanceof` of it
+ * appeared nowhere. Its whole effect was to force the inheritance of XState on every
+ * consumer of the contract, including `@xmachines/play-view` and
+ * `@xmachines/play-router`, which read `currentView`, `currentRoute` and `send`, and no
+ * other member.
+ *
+ * A capability is optional, and each one lives with the package that holds its shared
+ * machinery: `Routable` is in `@xmachines/play-router`, beside the bridge that reads it,
+ * and `Viewable` is in `@xmachines/play-view`, beside the view store lifecycle. Neither
+ * one names an engine, and neither one implies the other.
+ *
+ * @packageDocumentation
+ * @see [Play RFC](../../docs/rfc/play.md)
+ */
+import type { Signal } from "@xmachines/play-signals";
+/**
+ * The minimal shape of an event that an actor receives.
+ *
+ * It is the base of `PlayEvent` of `@xmachines/play`, and this package declares it again
+ * rather than import it: the constraint must accept the event union of a CONCRETE machine,
+ * and `PlayEvent` carries `Record<string, unknown>` in its default payload. An interface of
+ * a union member holds no index signature, so it satisfies that default never.
+ */
+export interface ActorEvent {
+    readonly type: string;
+}
+/**
+ * The actor contract of the Play Architecture. It names NO engine.
+ *
+ * An actor of XMachines holds exactly two things, and this interface names both: the
+ * reactive snapshot, and the typed event dispatch. A state machine library is the concern
+ * of an adapter, and `@xmachines/play-xstate` is the adapter of XState v5.
+ *
+ * Both type parameters carry their real type through, and neither one erases it.
+ * `AbstractActor` declares `Signal.State<unknown>`, so every consumer of a snapshot reads
+ * `unknown` and asserts its way back.
+ *
+ * A capability is optional, and each one lives with the package that holds its shared
+ * machinery: `Routable` is in `@xmachines/play-router`, and `Viewable` is in
+ * `@xmachines/play-view`. Neither one names an engine either, and neither one implies the
+ * other.
+ *
+ * @typeParam TSnapshot - The type of the snapshot that `state` holds, for example `SnapshotFrom<TMachine>`.
+ * @typeParam TEvent - The event union that `send` accepts, for example `EventFromLogic<TMachine>`.
+ *
+ * @example
+ * ```typescript
+ * import type { PlayActor } from "@xmachines/play-actor";
+ * import type { Viewable } from "@xmachines/play-view";
+ *
+ * // A renderer reads the view capability and the send of the contract. It names no
+ * // engine, and it keeps the event union of the machine.
+ * function mount<TSnapshot, TEvent extends ActorEvent>(
+ *   actor: PlayActor<TSnapshot, TEvent> & Viewable,
+ * ): void {
+ *   actor.currentView.get();
+ * }
+ * ```
+ */
+export interface PlayActor<TSnapshot = unknown, TEvent extends ActorEvent = ActorEvent> {
+    /**
+     * The reactive snapshot of the current actor state.
+     *
+     * The infrastructure observes this signal, and it reacts to each state change. It
+     * therefore holds no coupling to the internal state machine of the actor.
+     */
+    readonly state: Signal.State<TSnapshot>;
+    /**
+     * Sends an event to the actor.
+     *
+     * `TEvent` gives the type safety: a concrete adapter binds it to the event union of its
+     * own machine, and the compiler then refuses an event that the machine does not declare.
+     */
+    send(event: TEvent): void;
+}
+//# sourceMappingURL=play-actor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"play-actor.d.ts","sourceRoot":"","sources":["../src/play-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,SAAS,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,SAAS,UAAU,GAAG,UAAU;IACrF;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAExC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/play-actor.js

@@ -0,0 +1,28 @@
+/**
+ * The actor contract of the Play Architecture.
+ *
+ * An actor of XMachines holds exactly two things, and this file names both:
+ *
+ * - `state`: the reactive snapshot, as a TC39 Signal
+ * - `send`: the typed event dispatch
+ *
+ * It names NO engine. A state machine library is the concern of an adapter, and
+ * `@xmachines/play-xstate` is the adapter of XState v5.
+ *
+ * The contract was an abstract CLASS that extended `Actor` of `xstate`, and the class
+ * carried no implementation at all: both members were abstract, and `instanceof` of it
+ * appeared nowhere. Its whole effect was to force the inheritance of XState on every
+ * consumer of the contract, including `@xmachines/play-view` and
+ * `@xmachines/play-router`, which read `currentView`, `currentRoute` and `send`, and no
+ * other member.
+ *
+ * A capability is optional, and each one lives with the package that holds its shared
+ * machinery: `Routable` is in `@xmachines/play-router`, beside the bridge that reads it,
+ * and `Viewable` is in `@xmachines/play-view`, beside the view store lifecycle. Neither
+ * one names an engine, and neither one implies the other.
+ *
+ * @packageDocumentation
+ * @see [Play RFC](../../docs/rfc/play.md)
+ */
+export {};
+//# sourceMappingURL=play-actor.js.map

package/dist/play-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"play-actor.js","sourceRoot":"","sources":["../src/play-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@xmachines/play-actor",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "private": false,
-  "description": "Abstract Actor base class for XMachines Play Architecture",
+  "description": "The actor contract of the Play Architecture: state and send. It names no state machine library",
   "keywords": [
     "actor",
     "play-architecture",
@@ -42,28 +42,26 @@
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check ."
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
-    "@xmachines/json-render-core": "^0.20.0-xm.4",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
-    "vite": "^8.0.10",
-    "vitest": "^4.1.11",
-    "xstate": "^5.31.0"
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "@xmachines/play": "4.0.0",
+    "@xmachines/play-signals": "4.0.0",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "xstate": "^5.33.0"
   },
   "peerDependencies": {
-    "@xmachines/json-render-core": "^0.20.0-xm.4",
-    "@xmachines/play": "3.0.0",
-    "@xmachines/play-signals": "3.0.0",
-    "xstate": "^5.31.0"
+    "@xmachines/play-signals": "4.0.0"
   },
   "engines": {
-    "node": ">=22.0.0"
-  },
-  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds and tests. peerDependencies declares the consumer version constraint. Both are pinned to ^5.30.0 to prevent drift."
+    "node": ">=24.0.0"
+  }
 }