@vedmalex/statemachine 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   StateMachineError: () => StateMachineError,
   createEnhancedError: () => createEnhancedError,
   createMachine: () => createMachine,
+  createVirtualScheduler: () => createVirtualScheduler,
   isAdapter: () => isAdapter,
   isRecoverableError: () => isRecoverableError,
   isValidConfig: () => isValidConfig,
@@ -53,7 +54,9 @@ var TimerScheduler = class {
   intervalId = null;
   pollingInterval = 100;
   // ms
-  constructor() {
+  clock;
+  constructor(clock = Date.now) {
+    this.clock = clock;
   }
   /**
    * Настройка режима опроса
@@ -77,7 +80,7 @@ var TimerScheduler = class {
    */
   start() {
     if (this.intervalId) return;
-    this.intervalId = setInterval(() => this.process(), this.pollingInterval);
+    this.intervalId = setInterval(() => this.process(this.clock()), this.pollingInterval);
   }
   /**
    * Остановка единого таймера
@@ -96,7 +99,7 @@ var TimerScheduler = class {
    */
   schedule(delay, callback) {
     const token = {};
-    const executeAt = Date.now() + delay;
+    const executeAt = this.clock() + delay;
     const task = { token, executeAt, callback };
     this.activeTokens.add(token);
     this.insert(task);
@@ -112,7 +115,7 @@ var TimerScheduler = class {
   /**
    * Обработать очередь (вызывается таймером или вручную)
    */
-  process(now = Date.now()) {
+  process(now = this.clock()) {
     while (this.heap.length > 0) {
       const task = this.heap[0];
       if (task === void 0) break;
@@ -203,6 +206,23 @@ var TimerScheduler = class {
 function createDefaultScheduler() {
   return new TimerScheduler();
 }
+function createVirtualScheduler(clock) {
+  const inner = new TimerScheduler(clock);
+  return {
+    isActive() {
+      return true;
+    },
+    schedule(delay, callback) {
+      return inner.schedule(delay, callback);
+    },
+    cancel(token) {
+      inner.cancel(token);
+    },
+    process(now) {
+      inner.process(now ?? clock());
+    }
+  };
+}
 
 // src/logger.ts
 var LogLevel = {
@@ -1749,6 +1769,8 @@ var StateMachine = class _StateMachine {
   monitor;
   scheduler;
   errorHandler;
+  clock;
+  schedulerProvided;
   // Свойства
   states;
   events;
@@ -1799,7 +1821,9 @@ var StateMachine = class _StateMachine {
     this.initialState = config.initialState;
     this.logger = options?.logger ?? ConsoleLogger;
     this.monitor = options?.monitor ?? createDefaultMonitor();
+    this.schedulerProvided = options?.scheduler !== void 0;
     this.scheduler = options?.scheduler ?? createDefaultScheduler();
+    this.clock = options?.clock ?? Date.now;
     this.errorHandler = options?.errorHandler ?? createDefaultErrorHandler();
     if (adaptee) {
       if (!isAdapter(adaptee)) {
@@ -1850,6 +1874,9 @@ var StateMachine = class _StateMachine {
   setContext(context) {
     this.context = context;
   }
+  resolveCallbackOwner(value) {
+    return isAdapter(value) ? value.adaptee : value;
+  }
   enqueueEvent(eventName, obj, args, type) {
     if (this.externalQueue.length + this.internalQueue.length >= this.maxQueueDepth) {
       const _s0 = this.getCurrentState(obj);
@@ -1870,7 +1897,7 @@ var StateMachine = class _StateMachine {
           args,
           resolve,
           reject,
-          timestamp: Date.now(),
+          timestamp: this.clock(),
           type: "external"
         });
         this.scheduleProcessing();
@@ -1881,7 +1908,7 @@ var StateMachine = class _StateMachine {
       eventName,
       obj,
       args,
-      timestamp: Date.now(),
+      timestamp: this.clock(),
       type: "internal"
     });
     return Promise.resolve(true);
@@ -1892,7 +1919,7 @@ var StateMachine = class _StateMachine {
       eventName,
       obj,
       args,
-      timestamp: Date.now(),
+      timestamp: this.clock(),
       type: "internal"
     });
   }
@@ -1958,7 +1985,8 @@ var StateMachine = class _StateMachine {
     let transitions = event ? event.transitions.filter(
       (t) => this.isTransitionPossible(t, currentState)
     ) : [];
-    if (!transitions.length) {
+    const isEngineDoneEvent = String(eventName).startsWith("done.state.");
+    if (!transitions.length && !isEngineDoneEvent) {
       const wildcardEvent = this.events.get("*");
       if (wildcardEvent) {
         const wildcardTransitions = wildcardEvent.transitions.filter(
@@ -2052,7 +2080,7 @@ var StateMachine = class _StateMachine {
     };
   }
   getQueuedEvents() {
-    const now = Date.now();
+    const now = this.clock();
     const mapEvent = (evt) => ({
       id: evt.id,
       event: evt.eventName,
@@ -2163,57 +2191,59 @@ var StateMachine = class _StateMachine {
     if (!currentState) return expectedState === "";
     const currentParts = currentState.split("|").sort();
     const expectedParts = expectedState.split("|").sort();
+    const ancestorMatch = expectedParts.every(
+      (expectedPart) => currentParts.some((leaf) => this.isParentState(expectedPart, leaf))
+    );
+    if (ancestorMatch) return true;
     if (currentParts.length !== expectedParts.length) return false;
     return currentParts.every((part, index) => part === expectedParts[index]);
   }
   attachToObject(object, eventMap) {
-    for (const objectEventName in eventMap) {
-      if (eventMap.hasOwnProperty(objectEventName)) {
-        const stateMachineEventName = eventMap[objectEventName];
-        if (stateMachineEventName === void 0) continue;
-        if (typeof object.addEventListener === "function") {
-          object.addEventListener(objectEventName, (...args) => {
-            this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          });
-        } else if (typeof object.on === "function") {
-          object.on(objectEventName, (...args) => {
-            this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          });
-        } else {
-          object[`on${objectEventName}`] = async (...args) => {
-            return this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          };
-        }
+    for (const objectEventName of Object.keys(eventMap)) {
+      const stateMachineEventName = eventMap[objectEventName];
+      if (stateMachineEventName === void 0) continue;
+      if (typeof object.addEventListener === "function") {
+        object.addEventListener(objectEventName, (...args) => {
+          this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        });
+      } else if (typeof object.on === "function") {
+        object.on(objectEventName, (...args) => {
+          this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        });
+      } else {
+        object[`on${objectEventName}`] = async (...args) => {
+          return this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        };
       }
     }
   }
@@ -2541,7 +2571,7 @@ var StateMachine = class _StateMachine {
     const currentState = this.getCurrentState(adaptee) || "";
     const currentStateMap = this.parseCompositeState(currentState);
     const newStateParts = state.split("|");
-    const isRootState = newStateParts.length === 1 && !state.includes(".");
+    const isRootState = newStateParts.length === 1 && !state.includes(".") && !this.states.get(state)?.regions;
     if (isRootState) {
       currentStateMap.clear();
       currentStateMap.set(state, state);
@@ -2617,12 +2647,13 @@ var StateMachine = class _StateMachine {
       initialStates = initialState;
     }
     this.setCurrentState(initialStates, targetAdaptee);
-    const stateParts = initialStates.split("|");
+    const { enterStates } = this.computeEnterExitSets("", initialStates);
+    const enterFireOrder = enterStates.length > 0 ? enterStates : [initialStates];
     const context = {
       state: initialStates,
       phase: "enter"
     };
-    for (const statePart of stateParts) {
+    for (const statePart of enterFireOrder) {
       this.executeEnterActions(
         targetAdaptee,
         statePart,
@@ -2636,6 +2667,11 @@ var StateMachine = class _StateMachine {
         );
       });
     }
+    this.checkCompletion(
+      targetAdaptee,
+      "",
+      initialStates
+    );
   }
   getInitialCompositeState(initialState) {
     const stateConfig = this.states.get(initialState);
@@ -2675,6 +2711,211 @@ var StateMachine = class _StateMachine {
     }
     return regionStates.join("|");
   }
+  /**
+   * Whether `leaf` is a UML/SCXML `<final>` atomic state of its region.
+   *
+   * Reads the `final` marker straight from the flattened state map populated by
+   * processStates, so it works for any registered atomic leaf regardless of
+   * nesting depth. Returns `false` for unregistered names and for composites
+   * (the all-regions-final join derives doneness from atomic leaves, not from a
+   * `final` flag on a composite parent).
+   */
+  isStateFinal(leaf) {
+    return Boolean(this.states.get(leaf)?.final);
+  }
+  /**
+   * Whether composite `compositeId` has reached its UML/SCXML "done"
+   * configuration: every one of its regions has its active atomic leaf in a
+   * `final` state (recursively, for nested composites).
+   *
+   * D10 (mustFix): doneness is derived by scanning the active atomic `|`-leaves
+   * against the STATIC regions tree (`this.states.get(C)?.regions`), NEVER via a
+   * region-key Map lookup (`configMap.get`) — that map keys leaves by their
+   * deepest region container and so cannot answer "which leaf is active in
+   * region X of composite C". For each region we locate the active leaf via the
+   * `C.region.` dotted prefix; the region is final iff that leaf is `final`, or
+   * the leaf lives under a nested composite that is itself `isCompositeDone`.
+   *
+   * Returns `false` for a non-composite id, for a composite with no active leaf
+   * in some region, or when no substate under it is ever `final` (cheap miss).
+   */
+  isCompositeDone(compositeId, atomicLeaves) {
+    const regions = this.states.get(compositeId)?.regions;
+    if (!regions) return false;
+    for (const regionName of Object.keys(regions)) {
+      const regionPrefix = `${compositeId}.${regionName}.`;
+      const activeLeaf = atomicLeaves.find(
+        (leaf) => leaf.startsWith(regionPrefix)
+      );
+      if (!activeLeaf) return false;
+      const nestedComposite = this.regionComposite(activeLeaf, regionPrefix);
+      if (nestedComposite) {
+        if (this.isCompositeDone(nestedComposite, atomicLeaves)) continue;
+        return false;
+      }
+      if (this.isStateFinal(activeLeaf)) continue;
+      return false;
+    }
+    return true;
+  }
+  /**
+   * The OUTERMOST registered composite (regions-bearing) ancestor of `leaf`
+   * that lives strictly under `regionPrefix`, or `undefined` if the region
+   * holds a simple atomic state directly. Used by {@link isCompositeDone} to
+   * delegate a region's completeness to its nested composite (recursing over
+   * every parallel branch), independent of whether any single branch leaf
+   * happens to carry the `final` flag.
+   *
+   * ancestorChain is root-to-leaf, so the FIRST matching ancestor is the
+   * region's direct composite child (e.g. `C.p.D` for leaf `C.p.D.s.s2` under
+   * region prefix `C.p.`); isCompositeDone then recurses into its regions.
+   */
+  regionComposite(leaf, regionPrefix) {
+    for (const ancestor of this.ancestorChain(leaf)) {
+      if (ancestor !== leaf && ancestor.startsWith(regionPrefix) && this.states.get(ancestor)?.regions) {
+        return ancestor;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Whether composite `compositeId` has reached its all-regions-final ("done")
+   * configuration in the CURRENT active state. Public guard surface (`@stable`)
+   * for authoring a join as `guard: () => sm.isDone('C')` instead of (or
+   * alongside) listening on the engine `done.state.<C>` event.
+   *
+   * @param compositeId - The dotted id of the composite/parallel state.
+   * @returns `true` iff every region's active atomic leaf is `final`.
+   */
+  isDone(compositeId, adaptee) {
+    const currentState = this.getCurrentState(adaptee);
+    if (!currentState) return false;
+    const atomicLeaves = currentState.split("|").filter(Boolean);
+    return this.isCompositeDone(compositeId, atomicLeaves);
+  }
+  /**
+   * SCXML completion hook (D10/D11/D12): after a new configuration is written,
+   * raise `done.state.<C>` for each composite that became all-regions-final.
+   *
+   * - Scans only composites that GAINED an active leaf (the ancestor chain of
+   *   each `|`-leaf of `newState`), so unaffected composites are not re-checked.
+   * - Emits INNERMOST-first (a deeper composite's `done.state` precedes its
+   *   parent's), matching SCXML's inner-before-outer completion ordering, via a
+   *   per-config emitted-id Set so each id is raised at most once per call.
+   * - Gates each emission on `this.events.has('done.state.'+C)` (D11 mustFix):
+   *   raising an undeclared event would hit the `Invalid event` throw
+   *   (executeQueuedTransition) as an unhandled microtask rejection. No declared
+   *   `done.state.<C>` event => no emission, no crash, no observable effect.
+   * - Uses the internal queue (`raiseEvent`) + `scheduleProcessing` so the
+   *   completion event is processed before subsequent external events.
+   */
+  checkCompletion(obj, oldState, newState) {
+    const atomicLeaves = newState.split("|").filter(Boolean);
+    if (atomicLeaves.length === 0) return;
+    const oldLeaves = oldState.split("|").filter(Boolean);
+    const seen = /* @__PURE__ */ new Set();
+    for (const leaf of atomicLeaves) {
+      for (const ancestor of this.ancestorChain(leaf)) {
+        if (ancestor === leaf) continue;
+        if (seen.has(ancestor)) continue;
+        if (!this.states.get(ancestor)?.regions) continue;
+        seen.add(ancestor);
+      }
+    }
+    const candidates = Array.from(seen).sort(
+      (a, b) => b.split(".").length - a.split(".").length
+    );
+    const emitted = /* @__PURE__ */ new Set();
+    for (const compositeId of candidates) {
+      if (emitted.has(compositeId)) continue;
+      if (!this.isCompositeDone(compositeId, atomicLeaves)) continue;
+      if (this.isCompositeDone(compositeId, oldLeaves)) continue;
+      emitted.add(compositeId);
+      const doneEvent = `done.state.${compositeId}`;
+      if (!this.events.has(doneEvent)) continue;
+      this.raiseEvent(doneEvent, obj);
+      this.scheduleProcessing();
+    }
+  }
+  /**
+   * Build the registered ancestor chain for an atomic leaf, ordered root-to-leaf.
+   *
+   * Walks every dot-prefix of `leaf` and keeps only the ones that are real
+   * registered states (`this.states.has`). Region containers are never
+   * registered (only composite parents and atomic leaves are — see
+   * processStates/processRegions), so they are filtered out automatically. The
+   * result is exactly `[parent..leaf]` for a leaf inside a composite, and
+   * `[leaf]` for a flat state.
+   *
+   * Example: `ancestorChain('a.r1.c1')` -> `['a', 'a.r1.c1']` (the `a.r1`
+   * region container is excluded). Nested:
+   * `ancestorChain('a.r1.c1.r3.x')` -> `['a', 'a.r1.c1', 'a.r1.c1.r3.x']`.
+   */
+  ancestorChain(leaf) {
+    const chain = [];
+    let dotIndex = leaf.indexOf(".");
+    while (dotIndex !== -1) {
+      const prefix = leaf.substring(0, dotIndex);
+      if (this.states.has(prefix)) {
+        chain.push(prefix);
+      }
+      dotIndex = leaf.indexOf(".", dotIndex + 1);
+    }
+    if (this.states.has(leaf)) {
+      chain.push(leaf);
+    }
+    return chain;
+  }
+  /**
+   * Compute the ordered enter/exit sets between two composite configurations
+   * (SCXML ancestor-first entry / descendant-first exit).
+   *
+   * For each `|`-separated atomic leaf in `oldComposite` and `newComposite` the
+   * union of its {@link ancestorChain} forms the old/new active ancestry. A
+   * state shared by both ancestries lands in NEITHER diff, so a surviving
+   * ancestor is never re-entered nor exited (no onEnter/onExit re-fire, no
+   * timer re-arm/leak).
+   *
+   * - `enterStates` = new ancestry MINUS old, sorted ascending by depth then
+   *   document (insertion) order -> root-to-leaf entry.
+   * - `exitStates` = old ancestry MINUS new, sorted descending by depth ->
+   *   leaf-to-root exit.
+   *
+   * Consumed by BOTH R1 (applyTransition / setInitialState / reset) and R2.
+   */
+  computeEnterExitSets(oldComposite, newComposite) {
+    const collectAncestry = (composite) => {
+      const ancestry = /* @__PURE__ */ new Set();
+      if (!composite) return ancestry;
+      for (const leaf of composite.split("|")) {
+        if (!leaf) continue;
+        for (const ancestor of this.ancestorChain(leaf)) {
+          ancestry.add(ancestor);
+        }
+      }
+      return ancestry;
+    };
+    const oldAncestry = collectAncestry(oldComposite);
+    const newAncestry = collectAncestry(newComposite);
+    const depthOf = (state) => {
+      let depth = 0;
+      for (let i = 0; i < state.length; i++) {
+        if (state[i] === ".") depth++;
+      }
+      return depth;
+    };
+    const enterRaw = [];
+    for (const state of newAncestry) {
+      if (!oldAncestry.has(state)) enterRaw.push(state);
+    }
+    const exitRaw = [];
+    for (const state of oldAncestry) {
+      if (!newAncestry.has(state)) exitRaw.push(state);
+    }
+    const enterStates = enterRaw.map((state, index) => ({ state, index, depth: depthOf(state) })).sort((a, b) => a.depth - b.depth || a.index - b.index).map((entry) => entry.state);
+    const exitStates = exitRaw.map((state, index) => ({ state, index, depth: depthOf(state) })).sort((a, b) => b.depth - a.depth || a.index - b.index).map((entry) => entry.state);
+    return { enterStates, exitStates };
+  }
   validateCompositeState(compositeState) {
     const stateParts = compositeState.split("|");
     const regionKeys = /* @__PURE__ */ new Set();
@@ -2748,10 +2989,11 @@ var StateMachine = class _StateMachine {
     return (...args) => {
       const targetAdaptee = args.length >= 2 ? args[0] : adaptee;
       const error = args.length >= 2 ? args[1] : args[0];
-      return handler(targetAdaptee, error);
+      return handler(this.resolveCallbackOwner(targetAdaptee), error);
     };
   }
   async callAction(obj, actionName, ...args) {
+    const targetOwner = this.resolveCallbackOwner(obj);
     const _callActionState = this.getCurrentState(
       obj
     );
@@ -2766,16 +3008,16 @@ var StateMachine = class _StateMachine {
         if (this.context && this.context[actionName]) {
           const action = this.context[actionName];
           if (typeof action === "function") {
-            const result = action(this.context, ...args);
+            const result = action(targetOwner, ...args);
             return result instanceof Promise ? await result : result;
           }
         } else if (typeof actionName === "function") {
-          const result = actionName(obj, ...args);
+          const result = actionName(targetOwner, ...args);
           return result instanceof Promise ? await result : result;
         } else if (obj.get(actionName)) {
           const action = obj.get(actionName);
           if (typeof action === "function") {
-            const result = action(obj, ...args);
+            const result = action(targetOwner, ...args);
             return result instanceof Promise ? await result : result;
           }
         }
@@ -2791,19 +3033,22 @@ var StateMachine = class _StateMachine {
       }
     };
     if (this.transitionTimeout && this.transitionTimeout > 0) {
-      return Promise.race([
-        executeAction(),
-        new Promise(
-          (_, reject) => setTimeout(
-            () => reject(new StateMachineError("Transition timeout", {
-              /* c8 ignore next */
-              action: typeof actionName === "string" ? actionName : "anonymous",
-              phase: "action"
-            })),
-            this.transitionTimeout
-          )
-        )
-      ]);
+      const timeoutMs = this.transitionTimeout;
+      let timeoutHandle;
+      const timeoutPromise = new Promise((_, reject) => {
+        const fire = () => reject(new StateMachineError("Transition timeout", {
+          /* c8 ignore next */
+          action: typeof actionName === "string" ? actionName : "anonymous",
+          phase: "action"
+        }));
+        timeoutHandle = this.setTimer(fire, timeoutMs);
+      });
+      if (this.schedulerProvided) {
+        return Promise.race([executeAction(), timeoutPromise]).finally(() => {
+          this.clearTimer(timeoutHandle);
+        });
+      }
+      return Promise.race([executeAction(), timeoutPromise]);
     }
     return executeAction();
   }
@@ -2847,8 +3092,12 @@ var StateMachine = class _StateMachine {
       if (fromState === "*") return true;
       const regionKey = this.getRegionKey(fromState);
       const currentStateForRegion = currentStates.get(regionKey);
-      if (!currentStateForRegion) return false;
-      return currentStateForRegion === fromState || this.isParentState(currentStateForRegion, fromState);
+      if (currentStateForRegion && (currentStateForRegion === fromState || this.isParentState(currentStateForRegion, fromState))) {
+        return true;
+      }
+      return Array.from(currentStates.values()).some(
+        (leaf) => leaf === fromState || this.isParentState(fromState, leaf)
+      );
     });
   }
   isParentState(parentState, childState) {
@@ -2864,6 +3113,26 @@ var StateMachine = class _StateMachine {
     const targetState = transition.to === "*" ? currentState : transition.to;
     this._isTransitioning = true;
     this._targetState = targetState;
+    let newState;
+    let enterStates;
+    let exitStates;
+    try {
+      newState = this.updateState(currentState, targetState);
+      const sets = this.computeEnterExitSets(currentState, newState);
+      enterStates = sets.enterStates;
+      exitStates = sets.exitStates;
+    } catch (error) {
+      this.logger.warn("Transition aborted: invalid target configuration", {
+        state: currentState,
+        target: String(targetState),
+        error
+      });
+      this._isTransitioning = false;
+      this._targetState = void 0;
+      return void 0;
+    }
+    const exitFireOrder = exitStates.length > 0 ? exitStates : [transition.from];
+    const enterFireOrder = enterStates.length > 0 ? enterStates : [transition.to];
     try {
       if (transition.guard) {
         const allow = await this.callAction(obj, transition.guard, ...args).catch(
@@ -2889,7 +3158,9 @@ var StateMachine = class _StateMachine {
         );
       }
       try {
-        await this.executeExitActions(obj, transition.from, args, context);
+        for (const exitStateName of exitFireOrder) {
+          await this.executeExitActions(obj, exitStateName, args, context);
+        }
       } catch (error) {
         if (this.abortOnExitError) {
           this.logger.warn("Transition aborted due to onExit error", { state: currentState, error });
@@ -2909,12 +3180,14 @@ var StateMachine = class _StateMachine {
         );
       }
       try {
-        await this.executeEnterActions(obj, transition.to, args, context);
+        for (const enterStateName of enterFireOrder) {
+          await this.executeEnterActions(obj, enterStateName, args, context);
+        }
       } catch (error) {
         if (this.errorState) {
           this.logger.error(`Failed to enter state '${targetState}'. Fallback to error state '${this.errorState}'`, { error });
-          const newState2 = this.updateState(currentState, this.errorState);
-          this.setCurrentState(newState2, obj);
+          const errorNewState = this.updateState(currentState, this.errorState);
+          this.setCurrentState(errorNewState, obj);
           return this.states.get(this.errorState);
         }
         throw error;
@@ -2929,12 +3202,12 @@ var StateMachine = class _StateMachine {
             event.onError,
             this.onError
           );
-          errorHandler(obj, error);
+          errorHandler(this.resolveCallbackOwner(obj), error);
         }
       }
       const transitionStartTime = Date.now();
-      const newState = this.updateState(currentState, targetState);
       this.setCurrentState(newState, obj);
+      this.checkCompletion(obj, currentState, newState);
       const transitionTime = Date.now() - transitionStartTime;
       this.monitor.recordTransition(transitionTime, true);
       return this.states.get(targetState);
@@ -2992,7 +3265,7 @@ var StateMachine = class _StateMachine {
     }
     if (toState.invoke && toState.invoke.length > 0) {
       if (!this.stateEntryTimes.has(toStateName)) {
-        this.stateEntryTimes.set(toStateName, Date.now());
+        this.stateEntryTimes.set(toStateName, this.clock());
       }
       const timers = [];
       for (const invocation of toState.invoke) {
@@ -3038,6 +3311,9 @@ var StateMachine = class _StateMachine {
    */
   setTimer(callback, delay) {
     const scheduler = this.scheduler;
+    if (this.schedulerProvided) {
+      return scheduler.schedule(delay, callback);
+    }
     if (scheduler.isActive()) {
       return scheduler.schedule(delay, callback);
     }
@@ -3048,6 +3324,10 @@ var StateMachine = class _StateMachine {
    */
   clearTimer(timerId) {
     const scheduler = this.scheduler;
+    if (this.schedulerProvided) {
+      if (timerId !== void 0) scheduler.cancel(timerId);
+      return;
+    }
     if (scheduler.isActive() && typeof timerId === "object" && timerId !== null && !("ref" in timerId)) {
       scheduler.cancel(timerId);
     } else {
@@ -3110,7 +3390,7 @@ var StateMachine = class _StateMachine {
   updateState(currentState, toState) {
     const currentStateMap = this.parseCompositeState(currentState);
     const toStateParts = toState.split("|");
-    if (toStateParts.length === 1 && !toState.includes(".")) {
+    if (toStateParts.length === 1 && !toState.includes(".") && !this.states.get(toState)?.regions) {
       currentStateMap.clear();
       currentStateMap.set(toState, toState);
       return toState;
@@ -3205,13 +3485,13 @@ var StateMachine = class _StateMachine {
         this.stateEntryTimes.delete(stateName);
       }
     }
-    const now = Date.now();
+    const now = this.clock();
     for (const stateName of activeStates) {
       const state = this.states.get(stateName);
       if (!state || !state.invoke || state.invoke.length === 0) continue;
       const entryTime = this.stateEntryTimes.get(stateName);
-      const startTime = entryTime || now;
-      if (!entryTime) {
+      const startTime = entryTime ?? now;
+      if (entryTime === void 0) {
         this.stateEntryTimes.set(stateName, startTime);
       }
       const elapsed = now - startTime;
@@ -3492,6 +3772,7 @@ var ConfigValidator = class {
       this.validateInitialState(smConfig);
       this.validateCrossReferences(smConfig);
       this.validatePerformanceConstraints(smConfig);
+      this.validateFinalStates(smConfig);
       this.runCustomRules(smConfig);
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -3853,6 +4134,10 @@ var ConfigValidator = class {
         }
       }
     }
+    const finalStatePaths = this.collectFinalStatePaths(smConfig.states);
+    for (const finalPath of finalStatePaths) {
+      reachableStates.add(finalPath);
+    }
     for (const stateName of allStateNames) {
       if (!reachableStates.has(stateName)) {
         this.addWarning(
@@ -3863,8 +4148,9 @@ var ConfigValidator = class {
       }
     }
     for (const [eventName, event] of Object.entries(smConfig.events)) {
+      const isDoneStateEvent = eventName.startsWith("done.state.");
       const hasValidTransitions = event.transitions.some(
-        (t) => allStateNames.has(t.from) && allStateNames.has(t.to)
+        (t) => (allStateNames.has(t.from) || isDoneStateEvent && allStateNames.has(eventName.slice("done.state.".length))) && allStateNames.has(t.to)
       );
       if (!hasValidTransitions) {
         this.addWarning(
@@ -3892,6 +4178,168 @@ var ConfigValidator = class {
       }
     }
   }
+  /**
+   * Collects every state in the tree as {dottedPath, config} entries, walking
+   * region containers (region names are NOT registered states, so they are part
+   * of the path but never emitted as an entry — mirroring runtime expansion).
+   */
+  collectStateEntries(states, prefix, collector) {
+    for (const [stateName, state] of Object.entries(states)) {
+      const fullName = prefix ? `${prefix}.${stateName}` : stateName;
+      collector.push({ path: fullName, state });
+      if (state.regions) {
+        for (const [regionName, regionStates] of Object.entries(
+          state.regions
+        )) {
+          this.collectStateEntries(
+            regionStates,
+            `${fullName}.${regionName}`,
+            collector
+          );
+        }
+      }
+    }
+  }
+  /**
+   * True when `composite` has at least one `final:true` atomic substate reachable
+   * through its (possibly nested) region tree — i.e. some region of the composite
+   * can become done. Used by REGION_NO_REACHABLE_FINAL.
+   */
+  hasReachableFinal(composite) {
+    if (!composite.regions) return false;
+    for (const regionStates of Object.values(composite.regions)) {
+      for (const state of Object.values(regionStates)) {
+        if (state.final) return true;
+        if (state.regions && this.hasReachableFinal(state)) return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * SCXML/UML final-state and all-regions-final (done.state.<C>) join validation.
+   *
+   * - FINAL_STATE_HAS_OUTGOING (error): a `final:true` state is the `from` of a
+   *   transition (a final pseudo-state cannot itself transition out).
+   * - FINAL_ON_COMPOSITE (warning): `final:true` on a state that has regions
+   *   (final is meaningful only on an atomic leaf; ignored at runtime).
+   * - REGION_NO_REACHABLE_FINAL (warning): a `done.state.<C>` transition exists
+   *   but composite C declares no `final` substate, so the join can never fire.
+   * - DONE_VS_PARALLEL_EXIT_AMBIGUITY (warning): the same composite C has BOTH a
+   *   `done.state.C` join AND a plain `from:'C'` user-event parallel-exit, which
+   *   can preempt the all-final join (the user event is eligible on ANY leaf).
+   * - REGION_MISSING_INITIAL (advisory warning, valid:true): a region omits an
+   *   explicit `initial`, so expansion relies on first-key insertion order.
+   */
+  validateFinalStates(smConfig) {
+    const entries = [];
+    this.collectStateEntries(smConfig.states, "", entries);
+    const finalStatePaths = /* @__PURE__ */ new Set();
+    for (const { path, state } of entries) {
+      if (!state.final) continue;
+      if (state.regions) {
+        this.addWarning(
+          "FINAL_ON_COMPOSITE",
+          `Final flag on composite state "${path}" is ignored; mark an atomic leaf inside a region as final instead`,
+          `states.${path}.final`,
+          void 0,
+          "Remove `final: true` from this composite and set it on the atomic leaf state that represents the region's completion."
+        );
+      } else {
+        finalStatePaths.add(path);
+      }
+    }
+    const userFromStates = /* @__PURE__ */ new Set();
+    const doneStateComposites = /* @__PURE__ */ new Set();
+    for (const [eventName, event] of Object.entries(smConfig.events)) {
+      if (!event.transitions || !Array.isArray(event.transitions)) continue;
+      if (eventName.startsWith("done.state.")) {
+        const compositeId = eventName.slice("done.state.".length);
+        if (compositeId) doneStateComposites.add(compositeId);
+      }
+      for (const transition of event.transitions) {
+        if (typeof transition.from !== "string") continue;
+        for (const fromPart of transition.from.split("|")) {
+          if (finalStatePaths.has(fromPart)) {
+            this.addError(
+              "FINAL_STATE_HAS_OUTGOING",
+              `Final state "${fromPart}" cannot be the source of transition on event "${eventName}"; a final pseudo-state has no outgoing transitions`,
+              `events.${eventName}`,
+              void 0,
+              `Remove the outgoing transition from "${fromPart}", or clear its \`final: true\` flag if it is not actually a final state.`
+            );
+          }
+          if (!eventName.startsWith("done.state.")) {
+            userFromStates.add(fromPart);
+          }
+        }
+      }
+    }
+    const entryByPath = new Map(entries.map((e) => [e.path, e.state]));
+    for (const compositeId of doneStateComposites) {
+      const composite = entryByPath.get(compositeId);
+      if (!composite) {
+        continue;
+      }
+      if (!this.hasReachableFinal(composite)) {
+        this.addWarning(
+          "REGION_NO_REACHABLE_FINAL",
+          `Join event "done.state.${compositeId}" can never fire: composite "${compositeId}" has no \`final\` substate in any region`,
+          `events.done.state.${compositeId}`,
+          void 0,
+          `Mark the completion leaf of each region under "${compositeId}" with \`final: true\`, or remove the done.state join.`
+        );
+      }
+      if (userFromStates.has(compositeId)) {
+        this.addWarning(
+          "DONE_VS_PARALLEL_EXIT_AMBIGUITY",
+          `Composite "${compositeId}" has both a done.state join and a user-event transition with from:"${compositeId}"; the user event can preempt the all-final join because it is eligible on any active leaf`,
+          `events.done.state.${compositeId}`,
+          void 0,
+          `Disambiguate by using the done.state.${compositeId} join exclusively, or scope the user-event transition to a specific leaf instead of the bare composite.`
+        );
+      }
+    }
+    for (const { path, state } of entries) {
+      if (!state.regions) continue;
+      for (const [regionName, regionStates] of Object.entries(state.regions)) {
+        const regionKeys = Object.keys(regionStates);
+        if (regionKeys.length === 0) continue;
+        const parentInitialInRegion = state.initial !== void 0 && regionKeys.includes(state.initial);
+        if (!parentInitialInRegion) {
+          this.addWarning(
+            "REGION_MISSING_INITIAL",
+            `Region "${regionName}" of composite "${path}" has no explicit initial; expansion falls back to the first key "${regionKeys[0]}" (insertion-order dependent)`,
+            `states.${path}.regions.${regionName}`,
+            void 0,
+            `Set \`initial\` on composite "${path}" to a leaf of region "${regionName}", to make the starting substate explicit and order-independent.`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Collects the dotted paths of every `final:true` atomic leaf in the tree.
+   */
+  collectFinalStatePaths(states, prefix = "", collector = /* @__PURE__ */ new Set()) {
+    for (const [stateName, state] of Object.entries(states)) {
+      const fullName = prefix ? `${prefix}.${stateName}` : stateName;
+      if (state.final && !state.regions) {
+        collector.add(fullName);
+      }
+      if (state.regions) {
+        for (const [regionName, regionStates] of Object.entries(
+          state.regions
+        )) {
+          this.collectFinalStatePaths(
+            regionStates,
+            `${fullName}.${regionName}`,
+            collector
+          );
+        }
+      }
+    }
+    return collector;
+  }
   validatePerformanceConstraints(smConfig) {
     const stateCount = this.countStates(smConfig.states);
     const eventCount = Object.keys(smConfig.events).length;
@@ -3980,6 +4428,7 @@ function isValidConfig(config) {
   StateMachineError,
   createEnhancedError,
   createMachine,
+  createVirtualScheduler,
   isAdapter,
   isRecoverableError,
   isValidConfig,