xstate 6.0.0-alpha.70 → 6.0.0-alpha.71

package/dist/{createActor-11e36865.development.cjs.js → createActor-2136a8ad.development.cjs.js}

@@ -1,5 +1,392 @@
 'use strict';
 
+const STATE_DELIMITER = '.';
+const TARGETLESS_KEY = '';
+const NULL_EVENT = '';
+const STATE_IDENTIFIER = '#';
+const WILDCARD = '*';
+const XSTATE_INIT = 'xstate.init';
+const XSTATE_START = '@xstate.start';
+const XSTATE_SPAWN = '@xstate.spawn';
+/** The event an actor receives when it is stopped. */
+const XSTATE_STOP = 'xstate.stop';
+/** The effect that stops a child actor. */
+const XSTATE_STOP_EFFECT = '@xstate.stop';
+const XSTATE_TERMINATE = '@xstate.terminate';
+const XSTATE_TIMER = 'xstate.timer';
+const XSTATE_LOGIC_EFFECT_RESOLVE = 'xstate.logic.effect.resolve';
+const XSTATE_LOGIC_EFFECT_REJECT = 'xstate.logic.effect.reject';
+const XSTATE_LOGIC_EFFECT_START = 'xstate.logic.effect.start';
+
+const emptySubscription = {
+  unsubscribe() {}
+};
+const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
+
+/** @internal */
+function isRemoteActorRef(actorRef) {
+  return actorRef._remote === true;
+}
+
+/**
+ * @internal Whether a send target is an actor reference that went through
+ * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
+ */
+function isSerializedActorRef(target) {
+  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
+    return false;
+  }
+  for (const key in target) {
+    if (key !== '$actor' && key !== 'incarnation') {
+      return false;
+    }
+  }
+  const incarnation = target.incarnation;
+  return incarnation === undefined || typeof incarnation === 'string';
+}
+
+/** @internal The actor id that the last segment of an address encodes. */
+function getAddressId(address) {
+  const segment = address.slice(address.lastIndexOf('/') + 1);
+  return segment.includes('%') ? segment.replaceAll('%2F', '/').replaceAll('%25', '%') : segment;
+}
+
+/** @internal The error reported when no live actor has a serialized address. */
+function createMissingAddressError(target) {
+  return new Error(target.incarnation === undefined ? `Unable to send event to actor '${target.$actor}': no live actor has that address` : `Unable to send event to actor '${target.$actor}' (incarnation '${target.incarnation}'): no live actor has that address and incarnation`);
+}
+
+/**
+ * @internal The live actor a serialized ref names: the actor at its address,
+ * and, when the ref carries an `incarnation`, only that incarnation. A ref
+ * without one follows whichever actor is live at the address.
+ */
+function resolveSerializedActorRef(system, target) {
+  const live = system._getByAddress?.(target.$actor);
+  return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
+}
+
+/**
+ * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
+ * by construction: a completion removes the child from its parent's
+ * `children`, so a handle only exists while the child is presumed active,
+ * and the terminal result arrives as a completion event instead of a
+ * snapshot. Full snapshots are a co-location capability.
+ */
+const remoteSnapshot = Object.freeze({
+  status: 'active',
+  output: undefined,
+  error: undefined
+});
+
+/**
+ * Creates the inert ref `enq.spawn(...)` returns while a transition is only
+ * evaluated (for example by `snapshot.can(...)`, or to resolve conflicting
+ * transitions) and no actor is created. It carries the identity the spawn
+ * would get, accepts and drops events, exposes the same lifecycle-only
+ * snapshot as a remote handle, and serializes like any actor ref. Its address
+ * is unknown when the evaluating scope is detached from the parent actor.
+ *
+ * @internal
+ */
+function createInertActorRef(options) {
+  const {
+    id,
+    address
+  } = options;
+  const handle = {
+    ref: undefined,
+    id,
+    address,
+    src: options.src,
+    sessionId: undefined,
+    send() {},
+    getSnapshot() {
+      return remoteSnapshot;
+    },
+    subscribe() {
+      return emptySubscription;
+    },
+    on() {
+      return emptySubscription;
+    },
+    toJSON() {
+      if (address === undefined) {
+        throw new Error(`Cannot serialize actor ref '${id}': it was returned by a spawn during speculative transition evaluation, which creates no actor and has no parent address.`);
+      }
+      return {
+        $actor: address
+      };
+    }
+  };
+  const ref = handle;
+  handle.ref = ref;
+  return ref;
+}
+
+/**
+ * Creates a location-transparent handle to an actor whose state lives with
+ * another runtime. The handle is constructed from identity alone — no lookup
+ * — and every send routes through the system's runtime; its state is not
+ * synchronously readable.
+ *
+ * The surface is deliberately minimal: it covers every member the runtime
+ * reaches for a restored child (send/_send, lifecycle via start/_stop and
+ * system.stopActor, persistence, subscribe/on as inert subscriptions).
+ * Members that only make sense for a co-located actor (public stop(),
+ * select(), trigger) throw a descriptive error rather than being absent, so
+ * calling one reports what went wrong instead of a bare TypeError. Observable
+ * interop and _processingStatus are omitted entirely.
+ *
+ * @internal
+ */
+function createRemoteActorRef(system, options) {
+  const handle = {
+    _remote: true,
+    // Self-reference so context persistence recognizes the handle as an
+    // actor reference instead of recursing into it.
+    ref: undefined,
+    id: options.id,
+    address: options.address,
+    src: options.src,
+    registryKey: options.registryKey,
+    // The host-supplied incarnation token, when present: the owner's
+    // sessionId for this child, letting this side drop stale completions and
+    // journaled sends name the intended incarnation. Without one the handle
+    // does not know the child's incarnation and the owning runtime is the
+    // authority on staleness.
+    sessionId: options.incarnation,
+    system,
+    _parent: options.parent,
+    // Round-trips through persistence verbatim (undefined stays undefined,
+    // so re-persisting is byte-stable); a remote handle cannot act on it
+    // locally.
+    _syncSnapshot: options.syncSnapshot,
+    send(event) {
+      void system.sendEvent(undefined, ref, event);
+    },
+    _send(event) {
+      throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
+    },
+    getSnapshot() {
+      return remoteSnapshot;
+    },
+    getPersistedSnapshot() {
+      throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
+    },
+    start() {},
+    _stop() {},
+    stop() {
+      throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
+    },
+    select() {
+      throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
+    },
+    get trigger() {
+      throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
+    },
+    // Observation is a co-location capability: a remote handle never emits,
+    // so subscriptions are inert rather than errors — generic observers may
+    // attach to any ref.
+    subscribe() {
+      return emptySubscription;
+    },
+    on() {
+      return emptySubscription;
+    },
+    _isRunning() {
+      return false;
+    },
+    // The same shape Actor.toJSON produces, so serialized snapshots carry
+    // one actor-reference shape whether a child is co-located or remote.
+    toJSON() {
+      return {
+        $actor: options.address
+      };
+    }
+  };
+  const ref = handle;
+  handle.ref = ref;
+  return ref;
+}
+
+/** @internal */
+function publishEmittedEvent(source, event, runtime) {
+  source.system._notifyEmitted(source, event);
+  return runtime.emitEvent(source, event);
+}
+function getStepEffect(actor, key) {
+  const effects = actor.getSnapshot().effects;
+  return effects && Object.prototype.hasOwnProperty.call(effects, key) ? effects[key] : undefined;
+}
+
+// Live promises belong to an actor incarnation, unlike its persisted journal.
+// A restored active record has no promise here and must be retried locally.
+const pendingSteps = new WeakMap();
+
+/**
+ * Runs one keyed step of an async actor with the built-in journal: the
+ * result is memoized in the actor's own snapshot (`effects[key]`), so a
+ * restored actor skips completed steps when its logic function re-runs.
+ * Custom runtimes that implement `runStep` use this for the default local
+ * behavior, the same way `deliverEvent` exposes local delivery.
+ *
+ * @experimental
+ */
+async function runStep(actor, key, exec, sendSelf = event => void actor.system.sendEvent(actor, actor, event)) {
+  const effect = getStepEffect(actor, key);
+  if (effect?.status === 'done') {
+    return effect.output;
+  }
+  if (effect?.status === 'error') {
+    throw effect.error;
+  }
+  const running = pendingSteps.get(actor)?.get(key);
+  if (running) {
+    return running;
+  }
+  if (actor.getSnapshot().status !== 'active') {
+    throw new Error(`Actor terminated before step "${key}" completed`);
+  }
+  let resolve;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  let steps = pendingSteps.get(actor);
+  if (!steps) {
+    steps = new Map();
+    pendingSteps.set(actor, steps);
+  }
+  steps.set(key, promise);
+  // oxlint-disable-next-line prefer-const
+  let subscription;
+  const cleanup = () => {
+    subscription?.unsubscribe();
+    steps.delete(key);
+    if (!steps.size) {
+      pendingSteps.delete(actor);
+    }
+  };
+  void promise.then(cleanup, cleanup);
+  subscription = actor.subscribe({
+    error: reject,
+    complete: () => reject(new Error(`Actor terminated before step "${key}" completed`))
+  });
+  void (async () => {
+    try {
+      sendSelf({
+        type: XSTATE_LOGIC_EFFECT_START,
+        key
+      });
+      const output = await exec();
+      if (actor.getSnapshot().status === 'active') {
+        sendSelf({
+          type: XSTATE_LOGIC_EFFECT_RESOLVE,
+          key,
+          output
+        });
+        resolve(output);
+      }
+    } catch (error) {
+      if (actor.getSnapshot().status === 'active') {
+        sendSelf({
+          type: XSTATE_LOGIC_EFFECT_REJECT,
+          key,
+          error
+        });
+      }
+      reject(error);
+    }
+  })().catch(reject);
+  return promise;
+}
+
+/**
+ * Delivers an event directly to a target actor, bypassing any installed host
+ * runtime. Custom runtimes use this for the default local delivery behavior
+ * inside their own `sendEvent` implementations.
+ *
+ * @experimental
+ */
+function deliverEvent(source, target, event) {
+  if (isSerializedActorRef(target)) {
+    const serialized = target;
+    const system = source?.system;
+    const live = system && resolveSerializedActorRef(system, serialized);
+    if (!live) {
+      const error = createMissingAddressError(serialized);
+      if (!system) {
+        throw error;
+      }
+      void system.deadLetter(source, undefined, event, 'missingTarget', {
+        targetId: getAddressId(serialized.$actor),
+        error
+      });
+      return;
+    }
+    target = live;
+  }
+  if (rejectUndeliverableEvent(source, target, event)) {
+    return;
+  }
+  const runtimeTarget = target;
+  runtimeTarget._send(event, source);
+}
+
+/**
+ * Returns the boundary error preventing this delivery, if any: an internal
+ * event type cannot cross an actor boundary from an external sender.
+ */
+function getEventBoundaryError(source, target, event) {
+  const runtimeTarget = target;
+  if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
+    return new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
+  }
+  return undefined;
+}
+
+/**
+ * Rejects an event that must not cross the delivery boundary — an internal
+ * event type sent from outside its owning actor — by reporting it as a dead
+ * letter. Returns `true` when the event was rejected and must not be
+ * delivered. Host runtimes must call this before taking ownership of
+ * delivery.
+ */
+function rejectUndeliverableEvent(source, target, event) {
+  const error = getEventBoundaryError(source, target, event);
+  if (error) {
+    void target.system.deadLetter(source, target, event, 'internalEvent', {
+      error
+    });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Publishes an actor's terminal result, notifying its parent and observers.
+ * Custom runtimes use this for the default local behavior inside their own
+ * `terminateActor` implementations.
+ *
+ * @experimental
+ */
+function terminateActor(actor, termination) {
+  actor._terminate(termination);
+}
+
+/**
+ * Stops an actor without producing a completion result. Custom runtimes use
+ * this for the default local behavior inside their own `stopActor`
+ * implementations.
+ *
+ * @experimental
+ */
+function stopActor(actor) {
+  actor._stop();
+}
+
 class Mailbox {
   constructor(_process) {
     this._process = _process;
@@ -36,34 +423,16 @@ class Mailbox {
     }
   }
   flush() {
-    while (this._current) {
-      // atm the given _process is responsible for implementing proper try/catch handling
-      // we assume here that this won't throw in a way that can affect this mailbox
-      const consumed = this._current;
-      this._process(consumed.value);
-      this._current = consumed.next;
-    }
-    this._last = null;
-  }
-}
-
-const STATE_DELIMITER = '.';
-const TARGETLESS_KEY = '';
-const NULL_EVENT = '';
-const STATE_IDENTIFIER = '#';
-const WILDCARD = '*';
-const XSTATE_INIT = 'xstate.init';
-const XSTATE_START = '@xstate.start';
-const XSTATE_SPAWN = '@xstate.spawn';
-/** The event an actor receives when it is stopped. */
-const XSTATE_STOP = 'xstate.stop';
-/** The effect that stops a child actor. */
-const XSTATE_STOP_EFFECT = '@xstate.stop';
-const XSTATE_TERMINATE = '@xstate.terminate';
-const XSTATE_TIMER = 'xstate.timer';
-const XSTATE_LOGIC_EFFECT_RESOLVE = 'xstate.logic.effect.resolve';
-const XSTATE_LOGIC_EFFECT_REJECT = 'xstate.logic.effect.reject';
-const XSTATE_LOGIC_EFFECT_START = 'xstate.logic.effect.start';
+    while (this._current) {
+      // atm the given _process is responsible for implementing proper try/catch handling
+      // we assume here that this won't throw in a way that can affect this mailbox
+      const consumed = this._current;
+      this._process(consumed.value);
+      this._current = consumed.next;
+    }
+    this._last = null;
+  }
+}
 
 /**
  * Returns an event that represents an implicit event that is sent after the
@@ -543,254 +912,62 @@ function createListenerLogic() {
 }
 
 /** @internal The logic of helper actors created by `enq.listen()`. */
-const listenerLogic = /* #__PURE__ */createListenerLogic();
-
-/** @public */
-
-/** @public */
-
-/** @public */
-
-/** @public */
-
-/** @public */
-
-/**
- * Creates actor logic for subscribing to lifecycle events (done/error/snapshot)
- * from another actor. Used internally by `enq.subscribeTo()`.
- *
- * @public
- */
-function createSubscriptionLogic() {
-  return createAttachedLogic(({
-    actor,
-    mappers
-  }, {
-    self,
-    system
-  }) => {
-    const {
-      done,
-      error,
-      snapshot: onSnapshot
-    } = mappers;
-    return actor.subscribe({
-      next: snapshot => {
-        if (snapshot.status === 'done' && done) {
-          relayMappedToParent(self, system, () => done(snapshot.output));
-        } else if (snapshot.status === 'error' && error) {
-          relayMappedToParent(self, system, () => error(snapshot.error));
-        } else if (snapshot.status === 'active' && onSnapshot) {
-          relayMappedToParent(self, system, () => onSnapshot(snapshot));
-        }
-      },
-      error: err => {
-        if (error) {
-          relayMappedToParent(self, system, () => error(err));
-        }
-      },
-      complete: () => {
-        // Actor completed without output (stopped); no action needed
-      }
-    });
-  }, '@xstate.subscription');
-}
-
-/** @internal The logic of helper actors created by `enq.subscribeTo()`. */
-const subscriptionLogic = /* #__PURE__ */createSubscriptionLogic();
-
-const emptySubscription = {
-  unsubscribe() {}
-};
-const restoreHint = 'or restore this snapshot with embedded children on the runtime that owns them.';
-
-/** @internal */
-function isRemoteActorRef(actorRef) {
-  return actorRef._remote === true;
-}
-
-/**
- * @internal Whether a send target is an actor reference that went through
- * JSON (`actor.toJSON()`): plain data carrying an address, not an actor.
- */
-function isSerializedActorRef(target) {
-  if (typeof target !== 'object' || target === null || Array.isArray(target) || typeof target.$actor !== 'string') {
-    return false;
-  }
-  for (const key in target) {
-    if (key !== '$actor' && key !== 'incarnation') {
-      return false;
-    }
-  }
-  const incarnation = target.incarnation;
-  return incarnation === undefined || typeof incarnation === 'string';
-}
-
-/** @internal The actor id that the last segment of an address encodes. */
-function getAddressId(address) {
-  const segment = address.slice(address.lastIndexOf('/') + 1);
-  return segment.includes('%') ? segment.replaceAll('%2F', '/').replaceAll('%25', '%') : segment;
-}
-
-/** @internal The error reported when no live actor has a serialized address. */
-function createMissingAddressError(target) {
-  return new Error(target.incarnation === undefined ? `Unable to send event to actor '${target.$actor}': no live actor has that address` : `Unable to send event to actor '${target.$actor}' (incarnation '${target.incarnation}'): no live actor has that address and incarnation`);
-}
-
-/**
- * @internal The live actor a serialized ref names: the actor at its address,
- * and, when the ref carries an `incarnation`, only that incarnation. A ref
- * without one follows whichever actor is live at the address.
- */
-function resolveSerializedActorRef(system, target) {
-  const live = system._getByAddress?.(target.$actor);
-  return live && (target.incarnation === undefined || live.sessionId === target.incarnation) ? live : undefined;
-}
-
-/**
- * The lifecycle-only snapshot a remote handle exposes. `active` is accurate
- * by construction: a completion removes the child from its parent's
- * `children`, so a handle only exists while the child is presumed active,
- * and the terminal result arrives as a completion event instead of a
- * snapshot. Full snapshots are a co-location capability.
- */
-const remoteSnapshot = Object.freeze({
-  status: 'active',
-  output: undefined,
-  error: undefined
-});
-
-/**
- * Creates the inert ref `enq.spawn(...)` returns while a transition is only
- * evaluated (for example by `snapshot.can(...)`, or to resolve conflicting
- * transitions) and no actor is created. It carries the identity the spawn
- * would get, accepts and drops events, exposes the same lifecycle-only
- * snapshot as a remote handle, and serializes like any actor ref. Its address
- * is unknown when the evaluating scope is detached from the parent actor.
- *
- * @internal
- */
-function createInertActorRef(options) {
-  const {
-    id,
-    address
-  } = options;
-  const handle = {
-    ref: undefined,
-    id,
-    address,
-    src: options.src,
-    sessionId: undefined,
-    send() {},
-    getSnapshot() {
-      return remoteSnapshot;
-    },
-    subscribe() {
-      return emptySubscription;
-    },
-    on() {
-      return emptySubscription;
-    },
-    toJSON() {
-      if (address === undefined) {
-        throw new Error(`Cannot serialize actor ref '${id}': it was returned by a spawn during speculative transition evaluation, which creates no actor and has no parent address.`);
-      }
-      return {
-        $actor: address
-      };
-    }
-  };
-  const ref = handle;
-  handle.ref = ref;
-  return ref;
-}
-
-/**
- * Creates a location-transparent handle to an actor whose state lives with
- * another runtime. The handle is constructed from identity alone — no lookup
- * — and every send routes through the system's runtime; its state is not
- * synchronously readable.
- *
- * The surface is deliberately minimal: it covers every member the runtime
- * reaches for a restored child (send/_send, lifecycle via start/_stop and
- * system.stopActor, persistence, subscribe/on as inert subscriptions).
- * Members that only make sense for a co-located actor (public stop(),
- * select(), trigger) throw a descriptive error rather than being absent, so
- * calling one reports what went wrong instead of a bare TypeError. Observable
- * interop and _processingStatus are omitted entirely.
- *
- * @internal
- */
-function createRemoteActorRef(system, options) {
-  const handle = {
-    _remote: true,
-    // Self-reference so context persistence recognizes the handle as an
-    // actor reference instead of recursing into it.
-    ref: undefined,
-    id: options.id,
-    address: options.address,
-    src: options.src,
-    registryKey: options.registryKey,
-    // The host-supplied incarnation token, when present: the owner's
-    // sessionId for this child, letting this side drop stale completions and
-    // journaled sends name the intended incarnation. Without one the handle
-    // does not know the child's incarnation and the owning runtime is the
-    // authority on staleness.
-    sessionId: options.incarnation,
-    system,
-    _parent: options.parent,
-    // Round-trips through persistence verbatim (undefined stays undefined,
-    // so re-persisting is byte-stable); a remote handle cannot act on it
-    // locally.
-    _syncSnapshot: options.syncSnapshot,
-    send(event) {
-      void system.sendEvent(undefined, ref, event);
-    },
-    _send(event) {
-      throw new Error(`Remote actor '${options.address}' has no local mailbox to receive "${event.type}". Its state lives with another runtime; install a runtime that can reach it (via \`createDurable\`'s adapter runtime operations, or \`system.runtime\`) before sending, ${restoreHint}`);
-    },
-    getSnapshot() {
-      return remoteSnapshot;
-    },
-    getPersistedSnapshot() {
-      throw new Error(`Cannot persist remote actor '${options.address}' from here: its state lives with the runtime that owns it. Persist it there, ${restoreHint}`);
-    },
-    start() {},
-    _stop() {},
-    stop() {
-      throw new Error(`Cannot stop remote actor '${options.address}' directly: stopping is a co-located operation. Stop it through the system runtime that owns it (\`system.stopActor(ref)\`), ${restoreHint}`);
-    },
-    select() {
-      throw new Error(`Cannot select from remote actor '${options.address}': its snapshot is not synchronously readable because its state lives with another runtime. Read it on the runtime that owns it, ${restoreHint}`);
-    },
-    get trigger() {
-      throw new Error(`Remote actor '${options.address}' has no \`trigger\` shorthand: it requires a co-located actor. Use \`send(...)\`, which routes through the system runtime.`);
-    },
-    // Observation is a co-location capability: a remote handle never emits,
-    // so subscriptions are inert rather than errors — generic observers may
-    // attach to any ref.
-    subscribe() {
-      return emptySubscription;
-    },
-    on() {
-      return emptySubscription;
-    },
-    _isRunning() {
-      return false;
-    },
-    // The same shape Actor.toJSON produces, so serialized snapshots carry
-    // one actor-reference shape whether a child is co-located or remote.
-    toJSON() {
-      return {
-        $actor: options.address
-      };
-    }
-  };
-  const ref = handle;
-  handle.ref = ref;
-  return ref;
+const listenerLogic = /* #__PURE__ */createListenerLogic();
+
+/** @public */
+
+/** @public */
+
+/** @public */
+
+/** @public */
+
+/** @public */
+
+/**
+ * Creates actor logic for subscribing to lifecycle events (done/error/snapshot)
+ * from another actor. Used internally by `enq.subscribeTo()`.
+ *
+ * @public
+ */
+function createSubscriptionLogic() {
+  return createAttachedLogic(({
+    actor,
+    mappers
+  }, {
+    self,
+    system
+  }) => {
+    const {
+      done,
+      error,
+      snapshot: onSnapshot
+    } = mappers;
+    return actor.subscribe({
+      next: snapshot => {
+        if (snapshot.status === 'done' && done) {
+          relayMappedToParent(self, system, () => done(snapshot.output));
+        } else if (snapshot.status === 'error' && error) {
+          relayMappedToParent(self, system, () => error(snapshot.error));
+        } else if (snapshot.status === 'active' && onSnapshot) {
+          relayMappedToParent(self, system, () => onSnapshot(snapshot));
+        }
+      },
+      error: err => {
+        if (error) {
+          relayMappedToParent(self, system, () => error(err));
+        }
+      },
+      complete: () => {
+        // Actor completed without output (stopped); no action needed
+      }
+    });
+  }, '@xstate.subscription');
 }
 
+/** @internal The logic of helper actors created by `enq.subscribeTo()`. */
+const subscriptionLogic = /* #__PURE__ */createSubscriptionLogic();
+
 function execCustomEffect() {
   const result = this.action?.(...this.args);
   {
@@ -821,7 +998,7 @@ function warnOnIgnoredEffectResult(effect, result) {
   console.warn(`Action "${effect.type || '(anonymous)'}" returned { ${keys.join(', ')} }, which is ignored: functions passed to enq(...) run as effects after the transition. Return the patch from the transition, entry or exit function instead; a named action can be called there directly and its result returned.`);
 }
 function execEmitEffect(runtime = this.source.system) {
-  return runtime.emitEvent(this.source, this.event);
+  return publishEmittedEvent(this.source, this.event, runtime);
 }
 
 /** @internal Creates an emitted-event effect. */
@@ -1945,6 +2122,8 @@ function createSnapshotSystem(baseSystem, children, baseState) {
     },
     get: registryKey => keyedActors.get(registryKey),
     getAll: () => Object.fromEntries(keyedActors),
+    onEmitted: listener => baseSystem.onEmitted(listener),
+    _notifyEmitted: (actorRef, event) => baseSystem._notifyEmitted(actorRef, event),
     // Pure transition resolution must not leak topology inspection events
     // into a live runtime system — planning branches stay silent. The one
     // exception is a durable execution's own transitions (marked by the
@@ -3574,10 +3753,9 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
           }
         }
         if (contextChangedByEntry) {
-          nextState.context = context;
-          {
-            freezeContext(context);
-          }
+          nextState = cloneMachineSnapshot(nextState, {
+            context
+          });
         }
         if (statesForDefaultEntry.has(stateNodeToEnter)) {
           const defaultTransitions = [stateNodeToEnter.initial, ...(historyDefaultsByParent.get(stateNodeToEnter) ?? [])].filter(Boolean);
@@ -3595,10 +3773,9 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
               internalQueue.push(...initialInternalEvents);
             }
             if (initialContext !== undefined) {
-              nextState.context = mergeContextPatch(nextState.context, initialContext);
-              {
-                freezeContext(nextState.context);
-              }
+              nextState = cloneMachineSnapshot(nextState, {
+                context: mergeContextPatch(nextState.context, initialContext)
+              });
             }
             if (initialInput && defaultTransition.target) {
               for (const targetNode of defaultTransition.target) {
@@ -3665,6 +3842,27 @@ function microstep(transitions, currentSnapshot, actorScope, event, isInitial, i
         context
       });
     }
+    const transitionContent = nextState.machine._microstepHooks?.transitionContent?.(filteredTransitions, [...mutStateNodeSet]);
+    if (transitionContent) {
+      const source = filteredTransitions[0].source;
+      const [actions, nextContext, raisedEvents, nextChildren] = getStateActionsAndContext(transitionContent, nextState.context, nextState.children, getStateInput(nextState, source.id), 'transition', source);
+      if (raisedEvents?.length) {
+        internalQueue.push(...raisedEvents);
+      }
+      if (nextContext || nextChildren) {
+        nextState = cloneMachineSnapshot(nextState, {
+          ...(nextContext ? {
+            context: nextContext
+          } : {}),
+          ...(nextChildren ? {
+            children: nextChildren
+          } : {})
+        });
+      }
+      const [resolvedState, effects] = resolveActionsWithContext(nextState, event, actorScope, actions);
+      nextState = resolvedState;
+      executableActions.push(...effects);
+    }
 
     // Enter states
     if (isInitial || changesState) {
@@ -4055,7 +4253,7 @@ function hasEffect(transition, context, event, snapshot, actorScope) {
 function assertSyncTransitionResult(res, event, sourceId, kind) {
   if (res && typeof res.then === 'function') {
     void Promise.resolve(res).catch(() => {});
-    throw new Error(kind ? `${kind === 'entry' ? 'Entry' : 'Exit'} functions must be synchronous. The ${kind} function of state "${sourceId}" returned a promise (event "${event.type}"). Move async work into an invoked or spawned actor, or enq.effect.` : `Transition functions must be synchronous. Transition for event "${event.type}" in state "${sourceId}" returned a promise. Move async work into an invoked or spawned actor, or enq.effect.`);
+    throw new Error(kind && kind !== 'transition' ? `${kind === 'entry' ? 'Entry' : 'Exit'} functions must be synchronous. The ${kind} function of state "${sourceId}" returned a promise (event "${event.type}"). Move async work into an invoked or spawned actor, or enq.effect.` : `Transition functions must be synchronous. Transition for event "${event.type}" in state "${sourceId}" returned a promise. Move async work into an invoked or spawned actor, or enq.effect.`);
   }
 }
 function createTransitionSelection(parent) {
@@ -5042,178 +5240,6 @@ function matchesEventDescriptor(eventType, descriptor) {
   return true;
 }
 
-function getStepEffect(actor, key) {
-  const effects = actor.getSnapshot().effects;
-  return effects && Object.prototype.hasOwnProperty.call(effects, key) ? effects[key] : undefined;
-}
-
-// Live promises belong to an actor incarnation, unlike its persisted journal.
-// A restored active record has no promise here and must be retried locally.
-const pendingSteps = new WeakMap();
-
-/**
- * Runs one keyed step of an async actor with the built-in journal: the
- * result is memoized in the actor's own snapshot (`effects[key]`), so a
- * restored actor skips completed steps when its logic function re-runs.
- * Custom runtimes that implement `runStep` use this for the default local
- * behavior, the same way `deliverEvent` exposes local delivery.
- *
- * @experimental
- */
-async function runStep(actor, key, exec, sendSelf = event => void actor.system.sendEvent(actor, actor, event)) {
-  const effect = getStepEffect(actor, key);
-  if (effect?.status === 'done') {
-    return effect.output;
-  }
-  if (effect?.status === 'error') {
-    throw effect.error;
-  }
-  const running = pendingSteps.get(actor)?.get(key);
-  if (running) {
-    return running;
-  }
-  if (actor.getSnapshot().status !== 'active') {
-    throw new Error(`Actor terminated before step "${key}" completed`);
-  }
-  let resolve;
-  let reject;
-  const promise = new Promise((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = rejectPromise;
-  });
-  let steps = pendingSteps.get(actor);
-  if (!steps) {
-    steps = new Map();
-    pendingSteps.set(actor, steps);
-  }
-  steps.set(key, promise);
-  // oxlint-disable-next-line prefer-const
-  let subscription;
-  const cleanup = () => {
-    subscription?.unsubscribe();
-    steps.delete(key);
-    if (!steps.size) {
-      pendingSteps.delete(actor);
-    }
-  };
-  void promise.then(cleanup, cleanup);
-  subscription = actor.subscribe({
-    error: reject,
-    complete: () => reject(new Error(`Actor terminated before step "${key}" completed`))
-  });
-  void (async () => {
-    try {
-      sendSelf({
-        type: XSTATE_LOGIC_EFFECT_START,
-        key
-      });
-      const output = await exec();
-      if (actor.getSnapshot().status === 'active') {
-        sendSelf({
-          type: XSTATE_LOGIC_EFFECT_RESOLVE,
-          key,
-          output
-        });
-        resolve(output);
-      }
-    } catch (error) {
-      if (actor.getSnapshot().status === 'active') {
-        sendSelf({
-          type: XSTATE_LOGIC_EFFECT_REJECT,
-          key,
-          error
-        });
-      }
-      reject(error);
-    }
-  })().catch(reject);
-  return promise;
-}
-
-/**
- * Delivers an event directly to a target actor, bypassing any installed host
- * runtime. Custom runtimes use this for the default local delivery behavior
- * inside their own `sendEvent` implementations.
- *
- * @experimental
- */
-function deliverEvent(source, target, event) {
-  if (isSerializedActorRef(target)) {
-    const serialized = target;
-    const system = source?.system;
-    const live = system && resolveSerializedActorRef(system, serialized);
-    if (!live) {
-      const error = createMissingAddressError(serialized);
-      if (!system) {
-        throw error;
-      }
-      void system.deadLetter(source, undefined, event, 'missingTarget', {
-        targetId: getAddressId(serialized.$actor),
-        error
-      });
-      return;
-    }
-    target = live;
-  }
-  if (rejectUndeliverableEvent(source, target, event)) {
-    return;
-  }
-  const runtimeTarget = target;
-  runtimeTarget._send(event, source);
-}
-
-/**
- * Returns the boundary error preventing this delivery, if any: an internal
- * event type cannot cross an actor boundary from an external sender.
- */
-function getEventBoundaryError(source, target, event) {
-  const runtimeTarget = target;
-  if (source !== target && runtimeTarget.logic?.isInternalEventType?.(event.type)) {
-    return new Error(`Internal event "${event.type}" cannot be sent to actor "${target.id}" from outside.`);
-  }
-  return undefined;
-}
-
-/**
- * Rejects an event that must not cross the delivery boundary — an internal
- * event type sent from outside its owning actor — by reporting it as a dead
- * letter. Returns `true` when the event was rejected and must not be
- * delivered. Host runtimes must call this before taking ownership of
- * delivery.
- */
-function rejectUndeliverableEvent(source, target, event) {
-  const error = getEventBoundaryError(source, target, event);
-  if (error) {
-    void target.system.deadLetter(source, target, event, 'internalEvent', {
-      error
-    });
-    return true;
-  }
-  return false;
-}
-
-/**
- * Publishes an actor's terminal result, notifying its parent and observers.
- * Custom runtimes use this for the default local behavior inside their own
- * `terminateActor` implementations.
- *
- * @experimental
- */
-function terminateActor(actor, termination) {
-  actor._terminate(termination);
-}
-
-/**
- * Stops an actor without producing a completion result. Custom runtimes use
- * this for the default local behavior inside their own `stopActor`
- * implementations.
- *
- * @experimental
- */
-function stopActor(actor) {
-  actor._stop();
-}
-
 let executionIdPrefix;
 let nextExecutionId = 0;
 function createExecutionIdPrefix() {
@@ -5409,6 +5435,8 @@ function bookSessionId(system) {
  * @public
  */
 
+/** @public */
+
 /** @experimental */
 
 /** @internal Every operation of `ActorSystemRuntime`, for runtime wrappers. */
@@ -5656,6 +5684,32 @@ class RuntimeSystem {
       }
     };
   }
+  onEmitted(listener) {
+    const entry = emission => listener(emission);
+    (this._emissionListeners ??= new Set()).add(entry);
+    return {
+      unsubscribe: () => {
+        this._emissionListeners?.delete(entry);
+      }
+    };
+  }
+  _notifyEmitted(actorRef, event) {
+    const listeners = this._emissionListeners;
+    if (!listeners?.size) {
+      return;
+    }
+    const emission = {
+      actorRef,
+      event
+    };
+    for (const listener of Array.from(listeners)) {
+      try {
+        listener(emission);
+      } catch (err) {
+        reportUnhandledError(err);
+      }
+    }
+  }
   _hasInspectionObservers() {
     return !!this._inspectionObservers?.size;
   }
@@ -5858,6 +5912,17 @@ function createRuntimeSystem(rootActor, options) {
 
 let executingCustomAction = false;
 const emptyInspectionRecords = Object.freeze([]);
+const reservedMachineEventTypes = {
+  'xstate.done.actor': true,
+  'xstate.error.actor': true,
+  'xstate.error.execution': true,
+  'xstate.snapshot.actor': true,
+  'xstate.done.state': true,
+  'xstate.after': true,
+  'xstate.timeout.state': true,
+  'xstate.timeout.actor': true,
+  [XSTATE_TIMER]: true
+};
 
 // those values are currently used by @xstate/react directly so it's important to keep the assigned values in sync
 let ProcessingStatus = /*#__PURE__*/function (ProcessingStatus) {
@@ -6029,6 +6094,7 @@ class Actor {
     });
     if (!parent && resolvedOptions._systemRef && !resolvedOptions._systemRef.current) {
       resolvedOptions._systemRef.current = this.system;
+      resolvedOptions._systemRef.initialize?.();
     }
     if (inspect && !parent) {
       // Always inspect at the system-level
@@ -6132,7 +6198,7 @@ class Actor {
     return stopChild;
   }
   get emit() {
-    const emit = event => this.system.emitEvent(this, event);
+    const emit = event => publishEmittedEvent(this, event, this.system);
     Object.defineProperty(this, 'emit', {
       value: emit
     });
@@ -6595,10 +6661,7 @@ class Actor {
       const [nextSnapshot, effects] = nextState;
       if (nextSnapshot === previousSnapshot && !effects.length &&
       // State machine snapshots only; other logic may ignore events freely.
-      'machine' in previousSnapshot && (
-      // `xstate.route` is sent by users, so a route that matches nothing is
-      // reported like any other unhandled event.
-      !event.type.startsWith('xstate.') || event.type === 'xstate.route')) {
+      'machine' in previousSnapshot && event.type !== XSTATE_STOP && (!sourceRef || !Object.hasOwn(reservedMachineEventTypes, event.type))) {
         this._reportUnhandledEvent(event);
       }
       snapshot = nextSnapshot;
@@ -6929,6 +6992,9 @@ class Actor {
  * @public
  */
 function createActor(logic, ...[options]) {
+  if (options && 'parent' in options) {
+    throw new Error('The "parent" actor option was removed. Create child actors through invoke, spawn, or enq.spawn instead.');
+  }
   return new Actor(logic, options);
 }
 
@@ -7017,6 +7083,7 @@ exports.matchesTimerKey = matchesTimerKey;
 exports.mergeActorIdCounters = mergeActorIdCounters;
 exports.parseDelayToMilliseconds = parseDelayToMilliseconds;
 exports.parseGeneratedActorId = parseGeneratedActorId;
+exports.publishEmittedEvent = publishEmittedEvent;
 exports.readTimerKey = readTimerKey;
 exports.recordTimerStart = recordTimerStart;
 exports.reserveChildId = reserveChildId;