# State machine types

## MachineEvent

Event object with a string `type` discriminator.

## MachineEventRoutes

Maps event discriminators to typed transition handlers. Each handler receives its narrowed event.

## MachineStatus

Actor lifecycle: `not-started`, `active`, `stopped`, or `error`. A game-over application state can remain active.

## MachineSnapshot

Readonly state value, context, lifecycle status, error, and `matches(state)` predicate, published as one signal value.

## MachineTaskCleanup

Synchronous cleanup function for callback work. Called once when its state exits or its actor stops.

## MachineActionContext

Context, initiating event, immutable actor input, and queued send function supplied to synchronous actions.

## MachineAction

Synchronous effect used in entry, exit, or a transition. Use `assign` for context updates.

## MachineActions

One action or a readonly array of actions executed in order.

## MachineTaskContext

Entry context, initiating event (undefined initially), actor input, abort signal, and send function supplied to owned work.

## MachineTask

Cancelable state-owned function returning a cleanup, a promise, or no result. Promises select completion/error routes; cleanup functions remain owned until exit.

## MachineTaskDoneEvent

Internal completion event carrying the task output. Observed by its invocation’s `onDone` handler.

## MachineTaskErrorEvent

Internal failure event carrying the task error. Observed by its invocation’s `onError` handler.

## MachineInvocation

Task with optional diagnostic id and `onDone`/`onError` transitions. A state may declare one or several invocations.

## MachineTransitionConfig

Optional target, guard, ordered actions, and explicit same-state reentry flag.

## MachineTransition

A destination name, configured transition, or ordered list of guarded alternatives.

## MachineState

Flat state with optional entry/exit actions, owned invocations, and local event routes.

## MachineDefinition

Reusable initial state, context factory/value, state table, and machine-level fallback routes.

## CreateMachineOptions

Input captured by the actor at creation. Use `{ input: undefined }` for machines without input.

## MachineActor

Execution handle with a readonly snapshot signal and `start`, `send`, and terminal idempotent `stop` methods.

## MachineAnimationOptions

Optional existing playback conflict policy and diagnostic name, imported from the animation adapter entry.

## MachineAnimationProgramFactory

Builds one animation program per state entry from task context, imported from the animation adapter entry.

## API details from source

<span id="api-CreateMachineOptions"></span>

### CreateMachineOptions

Options used to create an explicitly owned actor.

```ts
interface CreateMachineOptions<Input>
```

Related API: [CreateMachineOptions](/reference/types/machines/#createmachineoptions).

#### See also

[MachineActor](/reference/types/machines/#machineactor)

[View source — packages/core/src/features/machines/types.ts:172](/source/packages/core/src/features/machines/types-ts/#L172)

#### Properties and methods

<span id="api-CreateMachineOptions-input"></span>
<details>
<summary>input</summary>


```ts
readonly input: Input
```

Immutable application input available to context factories, actions, and tasks.

[View source — packages/core/src/features/machines/types.ts:174](/source/packages/core/src/features/machines/types-ts/#L174)

</details>

<span id="api-MachineAction"></span>

### MachineAction

A synchronous effect run during entry, exit, or a transition.

```ts
type MachineAction<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = {
  // Method bivariance lets a reusable event-specific action (such as assign()) run on an initial
  // entry as long as that action does not inspect an absent event.
  /** Executes one synchronous effect.
   * @param context - Current transition values.
   */
  action(context: MachineActionContext<Context, Event, Input, SentEvent>): void;
}['action']
```

Related API: [MachineAction](/reference/types/machines/#machineaction), [MachineEvent](/reference/types/machines/#machineevent), [assign](/reference/functions/machines/), [MachineActionContext](/reference/types/machines/#machineactioncontext).

#### See also

[MachineActionContext](/reference/types/machines/#machineactioncontext)

[View source — packages/core/src/features/machines/types.ts:57](/source/packages/core/src/features/machines/types-ts/#L57)

<span id="api-MachineActionContext"></span>

### MachineActionContext

Values given to state actions. Context reflects all preceding `assign` actions.

```ts
interface MachineActionContext<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent>
```

Related API: [MachineActionContext](/reference/types/machines/#machineactioncontext), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineAction](/reference/types/machines/#machineaction)

[View source — packages/core/src/features/machines/types.ts:43](/source/packages/core/src/features/machines/types-ts/#L43)

#### Properties and methods

<span id="api-MachineActionContext-context"></span>
<details>
<summary>context</summary>


```ts
readonly context: Readonly<Context>
```

Context as it exists at this point in the transition.

[View source — packages/core/src/features/machines/types.ts:45](/source/packages/core/src/features/machines/types-ts/#L45)

</details>

<span id="api-MachineActionContext-event"></span>
<details>
<summary>event</summary>


```ts
readonly event: Event
```

Event which selected this transition.

[View source — packages/core/src/features/machines/types.ts:47](/source/packages/core/src/features/machines/types-ts/#L47)

</details>

<span id="api-MachineActionContext-input"></span>
<details>
<summary>input</summary>


```ts
readonly input: Input
```

Immutable actor input supplied at creation.

[View source — packages/core/src/features/machines/types.ts:49](/source/packages/core/src/features/machines/types-ts/#L49)

</details>

<span id="api-MachineActionContext-send"></span>
<details>
<summary>send</summary>


```ts
send: (event: SentEvent) => void
```

Queues an event after the current transition has completed.

##### Parameters

- **`event`** — Event to process after the active transition.

[View source — packages/core/src/features/machines/types.ts:53](/source/packages/core/src/features/machines/types-ts/#L53)

</details>

<span id="api-MachineActions"></span>

### MachineActions

One action or actions run in source order.

```ts
type MachineActions<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = | MachineAction<Context, Event, Input, SentEvent>
  | readonly MachineAction<Context, Event, Input, SentEvent>[]
```

Related API: [MachineActions](/reference/types/machines/#machineactions), [MachineEvent](/reference/types/machines/#machineevent), [MachineAction](/reference/types/machines/#machineaction).

#### See also

[MachineAction](/reference/types/machines/#machineaction)

[View source — packages/core/src/features/machines/types.ts:67](/source/packages/core/src/features/machines/types-ts/#L67)

<span id="api-MachineActor"></span>

### MachineActor

Explicitly owned machine execution. Call `start` before sending events and `stop` to release it.

```ts
interface MachineActor<Context, Event extends MachineEvent, _Input, State extends string = string>
```

Related API: [MachineActor](/reference/types/machines/#machineactor), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineDefinition](/reference/types/machines/#machinedefinition)

[View source — packages/core/src/features/machines/types.ts:178](/source/packages/core/src/features/machines/types-ts/#L178)

#### Properties and methods

<span id="api-MachineActor-snapshot"></span>
<details>
<summary>snapshot</summary>


```ts
readonly snapshot: Signal<MachineSnapshot<Context, State>>
```

Related API: [Signal](/reference/types/canvas-runtime/#signal), [MachineSnapshot](/reference/types/machines/#machinesnapshot).

Readonly, synchronous signal for the current state and context.

[View source — packages/core/src/features/machines/types.ts:180](/source/packages/core/src/features/machines/types-ts/#L180)

</details>

<span id="api-MachineActor-start"></span>
<details>
<summary>start</summary>


```ts
start: () => void
```

Starts the initial state once. Starting an active or stopped actor does nothing.

[View source — packages/core/src/features/machines/types.ts:182](/source/packages/core/src/features/machines/types-ts/#L182)

</details>

<span id="api-MachineActor-send"></span>
<details>
<summary>send</summary>


```ts
send: (event: Event) => void
```

Queues an event. Events sent during actions run after the current transition.

##### Parameters

- **`event`** — Event accepted by this actor.

[View source — packages/core/src/features/machines/types.ts:186](/source/packages/core/src/features/machines/types-ts/#L186)

</details>

<span id="api-MachineActor-stop"></span>
<details>
<summary>stop</summary>


```ts
stop: () => void
```

Terminal, idempotent cleanup. Cancels every task owned by the active state.

[View source — packages/core/src/features/machines/types.ts:188](/source/packages/core/src/features/machines/types-ts/#L188)

</details>

<span id="api-MachineDefinition"></span>

### MachineDefinition

Declarative, reusable machine definition. Definitions create no actor or scheduled work.

```ts
interface MachineDefinition<Context, Event extends MachineEvent, Input = undefined, State extends string = string>
```

Related API: [MachineDefinition](/reference/types/machines/#machinedefinition), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineActor](/reference/types/machines/#machineactor)

[View source — packages/core/src/features/machines/types.ts:157](/source/packages/core/src/features/machines/types-ts/#L157)

#### Properties and methods

<span id="api-MachineDefinition-initial"></span>
<details>
<summary>initial</summary>


```ts
readonly initial: State
```

State entered when an actor starts.

[View source — packages/core/src/features/machines/types.ts:159](/source/packages/core/src/features/machines/types-ts/#L159)

</details>

<span id="api-MachineDefinition-context"></span>
<details>
<summary>context</summary>


```ts
readonly context: Context | ((context: Readonly<{ input: Input; }>) => Context)
```

Initial context or a factory evaluated once for every actor.

##### Parameters

- **`context`** — Input used to create this actor's context.

##### Returns

Initial context for the new actor.

[View source — packages/core/src/features/machines/types.ts:164](/source/packages/core/src/features/machines/types-ts/#L164)

</details>

<span id="api-MachineDefinition-states"></span>
<details>
<summary>states</summary>


```ts
readonly states: Readonly<Record<State, MachineState<Context, Event, Input, State>>>
```

Related API: [MachineState](/reference/types/machines/#machinestate).

State table. This initial implementation supports flat states only.

[View source — packages/core/src/features/machines/types.ts:166](/source/packages/core/src/features/machines/types-ts/#L166)

</details>

<span id="api-MachineDefinition-on"></span>
<details>
<summary>on (optional)</summary>


```ts
readonly on?: MachineEventRoutes<Context, Event, Input, State> | undefined
```

Related API: [MachineEventRoutes](/reference/types/machines/#machineeventroutes).

Fallback routes for events not declared by the active state.

[View source — packages/core/src/features/machines/types.ts:168](/source/packages/core/src/features/machines/types-ts/#L168)

</details>

<span id="api-MachineEvent"></span>

### MachineEvent

An event accepted by a machine. The `type` selects the active state's handler.

```ts
interface MachineEvent
```

Related API: [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineDefinition](/reference/types/machines/#machinedefinition)

[View source — packages/core/src/features/machines/types.ts:4](/source/packages/core/src/features/machines/types-ts/#L4)

#### Properties and methods

<span id="api-MachineEvent-type"></span>
<details>
<summary>type</summary>


```ts
readonly type: string
```

Stable event discriminator.

[View source — packages/core/src/features/machines/types.ts:6](/source/packages/core/src/features/machines/types-ts/#L6)

</details>

<span id="api-MachineEventRoutes"></span>

### MachineEventRoutes

Maps each event discriminator to its narrowed event shape.

```ts
type MachineEventRoutes<Context, Event extends MachineEvent, Input, State extends string> = {
  /** Handler selected for the corresponding event discriminator. */
  [type in Event['type']]?: MachineTransition<Context, Extract<Event, { /** Discriminator used to select this event variant. */ readonly type: type }>, Input, State, Event>;
}
```

Related API: [MachineEventRoutes](/reference/types/machines/#machineeventroutes), [MachineEvent](/reference/types/machines/#machineevent), [MachineTransition](/reference/types/machines/#machinetransition).

#### See also

[MachineTransition](/reference/types/machines/#machinetransition)

[View source — packages/core/src/features/machines/types.ts:14](/source/packages/core/src/features/machines/types-ts/#L14)

<span id="api-MachineInvocation"></span>

### MachineInvocation

State-owned task and optional completion transitions.

```ts
interface MachineInvocation<Context, Event extends MachineEvent, Input, State extends string>
```

Related API: [MachineInvocation](/reference/types/machines/#machineinvocation), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineTask](/reference/types/machines/#machinetask)

[View source — packages/core/src/features/machines/types.ts:112](/source/packages/core/src/features/machines/types-ts/#L112)

#### Properties and methods

<span id="api-MachineInvocation-id"></span>
<details>
<summary>id (optional)</summary>


```ts
readonly id?: string | undefined
```

Optional diagnostic identity; IDs are local to one state entry.

[View source — packages/core/src/features/machines/types.ts:114](/source/packages/core/src/features/machines/types-ts/#L114)

</details>

<span id="api-MachineInvocation-task"></span>
<details>
<summary>task</summary>


```ts
readonly task: MachineTask<Context, Event, Input, unknown>
```

Related API: [MachineTask](/reference/types/machines/#machinetask).

Work started after this state's snapshot publishes.

[View source — packages/core/src/features/machines/types.ts:116](/source/packages/core/src/features/machines/types-ts/#L116)

</details>

<span id="api-MachineInvocation-onDone"></span>
<details>
<summary>onDone (optional)</summary>


```ts
readonly onDone?: MachineTransition<Context, MachineTaskDoneEvent<unknown>, Input, State, Event> | undefined
```

Related API: [MachineTransition](/reference/types/machines/#machinetransition), [MachineTaskDoneEvent](/reference/types/machines/#machinetaskdoneevent).

Transition selected if a promise resolves before cancellation.

[View source — packages/core/src/features/machines/types.ts:118](/source/packages/core/src/features/machines/types-ts/#L118)

</details>

<span id="api-MachineInvocation-onError"></span>
<details>
<summary>onError (optional)</summary>


```ts
readonly onError?: MachineTransition<Context, MachineTaskErrorEvent, Input, State, Event> | undefined
```

Related API: [MachineTransition](/reference/types/machines/#machinetransition), [MachineTaskErrorEvent](/reference/types/machines/#machinetaskerrorevent).

Transition selected if a task throws or a promise rejects before cancellation.

[View source — packages/core/src/features/machines/types.ts:120](/source/packages/core/src/features/machines/types-ts/#L120)

</details>

<span id="api-MachineSnapshot"></span>

### MachineSnapshot

Immutable state published by a running machine actor.

```ts
interface MachineSnapshot<Context, State extends string = string>
```

Related API: [MachineSnapshot](/reference/types/machines/#machinesnapshot).

#### See also

[MachineActor](/reference/types/machines/#machineactor)

[View source — packages/core/src/features/machines/types.ts:23](/source/packages/core/src/features/machines/types-ts/#L23)

#### Properties and methods

<span id="api-MachineSnapshot-value"></span>
<details>
<summary>value</summary>


```ts
readonly value: State
```

Active flat state name.

[View source — packages/core/src/features/machines/types.ts:25](/source/packages/core/src/features/machines/types-ts/#L25)

</details>

<span id="api-MachineSnapshot-context"></span>
<details>
<summary>context</summary>


```ts
readonly context: Readonly<Context>
```

Application-owned immutable context for the active state.

[View source — packages/core/src/features/machines/types.ts:27](/source/packages/core/src/features/machines/types-ts/#L27)

</details>

<span id="api-MachineSnapshot-status"></span>
<details>
<summary>status</summary>


```ts
readonly status: MachineStatus
```

Related API: [MachineStatus](/reference/types/machines/#machinestatus).

Whether the actor may receive events.

[View source — packages/core/src/features/machines/types.ts:29](/source/packages/core/src/features/machines/types-ts/#L29)

</details>

<span id="api-MachineSnapshot-error"></span>
<details>
<summary>error</summary>


```ts
readonly error: unknown
```

Unexpected failure that stopped this actor, if any.

[View source — packages/core/src/features/machines/types.ts:31](/source/packages/core/src/features/machines/types-ts/#L31)

</details>

<span id="api-MachineSnapshot-matches"></span>
<details>
<summary>matches</summary>


```ts
matches: (state: State) => boolean
```

Tests whether this flat machine currently occupies `state`.

##### Parameters

- **`state`** — State name to compare with the active value.

##### Returns

True when this is the active state.

[View source — packages/core/src/features/machines/types.ts:36](/source/packages/core/src/features/machines/types-ts/#L36)

</details>

<span id="api-MachineState"></span>

### MachineState

One flat state definition. Local event handlers shadow machine-level handlers.

```ts
interface MachineState<Context, Event extends MachineEvent, Input, State extends string>
```

Related API: [MachineState](/reference/types/machines/#machinestate), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineDefinition](/reference/types/machines/#machinedefinition)

[View source — packages/core/src/features/machines/types.ts:145](/source/packages/core/src/features/machines/types-ts/#L145)

#### Properties and methods

<span id="api-MachineState-entry"></span>
<details>
<summary>entry (optional)</summary>


```ts
readonly entry?: MachineActions<Context, Event | undefined, Input, Event> | undefined
```

Related API: [MachineActions](/reference/types/machines/#machineactions).

Effects run whenever this state is entered. The initial entry receives `undefined` as event.

[View source — packages/core/src/features/machines/types.ts:147](/source/packages/core/src/features/machines/types-ts/#L147)

</details>

<span id="api-MachineState-exit"></span>
<details>
<summary>exit (optional)</summary>


```ts
readonly exit?: MachineActions<Context, Event, Input, Event> | undefined
```

Related API: [MachineActions](/reference/types/machines/#machineactions).

Effects run whenever this state is exited.

[View source — packages/core/src/features/machines/types.ts:149](/source/packages/core/src/features/machines/types-ts/#L149)

</details>

<span id="api-MachineState-invoke"></span>
<details>
<summary>invoke (optional)</summary>


```ts
readonly invoke?: MachineInvocation<Context, Event, Input, State> | readonly MachineInvocation<Context, Event, Input, State>[] | undefined
```

Related API: [MachineInvocation](/reference/types/machines/#machineinvocation).

State-owned work, canceled before exit effects.

[View source — packages/core/src/features/machines/types.ts:151](/source/packages/core/src/features/machines/types-ts/#L151)

</details>

<span id="api-MachineState-on"></span>
<details>
<summary>on (optional)</summary>


```ts
readonly on?: MachineEventRoutes<Context, Event, Input, State> | undefined
```

Related API: [MachineEventRoutes](/reference/types/machines/#machineeventroutes).

Event routes local to this state. Declaring an event consumes machine-level handling.

[View source — packages/core/src/features/machines/types.ts:153](/source/packages/core/src/features/machines/types-ts/#L153)

</details>

<span id="api-MachineStatus"></span>

### MachineStatus

Lifecycle state of a machine actor.

```ts
type MachineStatus = 'not-started' | 'active' | 'stopped' | 'error'
```

Related API: [MachineStatus](/reference/types/machines/#machinestatus).

#### See also

[MachineActor](/reference/types/machines/#machineactor)

[View source — packages/core/src/features/machines/types.ts:20](/source/packages/core/src/features/machines/types-ts/#L20)

<span id="api-MachineTask"></span>

### MachineTask

Cancelable work owned by a state entry. Return a cleanup for subscriptions or a promise for
finite work. A task is never started until its entry snapshot has been published.

```ts
type MachineTask<Context, Event extends MachineEvent, Input, Output = unknown> = (
  context: MachineTaskContext<Context, Event, Input>,
) => void | MachineTaskCleanup | Promise<Output>
```

Related API: [MachineTask](/reference/types/machines/#machinetask), [MachineEvent](/reference/types/machines/#machineevent), [MachineTaskContext](/reference/types/machines/#machinetaskcontext), [MachineTaskCleanup](/reference/types/machines/#machinetaskcleanup).

#### Parameters

- **`context`** — State-entry values and cancellation signal.

#### Returns

Optional cleanup or a promise for finite work.

#### See also

[MachineInvocation](/reference/types/machines/#machineinvocation)

[View source — packages/core/src/features/machines/types.ts:94](/source/packages/core/src/features/machines/types-ts/#L94)

<span id="api-MachineTaskCleanup"></span>

### MachineTaskCleanup

Cleanup called when a callback task's owning state exits or its actor stops.

```ts
type MachineTaskCleanup = () => void
```

Related API: [MachineTaskCleanup](/reference/types/machines/#machinetaskcleanup).

#### See also

[MachineTask](/reference/types/machines/#machinetask)

[View source — packages/core/src/features/machines/types.ts:40](/source/packages/core/src/features/machines/types-ts/#L40)

<span id="api-MachineTaskContext"></span>

### MachineTaskContext

Values supplied to a state-owned task when that state is entered.

```ts
interface MachineTaskContext<Context, Event extends MachineEvent, Input>
```

Related API: [MachineTaskContext](/reference/types/machines/#machinetaskcontext), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineTask](/reference/types/machines/#machinetask)

[View source — packages/core/src/features/machines/types.ts:72](/source/packages/core/src/features/machines/types-ts/#L72)

#### Properties and methods

<span id="api-MachineTaskContext-context"></span>
<details>
<summary>context</summary>


```ts
readonly context: Readonly<Context>
```

Context captured when this particular task starts.

[View source — packages/core/src/features/machines/types.ts:74](/source/packages/core/src/features/machines/types-ts/#L74)

</details>

<span id="api-MachineTaskContext-event"></span>
<details>
<summary>event</summary>


```ts
readonly event: Event | undefined
```

Event that entered this state, or undefined for the initial state.

[View source — packages/core/src/features/machines/types.ts:76](/source/packages/core/src/features/machines/types-ts/#L76)

</details>

<span id="api-MachineTaskContext-input"></span>
<details>
<summary>input</summary>


```ts
readonly input: Input
```

Immutable actor input supplied at creation.

[View source — packages/core/src/features/machines/types.ts:78](/source/packages/core/src/features/machines/types-ts/#L78)

</details>

<span id="api-MachineTaskContext-signal"></span>
<details>
<summary>signal</summary>


```ts
readonly signal: AbortSignal
```

Related API: [signal](/reference/functions/signal/).

Aborted synchronously when the owning state exits.

[View source — packages/core/src/features/machines/types.ts:80](/source/packages/core/src/features/machines/types-ts/#L80)

</details>

<span id="api-MachineTaskContext-send"></span>
<details>
<summary>send</summary>


```ts
send: (event: Event) => void
```

Queues an event after the current transition, without re-entering the actor.

##### Parameters

- **`event`** — Event accepted by the owning actor.

[View source — packages/core/src/features/machines/types.ts:84](/source/packages/core/src/features/machines/types-ts/#L84)

</details>

<span id="api-MachineTaskDoneEvent"></span>

### MachineTaskDoneEvent

Completion data supplied to an invocation's `onDone` transition.

```ts
interface MachineTaskDoneEvent<Output = unknown> extends MachineEvent
```

Related API: [MachineTaskDoneEvent](/reference/types/machines/#machinetaskdoneevent), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineInvocation](/reference/types/machines/#machineinvocation)

[View source — packages/core/src/features/machines/types.ts:99](/source/packages/core/src/features/machines/types-ts/#L99)

#### Properties and methods

<span id="api-MachineTaskDoneEvent-type"></span>
<details>
<summary>type</summary>


```ts
readonly type: "@pibbl/machine.done"
```

Related API: [pibbl](/reference/functions/pibbl/).

Internal completion discriminator.

[View source — packages/core/src/features/machines/types.ts:100](/source/packages/core/src/features/machines/types-ts/#L100)

</details>

<span id="api-MachineTaskDoneEvent-output"></span>
<details>
<summary>output</summary>


```ts
readonly output: Output
```

Value resolved by the task promise.

[View source — packages/core/src/features/machines/types.ts:101](/source/packages/core/src/features/machines/types-ts/#L101)

</details>

<span id="api-MachineTaskErrorEvent"></span>

### MachineTaskErrorEvent

Failure data supplied to an invocation's `onError` transition.

```ts
interface MachineTaskErrorEvent extends MachineEvent
```

Related API: [MachineTaskErrorEvent](/reference/types/machines/#machinetaskerrorevent), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineInvocation](/reference/types/machines/#machineinvocation)

[View source — packages/core/src/features/machines/types.ts:105](/source/packages/core/src/features/machines/types-ts/#L105)

#### Properties and methods

<span id="api-MachineTaskErrorEvent-type"></span>
<details>
<summary>type</summary>


```ts
readonly type: "@pibbl/machine.error"
```

Related API: [pibbl](/reference/functions/pibbl/).

Internal failure discriminator.

[View source — packages/core/src/features/machines/types.ts:106](/source/packages/core/src/features/machines/types-ts/#L106)

</details>

<span id="api-MachineTaskErrorEvent-error"></span>
<details>
<summary>error</summary>


```ts
readonly error: unknown
```

Thrown or rejected task value.

[View source — packages/core/src/features/machines/types.ts:107](/source/packages/core/src/features/machines/types-ts/#L107)

</details>

<span id="api-MachineTransition"></span>

### MachineTransition

Shorthand state target, a configured route, or ordered guarded alternatives.

```ts
type MachineTransition<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event> = | State
  | MachineTransitionConfig<Context, Event, Input, State, SentEvent>
  | readonly MachineTransitionConfig<Context, Event, Input, State, SentEvent>[]
```

Related API: [MachineTransition](/reference/types/machines/#machinetransition), [MachineEvent](/reference/types/machines/#machineevent), [MachineTransitionConfig](/reference/types/machines/#machinetransitionconfig).

#### See also

[MachineTransitionConfig](/reference/types/machines/#machinetransitionconfig)

[View source — packages/core/src/features/machines/types.ts:139](/source/packages/core/src/features/machines/types-ts/#L139)

<span id="api-MachineTransitionConfig"></span>

### MachineTransitionConfig

A conditional route considered in list order.

```ts
interface MachineTransitionConfig<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event>
```

Related API: [MachineTransitionConfig](/reference/types/machines/#machinetransitionconfig), [MachineEvent](/reference/types/machines/#machineevent).

#### See also

[MachineTransition](/reference/types/machines/#machinetransition)

[View source — packages/core/src/features/machines/types.ts:124](/source/packages/core/src/features/machines/types-ts/#L124)

#### Properties and methods

<span id="api-MachineTransitionConfig-target"></span>
<details>
<summary>target (optional)</summary>


```ts
readonly target?: State | undefined
```

Destination state. Omit to run actions without leaving the current state.

[View source — packages/core/src/features/machines/types.ts:126](/source/packages/core/src/features/machines/types-ts/#L126)

</details>

<span id="api-MachineTransitionConfig-guard"></span>
<details>
<summary>guard (optional)</summary>


```ts
readonly guard?: ((context: MachineActionContext<Context, Event, Input, SentEvent>) => boolean) | undefined
```

Related API: [MachineActionContext](/reference/types/machines/#machineactioncontext).

Only select this route when it returns true.

##### Parameters

- **`context`** — Current transition values.

##### Returns

Whether this route may be selected.

[View source — packages/core/src/features/machines/types.ts:131](/source/packages/core/src/features/machines/types-ts/#L131)

</details>

<span id="api-MachineTransitionConfig-actions"></span>
<details>
<summary>actions (optional)</summary>


```ts
readonly actions?: MachineActions<Context, Event, Input, SentEvent> | undefined
```

Related API: [MachineActions](/reference/types/machines/#machineactions).

Effects run after exit and before entry.

[View source — packages/core/src/features/machines/types.ts:133](/source/packages/core/src/features/machines/types-ts/#L133)

</details>

<span id="api-MachineTransitionConfig-reenter"></span>
<details>
<summary>reenter (optional)</summary>


```ts
readonly reenter?: boolean | undefined
```

Restarts entry work when targeting the already active state.

[View source — packages/core/src/features/machines/types.ts:135](/source/packages/core/src/features/machines/types-ts/#L135)

</details>

<span id="api-MachineAnimationOptions"></span>

### MachineAnimationOptions

Playback options owned by a machine animation task.

Lifecycle callbacks are deliberately omitted: task completion and failure
become the invocation's `onDone` and `onError` transitions instead.

```ts
interface MachineAnimationOptions
```

Related API: [MachineAnimationOptions](/reference/types/machines/#machineanimationoptions).

#### See also

[playAnimation](/reference/functions/play-animation/)

[View source — packages/core/src/features/machines/animation.ts:23](/source/packages/core/src/features/machines/animation-ts/#L23)

#### Properties and methods

<span id="api-MachineAnimationOptions-conflict"></span>
<details>
<summary>conflict (optional)</summary>


```ts
readonly conflict?: "error" | "replace" | undefined
```

Selects the existing writer-conflict policy for this state-owned playback.
Defaults to the animation runtime's explicit-error policy.

[View source — packages/core/src/features/machines/animation.ts:28](/source/packages/core/src/features/machines/animation-ts/#L28)

</details>

<span id="api-MachineAnimationOptions-debugName"></span>
<details>
<summary>debugName (optional)</summary>


```ts
readonly debugName?: string | undefined
```

Optional label included in animation scheduler diagnostics.

[View source — packages/core/src/features/machines/animation.ts:30](/source/packages/core/src/features/machines/animation-ts/#L30)

</details>

<span id="api-MachineAnimationProgramFactory"></span>

### MachineAnimationProgramFactory

Builds the animation program for one state entry.

The callback runs once when the invocation starts. It receives the entry's
immutable context and event, the machine input, the cancellation signal, and
`send` for application-defined machine events.

```ts
type MachineAnimationProgramFactory<Context, Event extends MachineEvent, Input> = (
  context: MachineTaskContext<Context, Event, Input>,
) => PibblAnimationProgram
```

Related API: [MachineAnimationProgramFactory](/reference/types/machines/#machineanimationprogramfactory), [MachineEvent](/reference/types/machines/#machineevent), [MachineTaskContext](/reference/types/machines/#machinetaskcontext), [PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram).

#### Type parameters

- **`Context`** — Context captured when this state entry began.

- **`Event`** — Event type accepted by the owning machine.

- **`Input`** — Input captured by the owning machine actor.

#### Parameters

- **`context`** — Immutable state-entry values used to create this program.

#### Returns

The program that the machine invocation owns until it finishes or is cancelled.

#### See also

[MachineTaskContext](/reference/types/machines/#machinetaskcontext)

[View source — packages/core/src/features/machines/animation.ts:47](/source/packages/core/src/features/machines/animation-ts/#L47)

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Cancelable machine tasks](/minimal-examples/machines/tasks/): Run a state-owned task, observe completion, and release actors and listeners. [Plain source](/minimal/machines/tasks.tsx)
- [State-owned animation](/minimal-examples/machines/animation/): Move a circle with a machine-owned animation task that completes into the next state. [Plain source](/minimal/machines/animation.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.