@defold-typescript/transpiler 0.43.0 → 0.44.0

package/dist/hsm/index.ts

@@ -2,65 +2,139 @@ export interface EventObject {
   readonly type: string;
 }
 
+export type MoveCause = "event" | "after" | "update" | "stop" | "reload" | "always";
+
+/** @noSelf */
+export type MoveListener<E extends EventObject, P extends string = string> = (
+  from: P,
+  to: P | undefined,
+  cause: MoveCause,
+  event: E | undefined,
+) => void;
+
 /** @noSelf */
 export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
   readonly ctx: Ctx;
   readonly path: P | undefined;
+  readonly leaves: readonly P[];
   readonly matches: (path: P) => boolean;
   readonly send: (event: E) => void;
   readonly update: (dt: number) => void;
   readonly stop: () => void;
+  /**
+   * Adds a listener called after each move completes, with the leaf left, the leaf entered and
+   * the cause. It is not called for the first entry at `start` or for a move with no `to`; a
+   * parallel machine calls it once per moved region. Each call adds a listener, and the returned
+   * function removes that one.
+   */
+  readonly onMove: (listener: MoveListener<E, P>) => () => void;
 }
 
-export type TransitionAction<Ctx, E extends EventObject, V extends E = E> = (
+export type MoveAction<Ctx, E extends EventObject, V extends E = E> = (
   ctx: Ctx,
   event: V,
-  m: MachineInstance<Ctx, E>,
+  machine: MachineInstance<Ctx, E>,
 ) => void;
 
 /** @noSelf */
 export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E> {
-  readonly target?: string;
-  readonly guard?: (ctx: Ctx, event: V) => boolean;
-  readonly actions?: TransitionAction<Ctx, E, V> | readonly TransitionAction<Ctx, E, V>[];
-  readonly reenter?: boolean;
+  /**
+   * The full path of the state to move to. A `to` naming the state the rule is on exits and
+   * re-enters it, restarting its timers and `task`; a `to` below it keeps it active.
+   */
+  readonly to?: string;
+  /**
+   * The rule is taken only when this returns `true`. It must have no side effects: it is also
+   * checked when the move does not happen, in guarded lists and on every `always` recheck.
+   */
+  readonly when?: (ctx: Ctx, event: V) => boolean;
+  /**
+   * Runs during the move. The event is accepted when its key matches and `when` passes; then
+   * `exit` runs on each state left, deepest first; then `run`; then `enter` on each state
+   * entered, outermost first. Shared ancestors neither exit nor enter. A rule with no `to` runs
+   * only `run`.
+   */
+  readonly run?: MoveAction<Ctx, E, V> | readonly MoveAction<Ctx, E, V>[];
+  /** Renamed to `to`. */
+  readonly target?: never;
+  /** Renamed to `when`. */
+  readonly guard?: never;
+  /** Renamed to `run`. */
+  readonly actions?: never;
+  /** Removed: a `to` naming the state the rule is on restarts it. */
+  readonly reenter?: never;
 }
 
 export type TransitionSpec<Ctx, E extends EventObject, V extends E = E> =
   | string
   | TransitionConfig<Ctx, E, V>
-  // Lua cannot tell [] from {}, so an empty list would compile to a targetless transition.
+  // Lua cannot tell [] from {}, so an empty list would compile to a transition with no to.
   | readonly [TransitionConfig<Ctx, E, V>, ...TransitionConfig<Ctx, E, V>[]];
 
+/** @noSelf */
+export interface AlwaysConfig<Ctx> {
+  readonly to: string;
+  /** Checked on every recheck, so it must have no side effects. */
+  readonly when?: (ctx: Ctx) => boolean;
+  /** Renamed to `to`. */
+  readonly target?: never;
+  /** Renamed to `when`. */
+  readonly guard?: never;
+}
+
+export type AlwaysSpec<Ctx> =
+  | string
+  | AlwaysConfig<Ctx>
+  | readonly [AlwaysConfig<Ctx>, ...AlwaysConfig<Ctx>[]];
+
 export type OnConfig<Ctx, E extends EventObject> = {
   readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, { type: K }>>;
 };
 
-export type StateHook<Ctx, E extends EventObject> = (ctx: Ctx, m: MachineInstance<Ctx, E>) => void;
+/**
+ * Runs on every way in (`enter`) or out (`exit`) of the state: a move, `start` and `stop`. A hot
+ * reload enters the states it adds, but drops a removed state without its `exit`. It gets no
+ * event; event data reaches `enter` through `ctx`, set in `run`.
+ */
+export type StateHook<Ctx, E extends EventObject> = (
+  ctx: Ctx,
+  machine: MachineInstance<Ctx, E>,
+) => void;
 
 export type UpdateHook<Ctx, E extends EventObject> = (
   ctx: Ctx,
   dt: number,
-  m: MachineInstance<Ctx, E>,
+  machine: MachineInstance<Ctx, E>,
 ) => string | undefined;
 
-/** @noSelf */
-export type InvokeStart<Ctx, E extends EventObject> = (
+/**
+ * Starts work that lives as long as the state. `finish` sends one event and is ignored after the
+ * first call or once the state is left. The returned cleanup runs on every way out.
+ * @noSelf
+ */
+export type TaskStart<Ctx, E extends EventObject> = (
   ctx: Ctx,
-  settle: (event: E) => void,
-  m: MachineInstance<Ctx, E>,
-) => void;
+  finish: (event: E) => void,
+  machine: MachineInstance<Ctx, E>,
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` keeps an expression-body task returning a void call (`=> go.animate(...)`) valid.
+) => (() => void) | void;
 
 /** @noSelf */
 export interface StateConfig<Ctx, E extends EventObject> {
+  readonly type?: "parallel";
   readonly initial?: string;
+  readonly restoreDepth?: number | "all";
   readonly states?: { readonly [name: string]: StateConfig<Ctx, E> };
   readonly on?: OnConfig<Ctx, E>;
   readonly after?: { readonly [seconds: number]: string };
+  readonly always?: AlwaysSpec<Ctx>;
   readonly enter?: StateHook<Ctx, E>;
   readonly exit?: StateHook<Ctx, E>;
   readonly update?: UpdateHook<Ctx, E>;
-  readonly invoke?: InvokeStart<Ctx, E>;
+  /** Started on each entry; see `TaskStart`. */
+  readonly task?: TaskStart<Ctx, E>;
+  /** Renamed to `task`. */
+  readonly invoke?: never;
 }
 
 export interface MachineConfig<Ctx, E extends EventObject> extends StateConfig<Ctx, E> {
@@ -89,11 +163,34 @@ type PathsBelow<S, D extends number> = S extends { readonly states: infer Childr
 
 export type StatePath<C> = `/${PathsBelow<C, 4>}`;
 
+type NextCount = [never, 2, 3, 4, 5, 6];
+
+type RestoreCountBelow<Children, D extends number> = {
+  [K in keyof Children]: RestoreCount<Children[K], D>;
+}[keyof Children];
+
+// The counts a state's subtree can hold: a compound state is one level plus its deepest child,
+// a parallel state adds no level of its own, and a leaf holds none.
+type RestoreCount<S, D extends number> = S extends { readonly states: infer Children }
+  ? [D] extends [never]
+    ? number
+    : S extends { readonly type: "parallel" }
+      ? RestoreCountBelow<Children, PathDepth[D]>
+      :
+          | 1
+          | (RestoreCountBelow<Children, PathDepth[D]> extends infer N
+              ? N extends number
+                ? number extends N
+                  ? number
+                  : NextCount[N]
+                : never
+              : never)
+  : never;
+
 interface TransitionCheck<T> {
-  readonly target?: T;
-  readonly guard?: unknown;
-  readonly actions?: unknown;
-  readonly reenter?: unknown;
+  readonly to?: T;
+  readonly when?: unknown;
+  readonly run?: unknown;
 }
 
 type SpecCheck<T> = T | TransitionCheck<T> | readonly TransitionCheck<T>[];
@@ -101,9 +198,17 @@ type SpecCheck<T> = T | TransitionCheck<T> | readonly TransitionCheck<T>[];
 // Hooks are listed as unknown so a hooks-only leaf still shares a property with this
 // all-optional type; without them TypeScript rejects it as a weak-type mismatch.
 type PathCheck<S, Self extends string, All extends string, Ev extends string> = {
-  readonly initial?: S extends { readonly states: infer Children }
-    ? `${Self}/${keyof Children & string}`
-    : never;
+  readonly type?: unknown;
+  readonly initial?: S extends { readonly type: "parallel" }
+    ? never
+    : S extends { readonly states: infer Children }
+      ? `${Self}/${keyof Children & string}`
+      : never;
+  readonly restoreDepth?: S extends { readonly type: "parallel" }
+    ? never
+    : S extends { readonly states: object }
+      ? RestoreCount<S, 4> | "all"
+      : never;
   readonly states?: S extends { readonly states: infer Children }
     ? {
         readonly [K in keyof Children]: PathCheck<Children[K], `${Self}/${K & string}`, All, Ev>;
@@ -115,14 +220,15 @@ type PathCheck<S, Self extends string, All extends string, Ev extends string> =
   readonly after?: S extends { readonly after: infer After }
     ? { readonly [K in keyof After]: All }
     : unknown;
+  readonly always?: S extends { readonly always: unknown } ? SpecCheck<All> : unknown;
   readonly enter?: unknown;
   readonly exit?: unknown;
   readonly update?: unknown;
-  readonly invoke?: unknown;
+  readonly task?: unknown;
 };
 
 export interface MachineConfigError {
-  readonly "hsm: an initial or target names an unknown state path, or an on key an unknown event": never;
+  readonly "hsm: an initial or a to names an unknown state path, or an on key an unknown event": never;
 }
 
 export type DefinedMachine<Ctx, E extends EventObject, C> =
@@ -134,28 +240,33 @@ type Guard<Ctx, E extends EventObject> = (ctx: Ctx, event: E) => boolean;
 
 interface Transition<Ctx, E extends EventObject> {
   readonly target: number;
-  readonly guard: Guard<Ctx, E> | undefined;
-  readonly actions: readonly TransitionAction<Ctx, E>[];
-  readonly reenter: boolean;
+  readonly when: Guard<Ctx, E> | undefined;
+  readonly run: readonly MoveAction<Ctx, E>[];
 }
 
 interface Compiled<Ctx, E extends EventObject> {
   count: number;
-  maxDepth: number;
   readonly configs: StateConfig<Ctx, E>[];
   readonly paths: string[];
   readonly parent: number[];
   readonly depth: number[];
+  readonly children: number[][];
+  readonly parallel: boolean[];
   readonly initialChild: number[];
+  readonly restoreDepth: number[];
+  readonly levels: number[];
+  readonly records: boolean[];
   readonly onIndex: { [type: string]: number }[];
   readonly transitions: Transition<Ctx, E>[][];
   readonly afterDelays: number[][];
   readonly afterTargets: number[][];
+  readonly always: Transition<Ctx, E>[][];
   readonly pathIndex: { [path: string]: number };
 }
 
 const ROOT = 0;
 const NO_STATE = -1;
+const ALWAYS_LIMIT = 10;
 
 function describePath(path: string): string {
   return path === "" ? "(root)" : path;
@@ -185,6 +296,46 @@ function resolveTarget<Ctx, E extends EventObject>(
   return index;
 }
 
+// A structural cast keeps each read a plain method call: native in JavaScript, string.byte in Lua.
+interface StringUnits {
+  charCodeAt(index: number): number;
+  byte(index: number): number;
+}
+
+// JavaScript strings hold UTF-16 code units; Lua strings hold UTF-8 bytes.
+const UTF16_UNITS = "\u{E000}".length === 1;
+
+function unitAt(text: string, index: number): number {
+  const units = text as unknown as StringUnits;
+  if (UTF16_UNITS) {
+    return units.charCodeAt(index);
+  }
+  return units.byte(index + 1);
+}
+
+// Moves surrogates above the rest of the BMP, so UTF-16 units compare in code-point order.
+// UTF-8 bytes already do, and every byte is below the surrogate range.
+function codePointRank(unit: number): number {
+  if (unit >= 0xd800 && unit < 0xe000) {
+    return unit + 0x2000;
+  }
+  if (unit >= 0xe000) {
+    return unit - 0x800;
+  }
+  return unit;
+}
+
+function precedes(left: string, right: string): boolean {
+  for (let i = 0; i < left.length && i < right.length; i++) {
+    const leftUnit = unitAt(left, i);
+    const rightUnit = unitAt(right, i);
+    if (leftUnit !== rightUnit) {
+      return codePointRank(leftUnit) < codePointRank(rightUnit);
+    }
+  }
+  return left.length < right.length;
+}
+
 function registerState<Ctx, E extends EventObject>(
   compiled: Compiled<Ctx, E>,
   config: StateConfig<Ctx, E>,
@@ -193,26 +344,51 @@ function registerState<Ctx, E extends EventObject>(
 ): void {
   const index = compiled.count;
   compiled.count = index + 1;
-  const depth = parentIndex === NO_STATE ? 0 : (compiled.depth[parentIndex] as number) + 1;
-  if (depth > compiled.maxDepth) {
-    compiled.maxDepth = depth;
-  }
   compiled.configs[index] = config;
   compiled.paths[index] = path;
   compiled.parent[index] = parentIndex;
-  compiled.depth[index] = depth;
+  compiled.depth[index] =
+    parentIndex === NO_STATE ? 0 : (compiled.depth[parentIndex] as number) + 1;
+  compiled.children[index] = [];
+  compiled.parallel[index] = config.type === "parallel";
   compiled.initialChild[index] = NO_STATE;
+  compiled.restoreDepth[index] = 0;
+  compiled.levels[index] = 0;
+  compiled.records[index] = false;
   compiled.pathIndex[path] = index;
   const children = config.states;
   if (children === undefined) {
     return;
   }
+  let deepest = 0;
   for (const name in children) {
     if (name === "" || name.indexOf("/") !== -1) {
       throw `hsm: state "${describePath(path)}" has a child named "${name}"; state names must be non-empty and contain no "/"`;
     }
-    registerState(compiled, children[name] as StateConfig<Ctx, E>, index, `${path}/${name}`);
+    const child = compiled.count;
+    const childPath = `${path}/${name}`;
+    registerState(compiled, children[name] as StateConfig<Ctx, E>, index, childPath);
+    // Region order is child-name order by code point, the same in both runtimes: neither Lua's
+    // pairs nor JavaScript keeps the written order.
+    const siblings = compiled.children[index] as number[];
+    let slot = siblings.length;
+    while (
+      slot > 0 &&
+      precedes(childPath, compiled.paths[siblings[slot - 1] as number] as string)
+    ) {
+      siblings[slot] = siblings[slot - 1] as number;
+      slot--;
+    }
+    siblings[slot] = child;
+    const childLevels = compiled.levels[child] as number;
+    if (childLevels > deepest) {
+      deepest = childLevels;
+    }
   }
+  if (compiled.parallel[index] !== true) {
+    deepest++;
+  }
+  compiled.levels[index] = deepest;
 }
 
 function hasChildren<Ctx, E extends EventObject>(config: StateConfig<Ctx, E>): boolean {
@@ -233,12 +409,31 @@ function compileInitial<Ctx, E extends EventObject>(
   const config = compiled.configs[index] as StateConfig<Ctx, E>;
   const path = compiled.paths[index] as string;
   const initial = config.initial;
+  if (compiled.parallel[index] === true) {
+    if (index === ROOT) {
+      throw `hsm: state "${describePath(path)}" is parallel; put the regions in a child state`;
+    }
+    if (initial !== undefined) {
+      throw `hsm: parallel state "${path}" has initial "${initial}"; every child is entered`;
+    }
+    if (config.restoreDepth !== undefined) {
+      throw `hsm: parallel state "${path}" has restoreDepth; only a compound state resumes a child`;
+    }
+    if (!hasChildren(config)) {
+      throw `hsm: parallel state "${path}" has no child states`;
+    }
+    return;
+  }
   if (!hasChildren(config)) {
     if (initial !== undefined) {
       throw `hsm: state "${describePath(path)}" has initial "${initial}" but no child states`;
     }
+    if (config.restoreDepth !== undefined) {
+      throw `hsm: state "${describePath(path)}" has restoreDepth but no child states`;
+    }
     return;
   }
+  compileRestoreDepth(compiled, index);
   if (initial === undefined) {
     throw `hsm: compound state "${describePath(path)}" has no initial`;
   }
@@ -249,6 +444,47 @@ function compileInitial<Ctx, E extends EventObject>(
   compiled.initialChild[index] = child;
 }
 
+function compileRestoreDepth<Ctx, E extends EventObject>(
+  compiled: Compiled<Ctx, E>,
+  index: number,
+): void {
+  const depth = (compiled.configs[index] as StateConfig<Ctx, E>).restoreDepth;
+  if (depth === undefined) {
+    return;
+  }
+  const path = describePath(compiled.paths[index] as string);
+  const levels = compiled.levels[index] as number;
+  if (depth === "all") {
+    compiled.restoreDepth[index] = levels;
+    return;
+  }
+  if (typeof depth !== "number" || Math.floor(depth) !== depth || depth < 1) {
+    throw `hsm: state "${path}" has restoreDepth ${depth}; use a whole number from 1, or "all"`;
+  }
+  if (depth > levels) {
+    throw `hsm: state "${path}" has restoreDepth ${depth}, but only ${levels} ${levels === 1 ? "level" : "levels"} of child states below it`;
+  }
+  compiled.restoreDepth[index] = depth;
+}
+
+// A state records its last child only while some restoreDepth above or on it reaches its level.
+function compileRecords<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>): void {
+  const reach: number[] = [];
+  for (let index = 0; index < compiled.count; index++) {
+    const owner = compiled.parent[index] as number;
+    let inherited = 0;
+    if (owner !== NO_STATE) {
+      inherited = reach[owner] as number;
+      if (compiled.parallel[owner] !== true) {
+        inherited--;
+      }
+    }
+    const current = Math.max(compiled.restoreDepth[index] as number, inherited);
+    reach[index] = current;
+    compiled.records[index] = current > 0 && compiled.parallel[index] !== true;
+  }
+}
+
 function compileTransition<Ctx, E extends EventObject>(
   compiled: Compiled<Ctx, E>,
   source: number,
@@ -257,25 +493,23 @@ function compileTransition<Ctx, E extends EventObject>(
   if (typeof spec === "string") {
     return {
       target: resolveTarget(compiled, source, spec),
-      guard: undefined,
-      actions: [],
-      reenter: false,
+      when: undefined,
+      run: [],
     };
   }
-  const actions: TransitionAction<Ctx, E>[] = [];
-  const declared = spec.actions;
+  const run: MoveAction<Ctx, E>[] = [];
+  const declared = spec.run;
   if (typeof declared === "function") {
-    actions.push(declared);
+    run.push(declared);
   } else if (declared !== undefined) {
     for (let i = 0; i < declared.length; i++) {
-      actions.push(declared[i] as TransitionAction<Ctx, E>);
+      run.push(declared[i] as MoveAction<Ctx, E>);
     }
   }
   return {
-    target: spec.target === undefined ? NO_STATE : resolveTarget(compiled, source, spec.target),
-    guard: spec.guard,
-    actions,
-    reenter: spec.reenter === true,
+    target: spec.to === undefined ? NO_STATE : resolveTarget(compiled, source, spec.to),
+    when: spec.when,
+    run,
   };
 }
 
@@ -310,6 +544,29 @@ function compileOn<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, index
   }
 }
 
+function compileAlways<Ctx, E extends EventObject>(
+  compiled: Compiled<Ctx, E>,
+  index: number,
+): void {
+  const list: Transition<Ctx, E>[] = [];
+  compiled.always[index] = list;
+  const spec = (compiled.configs[index] as StateConfig<Ctx, E>).always;
+  if (spec === undefined) {
+    return;
+  }
+  const candidates: readonly (string | AlwaysConfig<Ctx>)[] =
+    typeof spec === "string" || (spec as readonly AlwaysConfig<Ctx>[])[0] === undefined
+      ? [spec as string | AlwaysConfig<Ctx>]
+      : (spec as readonly AlwaysConfig<Ctx>[]);
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i] as string | AlwaysConfig<Ctx>;
+    if (typeof candidate !== "string" && candidate.to === undefined) {
+      throw `hsm: state "${describePath(compiled.paths[index] as string)}" has an always transition with no "to"`;
+    }
+    list.push(compileTransition(compiled, index, candidate as string | TransitionConfig<Ctx, E>));
+  }
+}
+
 const NOT_A_DELAY = -1;
 
 // Number-literal keys arrive as numbers in Lua and as canonical number strings in JavaScript.
@@ -360,16 +617,21 @@ function compileAfter<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, in
 function compile<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>): Compiled<Ctx, E> {
   const compiled: Compiled<Ctx, E> = {
     count: 0,
-    maxDepth: 0,
     configs: [],
     paths: [],
     parent: [],
     depth: [],
+    children: [],
+    parallel: [],
     initialChild: [],
+    restoreDepth: [],
+    levels: [],
+    records: [],
     onIndex: [],
     transitions: [],
     afterDelays: [],
     afterTargets: [],
+    always: [],
     pathIndex: {},
   };
   registerState(compiled, config, NO_STATE, "");
@@ -377,7 +639,9 @@ function compile<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>): Com
     compileInitial(compiled, index);
     compileOn(compiled, index);
     compileAfter(compiled, index);
+    compileAlways(compiled, index);
   }
+  compileRecords(compiled);
   return compiled;
 }
 
@@ -398,165 +662,551 @@ function transitionDomain<Ctx, E extends EventObject>(
   compiled: Compiled<Ctx, E>,
   source: number,
   target: number,
-  reenter: boolean,
 ): number {
-  if (source === ROOT || (!reenter && isAncestorOrSelf(compiled, source, target))) {
-    return source;
+  let domain = source;
+  if (source !== ROOT && (target === source || !isAncestorOrSelf(compiled, source, target))) {
+    domain = compiled.parent[source] as number;
+    while (domain !== ROOT && (domain === target || !isAncestorOrSelf(compiled, domain, target))) {
+      domain = compiled.parent[domain] as number;
+    }
   }
-  let domain = compiled.parent[source] as number;
-  while (domain !== ROOT && (domain === target || !isAncestorOrSelf(compiled, domain, target))) {
+  // Regions enter and exit together, so a move spanning a parallel state re-enters it.
+  while (compiled.parallel[domain] === true) {
     domain = compiled.parent[domain] as number;
   }
   return domain;
 }
 
-function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>): Machine<Ctx, E> {
-  const compiled = compile(config);
-  const { paths, parent, depth, initialChild, configs, onIndex, transitions } = compiled;
-  const { afterDelays, afterTargets } = compiled;
+interface Definition<Ctx, E extends EventObject> {
+  compiled: Compiled<Ctx, E>;
+  generation: number;
+}
+
+interface Registered<Ctx, E extends EventObject> {
+  readonly definition: Definition<Ctx, E>;
+  readonly machine: Machine<Ctx, E>;
+}
 
+const registered: { [key: string]: Registered<unknown, EventObject> } = {};
+
+function createMachine<Ctx, E extends EventObject>(
+  definition: Definition<Ctx, E>,
+): Machine<Ctx, E> {
   function start(ctx: Ctx): MachineInstance<Ctx, E> {
-    const slots = compiled.maxDepth + 1;
-    const active: number[] = [];
+    let compiled = definition.compiled;
+    let generation = definition.generation;
+    let paths = compiled.paths;
+    let parent = compiled.parent;
+    let children = compiled.children;
+    let parallel = compiled.parallel;
+    let initialChild = compiled.initialChild;
+    let restoreDepth = compiled.restoreDepth;
+    let records = compiled.records;
+    let configs = compiled.configs;
+    let onIndex = compiled.onIndex;
+    let transitions = compiled.transitions;
+    let afterDelays = compiled.afterDelays;
+    let afterTargets = compiled.afterTargets;
+    let always = compiled.always;
+    const activeChild: number[] = [];
+    const isActive: boolean[] = [];
     const elapsed: number[] = [];
     const fired: number[] = [];
-    const scratch: number[] = [];
     const entryId: number[] = [];
-    for (let i = 0; i < slots; i++) {
-      active[i] = NO_STATE;
-      elapsed[i] = 0;
-      fired[i] = 0;
-      scratch[i] = NO_STATE;
-      entryId[i] = 0;
-    }
+    const cleanup: ((() => void) | undefined)[] = [];
+    // Keyed by path, not index, so a remembered child outlives a rebind's recompilation.
+    const remembered: { [parentPath: string]: string } = {};
+    let slotCount = 0;
+    growSlots();
+    const leaves: string[] = [];
     let entryCount = 0;
     const queue: (E | undefined)[] = [];
     let queueHead = 0;
     let queueTail = 0;
-    let leafDepth = NO_STATE;
     let running = true;
     let busy = false;
     let stopRequested = false;
+    let moved = false;
+    let listeners: MoveListener<E>[] = [];
 
     const instance = {
       ctx,
       path: undefined as string | undefined,
+      leaves,
       matches,
       send,
       update,
       stop,
+      onMove,
     };
 
+    function clearSlot(state: number): void {
+      activeChild[state] = NO_STATE;
+      isActive[state] = false;
+      elapsed[state] = 0;
+      fired[state] = 0;
+      entryId[state] = 0;
+      cleanup[state] = undefined;
+    }
+
+    function growSlots(): void {
+      while (slotCount < compiled.count) {
+        clearSlot(slotCount);
+        slotCount++;
+      }
+    }
+
+    function collectActive(state: number, order: number[]): void {
+      order.push(state);
+      const list = children[state] as number[];
+      for (let i = 0; i < list.length; i++) {
+        const child = list[i] as number;
+        if (isActive[child] === true) {
+          collectActive(child, order);
+        }
+      }
+    }
+
+    // Kept states hold their timers and entry id; a state whose path is gone, or whose
+    // parent was dropped, is dropped without exit hooks, since its config is gone.
+    function rebind(): void {
+      const from = instance.path as string;
+      const order: number[] = [];
+      collectActive(ROOT, order);
+      const keptPaths: string[] = [];
+      const keptElapsed: number[] = [];
+      const keptFired: number[] = [];
+      const keptEntryId: number[] = [];
+      const keptCleanup: ((() => void) | undefined)[] = [];
+      for (let i = 0; i < order.length; i++) {
+        const state = order[i] as number;
+        keptPaths[i] = paths[state] as string;
+        keptElapsed[i] = elapsed[state] as number;
+        keptFired[i] = fired[state] as number;
+        keptEntryId[i] = entryId[state] as number;
+        keptCleanup[i] = cleanup[state];
+      }
+      for (let state = 0; state < slotCount; state++) {
+        clearSlot(state);
+      }
+      compiled = definition.compiled;
+      generation = definition.generation;
+      paths = compiled.paths;
+      parent = compiled.parent;
+      children = compiled.children;
+      parallel = compiled.parallel;
+      initialChild = compiled.initialChild;
+      restoreDepth = compiled.restoreDepth;
+      records = compiled.records;
+      configs = compiled.configs;
+      onIndex = compiled.onIndex;
+      transitions = compiled.transitions;
+      afterDelays = compiled.afterDelays;
+      afterTargets = compiled.afterTargets;
+      always = compiled.always;
+      growSlots();
+      const dropped: number[] = [];
+      for (let i = 0; i < order.length; i++) {
+        const state = lookupPath(compiled, keptPaths[i] as string);
+        const owner = state === undefined ? NO_STATE : (parent[state] as number);
+        if (
+          state === undefined ||
+          (owner !== NO_STATE &&
+            (isActive[owner] !== true ||
+              (parallel[owner] !== true && activeChild[owner] !== NO_STATE)))
+        ) {
+          dropped.push(i);
+          continue;
+        }
+        isActive[state] = true;
+        if (owner !== NO_STATE && parallel[owner] !== true) {
+          activeChild[owner] = state;
+        }
+        elapsed[state] = keptElapsed[i] as number;
+        fired[state] = keptFired[i] as number;
+        entryId[state] = keptEntryId[i] as number;
+        cleanup[state] = keptCleanup[i];
+      }
+      for (let i = dropped.length - 1; i >= 0; i--) {
+        const run = keptCleanup[dropped[i] as number];
+        if (run !== undefined) {
+          run();
+        }
+      }
+      const entriesBefore = entryCount;
+      enterMissing(ROOT);
+      if (dropped.length === 0 && entryCount === entriesBefore) {
+        return;
+      }
+      refreshLeaves();
+      if (listeners.length > 0) {
+        report(from, instance.path, "reload", undefined);
+      }
+      settleAlways();
+    }
+
+    // Copy-on-write: a report walks the list it started with, so a listener removed mid-report
+    // never makes it skip another.
+    function onMove(listener: MoveListener<E>): () => void {
+      const added: MoveListener<E>[] = [];
+      for (let i = 0; i < listeners.length; i++) {
+        added.push(listeners[i] as MoveListener<E>);
+      }
+      added.push(listener);
+      listeners = added;
+      let removed = false;
+      return () => {
+        if (removed) {
+          return;
+        }
+        removed = true;
+        const kept: MoveListener<E>[] = [];
+        let skipped = false;
+        for (let i = 0; i < listeners.length; i++) {
+          const current = listeners[i] as MoveListener<E>;
+          if (current !== listener || skipped) {
+            kept.push(current);
+          } else {
+            skipped = true;
+          }
+        }
+        listeners = kept;
+      };
+    }
+
+    function report(
+      from: string,
+      to: string | undefined,
+      cause: MoveCause,
+      event: E | undefined,
+    ): void {
+      const current = listeners;
+      for (let i = 0; i < current.length; i++) {
+        (current[i] as MoveListener<E>)(from, to, cause, event);
+      }
+    }
+
+    function collectLeaves(state: number, count: number): number {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        let total = count;
+        for (let i = 0; i < list.length; i++) {
+          total = collectLeaves(list[i] as number, total);
+        }
+        return total;
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE) {
+        return collectLeaves(child, count);
+      }
+      leaves[count] = paths[state] as string;
+      return count + 1;
+    }
+
+    function refreshLeaves(): void {
+      const count = isActive[ROOT] === true ? collectLeaves(ROOT, 0) : 0;
+      while (leaves.length > count) {
+        leaves.pop();
+      }
+      instance.path = leaves[0];
+    }
+
     function enterState(state: number): void {
-      const level = depth[state] as number;
-      active[level] = state;
-      elapsed[level] = 0;
-      fired[level] = 0;
-      leafDepth = level;
+      const owner = parent[state] as number;
+      if (owner !== NO_STATE && parallel[owner] !== true) {
+        activeChild[owner] = state;
+      }
+      isActive[state] = true;
+      activeChild[state] = NO_STATE;
+      elapsed[state] = 0;
+      fired[state] = 0;
       entryCount++;
       const id = entryCount;
-      entryId[level] = id;
+      entryId[state] = id;
       const config = configs[state] as StateConfig<Ctx, E>;
       const hook = config.enter;
       if (hook !== undefined) {
         hook(ctx, instance);
       }
-      const invoke = config.invoke;
-      if (invoke !== undefined) {
-        let settled = false;
-        invoke(
+      const task = config.task;
+      if (task !== undefined) {
+        // A path, not an index, so a finish held across a rebind still finds its entry.
+        const path = paths[state] as string;
+        let finished = false;
+        const result = task(
           ctx,
           (event: E) => {
-            if (settled || !running || stopRequested || entryId[level] !== id) {
+            const current = lookupPath(compiled, path);
+            if (
+              finished ||
+              !running ||
+              stopRequested ||
+              current === undefined ||
+              entryId[current] !== id
+            ) {
               return;
             }
-            settled = true;
+            finished = true;
             send(event);
           },
           instance,
         );
+        if (typeof result === "function") {
+          cleanup[state] = result;
+        }
       }
     }
 
-    function exitTo(level: number): void {
-      while (leafDepth > level) {
-        const state = active[leafDepth] as number;
-        active[leafDepth] = NO_STATE;
-        entryId[leafDepth] = 0;
-        leafDepth--;
-        const hook = (configs[state] as StateConfig<Ctx, E>).exit;
-        if (hook !== undefined) {
-          hook(ctx, instance);
+    function exitSubtree(state: number): void {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = list.length - 1; i >= 0; i--) {
+          exitSubtree(list[i] as number);
+        }
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE) {
+        exitSubtree(child);
+      }
+      isActive[state] = false;
+      entryId[state] = 0;
+      const owner = parent[state] as number;
+      if (owner !== NO_STATE) {
+        activeChild[owner] = NO_STATE;
+        if (records[owner] === true) {
+          remembered[paths[owner] as string] = paths[state] as string;
         }
       }
+      const hook = (configs[state] as StateConfig<Ctx, E>).exit;
+      if (hook !== undefined) {
+        hook(ctx, instance);
+      }
+      const run = cleanup[state];
+      if (run !== undefined) {
+        cleanup[state] = undefined;
+        run();
+      }
     }
 
-    function enterDown(from: number, target: number): void {
-      let count = 0;
-      let state = target;
-      while (state !== from) {
-        scratch[count] = state;
-        count++;
-        state = parent[state] as number;
+    function defaultChild(state: number, restore: boolean): number {
+      if (restore) {
+        const path = remembered[paths[state] as string];
+        if (path !== undefined) {
+          const child = lookupPath(compiled, path);
+          if (child !== undefined && parent[child] === state) {
+            return child;
+          }
+        }
+      }
+      return initialChild[state] as number;
+    }
+
+    // budget counts the levels still restored from an ancestor's restoreDepth; a parallel
+    // state passes it to every region without spending a level.
+    function enterDefaults(state: number, budget: number): void {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = 0; i < list.length; i++) {
+          enterState(list[i] as number);
+          enterDefaults(list[i] as number, budget);
+        }
+        return;
       }
-      while (count > 0) {
-        count--;
-        enterState(scratch[count] as number);
-        scratch[count] = NO_STATE;
+      const remaining = Math.max(restoreDepth[state] as number, budget);
+      const child = defaultChild(state, remaining > 0);
+      if (child !== NO_STATE) {
+        enterState(child);
+        enterDefaults(child, remaining - 1);
       }
-      state = target;
-      while (initialChild[state] !== NO_STATE) {
-        state = initialChild[state] as number;
-        enterState(state);
+    }
+
+    function childToward(state: number, target: number): number {
+      let child = target;
+      while (parent[child] !== state) {
+        child = parent[child] as number;
+      }
+      return child;
+    }
+
+    function enterToward(state: number, target: number): void {
+      enterState(state);
+      if (state === target) {
+        enterDefaults(state, 0);
+        return;
+      }
+      const next = childToward(state, target);
+      if (parallel[state] !== true) {
+        enterToward(next, target);
+        return;
+      }
+      const list = children[state] as number[];
+      for (let i = 0; i < list.length; i++) {
+        const region = list[i] as number;
+        if (region === next) {
+          enterToward(region, target);
+        } else {
+          enterState(region);
+          enterDefaults(region, 0);
+        }
+      }
+    }
+
+    function enterMissing(state: number): void {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = 0; i < list.length; i++) {
+          const region = list[i] as number;
+          if (isActive[region] === true) {
+            enterMissing(region);
+          } else {
+            enterState(region);
+            enterDefaults(region, 0);
+          }
+        }
+        return;
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE) {
+        enterMissing(child);
+        return;
+      }
+      enterDefaults(state, 0);
+    }
+
+    function firstLeaf(state: number): string {
+      let leaf = state;
+      while (true) {
+        const child =
+          parallel[leaf] === true
+            ? ((children[leaf] as number[])[0] as number)
+            : (activeChild[leaf] as number);
+        if (child === NO_STATE) {
+          return paths[leaf] as string;
+        }
+        leaf = child;
       }
-      instance.path = paths[active[leafDepth] as number] as string;
     }
 
     function transition(
       source: number,
       target: number,
-      reenter: boolean,
-      actions: readonly TransitionAction<Ctx, E>[] | undefined,
+      run: readonly MoveAction<Ctx, E>[] | undefined,
       event: E | undefined,
+      cause: MoveCause,
     ): void {
       if (target === NO_STATE) {
-        runActions(actions, event);
+        runActions(run, event);
         return;
       }
-      const domain = transitionDomain(compiled, source, target, reenter);
-      exitTo(depth[domain] as number);
-      runActions(actions, event);
-      enterDown(domain, target);
+      const domain = transitionDomain(compiled, source, target);
+      const from = firstLeaf(domain);
+      const child = activeChild[domain] as number;
+      if (child !== NO_STATE) {
+        exitSubtree(child);
+      }
+      runActions(run, event);
+      if (target === domain) {
+        enterDefaults(domain, 0);
+      } else {
+        enterToward(childToward(domain, target), target);
+      }
+      refreshLeaves();
+      moved = true;
+      if (listeners.length > 0) {
+        report(from, firstLeaf(domain), cause, event);
+      }
+    }
+
+    function settleAlways(): void {
+      for (let moves = 0; !stopRequested; moves++) {
+        if (!takeAlways(ROOT, moves === ALWAYS_LIMIT)) {
+          return;
+        }
+      }
+    }
+
+    function takeAlways(state: number, overLimit: boolean): boolean {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = 0; i < list.length; i++) {
+          if (takeAlways(list[i] as number, overLimit)) {
+            return true;
+          }
+        }
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE && takeAlways(child, overLimit)) {
+        return true;
+      }
+      const list = always[state] as Transition<Ctx, E>[];
+      for (let i = 0; i < list.length; i++) {
+        const candidate = list[i] as Transition<Ctx, E>;
+        const when = candidate.when as ((ctx: Ctx) => boolean) | undefined;
+        if (when === undefined || when(ctx)) {
+          if (overLimit) {
+            clearQueue();
+            busy = false;
+            throw `hsm: state "${describePath(paths[state] as string)}" took ${ALWAYS_LIMIT} always transitions in a row; check for an always loop`;
+          }
+          transition(state, candidate.target, undefined, undefined, "always");
+          return true;
+        }
+      }
+      return false;
     }
 
     function runActions(
-      actions: readonly TransitionAction<Ctx, E>[] | undefined,
+      run: readonly MoveAction<Ctx, E>[] | undefined,
       event: E | undefined,
     ): void {
-      if (actions === undefined || event === undefined) {
+      if (run === undefined || event === undefined) {
         return;
       }
-      for (let i = 0; i < actions.length; i++) {
-        (actions[i] as TransitionAction<Ctx, E>)(ctx, event, instance);
+      for (let i = 0; i < run.length; i++) {
+        (run[i] as MoveAction<Ctx, E>)(ctx, event, instance);
       }
     }
 
-    function processEvent(event: E): void {
-      for (let level = leafDepth; level >= 0; level--) {
-        const state = active[level] as number;
-        const listIndex = (onIndex[state] as { [type: string]: number })[event.type];
-        if (typeof listIndex !== "number") {
-          continue;
+    function takeEvent(state: number, event: E): boolean {
+      const listIndex = (onIndex[state] as { [type: string]: number })[event.type];
+      if (typeof listIndex !== "number") {
+        return false;
+      }
+      const list = transitions[listIndex] as Transition<Ctx, E>[];
+      for (let i = 0; i < list.length; i++) {
+        const candidate = list[i] as Transition<Ctx, E>;
+        if (candidate.when === undefined || candidate.when(ctx, event)) {
+          transition(state, candidate.target, candidate.run, event, "event");
+          return true;
         }
-        const list = transitions[listIndex] as Transition<Ctx, E>[];
+      }
+      return false;
+    }
+
+    // Each region takes at most one transition; the event bubbles past the parallel
+    // state only when none did, and a move that left or re-entered it ends the offer.
+    function offerEvent(state: number, event: E): boolean {
+      if (parallel[state] === true) {
+        const id = entryId[state];
+        const list = children[state] as number[];
+        let taken = false;
         for (let i = 0; i < list.length; i++) {
-          const candidate = list[i] as Transition<Ctx, E>;
-          if (candidate.guard === undefined || candidate.guard(ctx, event)) {
-            transition(state, candidate.target, candidate.reenter, candidate.actions, event);
-            return;
+          if (offerEvent(list[i] as number, event)) {
+            taken = true;
+            if (stopRequested || entryId[state] !== id) {
+              return true;
+            }
           }
         }
+        if (taken) {
+          return true;
+        }
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE && offerEvent(child, event)) {
+        return true;
       }
+      return takeEvent(state, event);
     }
 
     function clearQueue(): void {
@@ -572,9 +1222,13 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
       running = false;
       busy = true;
       clearQueue();
-      exitTo(NO_STATE);
-      instance.path = undefined;
+      const from = instance.path as string;
+      exitSubtree(ROOT);
+      refreshLeaves();
       busy = false;
+      if (listeners.length > 0) {
+        report(from, undefined, "stop", undefined);
+      }
     }
 
     function endStep(): void {
@@ -582,7 +1236,11 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
         const event = queue[queueHead] as E;
         queue[queueHead] = undefined;
         queueHead++;
-        processEvent(event);
+        moved = false;
+        offerEvent(ROOT, event);
+        if (moved) {
+          settleAlways();
+        }
       }
       clearQueue();
       busy = false;
@@ -601,48 +1259,86 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
         return;
       }
       busy = true;
+      if (generation !== definition.generation) {
+        rebind();
+      }
       endStep();
     }
 
-    function fireUpdateHooks(dt: number): boolean {
-      for (let level = leafDepth; level >= 0; level--) {
-        const state = active[level] as number;
-        const hook = (configs[state] as StateConfig<Ctx, E>).update;
-        if (hook === undefined) {
-          continue;
+    function addElapsed(state: number, dt: number): void {
+      elapsed[state] = (elapsed[state] as number) + dt;
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = 0; i < list.length; i++) {
+          addElapsed(list[i] as number, dt);
         }
-        const target = hook(ctx, dt, instance);
-        if (stopRequested) {
-          return true;
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE) {
+        addElapsed(child, dt);
+      }
+    }
+
+    function tickRegion(state: number, dt: number): boolean {
+      return fireUpdateHooks(state, dt) || fireTimers(state);
+    }
+
+    // A parallel state's timers fire only after its regions tick, and only if none moved.
+    function fireUpdateHooks(state: number, dt: number): boolean {
+      if (parallel[state] === true) {
+        const id = entryId[state];
+        const list = children[state] as number[];
+        let regionMoved = false;
+        for (let i = 0; i < list.length; i++) {
+          if (tickRegion(list[i] as number, dt)) {
+            regionMoved = true;
+            if (stopRequested || entryId[state] !== id) {
+              return true;
+            }
+          }
         }
-        if (typeof target === "string") {
-          transition(state, resolveTarget(compiled, state, target), false, undefined, undefined);
+        if (regionMoved) {
           return true;
         }
       }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE && fireUpdateHooks(child, dt)) {
+        return true;
+      }
+      const hook = (configs[state] as StateConfig<Ctx, E>).update;
+      if (hook === undefined) {
+        return false;
+      }
+      const target = hook(ctx, dt, instance);
+      if (stopRequested) {
+        return true;
+      }
+      if (typeof target === "string") {
+        transition(state, resolveTarget(compiled, state, target), undefined, undefined, "update");
+        return true;
+      }
       return false;
     }
 
-    function fireTimers(dt: number): void {
-      for (let level = 0; level <= leafDepth; level++) {
-        elapsed[level] = (elapsed[level] as number) + dt;
-      }
-      for (let level = leafDepth; level >= 0; level--) {
-        const state = active[level] as number;
-        const delays = afterDelays[state] as number[];
-        const next = fired[level] as number;
-        if (next < delays.length && (delays[next] as number) <= (elapsed[level] as number)) {
-          fired[level] = next + 1;
-          transition(
-            state,
-            (afterTargets[state] as number[])[next] as number,
-            false,
-            undefined,
-            undefined,
-          );
-          return;
-        }
+    function fireTimers(state: number): boolean {
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE && fireTimers(child)) {
+        return true;
       }
+      const delays = afterDelays[state] as number[];
+      const next = fired[state] as number;
+      if (next < delays.length && (delays[next] as number) <= (elapsed[state] as number)) {
+        fired[state] = next + 1;
+        transition(
+          state,
+          (afterTargets[state] as number[])[next] as number,
+          undefined,
+          undefined,
+          "after",
+        );
+        return true;
+      }
+      return false;
     }
 
     function update(dt: number): void {
@@ -650,8 +1346,16 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
         return;
       }
       busy = true;
-      if (!fireUpdateHooks(dt)) {
-        fireTimers(dt);
+      if (generation !== definition.generation) {
+        rebind();
+      }
+      if (!stopRequested) {
+        addElapsed(ROOT, dt);
+        moved = false;
+        tickRegion(ROOT, dt);
+        if (moved) {
+          settleAlways();
+        }
       }
       endStep();
     }
@@ -668,17 +1372,15 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
     }
 
     function matches(path: string): boolean {
-      for (let level = 1; level <= leafDepth; level++) {
-        if (paths[active[level] as number] === path) {
-          return true;
-        }
-      }
-      return false;
+      const state = lookupPath(compiled, path);
+      return state !== undefined && state !== ROOT && isActive[state] === true;
     }
 
     busy = true;
     enterState(ROOT);
-    enterDown(ROOT, ROOT);
+    enterDefaults(ROOT, 0);
+    refreshLeaves();
+    settleAlways();
     endStep();
     return instance;
   }
@@ -686,11 +1388,31 @@ function createMachine<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>
   return { start };
 }
 
+function define<Ctx, E extends EventObject>(
+  key: string | undefined,
+  config: MachineConfig<Ctx, E>,
+): Machine<Ctx, E> {
+  const compiled = compile(config);
+  if (key === undefined) {
+    return createMachine({ compiled, generation: 0 });
+  }
+  const existing = registered[key] as unknown as Registered<Ctx, E> | undefined;
+  if (existing !== undefined) {
+    const definition = existing.definition;
+    definition.compiled = compiled;
+    definition.generation = definition.generation + 1;
+    return existing.machine;
+  }
+  const definition: Definition<Ctx, E> = { compiled, generation: 0 };
+  const machine = createMachine(definition);
+  registered[key] = { definition, machine } as unknown as Registered<unknown, EventObject>;
+  return machine;
+}
+
 // Ctx and E are given explicitly and the config is inferred, so the config takes a second call.
-export function defineMachine<Ctx, E extends EventObject>(): <
-  const C extends MachineConfig<Ctx, E>,
->(
-  config: C,
-) => DefinedMachine<Ctx, E, C> {
-  return createMachine as never;
+// A key makes a later definition under it (a hot-reloaded module re-running) rebind live instances.
+export function defineMachine<Ctx, E extends EventObject>(
+  key?: string,
+): <const C extends MachineConfig<Ctx, E>>(config: C) => DefinedMachine<Ctx, E, C> {
+  return ((config: MachineConfig<Ctx, E>) => define(key, config)) as never;
 }