xstate 6.0.0-alpha.4 → 6.0.0-alpha.41

package/dist/StateMachine-8e73d782.cjs.js

@@ -0,0 +1,1200 @@
+'use strict';
+
+var createActor = require('./createActor-f3afd774.cjs.js');
+var dist_xstateActors = require('./index-7fd92683.cjs.js');
+
+function createSpawner(actorScope, actors, spawnedChildren) {
+  return (src, options) => {
+    const referencedSrc = Object.entries(actors).find(([, logic]) => logic === src)?.[0];
+    // Generated ids come from the same transaction allocator as `enq.spawn`,
+    // so context-factory allocations persist with the snapshot and never
+    // collide with later spawns.
+    const id = options?.id ?? createActor.allocateChildId(actorScope, referencedSrc ?? src).id;
+    if (options?.id !== undefined) {
+      createActor.assertChildIdFree(actorScope, options.id);
+      createActor.reserveChildId(actorScope, options.id);
+    }
+    const actor = actorScope.system.createActorRef(src, {
+      id,
+      parent: actorScope.self,
+      syncSnapshot: options?.syncSnapshot,
+      input: options?.input,
+      src: referencedSrc ?? src,
+      registryKey: options?.registryKey
+    });
+    spawnedChildren[actor.id] = actor;
+    return actor;
+  };
+}
+
+const cache = new WeakMap();
+function memo(object, key, fn) {
+  let memoizedData = cache.get(object);
+  if (!memoizedData) {
+    memoizedData = {
+      [key]: fn()
+    };
+    cache.set(object, memoizedData);
+  } else if (!(key in memoizedData)) {
+    memoizedData[key] = fn();
+  }
+  return memoizedData[key];
+}
+
+const EMPTY_OBJECT = {};
+class StateNode {
+  constructor(/** The raw config used to create the machine. */
+  config, options) {
+    this.config = config;
+    /**
+     * The relative key of the state node, which represents its location in the
+     * overall state value.
+     */
+    this.key = void 0;
+    /** The unique ID of the state node. */
+    this.id = void 0;
+    /**
+     * The type of this state node:
+     *
+     * - `'atomic'` - no child state nodes
+     * - `'compound'` - nested child state nodes (XOR)
+     * - `'parallel'` - orthogonal nested child state nodes (AND)
+     * - `'history'` - history state node
+     * - `'choice'` - pure routing decision state node
+     * - `'final'` - final state node
+     */
+    this.type = void 0;
+    /** The string path from the root machine node to this node. */
+    this.path = void 0;
+    /** The child state nodes. */
+    this.states = void 0;
+    /**
+     * The type of history on this state node. Can be:
+     *
+     * - `'shallow'` - recalls only top-level historical state value
+     * - `'deep'` - recalls historical state value at all levels
+     */
+    this.history = void 0;
+    /** The action(s) to be executed upon entering the state node. */
+    this.entry = void 0;
+    /** The action(s) to be executed upon exiting the state node. */
+    this.exit = void 0;
+    /** The parent state node. */
+    this.parent = void 0;
+    /** The root machine node. */
+    this.machine = void 0;
+    /**
+     * The meta data associated with this state node, which will be returned in
+     * State instances.
+     */
+    this.meta = void 0;
+    /**
+     * The output data sent with the `xstate.done.state` event if this is a final
+     * state node.
+     */
+    this.output = void 0;
+    /**
+     * The order this state node appears. Corresponds to the implicit document
+     * order.
+     */
+    this.order = -1;
+    this.description = void 0;
+    this.schemas = void 0;
+    this.tags = [];
+    this.transitions = void 0;
+    this.always = void 0;
+    this.invoke = void 0;
+    this.on = void 0;
+    this.after = void 0;
+    this.events = void 0;
+    this.ownEvents = void 0;
+    this._candidateCache = void 0;
+    this.parent = options._parent;
+    this.key = options._key;
+    this.machine = options._machine;
+    this.path = this.parent ? this.parent.path.concat(this.key) : [];
+    const firstStateKey = this.config.states ? Object.keys(this.config.states)[0] : undefined;
+    this.id = this.config.id || [this.machine.id, ...this.path].join(createActor.STATE_DELIMITER);
+    this.type = this.config.type || (firstStateKey !== undefined ? 'compound' : this.config.history ? 'history' : 'atomic');
+    this.description = this.config.description;
+    this.schemas = this.config.schemas;
+    validateStateNodeConfig(this);
+    this.order = this.machine.idMap.size;
+    this.machine.idMap.set(this.id, this);
+    this.states = this.config.states ? createActor.mapValues(this.config.states, (stateConfig, key) => {
+      const stateNode = new StateNode(stateConfig, {
+        _parent: this,
+        _key: key,
+        _machine: this.machine
+      });
+      return stateNode;
+    }) : EMPTY_OBJECT;
+    if (this.type === 'compound' && !this.config.initial) {
+      throw new Error(`No initial state specified for compound state node "#${this.id}".`);
+    }
+
+    // History config
+    this.history = this.config.history === true ? 'shallow' : this.config.history || false;
+    this.entry = this.config.entry;
+    this.exit = this.config.exit;
+    if (this.entry) {
+      // @ts-expect-error _special is an internal marker not on the Action type
+      this.entry._special = true;
+    }
+    if (this.exit) {
+      // @ts-expect-error _special is an internal marker not on the Action type
+      this.exit._special = true;
+    }
+    this.meta = this.config.meta;
+    this.output = this.type === 'final' || !this.parent ? this.config.output : undefined;
+    this.tags = createActor.toArray(config.tags).slice();
+    this.invoke = createActor.toArray(this.config.invoke).map((invokeConfig, i) => {
+      const {
+        src,
+        registryKey
+      } = invokeConfig;
+      const invokeId = createActor.createInvokeId(this.id, i);
+      const resolvedId = invokeConfig.id ?? invokeId;
+      // Referenced (string) actors keep their logical name so persisted
+      // snapshots reference `src: 'fetchUser'` rather than a positional id;
+      // only inline logic gets the synthetic source name.
+      const sourceName = typeof src === 'string' ? src : `xstate.invoke.${invokeId}`;
+      return {
+        ...invokeConfig,
+        src: sourceName,
+        logic: src,
+        id: resolvedId,
+        registryKey
+      };
+    });
+  }
+
+  /** @internal */
+  _initialize() {
+    this.after = createActor.getDelayedTransitions(this);
+    this.transitions = formatTransitions(this);
+    if (this.type === 'choice') {
+      this.always = formatChoiceTransitions(this);
+    } else if (this.config.always) {
+      this.always = mapTransitionConfigs(this.config.always, transition => createActor.formatTransition(this, createActor.NULL_EVENT, transition));
+    }
+    for (const key of Object.keys(this.states)) {
+      this.states[key]._initialize();
+    }
+    this._refreshEventMetadata();
+  }
+
+  /** @internal */
+  _refreshEventMetadata() {
+    const on = {};
+    const ownEvents = [];
+    for (const [descriptor, transitions] of this.transitions) {
+      on[descriptor] = transitions.slice();
+      if (transitions.some(transition => transition.target || transition.reenter || transition.to)) {
+        ownEvents.push(descriptor);
+      }
+    }
+    this.on = on;
+    this.ownEvents = ownEvents;
+    const events = new Set(ownEvents);
+    for (const state of Object.values(this.states)) {
+      for (const event of state.events) {
+        events.add(event);
+      }
+    }
+    this.events = Array.from(events);
+  }
+  get initial() {
+    return memo(this, 'initial', () => formatInitialTransition(this, this.config.initial));
+  }
+
+  /** @internal */
+  next(snapshot, event, actorScope, selectionResults) {
+    const descriptorKey = createActor.getEventDescriptorKey(event);
+    let candidates = this._candidateCache?.get(descriptorKey);
+    if (!candidates) {
+      candidates = createActor.getCandidates(this, event);
+      (this._candidateCache ??= new Map()).set(descriptorKey, candidates);
+    }
+    for (const candidate of candidates) {
+      const guardPassed = createActor.evaluateCandidate(candidate, event, snapshot, this, actorScope, selectionResults);
+      if (guardPassed) {
+        return [candidate];
+      }
+    }
+    return undefined;
+  }
+}
+function validateStateNodeConfig(stateNode) {
+  const config = stateNode.config;
+  if (stateNode.type === 'history' && !(typeof config.target === 'string' && config.target.trim().length > 0 || Array.isArray(config.target) && config.target.length > 0 && config.target.every(target => typeof target === 'string' && target.trim().length > 0))) {
+    throw new Error(`Missing history target on "${stateNode.id}"`);
+  }
+  if (stateNode.type !== 'choice') {
+    return;
+  }
+  if (typeof config.choice !== 'function') {
+    throw new Error(`Missing \`choice\` function on "${stateNode.id}"`);
+  }
+}
+function formatChoiceTransitions(stateNode) {
+  const choice = stateNode.config.choice;
+  const validateChoiceResult = result => {
+    if (!result || result.target === undefined) {
+      throw new Error(`Choice "${stateNode.id}" has no target`);
+    }
+    return result;
+  };
+  return [createActor.formatTransition(stateNode, createActor.NULL_EVENT, {
+    to: args => validateChoiceResult(choice(args))
+  })];
+}
+function mapTransitionConfigs(transitionsConfig, mapper) {
+  const transitionConfigs = createActor.toTransitionConfigArray(transitionsConfig);
+  const transitions = new Array(transitionConfigs.length);
+  for (let i = 0; i < transitionConfigs.length; i++) {
+    transitions[i] = mapper(transitionConfigs[i]);
+  }
+  return transitions;
+}
+function formatTransitions(stateNode) {
+  const transitions = new Map();
+  const addTransitions = (descriptor, additions) => {
+    transitions.set(descriptor, [...(transitions.get(descriptor) ?? []), ...additions]);
+  };
+  if (stateNode.config.on) {
+    for (const descriptor of Object.keys(stateNode.config.on)) {
+      if (descriptor === createActor.NULL_EVENT) {
+        throw new Error('Null event transition key');
+      }
+      const transitionsConfig = stateNode.config.on[descriptor];
+      transitions.set(descriptor, mapTransitionConfigs(transitionsConfig, transition => createActor.formatTransition(stateNode, descriptor, transition)));
+    }
+  }
+  if (stateNode.config.onDone) {
+    const descriptor = 'xstate.done.state';
+    addTransitions(descriptor, mapTransitionConfigs(stateNode.config.onDone, transition => createActor.formatTransition(stateNode, descriptor, {
+      ...transition,
+      matches: {
+        ...transition.matches,
+        stateId: stateNode.id
+      }
+    })));
+  }
+  if (stateNode.config.onError) {
+    const descriptor = 'xstate.error.*';
+    transitions.set(descriptor, mapTransitionConfigs(stateNode.config.onError, transition => createActor.formatTransition(stateNode, descriptor, transition)));
+  }
+  const createCancelInvokeTimeoutTransition = (descriptor, timeoutEventId, actorId) => createActor.formatTransition(stateNode, descriptor, {
+    matches: {
+      actorId
+    },
+    _eventMatcher: (event, snapshot) => createActor.matchesActorSession(event, snapshot, actorId),
+    to: (_args, enq) => {
+      enq.cancel(timeoutEventId);
+      return {};
+    }
+  });
+  const formatInvokeCompletionTransition = (descriptor, transitionConfig, timeoutEventId) => {
+    const {
+      target,
+      to,
+      reenter,
+      ...rest
+    } = transitionConfig;
+    return createActor.formatTransition(stateNode, descriptor, {
+      ...rest,
+      reenter,
+      to: (args, enq) => {
+        if (to) {
+          let didEnqueue = false;
+          const trackingEnqueue = new Proxy(enq, {
+            apply(target, thisArg, argArray) {
+              didEnqueue = true;
+              return Reflect.apply(target, thisArg, argArray);
+            },
+            get(target, prop, receiver) {
+              const value = Reflect.get(target, prop, receiver);
+              if (typeof value !== 'function') {
+                return value;
+              }
+              return (...argArray) => {
+                didEnqueue = true;
+                return value.apply(target, argArray);
+              };
+            }
+          });
+          const result = to(args, trackingEnqueue);
+          if (result !== undefined || didEnqueue) {
+            enq.cancel(timeoutEventId);
+          }
+          return result;
+        }
+        enq.cancel(timeoutEventId);
+        return {
+          target,
+          reenter
+        };
+      }
+    });
+  };
+  for (const invokeDef of stateNode.invoke) {
+    const withInvokeMatch = transition => ({
+      ...transition,
+      matches: {
+        ...transition.matches,
+        actorId: invokeDef.id
+      },
+      _eventMatcher: (event, snapshot) => createActor.matchesActorSession(event, snapshot, invokeDef.id)
+    });
+    const invokeTimeoutEventId = invokeDef.timeout !== undefined ? createActor.createInvokeTimeoutEventId(invokeDef.id) : undefined;
+    if (invokeDef.onDone) {
+      const descriptor = 'xstate.done.actor';
+      const invokeDoneTransitions = mapTransitionConfigs(invokeDef.onDone, rawTransition => {
+        const transition = withInvokeMatch(rawTransition);
+        return invokeTimeoutEventId ? formatInvokeCompletionTransition(descriptor, transition, invokeTimeoutEventId) : createActor.formatTransition(stateNode, descriptor, transition);
+      });
+      if (invokeTimeoutEventId) {
+        invokeDoneTransitions.push(createCancelInvokeTimeoutTransition(descriptor, invokeTimeoutEventId, invokeDef.id));
+      }
+      addTransitions(descriptor, invokeDoneTransitions);
+    } else if (invokeTimeoutEventId) {
+      const descriptor = 'xstate.done.actor';
+      addTransitions(descriptor, [createCancelInvokeTimeoutTransition(descriptor, invokeTimeoutEventId, invokeDef.id)]);
+    }
+    if (invokeDef.onError) {
+      const descriptor = 'xstate.error.actor';
+      addTransitions(descriptor, mapTransitionConfigs(invokeDef.onError, rawTransition => {
+        const transition = withInvokeMatch(rawTransition);
+        return invokeTimeoutEventId ? formatInvokeCompletionTransition(descriptor, transition, invokeTimeoutEventId) : createActor.formatTransition(stateNode, descriptor, transition);
+      }));
+    }
+    if (invokeDef.onSnapshot) {
+      const descriptor = 'xstate.snapshot.actor';
+      addTransitions(descriptor, mapTransitionConfigs(invokeDef.onSnapshot, transition => createActor.formatTransition(stateNode, descriptor, withInvokeMatch(transition))));
+    }
+  }
+  for (const delayedTransition of stateNode.after) {
+    let existing = transitions.get(delayedTransition.eventType);
+    if (!existing) {
+      existing = [];
+      transitions.set(delayedTransition.eventType, existing);
+    }
+    existing.push(delayedTransition);
+  }
+  return transitions;
+}
+function formatInitialTransition(stateNode, _target) {
+  const targetString = typeof _target === 'object' && _target !== null ? _target.target : _target;
+  const input = typeof _target === 'object' && _target !== null ? _target.input : undefined;
+  const resolvedTarget = typeof targetString === 'string' ? stateNode.states[targetString] : undefined;
+  if (!resolvedTarget && targetString) {
+    throw new Error(`Initial state "${targetString}" not found on "#${stateNode.id}"`);
+  }
+  const transition = {
+    source: stateNode,
+    target: resolvedTarget ? [resolvedTarget] : undefined,
+    input
+  };
+  return transition;
+}
+
+const STATE_IDENTIFIER = '#';
+let emptyCanActor;
+let emptyCanActorScope;
+function getEmptyCanActor() {
+  // A minimal inert actor used purely as the `self`/`parent` argument when
+  // dry-running transitions for `snapshot.can(...)`. Intentionally not built
+  // on `createLogic` so `can()` does not pull that machinery into bundles.
+  return emptyCanActor ??= createActor.createActor({
+    transition: snapshot => [snapshot, []],
+    initialTransition: () => [{
+      status: 'active',
+      output: undefined,
+      error: undefined
+    }, []],
+    getInitialSnapshot: () => ({
+      status: 'active',
+      output: undefined,
+      error: undefined
+    }),
+    getPersistedSnapshot: snapshot => snapshot
+  });
+}
+function getEmptyCanActorScope() {
+  if (emptyCanActorScope) {
+    return emptyCanActorScope;
+  }
+  const actor = getEmptyCanActor();
+  emptyCanActorScope = {
+    self: actor,
+    logger: () => {},
+    id: '',
+    sessionId: '',
+    defer: () => {},
+    system: actor.system,
+    stopChild: () => {},
+    emit: () => {},
+    actionExecutor: () => {}
+  };
+  return emptyCanActorScope;
+}
+class StateMachine {
+  constructor(/** The raw config used to create the machine. */
+  config, sources, validator) {
+    this.config = config;
+    this.validator = validator;
+    /** The machine's own version. */
+    this.version = void 0;
+    this.schemas = void 0;
+    /** Standard Schema for snapshots persisted by this machine version. */
+    this.snapshotSchema = void 0;
+    /** Standard Schema for complete events accepted by this machine version. */
+    this.eventSchema = void 0;
+    this.sources = void 0;
+    /** Runtime options for machine execution. */
+    this.options = void 0;
+    /** @internal */
+    this.idMap = new Map();
+    this.root = void 0;
+    this.id = void 0;
+    this.states = void 0;
+    this.events = void 0;
+    this.internalEventDescriptors = void 0;
+    /** @internal Skips eventless-selection scans for machines without `always`. */
+    this._hasEventlessTransitions = void 0;
+    /**
+     * The original JSON definition this machine was created from (set by
+     * `createMachineFromConfig`), if any. Used by `serializeMachine` for lossless
+     * round-trips.
+     *
+     * @internal
+     */
+    this._json = void 0;
+    this.id = config.id || '(machine)';
+    this.sources = {
+      actors: config.actors ?? {},
+      actions: config.actions ?? {},
+      delays: config.delays ?? {},
+      guards: config.guards ?? {},
+      ...sources
+    };
+    this.version = this.config.version;
+    this.schemas = this.config.schemas;
+    this.snapshotSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected a persisted snapshot.'
+              }]
+            };
+          }
+          const snapshot = {
+            historyValue: {},
+            timers: {},
+            ...value
+          };
+          const contextSchema = this.schemas?.context;
+          let context = snapshot.context;
+          if (contextSchema) {
+            const result = await contextSchema['~standard'].validate(context);
+            if (result.issues) {
+              return {
+                issues: [{
+                  message: `Invalid context for machine '${this.id}' version '${this.version}': ${result.issues[0]?.message}`
+                }]
+              };
+            }
+            context = result.value;
+          }
+          for (const key of ['value', 'children']) {
+            if (!(key in snapshot)) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot is missing '${key}'.`
+                }]
+              };
+            }
+          }
+          if (!['active', 'done', 'error', 'stopped'].includes(snapshot.status)) {
+            return {
+              issues: [{
+                message: 'Persisted snapshot has invalid status.'
+              }]
+            };
+          }
+          for (const key of ['children', 'historyValue', 'timers']) {
+            if (snapshot[key] === null || typeof snapshot[key] !== 'object' || Array.isArray(snapshot[key])) {
+              return {
+                issues: [{
+                  message: `Persisted snapshot has invalid '${key}'.`
+                }]
+              };
+            }
+          }
+          try {
+            this.resolveState({
+              value: snapshot.value,
+              context
+            });
+          } catch (error) {
+            return {
+              issues: [{
+                message: error instanceof Error ? error.message : 'Persisted snapshot has invalid state value.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...snapshot,
+              context
+            }
+          };
+        }
+      }
+    };
+    this.eventSchema = {
+      '~standard': {
+        version: 1,
+        vendor: 'xstate',
+        validate: async value => {
+          if (value === null || typeof value !== 'object' || typeof value.type !== 'string') {
+            return {
+              issues: [{
+                message: 'Expected an event object.'
+              }]
+            };
+          }
+          const event = value;
+          const eventSchemas = this.schemas?.events;
+          const isFrameworkEvent = event.type.startsWith('xstate.') || event.type.startsWith('@xstate.');
+          const schema = eventSchemas && Object.hasOwn(eventSchemas, event.type) ? eventSchemas[event.type] : undefined;
+          if (eventSchemas && !schema && !isFrameworkEvent) {
+            return {
+              issues: [{
+                message: `Unknown event '${event.type}' for machine '${this.id}' version '${this.version}'.`
+              }]
+            };
+          }
+          if (!schema) {
+            return {
+              value: event
+            };
+          }
+          const {
+            type,
+            ...payload
+          } = event;
+          const result = await schema['~standard'].validate(payload);
+          if (result.issues) {
+            return result;
+          }
+          if (result.value === null || typeof result.value !== 'object') {
+            return {
+              issues: [{
+                message: 'Expected an event payload.'
+              }]
+            };
+          }
+          return {
+            value: {
+              ...result.value,
+              type
+            }
+          };
+        }
+      }
+    };
+    this.internalEventDescriptors = this.config.internalEvents ?? [];
+    this.options = {
+      maxIterations: Infinity,
+      ...this.config.options
+    };
+    this.transition = this.transition.bind(this);
+    this.initialTransition = this.initialTransition.bind(this);
+    this.getInitialSnapshot = this.getInitialSnapshot.bind(this);
+    this.getPersistedSnapshot = this.getPersistedSnapshot.bind(this);
+    this.restoreSnapshot = this.restoreSnapshot.bind(this);
+    this.start = this.start.bind(this);
+    this.root = new StateNode(config, {
+      _key: this.id,
+      _machine: this
+    });
+    this.root._initialize();
+    createActor.formatRouteTransitions(this.root);
+    this.root._refreshEventMetadata();
+    this._hasEventlessTransitions = Array.from(this.idMap.values()).some(stateNode => !!stateNode.always?.length);
+    this.states = this.root.states; // TODO: remove!
+    this.events = this.root.events;
+  }
+
+  /**
+   * Clones this state machine with the provided sources.
+   *
+   * @param sources Options (`actions`, `guards`, `actors`, `delays`) to
+   *   recursively merge with the existing options.
+   * @returns A new `StateMachine` instance with the provided sources.
+   */
+  provide(sources) {
+    const {
+      actions,
+      guards,
+      actors,
+      delays
+    } = this.sources;
+    const provided = new StateMachine(this.config, {
+      actions: {
+        ...actions,
+        ...sources.actions
+      },
+      guards: {
+        ...guards,
+        ...sources.guards
+      },
+      actors: {
+        ...actors,
+        ...sources.actors
+      },
+      delays: {
+        ...delays,
+        ...sources.delays
+      }
+    }, this.validator);
+    // Providing sources does not change the serializable definition.
+    provided._json = this._json;
+    return provided;
+  }
+  resolveState(config) {
+    const resolvedStateValue = createActor.resolveStateValue(this.root, config.value);
+    const nodeSet = createActor.getAllStateNodes(createActor.getStateNodes(this.root, resolvedStateValue));
+    const nodes = [...nodeSet];
+    return createActor.createMachineSnapshot({
+      _nodes: nodes,
+      value: resolvedStateValue,
+      context: config.context || {},
+      children: {},
+      status: createActor.isInFinalState(nodeSet, this.root) ? 'done' : config.status || 'active',
+      output: config.output,
+      error: config.error,
+      historyValue: config.historyValue
+    }, this);
+  }
+
+  /**
+   * Determines the next snapshot given the current `snapshot` and received
+   * `event`. Calculates a full macrostep from all microsteps.
+   *
+   * @param snapshot The current snapshot
+   * @param event The received event
+   */
+  transition(snapshot, event, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createActor.createInertActorScope(this, snapshot);
+    if (this.validator) {
+      dist_xstateActors.assertValid(this.validator, {
+        kind: 'event',
+        logic: this,
+        event,
+        eventOrigin: actorScope && actorScope.self._lastSourceRef ? 'actor' : 'external'
+      });
+    }
+    if (usesInertScope) {
+      createActor.setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
+    }
+    createActor.beginSpawnAllocation(resolvedActorScope);
+    const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
+    if (fastSnapshot) {
+      if (usesInertScope) {
+        createActor.setInertActorScopeSnapshot(resolvedActorScope, fastSnapshot, false);
+      }
+      const returnedSnapshot = usesInertScope && fastSnapshot !== snapshot ? createActor.attachSnapshotActorRef(resolvedActorScope, fastSnapshot) : this._attachPureActorRef(fastSnapshot, resolvedActorScope);
+      if (this.validator) {
+        dist_xstateActors.assertValid(this.validator, {
+          kind: 'result',
+          logic: this,
+          snapshot: returnedSnapshot,
+          effects: []
+        });
+      }
+      return [returnedSnapshot, []];
+    }
+    const {
+      snapshot: nextSnapshot,
+      microsteps
+    } = createActor.macrostep(snapshot, event, resolvedActorScope, []);
+    if (usesInertScope) {
+      createActor.setInertActorScopeSnapshot(resolvedActorScope, nextSnapshot, false);
+    }
+    const returnedSnapshot = usesInertScope ? nextSnapshot === snapshot ? nextSnapshot : createActor.attachSnapshotActorRef(resolvedActorScope, nextSnapshot) : this._attachPureActorRef(nextSnapshot, resolvedActorScope);
+    const effects = this._collectEffects(microsteps);
+    if (this.validator) {
+      dist_xstateActors.assertValid(this.validator, {
+        kind: 'result',
+        logic: this,
+        snapshot: returnedSnapshot,
+        effects
+      });
+    }
+    return [returnedSnapshot, effects];
+  }
+  _collectEffects(microsteps) {
+    return microsteps.flatMap(([, actions]) => actions);
+  }
+  _attachPureActorRef(snapshot, actorScope, skipInitializingActor = false) {
+    if (createActor.isInertActorScope(actorScope)) {
+      return snapshot;
+    }
+    if (skipInitializingActor && actorScope.self._actorScope === actorScope && actorScope.self._snapshot === undefined) {
+      return snapshot;
+    }
+    createActor.setSnapshotActorRef(snapshot, actorScope.self, actorScope.system);
+    return snapshot;
+  }
+  _transitionFast(snapshot, event, actorScope) {
+    if (snapshot.status !== 'active' || typeof snapshot.value !== 'string' || this.root.always?.length) {
+      return undefined;
+    }
+    const sourceNode = this.root.states[snapshot.value];
+    if (!sourceNode || sourceNode.type !== 'atomic' || sourceNode.exit || sourceNode.invoke.length || sourceNode.always?.length || sourceNode.after?.length) {
+      return undefined;
+    }
+    const transitions = sourceNode.transitions.get(event.type);
+    if (transitions?.length !== 1) {
+      return undefined;
+    }
+    const selected = transitions[0];
+    if (selected.guard || selected.actions || selected.to || selected.reenter || selected.input || typeof selected.context === 'function' || selected.target && selected.target.length !== 1) {
+      return undefined;
+    }
+    const targetNode = selected.target?.[0] ?? sourceNode;
+    const stateChanged = targetNode !== sourceNode;
+    if (targetNode.parent !== this.root || targetNode.type !== 'atomic' || stateChanged && (targetNode.entry || targetNode.invoke.length || targetNode.always?.length || targetNode.after?.length)) {
+      return undefined;
+    }
+    const context = selected.context !== undefined ? {
+      ...snapshot.context,
+      ...selected.context
+    } : snapshot.context;
+    if (!createActor.isInertActorScope(actorScope) && (actorScope.system._hasInspectionObservers?.() ?? true)) {
+      const collectedMicrosteps = actorScope.self._collectedMicrosteps || [];
+      collectedMicrosteps.push(selected);
+      actorScope.self._collectedMicrosteps = collectedMicrosteps;
+    }
+    return createActor.cloneMachineSnapshot(snapshot, {
+      ...(context !== snapshot.context ? {
+        context
+      } : {}),
+      ...(stateChanged ? {
+        _nodes: [this.root, targetNode]
+      } : {})
+    });
+  }
+
+  /**
+   * Determines the next state given the current `state` and `event`. Calculates
+   * a microstep.
+   *
+   * @param state The current state
+   * @param event The received event
+   */
+  microstep(snapshot, event, actorScope) {
+    const {
+      microsteps
+    } = createActor.macrostep(snapshot, event, actorScope, []);
+    const snapshots = new Array(microsteps.length);
+    for (let i = 0; i < microsteps.length; i++) {
+      snapshots[i] = microsteps[i][0];
+    }
+    return snapshots;
+  }
+  getTransitionData(snapshot, event, actorScope, selectionResults) {
+    return createActor.transitionNode(this.root, snapshot.value, snapshot, event, actorScope, selectionResults) || [];
+  }
+  isInternalEventType(eventType) {
+    if (eventType === createActor.XSTATE_TIMER) {
+      return true;
+    }
+    for (const descriptor of this.internalEventDescriptors) {
+      if (createActor.matchesEventDescriptor(eventType, descriptor)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Determines whether sending the `event` to the given snapshot would select a
+   * non-forbidden transition. Backs `snapshot.can(...)`; lives here so that
+   * non-machine bundles don't pay for the transition-resolution machinery.
+   *
+   * @internal
+   */
+  _canTransition(snapshot, event) {
+    const emptyActorScope = getEmptyCanActorScope();
+    const transitionData = this.getTransitionData(snapshot, event, emptyActorScope);
+    if (!transitionData?.length) {
+      return false;
+    }
+
+    // Check that at least one transition is not forbidden
+    for (const transition of transitionData) {
+      if (transition.target !== undefined) {
+        return true;
+      }
+      const res = createActor.getTransitionResult(transition, snapshot, event, emptyActorScope, {
+        resolveActions: false
+      });
+      if (res.targets?.length || res.context || createActor.hasEffect(transition, snapshot.context, event, snapshot, emptyActorScope)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Returns the error event that the actor should transition with to recover
+   * from an execution error, if any active state node declares `onError`.
+   *
+   * @internal
+   */
+  getExecutionErrorEvent(snapshot, error) {
+    if (snapshot?.status !== 'active' || !snapshot.nodes?.some(stateNode => stateNode.config.onError)) {
+      return undefined;
+    }
+    return createActor.createErrorPlatformEvent('execution', error);
+  }
+
+  /**
+   * The initial state _before_ evaluating any microsteps. This "pre-initial"
+   * state is provided to initial actions executed in the initial state.
+   *
+   * @internal
+   */
+  _getPreInitialState(actorScope, initEvent) {
+    const {
+      context
+    } = this.config;
+    const preInitial = createActor.createMachineSnapshot({
+      context: typeof context !== 'function' && context ? context : {},
+      _nodes: [this.root],
+      children: {},
+      status: 'active'
+    }, this);
+    if (typeof context === 'function') {
+      const children = {};
+      const spawn = createSpawner(actorScope, this.sources.actors, children);
+      const resolvedContext = context(createActor.withActorSelf({
+        spawn,
+        input: initEvent.input,
+        actors: this.sources.actors
+      }, actorScope));
+      const [nextState] = createActor.resolveActionsWithContext(preInitial, initEvent, actorScope, []);
+      if (resolvedContext) {
+        nextState.context = resolvedContext;
+      }
+      if (Object.keys(children).length > 0) {
+        nextState.children = {
+          ...nextState.children,
+          ...children
+        };
+        // Commit the transaction counters so context-factory allocations
+        // persist with the snapshot: a freed id is never handed out again
+        // after a restore or in a fresh replay process. (The spawner already
+        // registered each child for string-id resolution.)
+        const counters = createActor.takeSpawnAllocationCounters(actorScope);
+        if (counters) {
+          nextState._nextActorIds = createActor.mergeActorIdCounters(nextState._nextActorIds, counters);
+        }
+      }
+      return nextState;
+    }
+    return preInitial;
+  }
+
+  /**
+   * Returns the initial `State` instance, with reference to `self` as an
+   * `ActorRef`.
+   */
+  getInitialSnapshot(actorScope, input) {
+    return this.initialTransition(input, actorScope)[0];
+  }
+  initialTransition(input, actorScope) {
+    if (this.validator) {
+      dist_xstateActors.assertValid(this.validator, {
+        kind: 'input',
+        logic: this,
+        input
+      });
+    }
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createActor.createInertActorScope(this);
+    createActor.beginSpawnAllocation(resolvedActorScope);
+    const initEvent = createActor.createInitEvent(input); // TODO: fix;
+    const internalQueue = [];
+    const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
+    const contextSpawnEffects = Object.values(preInitialState.children).filter(Boolean).map(actor => createActor.createSpawnEffect(actor));
+    const finalizeInitialResult = (macroState, microsteps) => {
+      if (usesInertScope) {
+        createActor.setInertActorScopeSnapshot(resolvedActorScope, macroState, false);
+      }
+      const returnedSnapshot = usesInertScope ? createActor.attachSnapshotActorRef(resolvedActorScope, macroState) : this._attachPureActorRef(macroState, resolvedActorScope, true);
+      const effects = this._collectEffects(microsteps);
+      if (this.validator) {
+        dist_xstateActors.assertValid(this.validator, {
+          kind: 'result',
+          logic: this,
+          snapshot: returnedSnapshot,
+          effects
+        });
+      }
+      return [returnedSnapshot, effects];
+    };
+    try {
+      const [nextState, initialActions] = createActor.initialMicrostep(this.root, preInitialState, resolvedActorScope, initEvent, internalQueue);
+      const {
+        snapshot: macroState,
+        microsteps
+      } = createActor.macrostep(nextState, initEvent, resolvedActorScope, internalQueue, [[nextState, [...contextSpawnEffects, ...initialActions]]]);
+      return finalizeInitialResult(macroState, microsteps);
+    } catch (err) {
+      if (!this.root.config.onError) {
+        throw err;
+      }
+      const errorEvent = createActor.createErrorPlatformEvent('execution', err);
+      const errorMacrostep = createActor.macrostep(preInitialState, errorEvent, resolvedActorScope, [], [[preInitialState, contextSpawnEffects]]);
+      return finalizeInitialResult(errorMacrostep.snapshot, errorMacrostep.microsteps);
+    }
+  }
+  start(snapshot) {
+    // Start rehydrated children that were active when persisted. Freshly
+    // invoked/spawned children are NOT started here — they start via deferred
+    // `@xstate.start` actions so sync start errors route to `onError`.
+    if (!snapshot?.children) {
+      return;
+    }
+    const children = snapshot.children;
+    for (const childId in children) {
+      if (!Object.hasOwn(children, childId)) {
+        continue;
+      }
+      const child = children[childId];
+      if (child._rehydrated && child.getSnapshot?.().status === 'active') {
+        child.start();
+      }
+    }
+  }
+  getStateNodeById(stateId) {
+    const fullPath = createActor.toStatePath(stateId);
+    const relativePath = fullPath.slice(1);
+    const resolvedStateId = createActor.isStateId(fullPath[0]) ? fullPath[0].slice(STATE_IDENTIFIER.length) : fullPath[0];
+    const stateNode = this.idMap.get(resolvedStateId);
+    if (!stateNode) {
+      throw new Error(`Child state node '#${resolvedStateId}' does not exist on machine '${this.id}'`);
+    }
+    return createActor.getStateNodeByPath(stateNode, relativePath);
+  }
+  getPersistedSnapshot(snapshot, options) {
+    return createActor.getPersistedSnapshot(snapshot, options);
+  }
+  restoreSnapshot(snapshot, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createActor.createInertActorScope(this);
+    const persistedMachine = snapshot.machine;
+    const legacyPersistedVersion = snapshot.version;
+    const persistedVersion = typeof persistedMachine?.version === 'string' ? persistedMachine.version : legacyPersistedVersion;
+    if (legacyPersistedVersion !== undefined && persistedMachine?.version !== undefined && persistedMachine.version !== legacyPersistedVersion) {
+      throw new Error(`Persisted snapshot version '${legacyPersistedVersion}' conflicts with machine version '${persistedMachine.version}'.`);
+    }
+    if (persistedMachine && typeof persistedMachine.id === 'string' && persistedMachine.id !== this.id) {
+      throw new Error(`Machine ID mismatch: persisted snapshot machine '${persistedMachine.id}' does not match '${this.id}'.`);
+    }
+    if (persistedVersion !== this.version) {
+      const migrate = this.config.migrate;
+      if (typeof migrate !== 'function') {
+        throw new Error(`Persisted snapshot version '${persistedVersion}' does not match machine version '${this.version}'.`);
+      }
+      snapshot = migrate(snapshot, persistedVersion);
+    }
+    const snapshotData = snapshot;
+    const children = {};
+    const snapshotChildren = snapshotData.children;
+    for (const actorId of Object.keys(snapshotChildren)) {
+      const actorData = snapshotChildren[actorId];
+      if (actorData.remote === true && actorData.address !== undefined) {
+        if (typeof actorData.src !== 'string') {
+          // Fail loudly instead of fabricating a source key that hosts would
+          // route by.
+          throw new Error(`Unable to restore remote child '${actorId}': a child referenced by address requires a registered source key.`);
+        }
+        // The child's state lives with another runtime; restore a
+        // location-transparent handle constructed from its identity alone.
+        // The handle keeps its persisted address verbatim: the owning
+        // runtime's identity for the child wins over the local parent chain.
+        const handle = createActor.createRemoteActorRef(resolvedActorScope.system, {
+          id: actorId,
+          address: actorData.address,
+          src: actorData.src,
+          parent: resolvedActorScope.self,
+          registryKey: actorData.registryKey,
+          syncSnapshot: actorData.syncSnapshot,
+          incarnation: actorData.incarnation
+        });
+        if (actorData.registryKey) {
+          resolvedActorScope.system._set(actorData.registryKey, handle);
+        }
+        children[actorId] = handle;
+        continue;
+      }
+      const childState = actorData.snapshot;
+      const src = actorData.src;
+      const logic = typeof src === 'string' ? createActor.resolveReferencedActor(this, src) : src;
+      if (!logic) {
+        const sourceId = typeof src === 'string' ? src : '<unknown>';
+        throw new Error(`Unable to restore child actor '${actorId}': child source '${sourceId}' is not provided in machine '${this.id}'.`);
+      }
+      const actor = resolvedActorScope.system.createActorRef(logic, {
+        id: actorId,
+        parent: resolvedActorScope.self,
+        syncSnapshot: actorData.syncSnapshot,
+        snapshot: childState,
+        src,
+        registryKey: actorData.registryKey
+      });
+      // Mark so `start()` knows to start this child (freshly invoked/spawned
+      // children are started via deferred `@xstate.start` actions instead).
+      actor._rehydrated = true;
+      children[actorId] = actor;
+    }
+    const timers = {};
+    const persistedTimers = snapshotData.timers ?? {};
+    for (const [id, timer] of Object.entries(persistedTimers)) {
+      let event = timer.event;
+      if (event.type === 'xstate.timeout.actor') {
+        const actorId = event.actorId;
+        const child = children[actorId];
+        if (child) {
+          event = createActor.createInvokeTimeoutEvent(actorId, child.sessionId);
+        }
+      }
+      const target = typeof timer.target === 'string' ? timer.target === 'self' ? 'self' : children[timer.target] : resolvedActorScope.self._parent;
+      if (!target) {
+        const targetDescription = typeof timer.target === 'string' ? timer.target : timer.target.type;
+        throw new Error(`Unable to restore timer '${id}': target actor '${targetDescription}' is unavailable.`);
+      }
+      timers[id] = {
+        ...timer,
+        event,
+        target
+      };
+    }
+    const reviveHistoryValue = historyValue => {
+      if (!historyValue || typeof historyValue !== 'object') {
+        return {};
+      }
+      const revived = {};
+      for (const key of Object.keys(historyValue)) {
+        const arr = historyValue[key];
+        for (const item of arr) {
+          let resolved;
+          if (item instanceof StateNode) {
+            resolved = item;
+          } else {
+            try {
+              resolved = this.root.machine.getStateNodeById(item.id);
+            } catch {
+            }
+          }
+          if (!resolved) {
+            continue;
+          }
+          revived[key] ??= [];
+          revived[key].push(resolved);
+        }
+      }
+      return revived;
+    };
+    const revivedHistoryValue = reviveHistoryValue(snapshotData.historyValue);
+    const validateStateValue = (stateValue, node, path) => {
+      const missingStateError = statePath => new Error(`Persisted snapshot references state '${statePath.join('.')}' which does not exist on machine '${this.id}'.`);
+      if (typeof stateValue === 'string') {
+        if (!node.states[stateValue]) {
+          throw missingStateError(path.concat(stateValue));
+        }
+        return;
+      }
+      if (!stateValue || typeof stateValue !== 'object') {
+        return;
+      }
+      for (const key of Object.keys(stateValue)) {
+        const childNode = node.states[key];
+        if (!childNode) {
+          throw missingStateError(path.concat(key));
+        }
+        validateStateValue(stateValue[key], childNode, path.concat(key));
+      }
+    };
+    validateStateValue(snapshotData.value, this.root, []);
+    const nodes = Array.from(createActor.getAllStateNodes(createActor.getStateNodes(this.root, snapshotData.value)));
+    const {
+      version: _persistedSnapshotVersion,
+      // The legacy system-wide counter: superseded by per-snapshot
+      // `_nextActorIds` plus the child-id fold below; dropped so old and new
+      // snapshots round-trip to the same shape.
+      _nextActorId: _legacyNextActorId,
+      ...persistedRest
+    } = snapshot;
+    // Fold generated-shaped child ids into the counters as a floor: snapshots
+    // persisted before per-actor counters (or hand-crafted ones) still must
+    // never reuse a live child's id.
+    let restoredCounters = persistedRest._nextActorIds;
+    for (const childId of Object.keys(snapshotChildren)) {
+      const generated = createActor.parseGeneratedActorId(childId);
+      if (generated && (restoredCounters?.[generated.prefix] ?? 0) <= generated.index) {
+        restoredCounters = {
+          ...restoredCounters,
+          [generated.prefix]: generated.index + 1
+        };
+      }
+    }
+    const restoredSnapshot = createActor.createMachineSnapshot({
+      ...persistedRest,
+      children,
+      timers,
+      _nextActorIds: restoredCounters,
+      _nodes: nodes,
+      value: snapshotData.value,
+      historyValue: revivedHistoryValue,
+      _stateInputs: snapshotData.stateInputs ?? {}
+    }, this, resolvedActorScope.self);
+    const seen = new WeakSet();
+    function reviveContext(contextPart) {
+      if (seen.has(contextPart)) {
+        return;
+      }
+      seen.add(contextPart);
+      for (const key of Object.keys(contextPart)) {
+        const value = contextPart[key];
+        if (value && typeof value === 'object') {
+          if ('xstate$type' in value && value.xstate$type === createActor.ACTOR_REF_TYPE) {
+            contextPart[key] = children[value.id];
+            continue;
+          }
+          reviveContext(value);
+        }
+      }
+    }
+    reviveContext(restoredSnapshot.context);
+    if (usesInertScope) {
+      createActor.setInertActorScopeSnapshot(resolvedActorScope, restoredSnapshot, false);
+      return createActor.attachSnapshotActorRef(resolvedActorScope, restoredSnapshot);
+    }
+    return this._attachPureActorRef(restoredSnapshot, resolvedActorScope);
+  }
+}
+
+exports.StateMachine = StateMachine;
+exports.StateNode = StateNode;