xstate 6.0.0-alpha.21 → 6.0.0-alpha.22

package/dist/{StateMachine-e25dd61f.development.esm.js → StateMachine-9fad7a2b.development.esm.js}

@@ -1,4 +1,4 @@
-import { P as ProcessingStatus, H as resolveReferencedActor, e as createActor, S as STATE_DELIMITER, I as mapValues, t as toArray, J as createInvokeId, K as getDelayedTransitions, L as evaluateCandidate, M as formatTransition, N as NULL_EVENT, O as toTransitionConfigArray, Q as createInvokeTimeoutEvent, R as getCandidates, U as formatRouteTransitions, V as resolveStateValue, W as getAllStateNodes, l as getStateNodes, Y as createMachineSnapshot, Z as isInFinalState, f as macrostep, d as deriveDeferredStarts, _ as cloneMachineSnapshot, $ as transitionNode, m as matchesEventDescriptor, a0 as getTransitionResult, a1 as hasEffect, a2 as createErrorPlatformEvent, r as resolveActionsWithContext, g as createInitEvent, h as initialMicrostep, a3 as toStatePath, a4 as isStateId, a5 as getStateNodeByPath, a6 as getPersistedSnapshot, a7 as $$ACTOR_TYPE } from './index-d39fb138.development.esm.js';
+import { M as resolveReferencedActor, N as setSnapshotActorRef, O as getSnapshotActorRef, P as createSnapshotSystem, q as isMachineSnapshot, h as createActor, S as STATE_DELIMITER, Q as mapValues, t as toArray, R as createInvokeId, U as getDelayedTransitions, V as evaluateCandidate, W as formatTransition, Y as NULL_EVENT, Z as toTransitionConfigArray, _ as createInvokeTimeoutEvent, $ as getCandidates, a0 as formatRouteTransitions, a1 as resolveStateValue, a2 as getAllStateNodes, s as getStateNodes, a3 as createMachineSnapshot, a4 as isInFinalState, j as macrostep, a5 as cloneMachineSnapshot, a6 as transitionNode, e as XSTATE_TIMER, m as matchesEventDescriptor, a7 as getTransitionResult, a8 as hasEffect, a9 as createErrorPlatformEvent, r as resolveActionsWithContext, k as createInitEvent, l as createSpawnEffect, n as initialMicrostep, aa as toStatePath, ab as isStateId, ac as getStateNodeByPath, ad as getPersistedSnapshot, ae as $$ACTOR_TYPE } from './index-44d8c2d1.development.esm.js';
 
 function createSpawner(actorScope, {
   machine,
@@ -10,7 +10,7 @@ function createSpawner(actorScope, {
       if (!logic) {
         throw new Error(`Actor logic '${src}' not implemented in machine '${machine.id}'`);
       }
-      const actor = createActor(logic, {
+      const actor = actorScope.system.createActorRef(logic, {
         id: options?.id,
         parent: actorScope.self,
         syncSnapshot: options?.syncSnapshot,
@@ -25,7 +25,7 @@ function createSpawner(actorScope, {
       spawnedChildren[actor.id] = actor;
       return actor;
     } else {
-      const actor = createActor(src, {
+      const actor = actorScope.system.createActorRef(src, {
         id: options?.id,
         parent: actorScope.self,
         syncSnapshot: options?.syncSnapshot,
@@ -39,16 +39,114 @@ function createSpawner(actorScope, {
   return (src, options) => {
     const actor = spawn(src, options); // TODO: fix types
     spawnedChildren[actor.id] = actor;
-    actorScope.defer(() => {
-      if (actor._processingStatus === ProcessingStatus.Stopped) {
-        return;
-      }
-      actor.start();
-    });
     return actor;
   };
 }
 
+/** @internal */
+function setInertActorScopeSnapshot(actorScope, snapshot, attachActorRef = true) {
+  actorScope.self._snapshot = snapshot;
+  if (attachActorRef && snapshot && typeof snapshot === 'object') {
+    setSnapshotActorRef(snapshot, actorScope.self);
+  }
+  return snapshot;
+}
+
+/** @internal */
+function isInertActorScope(actorScope) {
+  return !!actorScope.self.options?._inert;
+}
+
+/** @internal */
+function attachSnapshotActorRef(actorLogic, actorScope, snapshot) {
+  const snapshotScope = createInertActorScope(actorLogic, snapshot, actorScope.self);
+  return setInertActorScopeSnapshot(snapshotScope, snapshot);
+}
+
+/** @internal */
+function createInertActorScope(actorLogic, snapshot, sourceSelf) {
+  const snapshotRef = snapshot ? getSnapshotActorRef(snapshot) : undefined;
+  const previousSelf = sourceSelf ?? snapshotRef?.actor;
+  const baseSystem = previousSelf?.system;
+  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, previousSelf, isMachineSnapshot(snapshot) ? snapshot.children : {}, sourceSelf ? undefined : snapshotRef?.systemState) : undefined;
+  const self = createActor(actorLogic, {
+    _inert: true,
+    ...(previousSelf ? {
+      id: previousSelf.id
+    } : {}),
+    ...(system ? {
+      _systemRef: {
+        current: system
+      }
+    } : {})
+  });
+  if (previousSelf?._parent) {
+    self._parent = previousSelf._parent;
+  }
+  if (snapshot) {
+    self._snapshot = snapshot;
+  }
+  const actorScope = {
+    self: self,
+    defer: () => {},
+    id: self.id,
+    logger: self.system._logger,
+    sessionId: self.sessionId,
+    stopChild: child => child._stop(),
+    system: self.system,
+    emit: event => self.system.emitEvent(self, event),
+    actionExecutor: () => {}
+  };
+  return actorScope;
+}
+
+/** @deprecated Use `initialTransition(…)` instead. */
+function getInitialSnapshot(actorLogic, ...[input]) {
+  const actorScope = createInertActorScope(actorLogic);
+  return actorLogic.initialTransition(input, actorScope)[0];
+}
+
+/**
+ * Determines the next snapshot for the given `actorLogic` based on the given
+ * `snapshot` and `event`.
+ *
+ * If the `snapshot` is `undefined`, the initial snapshot of the `actorLogic` is
+ * used.
+ *
+ * @deprecated Use `transition(…)` instead.
+ * @example
+ *
+ * ```ts
+ * import { getNextSnapshot } from 'xstate';
+ * import { trafficLightMachine } from './trafficLightMachine.ts';
+ *
+ * const nextSnapshot = getNextSnapshot(
+ *   trafficLightMachine, // actor logic
+ *   undefined, // snapshot (or initial state if undefined)
+ *   { type: 'TIMER' }
+ * ); // event object
+ *
+ * console.log(nextSnapshot.value);
+ * // => 'yellow'
+ *
+ * const nextSnapshot2 = getNextSnapshot(
+ *   trafficLightMachine, // actor logic
+ *   nextSnapshot, // snapshot
+ *   { type: 'TIMER' }
+ * ); // event object
+ *
+ * console.log(nextSnapshot2.value);
+ * // =>'red'
+ * ```
+ */
+function getNextSnapshot(actorLogic, snapshot, event) {
+  const actorScope = createInertActorScope(actorLogic, snapshot);
+  const transitionResult = actorLogic.transition(snapshot, event, actorScope);
+  const nextSnapshot = Array.isArray(transitionResult) ? transitionResult[0] : transitionResult;
+  setInertActorScopeSnapshot(actorScope, nextSnapshot, false);
+  return nextSnapshot === snapshot ? nextSnapshot : attachSnapshotActorRef(actorLogic, actorScope, nextSnapshot);
+}
+
 const cache = new WeakMap();
 function memo(object, key, fn) {
   let memoizedData = cache.get(object);
@@ -570,19 +668,37 @@ class StateMachine {
    * @param event The received event
    */
   transition(snapshot, event, actorScope) {
-    const fastSnapshot = this._transitionFast(snapshot, event, actorScope);
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this, snapshot);
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
+    }
+    const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
     if (fastSnapshot) {
-      return [fastSnapshot, []];
+      if (usesInertScope) {
+        setInertActorScopeSnapshot(resolvedActorScope, fastSnapshot, false);
+      }
+      const returnedSnapshot = usesInertScope && fastSnapshot !== snapshot ? attachSnapshotActorRef(this, resolvedActorScope, fastSnapshot) : this._attachPureActorRef(fastSnapshot, resolvedActorScope);
+      return [returnedSnapshot, []];
     }
     const {
       snapshot: nextSnapshot,
       microsteps
-    } = macrostep(snapshot, event, actorScope, []);
-    return [nextSnapshot, this._collectEffects(microsteps)];
+    } = macrostep(snapshot, event, resolvedActorScope, []);
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, nextSnapshot, false);
+    }
+    const returnedSnapshot = usesInertScope ? nextSnapshot === snapshot ? nextSnapshot : attachSnapshotActorRef(this, resolvedActorScope, nextSnapshot) : this._attachPureActorRef(nextSnapshot, resolvedActorScope);
+    return [returnedSnapshot, this._collectEffects(microsteps)];
+  }
+  _collectEffects(microsteps) {
+    return microsteps.flatMap(([, actions]) => actions);
   }
-  _collectEffects(microsteps, initialActions = []) {
-    const effects = [...initialActions, ...microsteps.flatMap(([, actions]) => actions)];
-    return [...effects, ...deriveDeferredStarts(effects)];
+  _attachPureActorRef(snapshot, actorScope) {
+    if (isInertActorScope(actorScope)) {
+      return snapshot;
+    }
+    return attachSnapshotActorRef(this, actorScope, snapshot);
   }
   _transitionFast(snapshot, event, actorScope) {
     if (snapshot.status !== 'active' || typeof snapshot.value !== 'string' || this.root.always?.length) {
@@ -643,6 +759,9 @@ class StateMachine {
     return transitionNode(this.root, snapshot.value, snapshot, event, self) || [];
   }
   isInternalEventType(eventType) {
+    if (eventType === XSTATE_TIMER) {
+      return true;
+    }
     for (const descriptor of this.internalEventDescriptors) {
       if (matchesEventDescriptor(eventType, descriptor)) {
         return true;
@@ -709,7 +828,7 @@ class StateMachine {
       _nodes: [this.root],
       children: {},
       status: 'active'
-    }, this);
+    }, this, actorScope.self);
     if (typeof context === 'function') {
       const children = {};
       const spawn = createSpawner(actorScope, preInitial, initEvent, children);
@@ -742,30 +861,37 @@ class StateMachine {
     return this.initialTransition(input, actorScope)[0];
   }
   initialTransition(input, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this);
     const initEvent = createInitEvent(input); // TODO: fix;
     const internalQueue = [];
-    const preInitialState = this._getPreInitialState(actorScope, initEvent);
+    const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
+    const contextSpawnEffects = Object.values(preInitialState.children).filter(Boolean).map(actor => createSpawnEffect(actor));
     let nextState;
     let initialActions = [];
     let microsteps = [];
     let macroState;
     try {
-      [nextState, initialActions] = initialMicrostep(this.root, preInitialState, actorScope, initEvent, internalQueue);
+      [nextState, initialActions] = initialMicrostep(this.root, preInitialState, resolvedActorScope, initEvent, internalQueue);
       ({
         snapshot: macroState,
         microsteps
-      } = macrostep(nextState, initEvent, actorScope, internalQueue));
+      } = macrostep(nextState, initEvent, resolvedActorScope, internalQueue, [[nextState, [...contextSpawnEffects, ...initialActions]]]));
     } catch (err) {
       if (!this.root.config.onError) {
         throw err;
       }
       const errorEvent = createErrorPlatformEvent('execution', err);
-      const errorMacrostep = macrostep(preInitialState, errorEvent, actorScope, []);
+      const errorMacrostep = macrostep(preInitialState, errorEvent, resolvedActorScope, [], [[preInitialState, contextSpawnEffects]]);
       macroState = errorMacrostep.snapshot;
       microsteps = errorMacrostep.microsteps;
       initialActions = [];
     }
-    return [macroState, this._collectEffects(microsteps, initialActions)];
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, macroState, false);
+    }
+    const returnedSnapshot = usesInertScope ? attachSnapshotActorRef(this, resolvedActorScope, macroState) : this._attachPureActorRef(macroState, resolvedActorScope);
+    return [returnedSnapshot, this._collectEffects(microsteps)];
   }
   start(snapshot) {
     // Start rehydrated children that were active when persisted. Freshly
@@ -793,7 +919,9 @@ class StateMachine {
   getPersistedSnapshot(snapshot, options) {
     return getPersistedSnapshot(snapshot, options);
   }
-  restoreSnapshot(snapshot, _actorScope) {
+  restoreSnapshot(snapshot, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this);
     const persistedVersion = snapshot.version;
     if (persistedVersion !== this.version) {
       const migrate = this.config.migrate;
@@ -813,9 +941,9 @@ class StateMachine {
       if (!logic) {
         continue;
       }
-      const actor = createActor(logic, {
+      const actor = resolvedActorScope.system.createActorRef(logic, {
         id: actorId,
-        parent: _actorScope.self,
+        parent: resolvedActorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -826,6 +954,19 @@ class StateMachine {
       actor._rehydrated = true;
       children[actorId] = actor;
     }
+    const timers = {};
+    const persistedTimers = snapshotData.timers ?? {};
+    for (const [id, timer] of Object.entries(persistedTimers)) {
+      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,
+        target
+      };
+    }
     const reviveHistoryValue = historyValue => {
       if (!historyValue || typeof historyValue !== 'object') {
         return {};
@@ -864,11 +1005,12 @@ class StateMachine {
     const restoredSnapshot = createMachineSnapshot({
       ...persistedRest,
       children,
+      timers,
       _nodes: nodes,
       value: snapshotData.value,
       historyValue: revivedHistoryValue,
       _stateInputs: snapshotData.stateInputs ?? {}
-    }, this);
+    }, this, resolvedActorScope.self);
     const seen = new WeakSet();
     function reviveContext(contextPart) {
       if (seen.has(contextPart)) {
@@ -887,8 +1029,12 @@ class StateMachine {
       }
     }
     reviveContext(restoredSnapshot.context);
-    return restoredSnapshot;
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, restoredSnapshot, false);
+      return attachSnapshotActorRef(this, resolvedActorScope, restoredSnapshot);
+    }
+    return this._attachPureActorRef(restoredSnapshot, resolvedActorScope);
   }
 }
 
-export { StateMachine as S, StateNode as a };
+export { StateMachine as S, attachSnapshotActorRef as a, getNextSnapshot as b, createInertActorScope as c, StateNode as d, getInitialSnapshot as g, setInertActorScopeSnapshot as s };

package/dist/{StateMachine-3c17fe3e.esm.js → StateMachine-ddb5d007.esm.js}

@@ -1,4 +1,4 @@
-import { P as ProcessingStatus, H as resolveReferencedActor, e as createActor, S as STATE_DELIMITER, I as mapValues, t as toArray, J as createInvokeId, K as getDelayedTransitions, L as evaluateCandidate, M as formatTransition, N as NULL_EVENT, O as toTransitionConfigArray, Q as createInvokeTimeoutEvent, R as getCandidates, U as formatRouteTransitions, V as resolveStateValue, W as getAllStateNodes, l as getStateNodes, Y as createMachineSnapshot, Z as isInFinalState, f as macrostep, d as deriveDeferredStarts, _ as cloneMachineSnapshot, $ as transitionNode, m as matchesEventDescriptor, a0 as getTransitionResult, a1 as hasEffect, a2 as createErrorPlatformEvent, r as resolveActionsWithContext, g as createInitEvent, h as initialMicrostep, a3 as toStatePath, a4 as isStateId, a5 as getStateNodeByPath, a6 as getPersistedSnapshot, a7 as $$ACTOR_TYPE } from './index-3f87408c.esm.js';
+import { M as resolveReferencedActor, N as setSnapshotActorRef, O as getSnapshotActorRef, P as createSnapshotSystem, q as isMachineSnapshot, h as createActor, S as STATE_DELIMITER, Q as mapValues, t as toArray, R as createInvokeId, U as getDelayedTransitions, V as evaluateCandidate, W as formatTransition, Y as NULL_EVENT, Z as toTransitionConfigArray, _ as createInvokeTimeoutEvent, $ as getCandidates, a0 as formatRouteTransitions, a1 as resolveStateValue, a2 as getAllStateNodes, s as getStateNodes, a3 as createMachineSnapshot, a4 as isInFinalState, j as macrostep, a5 as cloneMachineSnapshot, a6 as transitionNode, e as XSTATE_TIMER, m as matchesEventDescriptor, a7 as getTransitionResult, a8 as hasEffect, a9 as createErrorPlatformEvent, r as resolveActionsWithContext, k as createInitEvent, l as createSpawnEffect, n as initialMicrostep, aa as toStatePath, ab as isStateId, ac as getStateNodeByPath, ad as getPersistedSnapshot, ae as $$ACTOR_TYPE } from './index-2fe11873.esm.js';
 
 function createSpawner(actorScope, {
   machine,
@@ -10,7 +10,7 @@ function createSpawner(actorScope, {
       if (!logic) {
         throw new Error(`Actor logic '${src}' not implemented in machine '${machine.id}'`);
       }
-      const actor = createActor(logic, {
+      const actor = actorScope.system.createActorRef(logic, {
         id: options?.id,
         parent: actorScope.self,
         syncSnapshot: options?.syncSnapshot,
@@ -25,7 +25,7 @@ function createSpawner(actorScope, {
       spawnedChildren[actor.id] = actor;
       return actor;
     } else {
-      const actor = createActor(src, {
+      const actor = actorScope.system.createActorRef(src, {
         id: options?.id,
         parent: actorScope.self,
         syncSnapshot: options?.syncSnapshot,
@@ -39,16 +39,114 @@ function createSpawner(actorScope, {
   return (src, options) => {
     const actor = spawn(src, options); // TODO: fix types
     spawnedChildren[actor.id] = actor;
-    actorScope.defer(() => {
-      if (actor._processingStatus === ProcessingStatus.Stopped) {
-        return;
-      }
-      actor.start();
-    });
     return actor;
   };
 }
 
+/** @internal */
+function setInertActorScopeSnapshot(actorScope, snapshot, attachActorRef = true) {
+  actorScope.self._snapshot = snapshot;
+  if (attachActorRef && snapshot && typeof snapshot === 'object') {
+    setSnapshotActorRef(snapshot, actorScope.self);
+  }
+  return snapshot;
+}
+
+/** @internal */
+function isInertActorScope(actorScope) {
+  return !!actorScope.self.options?._inert;
+}
+
+/** @internal */
+function attachSnapshotActorRef(actorLogic, actorScope, snapshot) {
+  const snapshotScope = createInertActorScope(actorLogic, snapshot, actorScope.self);
+  return setInertActorScopeSnapshot(snapshotScope, snapshot);
+}
+
+/** @internal */
+function createInertActorScope(actorLogic, snapshot, sourceSelf) {
+  const snapshotRef = snapshot ? getSnapshotActorRef(snapshot) : undefined;
+  const previousSelf = sourceSelf ?? snapshotRef?.actor;
+  const baseSystem = previousSelf?.system;
+  const system = previousSelf && baseSystem ? createSnapshotSystem(baseSystem, previousSelf, isMachineSnapshot(snapshot) ? snapshot.children : {}, sourceSelf ? undefined : snapshotRef?.systemState) : undefined;
+  const self = createActor(actorLogic, {
+    _inert: true,
+    ...(previousSelf ? {
+      id: previousSelf.id
+    } : {}),
+    ...(system ? {
+      _systemRef: {
+        current: system
+      }
+    } : {})
+  });
+  if (previousSelf?._parent) {
+    self._parent = previousSelf._parent;
+  }
+  if (snapshot) {
+    self._snapshot = snapshot;
+  }
+  const actorScope = {
+    self: self,
+    defer: () => {},
+    id: self.id,
+    logger: self.system._logger,
+    sessionId: self.sessionId,
+    stopChild: child => child._stop(),
+    system: self.system,
+    emit: event => self.system.emitEvent(self, event),
+    actionExecutor: () => {}
+  };
+  return actorScope;
+}
+
+/** @deprecated Use `initialTransition(…)` instead. */
+function getInitialSnapshot(actorLogic, ...[input]) {
+  const actorScope = createInertActorScope(actorLogic);
+  return actorLogic.initialTransition(input, actorScope)[0];
+}
+
+/**
+ * Determines the next snapshot for the given `actorLogic` based on the given
+ * `snapshot` and `event`.
+ *
+ * If the `snapshot` is `undefined`, the initial snapshot of the `actorLogic` is
+ * used.
+ *
+ * @deprecated Use `transition(…)` instead.
+ * @example
+ *
+ * ```ts
+ * import { getNextSnapshot } from 'xstate';
+ * import { trafficLightMachine } from './trafficLightMachine.ts';
+ *
+ * const nextSnapshot = getNextSnapshot(
+ *   trafficLightMachine, // actor logic
+ *   undefined, // snapshot (or initial state if undefined)
+ *   { type: 'TIMER' }
+ * ); // event object
+ *
+ * console.log(nextSnapshot.value);
+ * // => 'yellow'
+ *
+ * const nextSnapshot2 = getNextSnapshot(
+ *   trafficLightMachine, // actor logic
+ *   nextSnapshot, // snapshot
+ *   { type: 'TIMER' }
+ * ); // event object
+ *
+ * console.log(nextSnapshot2.value);
+ * // =>'red'
+ * ```
+ */
+function getNextSnapshot(actorLogic, snapshot, event) {
+  const actorScope = createInertActorScope(actorLogic, snapshot);
+  const transitionResult = actorLogic.transition(snapshot, event, actorScope);
+  const nextSnapshot = Array.isArray(transitionResult) ? transitionResult[0] : transitionResult;
+  setInertActorScopeSnapshot(actorScope, nextSnapshot, false);
+  return nextSnapshot === snapshot ? nextSnapshot : attachSnapshotActorRef(actorLogic, actorScope, nextSnapshot);
+}
+
 const cache = new WeakMap();
 function memo(object, key, fn) {
   let memoizedData = cache.get(object);
@@ -541,19 +639,37 @@ class StateMachine {
    * @param event The received event
    */
   transition(snapshot, event, actorScope) {
-    const fastSnapshot = this._transitionFast(snapshot, event, actorScope);
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this, snapshot);
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, snapshot, false);
+    }
+    const fastSnapshot = this._transitionFast(snapshot, event, resolvedActorScope);
     if (fastSnapshot) {
-      return [fastSnapshot, []];
+      if (usesInertScope) {
+        setInertActorScopeSnapshot(resolvedActorScope, fastSnapshot, false);
+      }
+      const returnedSnapshot = usesInertScope && fastSnapshot !== snapshot ? attachSnapshotActorRef(this, resolvedActorScope, fastSnapshot) : this._attachPureActorRef(fastSnapshot, resolvedActorScope);
+      return [returnedSnapshot, []];
     }
     const {
       snapshot: nextSnapshot,
       microsteps
-    } = macrostep(snapshot, event, actorScope, []);
-    return [nextSnapshot, this._collectEffects(microsteps)];
+    } = macrostep(snapshot, event, resolvedActorScope, []);
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, nextSnapshot, false);
+    }
+    const returnedSnapshot = usesInertScope ? nextSnapshot === snapshot ? nextSnapshot : attachSnapshotActorRef(this, resolvedActorScope, nextSnapshot) : this._attachPureActorRef(nextSnapshot, resolvedActorScope);
+    return [returnedSnapshot, this._collectEffects(microsteps)];
+  }
+  _collectEffects(microsteps) {
+    return microsteps.flatMap(([, actions]) => actions);
   }
-  _collectEffects(microsteps, initialActions = []) {
-    const effects = [...initialActions, ...microsteps.flatMap(([, actions]) => actions)];
-    return [...effects, ...deriveDeferredStarts(effects)];
+  _attachPureActorRef(snapshot, actorScope) {
+    if (isInertActorScope(actorScope)) {
+      return snapshot;
+    }
+    return attachSnapshotActorRef(this, actorScope, snapshot);
   }
   _transitionFast(snapshot, event, actorScope) {
     if (snapshot.status !== 'active' || typeof snapshot.value !== 'string' || this.root.always?.length) {
@@ -614,6 +730,9 @@ class StateMachine {
     return transitionNode(this.root, snapshot.value, snapshot, event, self) || [];
   }
   isInternalEventType(eventType) {
+    if (eventType === XSTATE_TIMER) {
+      return true;
+    }
     for (const descriptor of this.internalEventDescriptors) {
       if (matchesEventDescriptor(eventType, descriptor)) {
         return true;
@@ -680,7 +799,7 @@ class StateMachine {
       _nodes: [this.root],
       children: {},
       status: 'active'
-    }, this);
+    }, this, actorScope.self);
     if (typeof context === 'function') {
       const children = {};
       const spawn = createSpawner(actorScope, preInitial, initEvent, children);
@@ -713,30 +832,37 @@ class StateMachine {
     return this.initialTransition(input, actorScope)[0];
   }
   initialTransition(input, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this);
     const initEvent = createInitEvent(input); // TODO: fix;
     const internalQueue = [];
-    const preInitialState = this._getPreInitialState(actorScope, initEvent);
+    const preInitialState = this._getPreInitialState(resolvedActorScope, initEvent);
+    const contextSpawnEffects = Object.values(preInitialState.children).filter(Boolean).map(actor => createSpawnEffect(actor));
     let nextState;
     let initialActions = [];
     let microsteps = [];
     let macroState;
     try {
-      [nextState, initialActions] = initialMicrostep(this.root, preInitialState, actorScope, initEvent, internalQueue);
+      [nextState, initialActions] = initialMicrostep(this.root, preInitialState, resolvedActorScope, initEvent, internalQueue);
       ({
         snapshot: macroState,
         microsteps
-      } = macrostep(nextState, initEvent, actorScope, internalQueue));
+      } = macrostep(nextState, initEvent, resolvedActorScope, internalQueue, [[nextState, [...contextSpawnEffects, ...initialActions]]]));
     } catch (err) {
       if (!this.root.config.onError) {
         throw err;
       }
       const errorEvent = createErrorPlatformEvent('execution', err);
-      const errorMacrostep = macrostep(preInitialState, errorEvent, actorScope, []);
+      const errorMacrostep = macrostep(preInitialState, errorEvent, resolvedActorScope, [], [[preInitialState, contextSpawnEffects]]);
       macroState = errorMacrostep.snapshot;
       microsteps = errorMacrostep.microsteps;
       initialActions = [];
     }
-    return [macroState, this._collectEffects(microsteps, initialActions)];
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, macroState, false);
+    }
+    const returnedSnapshot = usesInertScope ? attachSnapshotActorRef(this, resolvedActorScope, macroState) : this._attachPureActorRef(macroState, resolvedActorScope);
+    return [returnedSnapshot, this._collectEffects(microsteps)];
   }
   start(snapshot) {
     // Start rehydrated children that were active when persisted. Freshly
@@ -764,7 +890,9 @@ class StateMachine {
   getPersistedSnapshot(snapshot, options) {
     return getPersistedSnapshot(snapshot, options);
   }
-  restoreSnapshot(snapshot, _actorScope) {
+  restoreSnapshot(snapshot, actorScope) {
+    const usesInertScope = !actorScope;
+    const resolvedActorScope = actorScope ?? createInertActorScope(this);
     const persistedVersion = snapshot.version;
     if (persistedVersion !== this.version) {
       const migrate = this.config.migrate;
@@ -784,9 +912,9 @@ class StateMachine {
       if (!logic) {
         continue;
       }
-      const actor = createActor(logic, {
+      const actor = resolvedActorScope.system.createActorRef(logic, {
         id: actorId,
-        parent: _actorScope.self,
+        parent: resolvedActorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -797,6 +925,19 @@ class StateMachine {
       actor._rehydrated = true;
       children[actorId] = actor;
     }
+    const timers = {};
+    const persistedTimers = snapshotData.timers ?? {};
+    for (const [id, timer] of Object.entries(persistedTimers)) {
+      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,
+        target
+      };
+    }
     const reviveHistoryValue = historyValue => {
       if (!historyValue || typeof historyValue !== 'object') {
         return {};
@@ -832,11 +973,12 @@ class StateMachine {
     const restoredSnapshot = createMachineSnapshot({
       ...persistedRest,
       children,
+      timers,
       _nodes: nodes,
       value: snapshotData.value,
       historyValue: revivedHistoryValue,
       _stateInputs: snapshotData.stateInputs ?? {}
-    }, this);
+    }, this, resolvedActorScope.self);
     const seen = new WeakSet();
     function reviveContext(contextPart) {
       if (seen.has(contextPart)) {
@@ -855,8 +997,12 @@ class StateMachine {
       }
     }
     reviveContext(restoredSnapshot.context);
-    return restoredSnapshot;
+    if (usesInertScope) {
+      setInertActorScopeSnapshot(resolvedActorScope, restoredSnapshot, false);
+      return attachSnapshotActorRef(this, resolvedActorScope, restoredSnapshot);
+    }
+    return this._attachPureActorRef(restoredSnapshot, resolvedActorScope);
   }
 }
 
-export { StateMachine as S, StateNode as a };
+export { StateMachine as S, attachSnapshotActorRef as a, getNextSnapshot as b, createInertActorScope as c, StateNode as d, getInitialSnapshot as g, setInertActorScopeSnapshot as s };

package/dist/declarations/src/State.d.ts

@@ -1,4 +1,4 @@
-import type { AnyMachineSnapshot, AnyStateMachine, EventObject, HistoryValue, MachineContext, StateConfig, StateValue, StateValueMap, AnyActorRef, Snapshot, MetaObject, StateSchema, StateId, StateIdInputs, StateContextFromStateValue, SnapshotStatus, AnyStateNode } from "./types.js";
+import type { AnyMachineSnapshot, AnyStateMachine, AnyActor, EventObject, HistoryValue, MachineContext, StateConfig, StateValue, StateValueMap, AnyActorRef, Snapshot, MetaObject, StateSchema, StateId, StateIdInputs, StateContextFromStateValue, SnapshotStatus, AnyStateNode, LogicalTimer } from "./types.js";
 export declare function isMachineSnapshot(value: unknown): value is AnyMachineSnapshot;
 type Values<T> = T[keyof T];
 type MatchingObjectStateValue<TStateValue extends Record<string, unknown>, TTestStateValue extends Record<string, unknown>> = false extends Values<{
@@ -45,6 +45,8 @@ interface MachineSnapshotBase<TContext extends MachineContext, TEvent extends Ev
     _nodes: Array<AnyStateNode>;
     /** An object mapping actor names to spawned/invoked actors. */
     children: TChildren;
+    /** Pending logical timers owned by this machine snapshot. */
+    timers: Readonly<Record<string, LogicalTimer>>;
     /**
      * Whether the current state value is a subset of the given partial state
      * value.
@@ -98,7 +100,7 @@ interface StoppedMachineSnapshot<TContext extends MachineContext, TEvent extends
     error: undefined;
 }
 export type MachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> = ActiveMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | DoneMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | ErrorMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | StoppedMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema>;
-export declare function createMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TMeta extends MetaObject, TStateSchema extends StateSchema>(config: StateConfig<TContext, TEvent>, machine: AnyStateMachine): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, undefined, TMeta, TStateSchema>;
+export declare function createMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TMeta extends MetaObject, TStateSchema extends StateSchema>(config: StateConfig<TContext, TEvent>, machine: AnyStateMachine, actorRef?: AnyActor): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, undefined, TMeta, TStateSchema>;
 export declare function cloneMachineSnapshot<TState extends AnyMachineSnapshot>(snapshot: TState, config?: Partial<StateConfig<any, any>>): TState;
 export declare function getPersistedSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject>(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, any>, options?: unknown): Snapshot<unknown>;
 export {};