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

package/README.md

@@ -28,13 +28,48 @@ const sm = createMachine({
 })
 ```
 
+## Hierarchical regions, parallel states & join
+
+A state may declare `regions` to run several orthogonal sub-machines at once. Entry/exit follow SCXML/UML ordering, and a region may complete via a `final` state that raises a `done.state.<id>` join event.
+
+```ts
+const sm = createMachine({
+  name: 'proc',
+  initialState: 'proc',
+  states: {
+    proc: {
+      initial: 'a.run|b.run',          // both regions active in parallel
+      onEnter: () => {/* parent runs BEFORE region children (ancestor-first) */},
+      regions: {
+        a: { run: {}, done: { final: true } },
+        b: { run: {}, done: { final: true } },
+      },
+    },
+    complete: {},
+  },
+  events: {
+    finishA: { transitions: [{ from: 'proc.a.run', to: 'proc.a.done' }] },
+    finishB: { transitions: [{ from: 'proc.b.run', to: 'proc.b.done' }] },
+    // Join: raised automatically once EVERY region reached a `final` state.
+    'done.state.proc': { transitions: [{ from: 'proc', to: 'complete' }] },
+  },
+})
+```
+
+- **Expansion** — entering `proc` (as initial state *or* via a transition) expands to the parallel configuration `proc.a.run|proc.b.run`.
+- **Ordering** — entry is ancestor-first (`proc` then region children); exit is descendant-first (region children then `proc`).
+- **Parallel-exit** — a plain transition `from: 'proc'` on a user event preempts and exits all active regions immediately (LCCA).
+- **Join** — when all regions are `final`, the engine raises `done.state.proc`; `sm.isDone('proc')` reflects the all-final configuration. (`done.state.*` is never matched by a `from: '*'` wildcard.)
+
+See [`docs/regions-and-parallel.md`](./docs/regions-and-parallel.md) for the full model, ordering rules, and validation.
+
 ## Documentation
 
 Full API documentation: [https://vedmalex.github.io/statemachine/](https://vedmalex.github.io/statemachine/)
 
 ## Extension Points
 
-This package exposes 7 extension points (`IMonitor`, `ITimerScheduler`, `IErrorHandler`, `Adapter<T>`, `ILogger`, `StatePersistenceAdapter`, `validateConfig`) for host integration. See [`docs/extension-points.md`](./docs/extension-points.md) for the full catalog.
+This package exposes 7 extension points (`IMonitor`, `ITimerScheduler`, `IErrorHandler`, `Adapter<T>`, `ILogger`, `StatePersistenceAdapter`, `validateConfig`) for host integration. Callbacks resolved from config or `setContext()` receive the underlying owner object directly, so host code does not need to unwrap `Adapter<T>` inside each callback. See [`docs/extension-points.md`](./docs/extension-points.md) for the full catalog.
 
 ## Stability policy
 

package/dist/index.cjs

@@ -1850,6 +1850,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);
@@ -1958,7 +1961,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(
@@ -2163,6 +2167,10 @@ 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]);
   }
@@ -2541,7 +2549,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 +2625,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 +2645,11 @@ var StateMachine = class _StateMachine {
         );
       });
     }
+    this.checkCompletion(
+      targetAdaptee,
+      "",
+      initialStates
+    );
   }
   getInitialCompositeState(initialState) {
     const stateConfig = this.states.get(initialState);
@@ -2675,6 +2689,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 +2967,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 +2986,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;
           }
         }
@@ -2847,8 +3067,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 +3088,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 +3133,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 +3155,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 +3177,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);
@@ -3110,7 +3358,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;
@@ -3492,6 +3740,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 +4102,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 +4116,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 +4146,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;