# State machine functions

Import from `@pibbl/core/machines` or `pibbl/machines`. Standalone actors have no
renderer or animation dependency. See the [guide](/guides/state-machines/)
and [types](/reference/types/machines/).

## defineMachine

`defineMachine<Context, Event, Input>(definition)` validates and normalizes a
reusable flat machine. `Input` defaults to `undefined`. Supply `initial`, `context`
(an initial value or a per-actor input factory), and `states`. Optional machine-level
`on` handlers provide fallback behavior. Unknown state targets reject at definition
time. Creating a definition starts no tasks, timers, or animation.

## createMachine

`createMachine(definition, { input })` returns an actor with `snapshot`, `start`,
`send`, and `stop`. It begins as `not-started`. `start()` enters the initial state;
`send(event)` processes serially while active. Nested sends queue. `stop()` is
terminal and idempotent, canceling all state-owned tasks. Sends before start or
after stop do nothing. Retain the actor and stop it when its owner ends.

Snapshots carry state value, context, status, error, and `matches(state)`. Read
with `.get()` or derive a `computed` signal. Never send while rendering or computing.
Use [useMachine](/reference/hooks/use-machine/) for component ownership.

## assign

`assign(({ context, event, input, send }) => patch)` creates an action which
shallowly merges a context patch. Earlier assignments are visible to later actions
in the same transition. Treat nested context objects as immutable. An event's
transition publishes state and context together; assignments do not individually
publish intermediate snapshots.

## fromCallback

`fromCallback(callback)` adapts subscription-style work for `invoke.task`. The
callback receives context, event, input, signal, and send. It can return a cleanup
function, called once on state exit or stop. Returning cleanup does not complete
an invocation. Use promise tasks for finite results and `onDone`/`onError`.

Cancellation aborts the task signal. Stale task results are ignored even if external
work failed to honor cancellation. Unexpected action/guard errors terminate the
actor; invocation errors may take their declared `onError` route.

Related types: [MachineDefinition](/reference/types/machines/#machinedefinition), [MachineActor](/reference/types/machines/#machineactor), [MachineSnapshot](/reference/types/machines/#machinesnapshot), [MachineTask](/reference/types/machines/#machinetask).

## API details from source

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

### assign

Creates an action that shallowly merges a context patch. Earlier assignments in the same
transition are visible to later actions. Context itself remains application-owned data.

```ts
assign: <Context extends object, Event extends MachineEvent, Input>(update: (context: MachineActionContext<Context, Event, Input>) => Partial<Context>) => MachineAction<Context, Event, Input>
```

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

#### Examples

```ts
const collect = assign(({ context }) => ({ coins: context.coins + 1 }));
```

#### Parameters

- **`update`** — Produces the shallow context patch for this transition.

#### Returns

An action accepted by state entry, exit, and transition action lists.

#### See also

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

[View source — packages/core/src/features/machines/assign.ts:22](/source/packages/core/src/features/machines/assign-ts/#L22)

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

### fromCallback

Marks callback-style cancelable work as a machine task. The callback may return a cleanup;
its cleanup runs exactly once when the owning state exits or the actor stops.

```ts
fromCallback: <Context, Event extends MachineEvent, Input>(callback: MachineTask<Context, Event, Input>) => MachineTask<Context, Event, Input>
```

Related API: [fromCallback](/reference/functions/machines/), [MachineEvent](/reference/types/machines/#machineevent), [MachineTask](/reference/types/machines/#machinetask).

#### Parameters

- **`callback`** — Callback task to retain as state-owned work.

#### Returns

The same callback, typed for an invocation's `task` field.

#### See also

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

[View source — packages/core/src/features/machines/callback.ts:10](/source/packages/core/src/features/machines/callback-ts/#L10)

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

### createMachine

Creates an explicitly owned, initially idle machine actor. Call `start()` when ownership begins
and `stop()` when it ends. The actor has no renderer, scheduler, or animation dependency.

```ts
createMachine: <Context, Event extends MachineEvent, Input, State extends string = string>(definition: MachineDefinition<Context, Event, Input, State>, options: CreateMachineOptions<Input>) => MachineActor<Context, Event, Input, State>
```

Related API: [createMachine](/reference/functions/machines/), [MachineEvent](/reference/types/machines/#machineevent), [MachineDefinition](/reference/types/machines/#machinedefinition), [CreateMachineOptions](/reference/types/machines/#createmachineoptions), [MachineActor](/reference/types/machines/#machineactor).

#### Parameters

- **`definition`** — Reusable behavior previously authored with [defineMachine](/reference/functions/machines/).

- **`options`** — Immutable input supplied to this actor.

#### Returns

An idle actor that owns no task until it starts.

#### See also

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

[View source — packages/core/src/features/machines/runtime.ts:55](/source/packages/core/src/features/machines/runtime-ts/#L55)

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

### defineMachine

Validates and records a reusable flat machine definition. Calling this function performs no
work and creates no actor; use createMachine or `useMachine` to execute it.

```ts
defineMachine: <Context, Event extends MachineEvent, Input = undefined, State extends string = string>(definition: MachineDefinition<Context, Event, Input, State>) => MachineDefinition<Context, Event, Input, State>
```

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

#### Parameters

- **`definition`** — Reusable machine behavior to validate and normalize.

#### Returns

The supplied definition, suitable for actor creation.

#### See also

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

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

## 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)
## Documentation version

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