iobroker.statechart 0.2.0 → 0.3.0

package/build/lib/chart-runtime.js

@@ -43,19 +43,22 @@ var import_chart_structure = require("./chart-structure");
 var import_chart_validation = require("./chart-validation");
 const SCRIPT_TIMEOUT_MS = 1e3;
 const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+const DAY_MS = 24 * 60 * 60 * 1e3;
+const MAX_ADVANCE_TIMERS = 1e4;
 const PERSISTED_VERSION = 1;
 function getChartHash(chart) {
   const logic = {
     initial: chart.initial,
     symbols: chart.symbols,
-    // comments and notes are only documentation
-    states: chart.states.map(({ x: _x, y: _y, width: _w, height: _h, comment: _c, ...state }) => state),
+    // comments, notes and colors are only documentation
+    states: chart.states.map(({ x: _x, y: _y, width: _w, height: _h, comment: _c, color: _co, ...state }) => state),
     transitions: chart.transitions.map(
       ({
         sourceHandle: _s,
         targetHandle: _t,
         sourceAnchor: _sa,
         targetAnchor: _ta,
+        labelOffset: _lo,
         comment: _c,
         ...transition
       }) => transition
@@ -64,14 +67,25 @@ function getChartHash(chart) {
   };
   return import_node_crypto.default.createHash("sha1").update(JSON.stringify(logic)).digest("hex");
 }
+function toSnapshot(state) {
+  return state ? { val: state.val, ack: !!state.ack, ts: state.ts, lc: state.lc } : null;
+}
 class ChartRuntime {
-  constructor(chartId, chart, host) {
+  /**
+   * @param chartId ID of the chart object
+   * @param chart The chart
+   * @param host The connection to the outside world
+   * @param simulated Simulation: the inputs are only changed by simulateInput(), outputs, setState() etc. are not
+   * written but recorded in the history, nothing is persisted
+   */
+  constructor(chartId, chart, host, simulated = false) {
     this.chartId = chartId;
     this.chart = chart;
     this.host = host;
+    this.simulated = simulated;
     this.structure = new import_chart_structure.ChartStructure(chart);
     this.statesById = this.structure.statesById;
-    this.sandbox = import_node_vm.default.createContext(this.createHelpers());
+    this.sandbox = import_node_vm.default.createContext({ ...this.createHelpers(), ...import_chart_model.TIME_UNITS });
     this.hash = getChartHash(chart);
     this.prepareAllCode();
   }
@@ -93,10 +107,26 @@ class ChartRuntime {
   activeIds = [];
   /** time each active state was entered */
   enteredAt = /* @__PURE__ */ new Map();
+  /** how often each state was entered, to notice that a parallel state was left and entered again */
+  entryCount = /* @__PURE__ */ new Map();
   /** timers of the temporal transitions by state */
   timers = /* @__PURE__ */ new Map();
-  /** temporal transitions whose time has come */
+  /** after(n, unit) transitions whose time has come */
   expired = /* @__PURE__ */ new Set();
+  /** at() and every() transitions whose timer caused the current wakeup */
+  firedTimers = /* @__PURE__ */ new Set();
+  /** wakeups by each input since each active state was entered, by state */
+  inputCounts = /* @__PURE__ */ new Map();
+  /** since when the condition of each after(n, unit, condition) of the active states is true, by transition */
+  trueSince = /* @__PURE__ */ new Map();
+  /** timers of after(n, unit, condition), by transition */
+  durationTimers = /* @__PURE__ */ new Map();
+  /** for duration(): since when the value of each call is true, by call and state */
+  durationCalls = /* @__PURE__ */ new Map();
+  /** number of duration() calls found in the code, to give each of them an ID */
+  durationCallCount = 0;
+  /** the state whose condition or action is executed, used by elapsed() and duration() */
+  context = null;
   /** timers of inputs with debounce, by variable name */
   debounceTimers = /* @__PURE__ */ new Map();
   /** JSON of the last persisted data, to persist only changes */
@@ -115,14 +145,36 @@ class ChartRuntime {
   preparedCode = /* @__PURE__ */ new Map();
   /** the variables used by hasChanged() etc. */
   changeVariables = /* @__PURE__ */ new Set();
+  /** the IDs of the states read by getState(), they are read at the start and then kept up to date */
+  readStateIds = /* @__PURE__ */ new Set();
+  /** the states read by getState(), null if a state does not exist */
+  stateCache = /* @__PURE__ */ new Map();
   /** their values at the start of the previous wakeup, null before the second wakeup */
   previousValues = null;
   /** their values at the start of the current wakeup, null before the first one */
   currentValues = null;
   hash;
   actor = null;
-  /** the current time, can be replaced in tests */
-  now = () => Date.now();
+  /** true while a wakeup is processed, effects outside of wakeups are published right away */
+  wakingUp = false;
+  /** all running timers, to fire them early when the time of a simulation is advanced */
+  scheduled = /* @__PURE__ */ new Set();
+  /** simulation: added to the real time, see advanceTime() */
+  timeOffset = 0;
+  /** simulation: paused, the wakeups wait in the queue */
+  paused = false;
+  /** simulation: the wakeups which wait while paused */
+  queue = [];
+  /** simulation: IDs of the states and transitions with a breakpoint */
+  breakpoints = /* @__PURE__ */ new Set();
+  /** simulation: set when a breakpoint is reached during a wakeup, it pauses after the step */
+  pendingBreak = null;
+  /** simulation: where it stopped at a breakpoint, until it continues */
+  breakpointHit = null;
+  /** JSON of the last status passed to host.onSimulationStatus() */
+  lastStatus = "";
+  /** the current time, can be replaced in tests. A simulation can be ahead of the real time. */
+  now = () => Date.now() + this.timeOffset;
   /**
    * Prepares all code of the chart for the change detection, so its variables are known from the first wakeup on
    */
@@ -135,6 +187,7 @@ class ChartRuntime {
     for (const transition of this.chart.transitions) {
       try {
         const label = (0, import_chart_model.parseTransitionLabel)(transition.label);
+        this.prepareCode(label.temporal?.condition, "expression");
         this.prepareCode(label.condition, "expression");
         this.prepareCode(label.action, "statements");
       } catch {
@@ -147,7 +200,8 @@ class ChartRuntime {
   /**
    * @param code A condition, action or function block
    * @param kind Expression or statements
-   * @returns the code with the names of the variables in hasChanged() etc., see quoteChangeArguments()
+   * @returns the code with the names of the variables in hasChanged() etc. and the IDs of the duration() calls,
+   * see prepareHelperCalls()
    */
   prepareCode(code, kind) {
     if (!code) {
@@ -156,11 +210,14 @@ class ChartRuntime {
     const key = `${kind}:${code}`;
     let prepared = this.preparedCode.get(key);
     if (prepared === void 0) {
-      const quoted = (0, import_chart_validation.quoteChangeArguments)(code, kind);
+      const quoted = (0, import_chart_validation.prepareHelperCalls)(code, kind, () => `d${++this.durationCallCount}`);
       prepared = quoted.code;
       for (const name of quoted.names) {
         this.changeVariables.add(name);
       }
+      for (const id of quoted.stateIds) {
+        this.readStateIds.add(id);
+      }
       this.preparedCode.set(key, prepared);
     }
     return prepared;
@@ -171,12 +228,34 @@ class ChartRuntime {
   get inputStateIds() {
     return this.chart.symbols.filter((s) => s.scope === "input" && s.stateId).map((s) => s.stateId);
   }
+  /**
+   * IDs of all states whose changes must be passed to handleStateChange(): the inputs and the states read by
+   * getState()
+   */
+  get subscribedStateIds() {
+    return [.../* @__PURE__ */ new Set([...this.simulated ? [] : this.inputStateIds, ...this.readStateIds])];
+  }
   /**
    * @param options Start options
    * @param options.restore Continue with the persisted state, if the chart was not changed since
    */
   async start(options = {}) {
     this.logProblems();
+    for (const id of this.readStateIds) {
+      try {
+        let state;
+        if (this.host.getState) {
+          state = await this.host.getState(id);
+        } else {
+          const val = await this.host.readState(id);
+          state = val === void 0 ? null : { val, ack: true, ts: this.now(), lc: this.now() };
+        }
+        this.stateCache.set(id, toSnapshot(state));
+      } catch (err) {
+        this.host.log.warn(`[${this.chart.name}] Cannot read ${id}: ${err.message}`);
+        this.stateCache.set(id, null);
+      }
+    }
     for (const symbol of this.chart.symbols) {
       if (symbol.scope === "local") {
         this.sandbox[symbol.name] = structuredClone(symbol.initial);
@@ -193,6 +272,7 @@ class ChartRuntime {
       this.run(this.compile(this.prepareCode(fn.code, "statements"), where), where);
     }
     this.writeChangedOutputs();
+    this.wakingUp = true;
     const machine = (0, import_xstate.createMachine)(this.buildMachineConfig());
     const persisted = options.restore && this.chart.restoreState !== false ? await this.loadPersisted() : null;
     let restored = false;
@@ -209,7 +289,8 @@ class ChartRuntime {
     } else {
       this.startActor(machine);
     }
-    this.pendingHistory.push({ ts: this.now(), kind: "start", restored, active: this.activeNames });
+    this.pendingHistory.unshift({ ts: this.now(), kind: "start", restored, active: this.activeNames });
+    this.wakingUp = false;
     this.wakeup(null, "start");
   }
   /**
@@ -243,9 +324,19 @@ class ChartRuntime {
     this.publishActiveStates(this.actor.getSnapshot().value);
     for (const id of this.activeIds) {
       this.enteredAt.set(id, persisted.entered[id] ?? this.now());
+      this.inputCounts.set(id, new Map(Object.entries(persisted.counts?.[id] ?? {})));
+      for (const transition of this.temporalTransitions.get(id) || []) {
+        const since = persisted.trueSince?.[transition.id];
+        if (since !== void 0) {
+          this.trueSince.set(transition.id, since);
+        }
+      }
       this.startTimers(id);
     }
   }
+  /**
+   * Publishes the active states after each transition, and logs errors of the state machine
+   */
   subscribe() {
     this.actor?.subscribe({
       next: (snapshot) => this.publishActiveStates(snapshot.value),
@@ -270,13 +361,19 @@ class ChartRuntime {
       this.host.log.info(`[${this.chart.name}] The chart was changed, starting in the initial state`);
       return null;
     }
-    return { ...persisted, entered: persisted.entered || {}, locals: persisted.locals || {} };
+    return {
+      ...persisted,
+      entered: persisted.entered || {},
+      locals: persisted.locals || {},
+      counts: persisted.counts || {},
+      trueSince: persisted.trueSince || {}
+    };
   }
   /**
    * Stores the current state of the chart, if it changed since the last time
    */
   persist() {
-    if (!this.actor || !this.host.persist) {
+    if (!this.actor || !this.host.persist || this.simulated) {
       return;
     }
     const data = {
@@ -286,7 +383,11 @@ class ChartRuntime {
       entered: Object.fromEntries(this.enteredAt),
       locals: Object.fromEntries(
         this.chart.symbols.filter((s) => s.scope === "local").map((s) => [s.name, this.sandbox[s.name]])
-      )
+      ),
+      counts: Object.fromEntries(
+        [...this.inputCounts].filter(([, counts]) => counts.size).map(([id, counts]) => [id, Object.fromEntries(counts)])
+      ),
+      trueSince: Object.fromEntries(this.trueSince)
     };
     let json;
     try {
@@ -306,7 +407,12 @@ class ChartRuntime {
    * @param id ID of the state
    */
   onEnter(id) {
+    if (this.simulated && this.breakpoints.has(id)) {
+      this.pendingBreak ??= this.statesById.get(id)?.name ?? id;
+    }
     this.enteredAt.set(id, this.now());
+    this.entryCount.set(id, (this.entryCount.get(id) ?? 0) + 1);
+    this.inputCounts.set(id, /* @__PURE__ */ new Map());
     this.startTimers(id);
   }
   /**
@@ -317,13 +423,109 @@ class ChartRuntime {
   onExit(id) {
     this.enteredAt.delete(id);
     for (const timer of this.timers.get(id) || []) {
-      clearTimeout(timer.handle);
+      this.cancelTimer(timer);
     }
     this.timers.delete(id);
+    this.inputCounts.delete(id);
     for (const transition of this.temporalTransitions.get(id) || []) {
       this.expired.delete(transition.id);
+      this.stopDuration(transition.id);
+    }
+    for (const [key, call] of this.durationCalls) {
+      if (call.state === id) {
+        this.durationCalls.delete(key);
+      }
+    }
+  }
+  /**
+   * Stops measuring how long the condition of an after(n, unit, condition) is true
+   *
+   * @param id ID of the transition
+   */
+  stopDuration(id) {
+    this.trueSince.delete(id);
+    this.cancelTimer(this.durationTimers.get(id));
+    this.durationTimers.delete(id);
+  }
+  /**
+   * Starts a timer with the functions of the host, so the adapter can clear it when it is unloaded
+   *
+   * @param callback Called when the time has come
+   * @param ms The delay
+   * @returns the handle to stop it
+   */
+  startTimeout(callback, ms) {
+    return this.host.setTimeout ? this.host.setTimeout(callback, ms) : globalThis.setTimeout(callback, ms);
+  }
+  /**
+   * @param handle The handle of a timer started by startTimeout(), may be undefined
+   */
+  stopTimeout(handle) {
+    if (handle === void 0) {
+      return;
+    }
+    if (this.host.clearTimeout) {
+      this.host.clearTimeout(handle);
+    } else {
+      globalThis.clearTimeout(handle);
+    }
+  }
+  /**
+   * @param timer The timer to stop, may be undefined
+   */
+  cancelTimer(timer) {
+    if (timer) {
+      this.stopTimeout(timer.handle);
+      this.scheduled.delete(timer);
     }
   }
+  /**
+   * Wakes up the chart for a timer. A paused simulation queues the wakeup.
+   *
+   * @param fired ID of the at() or every() transition whose timer fired, they are only valid in this wakeup
+   */
+  timerWakeup(fired) {
+    if (this.simulated && this.paused) {
+      this.queue.push({ kind: "timer", fired });
+      this.publishLive();
+      return;
+    }
+    if (fired) {
+      this.firedTimers.add(fired);
+    }
+    try {
+      this.wakeup(null);
+    } finally {
+      if (fired) {
+        this.firedTimers.delete(fired);
+      }
+    }
+  }
+  /**
+   * Calls the callback at the given time, also after delays which are too long for setTimeout()
+   *
+   * @param due The time (ms since 1970), the callback is called right away if it has passed
+   * @param timer Gets the handle of the timeout, to clear it
+   * @param callback Called at the time
+   */
+  scheduleAt(due, timer, callback) {
+    this.stopTimeout(timer.handle);
+    timer.due = due;
+    timer.callback = callback;
+    this.scheduled.add(timer);
+    const remaining = due - this.now();
+    timer.handle = this.startTimeout(
+      () => {
+        if (remaining > MAX_TIMEOUT_MS && due - this.now() > 0) {
+          this.scheduleAt(due, timer, callback);
+        } else {
+          this.scheduled.delete(timer);
+          callback();
+        }
+      },
+      Math.min(Math.max(remaining, 0), MAX_TIMEOUT_MS)
+    );
+  }
   /**
    * Starts a timer for every temporal transition of a state, which wakes up the chart when its time has come
    *
@@ -332,27 +534,95 @@ class ChartRuntime {
   startTimers(id) {
     const entered = this.enteredAt.get(id) ?? this.now();
     const timers = [];
+    this.timers.set(id, timers);
     for (const transition of this.temporalTransitions.get(id) || []) {
-      const timer = {};
-      const due = entered + transition.afterMs;
-      const wait = () => {
-        const remaining = due - this.now();
-        timer.handle = setTimeout(
-          () => {
-            if (due - this.now() > 0 && remaining > MAX_TIMEOUT_MS) {
-              wait();
-              return;
-            }
-            this.expired.add(transition.id);
-            this.wakeup(null);
-          },
-          Math.min(Math.max(remaining, 0), MAX_TIMEOUT_MS)
-        );
-      };
-      wait();
+      const { operator, ms, condition, time } = transition.temporal;
+      if (time !== void 0) {
+        const timer2 = { label: transition.where };
+        timers.push(timer2);
+        this.scheduleDaily(id, transition, timer2, this.now());
+        continue;
+      }
+      if (ms === void 0 || operator === "before" || condition !== void 0) {
+        continue;
+      }
+      const timer = { label: transition.where };
       timers.push(timer);
+      const fire = (due2) => {
+        if (operator === "after") {
+          this.expired.add(transition.id);
+          this.timerWakeup(null);
+          return;
+        }
+        this.timerWakeup(transition.id);
+        if (operator === "every" && this.timers.get(id)?.includes(timer)) {
+          this.scheduleAt(due2 + ms, timer, () => fire(due2 + ms));
+        }
+      };
+      let due = entered + ms;
+      if (operator === "every" && due < this.now()) {
+        due = entered + Math.ceil((this.now() - entered) / ms) * ms;
+      }
+      this.scheduleAt(due, timer, () => fire(due));
     }
-    this.timers.set(id, timers);
+  }
+  /**
+   * Starts the timer of at("sunset", offset) or at("22:30") for the next time, which wakes up the chart
+   *
+   * @param stateId ID of the source state
+   * @param transition The transition
+   * @param timer Gets the handle of the timeout
+   * @param after The timer is started for the next time after this one (ms since 1970)
+   */
+  scheduleDaily(stateId, transition, timer, after) {
+    let due;
+    try {
+      due = this.getNextDailyTime(transition.temporal, after);
+    } catch (err) {
+      this.host.log.warn(`[${this.chart.name}] ${transition.where}: ${err.message}`);
+      return;
+    }
+    if (due === null) {
+      this.scheduleAt(
+        after + DAY_MS,
+        timer,
+        () => this.scheduleDaily(stateId, transition, timer, after + DAY_MS)
+      );
+      return;
+    }
+    this.scheduleAt(due, timer, () => {
+      this.timerWakeup(transition.id);
+      if (this.timers.get(stateId)?.includes(timer)) {
+        this.scheduleDaily(stateId, transition, timer, Math.max(due, this.now()));
+      }
+    });
+  }
+  /**
+   * @param temporal at("sunset", offset) or at("22:30")
+   * @param after The time is searched after this one (ms since 1970)
+   * @returns the next time (ms since 1970), null if there is none in the next week (astro events in polar regions)
+   * @throws {Error} for astro events if no location is configured
+   */
+  getNextDailyTime(temporal, after) {
+    const time = temporal.time;
+    const offset = (temporal.offsetMinutes ?? 0) * 6e4;
+    const day = new Date(after);
+    day.setDate(day.getDate() - 1);
+    for (let i = 0; i < 9; i++) {
+      let at;
+      if (import_chart_model.TIME_OF_DAY.test(time)) {
+        const [hours, minutes, seconds = 0] = time.split(":").map(Number);
+        at = new Date(day).setHours(hours, minutes, seconds, 0);
+      } else {
+        const event = this.getSunTimes(new Date(new Date(day).setHours(12, 0, 0, 0)))[time];
+        at = event instanceof Date ? event.getTime() : null;
+      }
+      if (at !== null && at + offset > after) {
+        return at + offset;
+      }
+      day.setDate(day.getDate() + 1);
+    }
+    return null;
   }
   /**
    * Logs the problems found by the validation, the chart is started anyway
@@ -361,7 +631,9 @@ class ChartRuntime {
     for (const { kind, id, field, diagnostic } of (0, import_chart_validation.validateChart)(this.chart)) {
       let where;
       if (kind === "state") {
-        where = `${this.statesById.get(id)?.name ?? id}/${field}`;
+        where = `${this.statesById.get(id)?.name ?? id}${field ? `/${field}` : ""}`;
+      } else if (kind === "symbol") {
+        where = `Variable ${id}`;
       } else if (kind === "function") {
         const fn = this.chart.functions?.find((f) => f.id === id);
         where = `Function block ${(0, import_chart_validation.getDeclarations)(fn?.code).map((d) => d.name).join(", ")}`;
@@ -371,27 +643,27 @@ class ChartRuntime {
         const target = this.statesById.get(transition?.target ?? "")?.name;
         where = `Transition ${source} -> ${target}`;
       }
-      const log = diagnostic.severity === "error" ? this.host.log.error : this.host.log.warn;
+      const log = { error: this.host.log.error, warning: this.host.log.warn, info: this.host.log.debug }[diagnostic.severity];
       log(`[${this.chart.name}] ${where}: ${diagnostic.message}`);
     }
   }
+  /**
+   * Stops the state machine and all timers, delayed writes are discarded
+   */
   stop() {
     this.actor?.stop();
     this.actor = null;
-    for (const timers of this.timers.values()) {
-      for (const timer of timers) {
-        clearTimeout(timer.handle);
-      }
+    for (const timer of this.scheduled) {
+      this.stopTimeout(timer.handle);
     }
+    this.scheduled.clear();
     this.timers.clear();
     this.expired.clear();
+    this.durationTimers.clear();
     for (const timer of this.debounceTimers.values()) {
-      clearTimeout(timer);
+      this.stopTimeout(timer);
     }
     this.debounceTimers.clear();
-    for (const timer of this.delayedWrites) {
-      clearTimeout(timer);
-    }
     this.delayedWrites.clear();
   }
   /**
@@ -400,25 +672,36 @@ class ChartRuntime {
   createHelpers() {
     const prefix = `[${this.chart.name}]`;
     const write = (id, value, ack) => this.host.writeState(String(id), value, !!ack).catch((err) => this.host.log.warn(`${prefix} Cannot write ${id}: ${err}`));
+    const describe = (name, args) => `${name}(${args.map((arg) => arg === void 0 ? "undefined" : JSON.stringify(arg)).join(", ")})`;
     return {
       log: (message, level = "info") => {
         const method = ["debug", "info", "warn", "error"].includes(level) ? level : "info";
         this.host.log[method](`${prefix} ${message}`);
       },
       setState: (id, value, ack = false) => {
+        if (this.simulated) {
+          this.recordEffect(describe("setState", [id, value, ...ack ? [true] : []]));
+          return;
+        }
         void write(id, value, ack);
       },
       setStateDelayed: (id, value, delayMs, ack = false) => {
-        const timer = setTimeout(
-          () => {
-            this.delayedWrites.delete(timer);
-            void write(id, value, ack);
-          },
-          Math.min(Math.max(Number(delayMs) || 0, 0), MAX_TIMEOUT_MS)
-        );
+        const timer = { label: describe("setStateDelayed", [id, value]) };
         this.delayedWrites.add(timer);
+        this.scheduleAt(this.now() + Math.max(Number(delayMs) || 0, 0), timer, () => {
+          this.delayedWrites.delete(timer);
+          if (this.simulated) {
+            this.recordEffect(describe("setState", [id, value, ...ack ? [true] : []]));
+            return;
+          }
+          void write(id, value, ack);
+        });
       },
       sendTo: (instance, command, message) => {
+        if (this.simulated) {
+          this.recordEffect(describe("sendTo", [instance, command, message]));
+          return;
+        }
         if (!this.host.sendTo) {
           throw new Error("sendTo() is not available");
         }
@@ -444,6 +727,33 @@ class ChartRuntime {
         }
         return new Date(time.getTime() + (Number(offsetMinutes) || 0) * 6e4);
       },
+      getState: (id) => {
+        if (!this.stateCache.has(id)) {
+          throw new Error(
+            `getState() can only read states whose ID is written as text, e.g. getState("${id}")`
+          );
+        }
+        const state = this.stateCache.get(id);
+        return state ? { ...state } : null;
+      },
+      elapsed: (unit = import_chart_model.TIME_UNITS.sec) => {
+        const entered = this.context === null ? void 0 : this.enteredAt.get(this.context);
+        if (entered === void 0) {
+          throw new Error("elapsed() can only be used in conditions and in the actions of states");
+        }
+        return (this.now() - entered) / unit;
+      },
+      // the ID of the call is added by prepareHelperCalls()
+      duration: (call, value, unit = import_chart_model.TIME_UNITS.sec) => {
+        const key = `${call}@${this.context}`;
+        if (!value) {
+          this.durationCalls.delete(key);
+          return 0;
+        }
+        const since = this.durationCalls.get(key)?.since ?? this.now();
+        this.durationCalls.set(key, { since, state: this.context });
+        return (this.now() - since) / unit;
+      },
       hasChanged: (name) => this.getChange(name, "hasChanged").changed,
       hasChangedFrom: (name, value) => {
         const { changed, previous } = this.getChange(name, "hasChangedFrom");
@@ -467,6 +777,163 @@ class ChartRuntime {
     }
     return import_suncalc.default.getTimes(date, location.latitude, location.longitude);
   }
+  /**
+   * Must be called when one of the subscribedStateIds is updated
+   *
+   * @param stateId ID of the updated state
+   * @param state The new state
+   */
+  handleStateChange(stateId, state) {
+    if (this.readStateIds.has(stateId)) {
+      this.stateCache.set(stateId, toSnapshot(state));
+    }
+    if (!this.simulated) {
+      this.handleInput(stateId, state.val, { ack: state.ack });
+    }
+  }
+  /**
+   * Simulation: sets the value of an input and wakes up the chart, like a change of the input
+   *
+   * @param name Name of the input
+   * @param val The new value
+   * @returns false if the chart has no input with this name
+   */
+  simulateInput(name, val) {
+    const symbol = this.chart.symbols.find((s) => s.scope === "input" && s.name === name);
+    if (!symbol || !this.actor) {
+      return false;
+    }
+    if (this.paused) {
+      this.queue.push({ kind: "input", name, value: val });
+      this.publishLive();
+      return true;
+    }
+    this.applyInput(symbol, val);
+    return true;
+  }
+  /**
+   * Simulation: pauses, the following wakeups wait in a queue
+   */
+  pauseSimulation() {
+    this.paused = true;
+    this.publishLive();
+  }
+  /**
+   * Simulation: processes the queued wakeups until a breakpoint is reached, then continues normally
+   */
+  resumeSimulation() {
+    this.paused = false;
+    this.breakpointHit = null;
+    while (!this.paused && this.queue.length) {
+      this.processQueued(this.queue.shift());
+    }
+    this.publishLive();
+  }
+  /**
+   * Simulation: processes the next queued wakeup, and stays paused
+   *
+   * @returns false if no wakeup was queued
+   */
+  stepSimulation() {
+    const next = this.queue.shift();
+    if (!next) {
+      return false;
+    }
+    this.breakpointHit = null;
+    this.paused = false;
+    try {
+      this.processQueued(next);
+    } finally {
+      this.paused = true;
+    }
+    this.publishLive();
+    return true;
+  }
+  /**
+   * @param wakeup A wakeup which waited while the simulation was paused
+   */
+  processQueued(wakeup) {
+    if (wakeup.kind === "input") {
+      const symbol = this.chart.symbols.find((s) => s.scope === "input" && s.name === wakeup.name);
+      if (symbol) {
+        this.applyInput(symbol, wakeup.value);
+      }
+    } else if (wakeup.kind === "event") {
+      this.wakeup(wakeup.name);
+    } else if (wakeup.kind === "timer") {
+      this.timerWakeup(wakeup.fired);
+    } else {
+      this.wakeup(null);
+    }
+  }
+  /**
+   * Simulation: lets time pass. The timers which are due meanwhile fire in the order of their time, a paused
+   * simulation queues their wakeups.
+   *
+   * @param ms The time to advance
+   */
+  advanceTime(ms) {
+    const target = this.now() + Math.max(0, ms);
+    for (let fired = 0; ; fired++) {
+      let next;
+      for (const timer of this.scheduled) {
+        if (timer.due <= target && (!next || timer.due < next.due)) {
+          next = timer;
+        }
+      }
+      if (!next) {
+        break;
+      }
+      if (fired >= MAX_ADVANCE_TIMERS) {
+        this.host.log.warn(`[${this.chart.name}] Stopped advancing the time after ${fired} timers`);
+        return;
+      }
+      this.timeOffset += Math.max(0, next.due - this.now());
+      this.cancelTimer(next);
+      next.callback();
+    }
+    this.timeOffset += Math.max(0, target - this.now());
+    for (const timer of [...this.scheduled]) {
+      this.scheduleAt(timer.due, timer, timer.callback);
+    }
+    this.publishLive();
+  }
+  /**
+   * Simulation: advances the time to the next timer, see advanceTime()
+   *
+   * @returns false if there is no timer
+   */
+  advanceToNextTimer() {
+    const next = this.getNextTimer();
+    if (!next) {
+      return false;
+    }
+    this.advanceTime(next.due - this.now());
+    return true;
+  }
+  /**
+   * @returns the timer which fires next, null if there is none
+   */
+  getNextTimer() {
+    let next;
+    for (const timer of this.scheduled) {
+      if (!next || timer.due < next.due) {
+        next = timer;
+      }
+    }
+    return next ? { due: next.due, label: next.label ?? "" } : null;
+  }
+  /**
+   * Simulation: records something which was not executed, shown in the history
+   *
+   * @param text What was not executed
+   */
+  recordEffect(text) {
+    this.pendingHistory.push({ ts: this.now(), kind: "effect", text, active: this.activeNames });
+    if (!this.wakingUp) {
+      this.publishLive();
+    }
+  }
   /**
    * Must be called when an input state is updated
    *
@@ -488,10 +955,10 @@ class ChartRuntime {
       }
       const debounceMs = symbol.debounceMs || 0;
       if (debounceMs > 0) {
-        clearTimeout(this.debounceTimers.get(symbol.name));
+        this.stopTimeout(this.debounceTimers.get(symbol.name));
         this.debounceTimers.set(
           symbol.name,
-          setTimeout(() => {
+          this.startTimeout(() => {
             this.debounceTimers.delete(symbol.name);
             this.applyInput(symbol, val);
           }, debounceMs)
@@ -501,6 +968,25 @@ class ChartRuntime {
       }
     }
   }
+  /**
+   * Wakes up the chart with the event of an input, without changing the value of the input
+   * (state charts.<chart>.event)
+   *
+   * @param name Name of the input
+   * @returns false if the chart has no input with this name
+   */
+  handleEvent(name) {
+    if (!this.chart.symbols.some((s) => s.scope === "input" && s.name === name)) {
+      return false;
+    }
+    if (this.simulated && this.paused) {
+      this.queue.push({ kind: "event", name });
+      this.publishLive();
+    } else {
+      this.wakeup(name);
+    }
+    return true;
+  }
   /**
    * Sets the variable of an input and wakes up the chart
    *
@@ -524,7 +1010,40 @@ class ChartRuntime {
     }
     this.wakeupCause = cause;
     this.wakeupInput = input;
+    this.wakingUp = true;
+    try {
+      this.processWakeup(input);
+      this.writeChangedOutputs();
+    } finally {
+      this.wakingUp = false;
+    }
+    if (this.pendingBreak) {
+      this.paused = true;
+      this.breakpointHit = this.pendingBreak;
+      this.pendingHistory.push({
+        ts: this.now(),
+        kind: "break",
+        text: this.pendingBreak,
+        active: this.activeNames
+      });
+      this.pendingBreak = null;
+    }
+    this.persist();
+    this.publishLive();
+  }
+  /**
+   * @param input Name of the input which caused the wakeup, null for timers and the start
+   */
+  processWakeup(input) {
     this.rememberValues();
+    if (input !== null) {
+      for (const [id, counts] of this.inputCounts) {
+        if (this.temporalTransitions.get(id)?.some((t) => t.temporal?.event === input)) {
+          counts.set(input, (counts.get(input) ?? 0) + 1);
+        }
+      }
+    }
+    this.updateDurations();
     if (!this.chart.superStep) {
       this.step(input);
     } else {
@@ -533,6 +1052,10 @@ class ChartRuntime {
       while (steps < import_chart_model.MAX_SUPER_STEPS && this.step(stepInput)) {
         steps++;
         stepInput = null;
+        if (this.pendingBreak) {
+          this.queue.unshift({ kind: "continue" });
+          break;
+        }
       }
       if (steps >= import_chart_model.MAX_SUPER_STEPS) {
         this.host.log.warn(
@@ -540,9 +1063,35 @@ class ChartRuntime {
         );
       }
     }
-    this.writeChangedOutputs();
-    this.persist();
-    this.publishLive();
+    this.updateDurations();
+  }
+  /**
+   * Checks the conditions of after(n, unit, condition) of the active states, and starts a timer which wakes up the
+   * chart when a condition has been true for the time
+   */
+  updateDurations() {
+    for (const id of this.activeIds) {
+      for (const transition of this.temporalTransitions.get(id) || []) {
+        const temporal = transition.temporal;
+        if (temporal.condition === void 0) {
+          continue;
+        }
+        if (!this.run(transition.temporalCondition, `${transition.where}/after condition`, id)) {
+          this.stopDuration(transition.id);
+          continue;
+        }
+        const since = this.trueSince.get(transition.id) ?? this.now();
+        this.trueSince.set(transition.id, since);
+        if (!this.durationTimers.has(transition.id)) {
+          const timer = { label: transition.where };
+          this.durationTimers.set(transition.id, timer);
+          this.scheduleAt(since + temporal.ms, timer, () => {
+            this.durationTimers.delete(transition.id);
+            this.timerWakeup(null);
+          });
+        }
+      }
+    }
   }
   /**
    * Stores the values of the variables used by the change detection at the start of a wakeup
@@ -588,22 +1137,31 @@ class ChartRuntime {
    * @returns true if a transition was taken
    */
   step(input) {
-    for (const id of this.getActiveChildren(null)) {
-      if (this.processState(id, input)) {
-        return true;
-      }
-    }
-    return false;
+    return this.processChildren(null, input);
   }
   /**
    * Passes the events since the last call and the changed values of the variables to the host
    */
   publishLive() {
     if (this.pendingHistory.length) {
-      const entries = this.pendingHistory;
+      const entries = this.simulated ? this.pendingHistory.map((entry) => ({ ...entry, simulated: true })) : this.pendingHistory;
       this.pendingHistory = [];
       this.host.onHistory?.(entries);
     }
+    if (this.simulated && this.host.onSimulationStatus) {
+      const status = {
+        paused: this.paused,
+        timeOffset: this.timeOffset,
+        queued: this.queue.length,
+        nextTimer: this.getNextTimer(),
+        breakpoint: this.breakpointHit
+      };
+      const json2 = JSON.stringify(status);
+      if (json2 !== this.lastStatus) {
+        this.lastStatus = json2;
+        this.host.onSimulationStatus(status);
+      }
+    }
     if (!this.host.onValues) {
       return;
     }
@@ -639,17 +1197,40 @@ class ChartRuntime {
     }
     const state = this.statesById.get(id);
     if (state?.during) {
-      this.runAction(state.during, `${state.name}/during`);
+      this.runAction(state.during, `${state.name}/during`, id);
     }
     if (this.takeFirstValid(this.innerTransitions.get(id), input)) {
       return true;
     }
-    for (const child of this.getActiveChildren(id)) {
-      if (this.processState(child, input)) {
-        return true;
+    return this.processChildren(id, input);
+  }
+  /**
+   * Processes the active child of a state, or all children of a parallel state, see the class description
+   *
+   * @param parent ID of the state, null for the top level
+   * @param input Name of the input which caused the wakeup, null for timers
+   * @returns true if a transition was taken
+   */
+  processChildren(parent, input) {
+    if (!this.structure.isParallel(parent)) {
+      for (const child of this.getActiveChildren(parent)) {
+        if (this.processState(child, input)) {
+          return true;
+        }
       }
+      return false;
     }
-    return false;
+    const entries = parent && this.entryCount.get(parent);
+    let taken = false;
+    for (const child of this.structure.getChildren(parent)) {
+      if (parent && (!this.activeIds.includes(parent) || this.entryCount.get(parent) !== entries)) {
+        break;
+      }
+      if (this.activeIds.includes(child.id) && this.processState(child.id, input)) {
+        taken = true;
+      }
+    }
+    return taken;
   }
   /**
    * @param parent null for the top level
@@ -667,17 +1248,18 @@ class ChartRuntime {
    */
   takeFirstValid(transitions, input) {
     for (const transition of transitions || []) {
-      if (transition.event && transition.event !== input) {
+      if (!this.isTriggered(transition, input)) {
         continue;
       }
-      if (transition.afterMs !== void 0 && !this.isExpired(transition)) {
+      if (transition.condition && !this.run(transition.condition, `${transition.where}/condition`, transition.source)) {
         continue;
       }
-      if (transition.condition && !this.run(transition.condition, `${transition.where}/condition`)) {
-        continue;
+      const at = this.pendingHistory.length;
+      if (this.simulated && this.breakpoints.has(transition.id)) {
+        this.pendingBreak ??= `${transition.from} \u2192 ${transition.to}`;
       }
       this.actor?.send({ type: `T.${transition.id}` });
-      this.pendingHistory.push({
+      this.pendingHistory.splice(at, 0, {
         ts: this.now(),
         kind: "transition",
         transition: transition.id,
@@ -693,16 +1275,54 @@ class ChartRuntime {
     return false;
   }
   /**
-   * @param transition A temporal transition
-   * @returns true if its source state is active for at least its delay
+   * @param transition The transition
+   * @param input Name of the input which caused the wakeup, null for timers
+   * @returns true if its event and its temporal expression allow it in this wakeup (the condition is not checked)
    */
-  isExpired(transition) {
-    if (this.expired.has(transition.id)) {
+  isTriggered(transition, input) {
+    if (transition.event && transition.event !== input) {
+      return false;
+    }
+    const temporal = transition.temporal;
+    if (!temporal) {
       return true;
     }
+    if (temporal.event !== void 0) {
+      if (temporal.event !== input) {
+        return false;
+      }
+      const count = this.inputCounts.get(transition.source)?.get(temporal.event) ?? 0;
+      const n = temporal.count;
+      switch (temporal.operator) {
+        case "after":
+          return count >= n;
+        case "before":
+          return count < n;
+        case "at":
+          return count === n;
+        case "every":
+          return count % n === 0;
+      }
+    }
+    const ms = temporal.ms;
+    if (temporal.condition !== void 0) {
+      const since = this.trueSince.get(transition.id);
+      return since !== void 0 && this.now() - since >= ms;
+    }
     const entered = this.enteredAt.get(transition.source);
-    return entered !== void 0 && this.now() - entered >= transition.afterMs;
+    switch (temporal.operator) {
+      case "after":
+        return this.expired.has(transition.id) || entered !== void 0 && this.now() - entered >= ms;
+      case "before":
+        return entered !== void 0 && this.now() - entered < ms;
+      default:
+        return this.firedTimers.has(transition.id);
+    }
   }
+  /**
+   * @returns the configuration of the XState machine: the states with their entry and exit actions, the
+   *   transitions as guarded events
+   */
   buildMachineConfig() {
     const structure = this.structure;
     const buildState = (state) => {
@@ -710,10 +1330,10 @@ class ChartRuntime {
         id: state.id,
         entry: [
           () => this.onEnter(state.id),
-          ...state.entry ? [() => this.runAction(state.entry, `${state.name}/entry`)] : []
+          ...state.entry ? [() => this.runAction(state.entry, `${state.name}/entry`, state.id)] : []
         ],
         exit: [
-          ...state.exit ? [() => this.runAction(state.exit, `${state.name}/exit`)] : [],
+          ...state.exit ? [() => this.runAction(state.exit, `${state.name}/exit`, state.id)] : [],
           () => this.onExit(state.id)
         ],
         on: {}
@@ -732,12 +1352,19 @@ class ChartRuntime {
       this.innerTransitions.set(state.id, inner);
       this.temporalTransitions.set(
         state.id,
-        [...outer, ...inner].filter((t) => t.afterMs !== void 0)
+        [...outer, ...inner].filter((t) => t.temporal !== void 0)
       );
       const subStates = structure.getChildren(state.id);
       if (subStates.length) {
-        node.initial = structure.getInitialChild(state.id);
+        if (structure.isParallel(state.id)) {
+          node.type = "parallel";
+        } else {
+          node.initial = structure.getInitialChild(state.id);
+        }
         node.states = Object.fromEntries(subStates.map((s) => [s.id, buildState(s)]));
+        if (structure.hasHistory(state.id)) {
+          node.states[import_chart_structure.HISTORY_SUFFIX] = { id: `${state.id}${import_chart_structure.HISTORY_SUFFIX}`, type: "history" };
+        }
       }
       return node;
     };
@@ -747,7 +1374,7 @@ class ChartRuntime {
     }
     return {
       id: `chart_${this.chartId}`,
-      initial: structure.getInitialChild(null),
+      ...structure.isParallel(null) ? { type: "parallel" } : { initial: structure.getInitialChild(null) },
       states: Object.fromEntries(topLevel.map((s) => [s.id, buildState(s)]))
     };
   }
@@ -762,6 +1389,9 @@ class ChartRuntime {
       this.host.log.warn(`[${this.chart.name}] Transition ${where}: unknown target, ignored`);
       return null;
     }
+    if (this.structure.getCrossedParallel(transition) !== void 0) {
+      return null;
+    }
     let label;
     try {
       label = (0, import_chart_model.parseTransitionLabel)(transition.label);
@@ -770,11 +1400,12 @@ class ChartRuntime {
       return null;
     }
     const condition = label.condition ? this.compile(`(${this.prepareCode(label.condition, "expression")})`, `${where}/condition`) : null;
+    const temporalCondition = label.temporal?.condition ? this.compile(`(${this.prepareCode(label.temporal.condition, "expression")})`, `${where}/after condition`) : null;
     const { inner, reenter } = this.structure.getTransitionKind(transition);
     const config = {
-      target: `#${target.id}`,
+      target: `#${this.structure.getTargetId(transition)}`,
       reenter,
-      actions: label.action ? [() => this.runAction(label.action, `${where}/action`)] : []
+      actions: label.action ? [() => this.runAction(label.action, `${where}/action`, source.id)] : []
     };
     return {
       inner,
@@ -786,7 +1417,8 @@ class ChartRuntime {
         from: source.name,
         to: target.name,
         event: label.event,
-        afterMs: label.afterMs,
+        temporal: label.temporal,
+        temporalCondition,
         condition
       }
     };
@@ -806,16 +1438,21 @@ class ChartRuntime {
   /**
    * @param script The compiled code
    * @param where Used in error messages
+   * @param context The state whose condition or action it is, for elapsed() and duration()
    */
-  run(script, where) {
+  run(script, where, context = this.context) {
     if (!script) {
       return void 0;
     }
+    const previous = this.context;
+    this.context = context;
     try {
       return script.runInContext(this.sandbox, { timeout: SCRIPT_TIMEOUT_MS });
     } catch (err) {
       this.host.log.warn(`[${this.chart.name}] ${where}: ${err.message}`);
       return void 0;
+    } finally {
+      this.context = previous;
     }
   }
   /**
@@ -823,13 +1460,17 @@ class ChartRuntime {
    *
    * @param code The action
    * @param where Used in error messages
+   * @param context The state whose action it is (the source state for transition actions)
    */
-  runAction(code, where) {
+  runAction(code, where, context) {
     this.run(this.compile(`{
 ${this.prepareCode(code, "statements")}
-}`, where), where);
+}`, where), where, context);
     this.writeChangedOutputs();
   }
+  /**
+   * Writes the outputs whose values were changed by actions to their states, in a simulation only records them
+   */
   writeChangedOutputs() {
     for (const symbol of this.chart.symbols) {
       if (symbol.scope !== "output" || !symbol.stateId) {
@@ -838,6 +1479,10 @@ ${this.prepareCode(code, "statements")}
       const val = this.sandbox[symbol.name];
       if (val !== this.outputValues.get(symbol.name)) {
         this.outputValues.set(symbol.name, val);
+        if (this.simulated) {
+          this.recordEffect(`${symbol.name} = ${val === void 0 ? "undefined" : JSON.stringify(val)}`);
+          continue;
+        }
         this.host.writeState(symbol.stateId, val).catch((err) => this.host.log.warn(`[${this.chart.name}] Cannot write ${symbol.stateId}: ${err}`));
       }
     }