State adapters

Ignite Element wraps your state source in an adapter that handles lifecycle, subscriptions, and snapshots for you.

Adapter shapes

XState: pass a machine definition or a started actor to igniteCore. Ignite starts machine-backed actors and stops the ones it owns; if you pass a pre-started actor, Ignite will subscribe to it but will not stop it for you.
Redux Toolkit: pass a slice (factory) or a store instance; Ignite subscribes and reads state on change. If you pass your own store, Ignite will unsubscribe on cleanup but will not dispose it.
MobX: pass an observable or factory; Ignite reads derived values when observables mutate. Externally created observables are left running; Ignite only tears down the subscriptions it owns.

cleanup only controls adapters Ignite owns. For XState machines (actors Ignite creates), cleanup applies; for pre-started actors you provide, Ignite will never stop them.
The same pattern holds for Redux/MobX: Ignite will unsubscribe its adapters on cleanup, but user-provided stores/observables are not disposed. Manage their lifetime yourself.
Rationale: cleanup is a contract for the adapter Ignite creates. A started actor you pass in may be used elsewhere; auto-stopping it would be surprising/destructive. When cleanup runs on shared adapters, Ignite drops its subscription; it only calls actor.stop() when it owns the actor (e.g., from a machine). Stop user-owned actors yourself if needed.

import { createActor } from 'xstate';
import { igniteCore } from 'ignite-element/xstate';
import { toggleMachine } from './machine';

const sharedActor = createActor(toggleMachine);
sharedActor.start();

const register = igniteCore({
  source: sharedActor,
  // ...states/commands/events
});

register('ignite-toggle', /* renderer */);

// Later, when you no longer need the shared actor:
sharedActor.stop();

Machine (definition)          Started actor (you own)
  │                               │
  ▼                               ▼
Ignite adapter (isolated)      Ignite adapter (shared)
owns actor; stop on disconnect stops? only if Ignite owns actor
cleanup flag: n/a              cleanup flag: keep/release adapter subscription

Isolated (machine): per-element actors, stopped on disconnect; cleanup doesn’t apply.
Shared (passed actor/store/observable): one adapter reused; cleanup drops or keeps Ignite’s subscription. User-owned sources are never stopped by Ignite.

Shared vs. isolated

Isolated (default): Ignite constructs a new adapter per element instance. Great for local state.
Shared: pass a long-lived actor/store/observable. Ignite reference-counts subscriptions and, when it owns the underlying resource, stops/unsubscribes after the last element disconnects. External sources you provide stay alive; set cleanup: false to skip auto-teardown even for Ignite-created shared resources.

Deriving render state

Use the states callback to map raw snapshots into render-friendly data. It runs on access and reflects the latest adapter snapshot; it is not memoized, so keep it fast.

states: (snapshot) => ({
  count: snapshot.context.count,
  canUndo: snapshot.can?.({ type: 'UNDO' }) ?? false,
})

Commands

commands receive { actor, emit, host }. Keep them small and focused on dispatching state transitions or tiny side effects.

commands: ({ actor }) => ({
  increment: () => actor.send({ type: 'INCREMENT' }),
});

Events

Declare events to type emit, then fire DOM CustomEvents from your commands. Prefer names with casing that maps to Ignite JSX handler props (onEventName). See Events & commands for more patterns.

events: (event) => ({
  incremented: event<{ count: number }>(),
}),
commands: ({ actor, emit }) => ({
  increment: () => {
    actor.send({ type: 'INCREMENT' });
    emit('incremented', { count: actor.getSnapshot().context.count });
  },
}),

In Ignite JSX, the handler name follows the event:
<my-counter onIncremented={(event) => handleIncrement(event.detail)}></my-counter>