Class: PlayerActor<TMachine>

API / @xmachines/play-xstate / PlayerActor

Defined in: packages/play-xstate/src/player-actor.ts:342

Concrete XState actor implementing Play Architecture signal protocol

Extends @xmachines/play-actor!AbstractActor to provide XState v5 integration while maintaining ecosystem compatibility (XState inspection, devtools). This actor wraps an internal XState actor and exposes TC39 Signal-based reactive state for Infrastructure observation.

Capabilities: Implements both @xmachines/play-actor!Routable and @xmachines/play-actor!Viewable interfaces, providing routing and view rendering support.

Architectural Context: Implements Actor Authority (INV-01) by ensuring the XState machine’s guards control all navigation decisions. Infrastructure observes the actor’s signals (state, currentRoute, currentView) but cannot directly manipulate state—all mutations flow through the state machine’s event handlers.

Examples

Basic actor creation and lifecycle

import { setup } from "xstate";
import { definePlayer } from "@xmachines/play-xstate";

const machine = setup({}).createMachine({
  initial: "idle",
  states: {
    idle: {
      meta: { route: "/", view: { component: "HomePage" } },
    },
  },
});

const createPlayer = definePlayer({ machine });
const actor = createPlayer();
actor.start();

// Observe signals
console.log(actor.currentRoute.get()); // '/'
console.log(actor.currentView.get()); // { component: 'HomePage' }

Signal lifecycle with watchers

import { Signal } from "@xmachines/play-signals";

const watcher = new Signal.subtle.Watcher(() => {
  queueMicrotask(() => {
    const pending = watcher.getPending();
    console.log("State changed:", actor.state.get());
  });
});

watcher.watch(actor.state);
actor.send({ type: "play.route", to: "#about" });
// Watcher notification scheduled via microtask by the watcher itself

See

Play RFC
definePlayer for factory creation
@xmachines/play-actor!AbstractActor for signal protocol
@xmachines/play-actor!Routable for routing capability
@xmachines/play-actor!Viewable for view rendering capability

Remarks

Routing: This actor supports both XState’s route: {} config pattern and play.route events with parameters. The deriveRoute() function checks meta.route (Stately pattern) for URL templates with parameter substitution support.

View Signal Pattern: The currentView signal is a direct Signal.State (not Signal.Computed) to ensure proper watcher propagation in PlayRenderer. Views are cached and updated at state entry, not computed on every read.

Extends

AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>

Type Parameters

Type Parameter	Description
`TMachine` extends `AnyStateMachine`	XState v5 state machine type

Implements

Constructors

Constructor

new PlayerActor<TMachine>(
   machine,
   options,
   input?,
   restoredSnapshot?,
_cachedInitialRoute?): PlayerActor<TMachine>;

Defined in: packages/play-xstate/src/player-actor.ts:434

Parameters

Parameter	Type	Description
`machine`	`TMachine`	-
`options`	`PlayerOptions`<`TMachine`>	-
`input?`	`InputFrom`<`TMachine`>	-
`restoredSnapshot?`	`SnapshotFrom`<`TMachine`>	-
`_cachedInitialRoute?`	`string` \| `null`	`Internal` Pre-computed initial route from `definePlayer`. `initialRoute` is determined by the machine’s initial state node and its `meta.route` template — both fixed at machine definition time regardless of `input` or `snapshot`. When provided, used directly on every construction, eliminating a redundant `createActor()` call per actor instance. — set by `definePlayer`; callers should not pass this directly.

Returns

PlayerActor<TMachine>

Overrides

AbstractActor.constructor

Properties

Property	Modifier	Type	Description	Overrides	Inherited from	Defined in
`_parent?`	`public`	`AnyActorRef`	-	-	`AbstractActor`.`_parent`	-
`clock`	`public`	`Clock`	The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.	-	`AbstractActor`.`clock`	-
`currentRoute`	`public`	`Computed`<`string` \| `null`>	A TC39 `Signal.Computed` that derives the current URL path from the active machine state’s `meta.route` template and the actor’s context. Returns `null` when the current state has no `meta.route`, or when the route template cannot be fully resolved (e.g. a required parameter is absent from context). Throws When a required `:param` placeholder in the route template has no matching value in the actor’s context. Import the class from `@xmachines/play-xstate/errors`. Example `// Returns "/profile/alice" when context.userId === "alice" const route = actor.currentRoute.get();`	-	-	packages/play-xstate/src/player-actor.ts:387
`currentView`	`public`	`State`<`PlaySpec` \| `null`>	Reactive signal containing the current view spec derived from the active state’s `meta.view` metadata. Always emits a fresh object reference on every state transition (including self-transitions with `reenter: true`) so TC39 Signal equality checks reliably detect changes. The emitted `PlaySpec` has its element `props` enriched with `context.params` before emission — URL path parameters (e.g. `:section?`) flow into component props automatically. See `mergeRouteParamsIntoProps` for the merge priority rules. Returns `null` when the current state has no `meta.view` metadata. Example `const view = actor.currentView.get(); if (view) { console.log(view.root); // e.g. "root" console.log(view.elements); // @json-render/core Spec elements }`	-	-	packages/play-xstate/src/player-actor.ts:432
`id`	`public`	`string`	The unique identifier for this actor relative to its parent.	-	`AbstractActor`.`id`	-
`initialRoute`	`readonly`	`string` \| `null`	The route derived from the machine’s initial state — fixed at construction, never changes even when the actor is restored from a snapshot. Router bridges compare this against the browser URL to distinguish a deep-link (non-initial URL → router wins) from a restore (initial URL + actor at a different restored route → actor wins). Determined by the machine’s initial state node and its `meta.route` template — both are fixed at machine definition time. `definePlayer` pre-computes this value once from the machine definition and passes it to every actor it constructs, so no extra `createActor()` call is needed per construction. When `PlayerActor` is constructed directly (without `definePlayer`), the value is derived from `xstateActor.getSnapshot()` (normal path) or a transient `createActor(machine, { input })` call (restore path, to avoid using the snapshot’s state instead of the machine’s default).	-	-	packages/play-xstate/src/player-actor.ts:407
`logic`	`public`	`AnyActorLogic`	-	-	`AbstractActor`.`logic`	-
`options`	`public`	`Readonly`<`ActorOptions`<`TLogic`>>	-	-	`AbstractActor`.`options`	-
`ref`	`public`	`ActorRef`<`any`, `any`, `any`>	-	-	`AbstractActor`.`ref`	-
`sessionId`	`public`	`string`	The globally unique process ID for this invocation.	-	`AbstractActor`.`sessionId`	-
`src`	`public`	\| `string` \| `AnyActorLogic`	-	-	`AbstractActor`.`src`	-
`state`	`public`	`State`<`ReturnType`<`TMachine`[`"transition"`]>>	Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor’s internal state machine implementation.	`AbstractActor`.`state`	-	packages/play-xstate/src/player-actor.ts:352
`system`	`public`	`AnyActorSystem`	The system to which this actor belongs.	-	`AbstractActor`.`system`	-
`systemId`	`public`	`string` \| `undefined`	-	-	`AbstractActor`.`systemId`	-

Methods

[observable]()

observable: InteropSubscribable<any>;

Defined in: xstate

Returns

InteropSubscribable<any>

Inherited from

AbstractActor.[observable]

can()

can(event): boolean;

Defined in: packages/play-xstate/src/player-actor.ts:365

Returns whether the actor’s current state can accept the given event.

Typed to the machine’s event union — passing an unknown event type is a compile error. Delegates to the underlying XState actor’s snapshot.

Parameters

Parameter	Type
`event`	`EventFromLogic`<`TMachine`>

Returns

boolean

Example

if (actor.can({ type: "auth.logout" })) { ... }

dispose()

dispose(): void;

Defined in: packages/play-xstate/src/player-actor.ts:647

Convenience dispose method for cleanup

Per CONTEXT.md: “Both .dispose() convenience method and manual machine.stop()“

Returns

void

getPersistedSnapshot()

getPersistedSnapshot(): Snapshot<unknown>;

Defined in: xstate

Obtain the internal state of the actor, which can be persisted.

Returns

Snapshot<unknown>

Remarks

The internal state can be persisted from any actor, not only machines.

Note that the persisted state is not the same as the snapshot from Actor.getSnapshot. Persisted state represents the internal state of the actor, while snapshots represent the actor’s last emitted value.

Can be restored with ActorOptions.state

See

https://stately.ai/docs/persistence

Inherited from

AbstractActor.getPersistedSnapshot

getSnapshot()

getSnapshot(): SnapshotFrom<TMachine>;

Defined in: packages/play-xstate/src/player-actor.ts:616

Get current snapshot

Returns

SnapshotFrom<TMachine>

Overrides

AbstractActor.getSnapshot

on()

on<TType>(type, handler): Subscription;

Defined in: xstate

Type Parameters

Type Parameter
`TType` extends `any`

Parameters

Parameter	Type
`type`	`TType`
`handler`	(`emitted`) => `void`

Returns

Subscription

Inherited from

AbstractActor.on

select()

select<TSelected>(selector, equalityFn?): Readable<TSelected>;

Defined in: xstate

Type Parameters

Type Parameter
`TSelected`

Parameters

Parameter	Type
`selector`	(`snapshot`) => `TSelected`
`equalityFn?`	(`a`, `b`) => `boolean`

Returns

Readable<TSelected>

Inherited from

AbstractActor.select

send()

send(event): void;

Defined in: packages/play-xstate/src/player-actor.ts:593

Send an event to the underlying XState actor.

The actor’s state machine guards decide whether the event causes a transition. Pass any event from the machine’s event union — domain events, routing events, etc.

Parameters

Parameter	Type	Description
`event`	`EventFromLogic`<`TMachine`>	An event from the machine’s `EventFromLogic<TMachine>` union.

Returns

void

Throws

When event is not a plain object (null, undefined, a string, number, etc.). Import the class from @xmachines/play-xstate/errors.

Example

// Domain event (typed to machine's event union)
actor.send({ type: "auth.login", userId: "123" });

// Routing event
actor.send({ type: "play.route", to: "#home" });

Overrides

AbstractActor.send

start()

start(): this;

Defined in: packages/play-xstate/src/player-actor.ts:547

Start the actor

Per RESEARCH.md Pitfall 1: Always call start() after creation

Returns

this

Overrides

AbstractActor.start

stop()

stop(): this;

Defined in: packages/play-xstate/src/player-actor.ts:561

Stop the actor and cleanup

Returns

this

Overrides

AbstractActor.stop

Call Signature

subscribe(observer): Subscription;

Defined in: xstate

Subscribe an observer to an actor’s snapshot values.

Parameters

Parameter	Type	Description
`observer`	`Observer`<`any`>	Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot

Returns

Subscription

Remarks

The observer will receive the actor’s snapshot value when it is emitted. The observer can be:

A plain function that receives the latest snapshot, or
An observer object whose .next(snapshot) method receives the latest snapshot

Examples

// Observer as a plain function
const subscription = actor.subscribe((snapshot) => {
  console.log(snapshot);
});

// Observer as an object
const subscription = actor.subscribe({
  next(snapshot) {
    console.log(snapshot);
  },
  error(err) {
    // ...
  },
  complete() {
    // ...
  },
});

The return value of actor.subscribe(observer) is a subscription object that has an .unsubscribe() method. You can call subscription.unsubscribe() to unsubscribe the observer:

const subscription = actor.subscribe((snapshot) => {
  // ...
});

// Unsubscribe the observer
subscription.unsubscribe();

When the actor is stopped, all of its observers will automatically be unsubscribed.

Inherited from

AbstractActor.subscribe

Call Signature

subscribe(
   nextListener?,
   errorListener?,
   completeListener?): Subscription;

Defined in: xstate

Subscribe an observer to an actor’s snapshot values.

Parameters

Parameter	Type
`nextListener?`	(`snapshot`) => `void`
`errorListener?`	(`error`) => `void`
`completeListener?`	() => `void`

Returns

Subscription

Remarks

The observer will receive the actor’s snapshot value when it is emitted. The observer can be:

A plain function that receives the latest snapshot, or
An observer object whose .next(snapshot) method receives the latest snapshot

Examples

// Observer as a plain function
const subscription = actor.subscribe((snapshot) => {
  console.log(snapshot);
});

// Observer as an object
const subscription = actor.subscribe({
  next(snapshot) {
    console.log(snapshot);
  },
  error(err) {
    // ...
  },
  complete() {
    // ...
  },
});

The return value of actor.subscribe(observer) is a subscription object that has an .unsubscribe() method. You can call subscription.unsubscribe() to unsubscribe the observer:

const subscription = actor.subscribe((snapshot) => {
  // ...
});

// Unsubscribe the observer
subscription.unsubscribe();

When the actor is stopped, all of its observers will automatically be unsubscribed.

Inherited from

AbstractActor.subscribe

toJSON()

toJSON(): object;

Defined in: xstate

Returns

object

Name	Type	Defined in
`id`	`string`	-
`xstate$$type`	`number`	-

Inherited from

AbstractActor.toJSON