@defold-typescript/transpiler 0.48.0 → 0.49.0

package/dist/hsm/index.ts

@@ -17,24 +17,33 @@ export type MoveCause = "event" | "after" | "update" | "stop" | "reload" | "alwa
 /**
  * A listener given to `onMove`. It gets the leaf left, the leaf entered (`undefined` after
  * `stop()`), the cause, and the event, which is `undefined` unless the cause is `event`. It runs
- * after the move's `enter` hooks.
+ * after the move's `enter` hooks. The event is read-only: the listener cannot assign to its
+ * fields.
  * @noSelf
  */
 export type MoveListener<E extends EventObject, P extends string = string> = (
   from: P,
   to: P | undefined,
   cause: MoveCause,
-  event: E | undefined,
+  event: Readonly<E> | undefined,
 ) => void;
 
 /**
- * One running machine, returned by `start`. `P` is the union of the machine's state paths; the
- * `machine` a hook, a `run` or a `task` receives uses plain `string` paths instead.
+ * A listener given to `onUnhandled`. It gets the event no rule of an active state took. The
+ * event is read-only: the listener cannot assign to its fields.
  * @noSelf
  */
-export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
-  /** The context passed to `start`. */
-  readonly ctx: Ctx;
+export type UnhandledListener<E extends EventObject> = (event: Readonly<E>) => void;
+
+/**
+ * What a `when` sees of the running machine: which states are active, and nothing that changes
+ * it. `P` is the union of the paths it takes. The `machine` a `when` receives takes the machine's
+ * state paths, and also any path below a state that holds only callbacks with unannotated
+ * parameters and `after` or `every` lists with one in them, or whose child states all do. `Tag`
+ * is the union of the machine's tag names.
+ * @noSelf
+ */
+export interface MachineView<P extends string = string, Tag extends string = never> {
   /**
    * The full path of the deepest active state, or `undefined` once stopped. In a parallel state
    * it is the first region's leaf.
@@ -45,17 +54,54 @@ export interface MachineInstance<Ctx, E extends EventObject, P extends string =
    * once stopped. It is the same array on every read, updated in place.
    */
   readonly leaves: readonly P[];
+  // Read off a method signature, which TypeScript compares bivariantly: a machine with narrower
+  // paths fits a parameter typed with wider ones, so a hook typed `StateHook<Ctx, E>` fits its
+  // slot. `this: void` repeats on the signature what `@noSelf` says of the interface: a call
+  // passes no self in Lua.
   /** Whether the state at the full path `path` is active. Ancestors of the current state count. */
-  readonly matches: (path: P) => boolean;
+  readonly matches: { matches(this: void, path: P): boolean }["matches"];
+  /**
+   * Whether an active state carries `tag`. A parent's tag holds while any of its children is
+   * active, and a tag in any region of a parallel state counts. The answer is `false` for a name
+   * no state carries, and once stopped.
+   */
+  readonly hasTag: (tag: Tag) => boolean;
+}
+
+/**
+ * One running machine, returned by `start`. `P` is the union of the paths it takes: the
+ * machine's state paths on a started instance. The `machine` a hook, a `run` or a `task`
+ * receives takes those paths, and also any path below a state that holds only callbacks with
+ * unannotated parameters and `after` or `every` lists with one in them, or whose child states all
+ * do. `Tag` is the union of the machine's tag names.
+ * @noSelf
+ */
+export interface MachineInstance<
+  Ctx,
+  E extends EventObject,
+  P extends string = string,
+  Tag extends string = never,
+> extends MachineView<P, Tag> {
+  /** The context passed to `start`. */
+  readonly ctx: Ctx;
+  /**
+   * Whether a rule of an active state would take `event` if it were sent at that moment. The
+   * answer is for that one event, payload included: a rule's `when` reads it. A rule with no
+   * `to` counts. No hook, `run` or listener runs and nothing is queued, and once the machine is
+   * stopped the answer is `false`.
+   */
+  readonly can: (event: E) => boolean;
   /**
    * Handles `event`, or queues it when called during a step. An event no active state handles is
-   * dropped, and once the machine is stopped the call does nothing.
+   * dropped: it runs the active states' `unhandled` hooks and is then reported to the
+   * `onUnhandled` listeners. Once the machine is stopped the call does nothing.
    */
   readonly send: (event: E) => void;
   /**
-   * Advances the machine by `dt` seconds: runs the `update` hooks, then the `after` timers if no
-   * hook moved it. A machine whose `update` is not called is frozen in time, and once the machine
-   * is stopped the call does nothing.
+   * Advances the machine by `dt` seconds: runs the `update` hooks, then, in every region no hook
+   * moved, each state's `every` entries and after them its `after` timers. A machine with no
+   * parallel state is one region. A machine whose `update` is not called is frozen in time, and
+   * once the machine is stopped the call does nothing.
    */
   readonly update: (dt: number) => void;
   /**
@@ -70,17 +116,53 @@ export interface MachineInstance<Ctx, E extends EventObject, P extends string =
    * function removes that one.
    */
   readonly onMove: (listener: MoveListener<E, P>) => () => void;
+  /**
+   * Adds a listener called with each event the machine processes that no rule of an active state
+   * takes. It runs inside the step, after the active states' `unhandled` hooks and before the
+   * next queued event. A rule with no `to` takes its event. Each call adds a listener, and the
+   * returned function removes that one.
+   */
+  readonly onUnhandled: (listener: UnhandledListener<E>) => () => void;
 }
 
 /**
  * A function a rule's `run` calls during the move, after the `exit` hooks and before the `enter`
- * hooks. Its `event` is the variant the `on` key names.
+ * hooks. Its `event` is the variant the `on` key names, and is read-only: a `run` changes `ctx`
+ * and cannot assign to a field of the event. `Hook` is the union of the paths its `machine`
+ * takes: the machine's paths for a `run` written in the config, and any `string` when left out.
  */
-export type MoveAction<Ctx, E extends EventObject, V extends E = E> = (
-  ctx: Ctx,
-  event: V,
-  machine: MachineInstance<Ctx, E>,
-) => void;
+export type MoveAction<
+  Ctx,
+  E extends EventObject,
+  V extends E = E,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (ctx: Ctx, event: Readonly<V>, machine: MachineInstance<Ctx, E, Hook, Tag>) => void;
+
+/**
+ * A function a `run` calls where there is no event: under `after`, `always` and `every`. `Hook`
+ * is the union of the paths its `machine` takes: the machine's paths for a `run` written in the
+ * config, and any `string` when left out.
+ */
+export type RunAction<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (ctx: Ctx, machine: MachineInstance<Ctx, E, Hook, Tag>) => void;
+
+// A rule typed without the machine's event type has no run. The default cannot be EventObject:
+// MachineInstance is invariant in E, so such a rule would not fit a machine with narrower events.
+// That makes the rule types invariant in E too, and TypeScript does not compare two instances of
+// one type by structure, so each slot lists the rule typed without E beside the one typed with it.
+type RuleRun<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> = [E] extends [never]
+  ? never
+  : RunAction<Ctx, E, Tag, Hook> | readonly RunAction<Ctx, E, Tag, Hook>[];
 
 // A list with a first entry: Lua cannot tell [] from {}, so an empty list would compile to a
 // transition with no to. It is an object type, not a tuple, because TypeScript reports a bad
@@ -101,6 +183,8 @@ export interface TransitionConfig<
   E extends EventObject,
   V extends E = E,
   To extends string = string,
+  Tag extends string = never,
+  Hook extends string = string,
 > {
   /**
    * The full path of the state to move to. A `to` naming the state the rule is on exits and
@@ -110,15 +194,22 @@ export interface TransitionConfig<
   /**
    * 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.
+   * `ctx` and `event` are read-only here, one level deep: a write belongs in `run`.
+   * `machine` reads the active states; inside a parallel state it shows the regions that already
+   * took the event.
    */
-  readonly when?: (ctx: Ctx, event: V) => boolean;
+  readonly when?: (
+    ctx: Readonly<Ctx>,
+    event: Readonly<V>,
+    machine: MachineView<Hook, Tag>,
+  ) => 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>[];
+  readonly run?: MoveAction<Ctx, E, V, Tag, Hook> | readonly MoveAction<Ctx, E, V, Tag, Hook>[];
   /** Renamed to `to`. */
   readonly target?: never;
   /** Renamed to `when`. */
@@ -138,21 +229,39 @@ export type TransitionSpec<
   E extends EventObject,
   V extends E = E,
   To extends string = string,
-> = To | TransitionConfig<Ctx, E, V, To> | RuleList<TransitionConfig<Ctx, E, V, To>>;
+  Tag extends string = never,
+  Hook extends string = string,
+> =
+  | To
+  | TransitionConfig<Ctx, E, V, To, Tag, Hook>
+  | RuleList<TransitionConfig<Ctx, E, V, To, Tag, Hook>>;
 
 /**
- * The object form of an `always` rule: a `to` and an optional `when`. It gets no event and has
- * no `run`; side effects belong in the target's `enter`.
+ * The object form of an `always` rule: a `to`, an optional `when` and an optional `run`. It gets
+ * no event. `E` is the machine's event type; a rule typed without it has no `run`. `Hook` is
+ * the union of the paths the `machine` of its `when` and `run` takes: any `string` when left out.
  * @noSelf
  */
-export interface AlwaysConfig<Ctx, To extends string = string> {
+export interface AlwaysConfig<
+  Ctx,
+  To extends string = string,
+  E extends EventObject = never,
+  Tag extends string = never,
+  Hook extends string = string,
+> {
   /**
    * The full path of the state to move to. An `always` rule without one throws when the machine
    * is defined.
    */
   readonly to: To;
-  /** Checked on every recheck, so it must have no side effects. */
-  readonly when?: (ctx: Ctx) => boolean;
+  /**
+   * Checked on every recheck, so it must have no side effects. `ctx` is read-only here, one
+   * level deep: a write belongs in `run`. `machine` reads the active states; inside a parallel
+   * state it shows the regions that already moved.
+   */
+  readonly when?: (ctx: Readonly<Ctx>, machine: MachineView<Hook, Tag>) => boolean;
+  /** Runs between the `exit` and `enter` hooks of the move, only when the rule is taken. */
+  readonly run?: RuleRun<Ctx, E, Tag, Hook>;
   /** Renamed to `to`. */
   readonly target?: never;
   /** Renamed to `when`. */
@@ -163,80 +272,221 @@ export interface AlwaysConfig<Ctx, To extends string = string> {
  * What `always` takes: a target path, an `AlwaysConfig`, or a non-empty list of them. The first
  * whose `when` is missing or passes is taken.
  */
-export type AlwaysSpec<Ctx, To extends string = string> =
+export type AlwaysSpec<
+  Ctx,
+  To extends string = string,
+  E extends EventObject = never,
+  Tag extends string = never,
+  Hook extends string = string,
+> =
   | To
-  | AlwaysConfig<Ctx, To>
-  | RuleList<AlwaysConfig<Ctx, To>>;
+  | AlwaysConfig<Ctx, To, E, Tag, Hook>
+  | AlwaysConfig<Ctx, To, never, Tag, Hook>
+  | RuleList<AlwaysConfig<Ctx, To, E, Tag, Hook> | AlwaysConfig<Ctx, To, never, Tag, Hook>>;
 
 /**
- * One entry of the list form of `after`: a `delay` and the `to` its timer leads to.
+ * The object form of a rule on an `after` timer: a `to`, a `when` and a `run`, each optional. A
+ * rule with neither a `to` nor a `run` throws when the machine is defined. `E` is the machine's
+ * event type; a rule typed without it has no `run`. `Hook` is the union of the paths the
+ * `machine` of its `when` and `run` takes: any `string` when left out.
  * @noSelf
  */
-export interface AfterConfig<Ctx, To extends string = string> {
+export interface AfterRule<
+  Ctx,
+  To extends string = string,
+  E extends EventObject = never,
+  Tag extends string = never,
+  Hook extends string = string,
+> {
+  /**
+   * The full path of the state to move to when the timer fires. A rule without one runs its
+   * `run` and nothing else: no state exits or enters, and it is not a move.
+   */
+  readonly to?: To;
+  /**
+   * The timer fires only when this returns `true`. It is first checked once the delay has
+   * passed, then on every `update` call until it passes or the state is left, so it must have no
+   * side effects. `ctx` is read-only here, one level deep: a write belongs in `run`. `machine`
+   * reads the active states.
+   */
+  readonly when?: (ctx: Readonly<Ctx>, machine: MachineView<Hook, Tag>) => boolean;
+  /**
+   * Runs when the timer fires: between the `exit` and `enter` hooks of the move, or on its own
+   * for a rule with no `to`.
+   */
+  readonly run?: RuleRun<Ctx, E, Tag, Hook>;
+}
+
+/**
+ * One entry of the list form of `after`: a `delay` beside the fields of an `AfterRule`.
+ * @noSelf
+ */
+export interface AfterConfig<
+  Ctx,
+  To extends string = string,
+  E extends EventObject = never,
+  Tag extends string = never,
+  Hook extends string = string,
+> extends AfterRule<Ctx, To, E, Tag, Hook> {
   /**
    * The delay in seconds of game time: a number, or a function of the context that returns one.
    * A function is read once each time the state is entered, after its `enter` hook, and again on
-   * a hot reload, so the delay is fixed for that stay. A result that is not a non-negative number
+   * a hot reload, so the delay is fixed for that stay. The function only reads the context: it
+   * cannot assign to a field of `ctx`. A result that is not a non-negative number throws, naming
+   * the state.
+   */
+  readonly delay: number | ((ctx: Readonly<Ctx>) => number);
+}
+
+/**
+ * One entry of the list form of `every`: a `delay` and the `run` it repeats.
+ * @noSelf
+ */
+export interface EveryConfig<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> {
+  /**
+   * The seconds of game time between two runs: a number, or a function of the context that
+   * returns one. A function is read once each time the state is entered, after its `enter` hook,
+   * and again on a hot reload, so the delay is fixed for that stay. The function only reads the
+   * context: it cannot assign to a field of `ctx`. A result that is not a positive number
    * throws, naming the state.
    */
-  readonly delay: number | ((ctx: Ctx) => number);
-  /** The full path of the state to move to when the delay has passed. */
-  readonly to: To;
+  readonly delay: number | ((ctx: Readonly<Ctx>) => number);
+  /** Runs each time the delay passes: one function, or a list run in order. */
+  readonly run: RunAction<Ctx, E, Tag, Hook> | readonly RunAction<Ctx, E, Tag, Hook>[];
+  /** Not taken here: an `after` timer leaves the state. */
+  readonly to?: never;
+  /** Not taken here: a `run` tests a condition itself. */
+  readonly when?: never;
 }
 
 /**
  * A state's rules by event `type`. Only the machine's event types are keys, and each rule's
  * `when` and `run` see the event variant its key names.
  */
-export type OnConfig<Ctx, E extends EventObject, To extends string = string> = {
-  readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, { type: K }>, To>;
+export type OnConfig<
+  Ctx,
+  E extends EventObject,
+  To extends string = string,
+  Tag extends string = never,
+  Hook extends string = string,
+> = {
+  readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, { type: K }>, To, Tag, Hook>;
 };
 
 /**
  * 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`.
+ * event; event data reaches `enter` through `ctx`, set in `run`. `Hook` is the union of the
+ * paths its `machine` takes: the machine's paths for a hook written in the config, and any
+ * `string` when left out.
  */
-export type StateHook<Ctx, E extends EventObject> = (
-  ctx: Ctx,
-  machine: MachineInstance<Ctx, E>,
-) => void;
+export type StateHook<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (ctx: Ctx, machine: MachineInstance<Ctx, E, Hook, Tag>) => void;
 
 /**
  * Runs on every `update(dt)` while the state is active, deepest state first. It returns a full
  * path to move there, or `undefined` to pass. The first hook to return a path wins: the hooks
- * above it and the `after` timers do not run on that call, and the move has no `run`.
+ * above it and the `after` timers of its region do not run on that call, and the move has no
+ * `run`. Under a parallel state the other regions still run their hooks and timers, unless the
+ * move left the parallel state or entered it again. `Hook` is the union of the paths its
+ * `machine` takes: the machine's paths for a hook written in the config, and any `string` when
+ * left out.
  */
-export type UpdateHook<Ctx, E extends EventObject, To extends string = string> = (
-  ctx: Ctx,
-  dt: number,
-  machine: MachineInstance<Ctx, E>,
-) => To | undefined;
+export type UpdateHook<
+  Ctx,
+  E extends EventObject,
+  To extends string = string,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (ctx: Ctx, dt: number, machine: MachineInstance<Ctx, E, Hook, Tag>) => To | undefined;
+
+/**
+ * Runs when the machine drops an event while the state is active: for the events `onUnhandled`
+ * reports, and no others. Every active state that has the hook runs it, deepest first, in the
+ * order `update` hooks run. `event` is the machine's whole event union, and is read-only: the
+ * hook cannot assign to its fields. The hook moves nothing: a `send` from it queues, and a
+ * `stop()` ends the step once every hook and listener has run for the event. `Hook` is the
+ * union of the paths its `machine` takes: the machine's paths for a hook written in the config,
+ * and any `string` when left out.
+ */
+export type UnhandledHook<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (ctx: Ctx, event: Readonly<E>, machine: MachineInstance<Ctx, E, Hook, Tag>) => void;
 
 /**
  * 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.
+ * first call or once the state is left. The returned cleanup runs on every way out. A task that
+ * starts several callbacks counts them with `waitGroup`. `Hook` is the union of the paths its
+ * `machine` takes: the machine's paths for a task written in the config, and any `string` when
+ * left out.
  * @noSelf
  */
-export type TaskStart<Ctx, E extends EventObject> = (
+export type TaskStart<
+  Ctx,
+  E extends EventObject,
+  Tag extends string = never,
+  Hook extends string = string,
+> = (
   ctx: Ctx,
   finish: (event: E) => void,
-  machine: MachineInstance<Ctx, E>,
+  machine: MachineInstance<Ctx, E, Hook, Tag>,
   // biome-ignore lint/suspicious/noConfusingVoidType: `void` keeps an expression-body task returning a void call (`=> go.animate(...)`) valid.
 ) => (() => void) | void;
 
+/**
+ * Counts several pieces of engine work a state starts and waits for, returned by `waitGroup()`.
+ * It knows nothing about a machine: built inside a `task`, it is new for each entry of the
+ * state.
+ * @noSelf
+ */
+export interface WaitGroup {
+  /**
+   * Records one pending piece of work and returns the function that reports it finished. That
+   * function counts once, and a later call does nothing. It ignores its arguments, so an engine
+   * function takes it as its callback, as in `http.request(url, "GET", group.add())`.
+   */
+  readonly add: () => () => void;
+  /**
+   * Calls `callback` once when no added work is pending: at once when none is pending at the
+   * call, and otherwise inside the report that finishes the last pending piece. Each call
+   * registers one callback, and several run in the order registered. A `wait` made before the
+   * first `add` runs at once, so it goes after them.
+   */
+  readonly wait: (callback: () => void) => void;
+}
+
 /**
  * A machine definition, returned by the second `defineMachine` call. Its `start` creates the
  * instances that run.
  * @noSelf
  */
-export interface Machine<Ctx, E extends EventObject, P extends string = string> {
+export interface Machine<
+  Ctx,
+  E extends EventObject,
+  P extends string = string,
+  Tag extends string = never,
+> {
   /**
-   * Creates an instance with `ctx` as its context and enters the root's `initial` chain. Each
-   * call returns a separate instance, which has already handled the events its `enter` hooks
-   * sent.
+   * Creates an instance with `ctx` as its context. Without `at` it enters the root's `initial`
+   * chain. With `at`, a list of full state paths such as a copy of `leaves`, it enters toward
+   * each path: a level or region no path names goes through `initial`, a path the machine lacks
+   * falls back to its closest parent, and of two paths that cannot be active together the first
+   * wins. Timer progress and `restoreDepth` memory are not part of the list. Each call returns a
+   * separate instance, which has already handled the events its `enter` hooks sent.
    */
-  readonly start: (ctx: Ctx) => MachineInstance<Ctx, E, P>;
+  readonly start: (ctx: Ctx, at?: readonly P[]) => MachineInstance<Ctx, E, P, Tag>;
 }
 
 type PathDepth = [never, 0, 1, 2, 3];
@@ -256,19 +506,6 @@ type TreePathsBelow<T, D extends number> = {
 
 type TreePath<T> = `/${TreePathsBelow<T, 4>}`;
 
-// The paths a config slot accepts. TypeScript checks a config once before it types the
-// callbacks, and a level whose states hold only callbacks has no inferred children in that
-// check, so a node with no inferred children accepts any path below it.
-type SlotPathsBelow<T, D extends number> = unknown extends T
-  ? string
-  : {
-      [K in keyof T & string]:
-        | K
-        | `${K}/${D extends 1 ? string : SlotPathsBelow<T[K], PathDepth[D]>}`;
-    }[keyof T & string];
-
-type SlotPath<T> = `/${SlotPathsBelow<T, 4>}`;
-
 type TreeOf<C> = C extends { readonly states: infer Children }
   ? { readonly [K in keyof Children]: TreeOf<Children[K]> }
   : unknown;
@@ -297,68 +534,142 @@ type TreeDepth<T, D extends number> = unknown extends T
               : never
             : never);
 
-type AnyChild<Ctx, E extends EventObject, T, To extends string> = unknown extends T
-  ? { readonly [name: string]: StateNode<Ctx, E, unknown, string, To> }
+type AnyChild<
+  Ctx,
+  E extends EventObject,
+  T,
+  To extends string,
+  Tag extends string = never,
+  Hook extends string = string,
+> = unknown extends T
+  ? { readonly [name: string]: StateNode<Ctx, E, unknown, string, To, Tag, Hook> }
   : unknown;
 
+// A config is read into three trees. `T`, inferred from the `states` keys alone, types the
+// started instance and each state's `initial` and `restoreDepth`. The node tree types the
+// config slots, through `To`. The hook node tree types the callbacks, through `Hook`. The two
+// node trees are intersected onto the root's `states` in `RootState`.
 // `states` is the only slot that infers the tree; every other slot that mentions it is wrapped
 // in NoInfer. `on`, `after` and `update` are wrapped whole so inference never reads them:
 // without exactOptionalPropertyTypes, reading `on` asks for the paths while the tree is still
 // being inferred, and a valid config fails as circular. `always` is wrapped only through `To`:
 // NoInfer over a union that holds object types hides its string members from completion.
-// No callback parameter mentions the tree: one that did would make TypeScript settle the tree
-// at the first such callback, before the states beside it are read.
+// `every` mentions no path and is wrapped whole all the same: where inference reads it, an
+// unannotated callback in it, such as `delay: (ctx) => ctx.rate`, gets no parameter types.
+// No callback parameter mentions `T`: one that did would make TypeScript settle the tree at the
+// first such callback, before the states beside it are read. Callback parameters mention the
+// hook node tree, through `Hook`: a second node tree inferred from the same config, which
+// settles at the first callback and types nothing else.
+// `tags` mentions only `Tag`, which the first `defineMachine` call fixes and nothing infers, so
+// it stays outside NoInfer.
 /** @noSelf */
-interface StateBase<Ctx, E extends EventObject, T, Self extends string, To extends string> {
+interface StateBase<
+  Ctx,
+  E extends EventObject,
+  T,
+  Self extends string,
+  To extends string,
+  Tag extends string = never,
+  Hook extends string = string,
+> {
   /** Child states, by name. A name is non-empty and contains no `/`. */
   readonly states?: {
-    readonly [K in keyof T]: StateNode<Ctx, E, T[K], `${Self}/${K & string}`, To>;
-  } & NoInfer<AnyChild<Ctx, E, T, To>>;
+    readonly [K in keyof T]: StateNode<Ctx, E, T[K], `${Self}/${K & string}`, To, Tag, Hook>;
+  } & NoInfer<AnyChild<Ctx, E, T, To, Tag, Hook>>;
+  /**
+   * Names from the machine's third type argument that hold while the state is active, read with
+   * `hasTag`.
+   */
+  readonly tags?: readonly Tag[];
   /**
    * Rules by event `type`, each a target path, a rule object or a list of them. An event starts
    * at the deepest active state and moves up to the parent while no rule takes it.
    */
-  readonly on?: NoInfer<OnConfig<Ctx, E, To>>;
+  readonly on?: NoInfer<OnConfig<Ctx, E, To, Tag, Hook>>;
   /**
-   * Timers, in one of two forms: targets by delay in seconds of game time, such as
-   * `{ 2: "/idle" }`, or a list of `AfterConfig` entries, such as
+   * Timers, in one of two forms: targets or `AfterRule` objects by delay in seconds of game
+   * time, such as `{ 2: "/idle" }`, or a list of `AfterConfig` entries, such as
    * `[{ delay: (ctx) => ctx.patrolFor, to: "/rest" }]`, whose `delay` is a number or a function
    * of the context. A delay function is read once each time the state is entered, after its
    * `enter` hook, and again on a hot reload. The delay is counted by `update(dt)` while the state
-   * is active, from zero on each entry. One `update` call fires at most one timer, and none when
-   * an `update` hook moved the machine.
+   * is active, from zero on each entry, and a timer fires at most once per stay. An `update`
+   * call tries the due timers in delay order: one whose `when` fails stays pending, one with no
+   * `to` runs its `run` and the call goes on, and the first that moves ends the timers of its
+   * region for that call. None is tried in a region an `update` hook moved on that call. Under a
+   * parallel state each region follows both rules on its own, and the parallel state's own
+   * timers are tried only when no region moved. A state's `every` entries run before its timers.
    */
-  readonly after?: NoInfer<{ readonly [seconds: number]: To } | readonly AfterConfig<Ctx, To>[]>;
+  readonly after?: NoInfer<
+    | {
+        readonly [seconds: number]:
+          | To
+          | AfterRule<Ctx, To, E, Tag, Hook>
+          | AfterRule<Ctx, To, never, Tag, Hook>;
+      }
+    | readonly (AfterConfig<Ctx, To, E, Tag, Hook> | AfterConfig<Ctx, To, never, Tag, Hook>)[]
+  >;
   /**
-   * Targets taken right after any move that leaves this state active; the first whose `when` is
-   * missing or passes wins. It is checked after a move only: not after a rule with no `to`, and
-   * not on an `update` call that moves nothing.
+   * Code that repeats while the state is active, in one of two forms: a `run` by delay in
+   * seconds of game time, such as `{ 0.5: (ctx) => burn(ctx) }`, or a list of `EveryConfig`
+   * entries, such as `[{ delay: (ctx) => ctx.fireEvery, run: fire }]`, whose `delay` is a number
+   * or a function of the context, read as an `after` delay is. A `run` is one function or a list
+   * run in order. An entry first runs one delay after the state is entered, then each time
+   * another delay has passed on the state's clock, which `update(dt)` advances while the state
+   * is active, from zero on each entry. It runs at most once per `update` call: a call that
+   * covers several delays runs it once, and its later runs stay on multiples of the delay. A run
+   * is not a move: no `update` hook is skipped, `always` is not rechecked and `onMove` is not
+   * called. A state's entries run where its `after` timers are tried and before them, a list in
+   * list order and the other form shortest delay first; on a call in which an `update` hook or a
+   * timer of a deeper state moved, they wait for the next call. A delay that is not a positive
+   * number throws, naming the state.
    */
-  readonly always?: AlwaysSpec<Ctx, To>;
+  readonly every?: NoInfer<
+    | {
+        readonly [seconds: number]:
+          | RunAction<Ctx, E, Tag, Hook>
+          | readonly RunAction<Ctx, E, Tag, Hook>[];
+      }
+    | readonly EveryConfig<Ctx, E, Tag, Hook>[]
+  >;
+  /**
+   * Rules taken right after any move that leaves this state active; the first whose `when` is
+   * missing or passes wins, and its `run` runs during the move. It is checked after a move only:
+   * not after a rule with no `to`, and not on an `update` call that moves nothing.
+   */
+  readonly always?: AlwaysSpec<Ctx, To, E, Tag, Hook>;
   /**
    * Runs each time the state is entered, outermost state first: on a move, at `start`, and when
    * a hot reload adds the state. It gets no event.
    */
-  readonly enter?: StateHook<Ctx, E>;
+  readonly enter?: StateHook<Ctx, E, Tag, Hook>;
   /**
    * Runs each time the state is left, deepest state first, including on `stop()`. A state a hot
    * reload removes is dropped without it.
    */
-  readonly exit?: StateHook<Ctx, E>;
+  readonly exit?: StateHook<Ctx, E, Tag, Hook>;
   /**
    * Runs on every `update(dt)` while the state is active. Return one of the machine's full paths
    * to move there, or `undefined` to stay.
    */
-  readonly update?: NoInfer<UpdateHook<Ctx, E, To>>;
+  readonly update?: NoInfer<UpdateHook<Ctx, E, To, Tag, Hook>>;
   /** Started on each entry; see `TaskStart`. */
-  readonly task?: TaskStart<Ctx, E>;
+  readonly task?: TaskStart<Ctx, E, Tag, Hook>;
+  /** Runs when the machine drops an event while the state is active; see `UnhandledHook`. */
+  readonly unhandled?: UnhandledHook<Ctx, E, Tag, Hook>;
   /** Renamed to `task`. */
   readonly invoke?: never;
 }
 
 /** @noSelf */
-interface CompoundState<Ctx, E extends EventObject, T, Self extends string, To extends string>
-  extends StateBase<Ctx, E, T, Self, To> {
+interface CompoundState<
+  Ctx,
+  E extends EventObject,
+  T,
+  Self extends string,
+  To extends string,
+  Tag extends string = never,
+  Hook extends string = string,
+> extends StateBase<Ctx, E, T, Self, To, Tag, Hook> {
   /**
    * `"parallel"` keeps every child active at once, each as a region with its own active state.
    * Not allowed on the root.
@@ -379,8 +690,15 @@ interface CompoundState<Ctx, E extends EventObject, T, Self extends string, To e
 }
 
 /** @noSelf */
-interface ParallelState<Ctx, E extends EventObject, T, Self extends string, To extends string>
-  extends StateBase<Ctx, E, T, Self, To> {
+interface ParallelState<
+  Ctx,
+  E extends EventObject,
+  T,
+  Self extends string,
+  To extends string,
+  Tag extends string = never,
+  Hook extends string = string,
+> extends StateBase<Ctx, E, T, Self, To, Tag, Hook> {
   /**
    * `"parallel"` keeps every child active at once, each as a region with its own active state.
    * Not allowed on the root.
@@ -390,51 +708,144 @@ interface ParallelState<Ctx, E extends EventObject, T, Self extends string, To e
   readonly restoreDepth?: never;
 }
 
-type StateNode<Ctx, E extends EventObject, T, Self extends string, To extends string> =
-  | CompoundState<Ctx, E, T, Self, To>
-  | ParallelState<Ctx, E, T, Self, To>;
-
-type RootState<Ctx, E extends EventObject, T> = CompoundState<
+type StateNode<
   Ctx,
-  E,
+  E extends EventObject,
   T,
-  "",
-  NoInfer<SlotPath<T>>
-> & {
+  Self extends string,
+  To extends string,
+  Tag extends string = never,
+  Hook extends string = string,
+> = CompoundState<Ctx, E, T, Self, To, Tag, Hook> | ParallelState<Ctx, E, T, Self, To, Tag, Hook>;
+
+type StateKey =
+  | keyof CompoundState<unknown, EventObject, unknown, string, string>
+  | keyof ParallelState<unknown, EventObject, unknown, string, string>;
+
+// The node tree: every key each state writes, so a state with a `states` key is a level
+// whatever its children are, and a state without one is a leaf. Each state is inferred at two
+// sites. The mapped type `NodeKeys` reads a state that holds a callback with unannotated
+// parameters beside one other slot, property by property. The bare site `InferOnly` reads a
+// state that holds no such callback whole, `{}` included, which the mapped type never reads
+// because `{}` has no property. A bare `NT[K]` in its place would intersect the state literal
+// into every slot type, and a bad target would be reported on the whole `on` object.
+type NodeLevel<NT> = { readonly [K in keyof NT]: NodeKeys<NT[K]> & InferOnly<NT[K]> };
+
+type NodeKeys<N> = { readonly [P in keyof N]: NodeSlot<P, N[P], keyof N> };
+
+// The slot value is a type argument of its own: inside the true branch of
+// `P extends "states"`, `N[P]` reads as `N[P & "states"]`, which inference does not look for,
+// and the level below would never be inferred. `NodeKeys` makes every key the config writes a
+// known property, which switches the excess-property check off for a state, so a key no state
+// has maps to `never` to keep that error. `initial` and `restoreDepth` map to `never` on a
+// state with no `states` key.
+type NodeSlot<P, V, Keys> = P extends "states"
+  ? NodeLevel<V>
+  : P extends "initial" | "restoreDepth"
+    ? "states" extends Keys
+      ? unknown
+      : never
+    : P extends StateKey
+      ? unknown
+      : never;
+
+type InferOnly<X> = X extends unknown ? unknown : X;
+
+type StatesOf<N> = N extends { readonly states: infer C } ? C : unknown;
+
+type HasStates<N> = "states" extends keyof N ? true : false;
+
+// The paths a config slot or a callback's machine accepts, read off a node tree. TypeScript
+// checks a config once before it types the callbacks, and a state that holds only callbacks
+// with unannotated parameters, or `after` and `every` lists with one in them, is `unknown` in
+// that check: it may be a leaf, or a compound state whose `initial` is missing. Such a state
+// accepts any path below it. Every other state with no `states` key accepts none.
+type NodePathsBelow<L, D extends number> = unknown extends L
+  ? string
+  : {
+      [K in keyof L & string]:
+        | K
+        | (unknown extends L[K]
+            ? `${K}/${string}`
+            : HasStates<L[K]> extends true
+              ? `${K}/${D extends 1 ? string : NodePathsBelow<StatesOf<L[K]>, PathDepth[D]>}`
+              : never);
+    }[keyof L & string];
+
+type NodePath<NT> = `/${NodePathsBelow<NT, 4>}`;
+
+// The node tree is applied to the children of `states` only; the root's own keys, `privateCtx`
+// among them, are not read into it.
+type RootState<
+  Ctx,
+  E extends EventObject,
+  T,
+  Tag extends string = never,
+  NT = unknown,
+  HT = unknown,
+> = CompoundState<Ctx, E, T, "", NoInfer<NodePath<NT>>, Tag, NoInfer<NodePath<HT>>> & {
   readonly initial: string;
   readonly states: object;
-};
+} & { readonly states: NodeLevel<NT> } & { readonly states: NodeLevel<HT> };
 
 /**
  * The config of one state. Every field is optional. A state with child `states` is a compound
  * state and needs an `initial`, unless its `type` is `"parallel"`; a state without children is a
- * leaf.
+ * leaf. `Tag` is the union of the machine's tag names. The `machine` a callback of a config
+ * typed this way receives takes any `string` path.
  */
-export type StateConfig<Ctx, E extends EventObject> = StateNode<Ctx, E, unknown, string, string>;
+export type StateConfig<Ctx, E extends EventObject, Tag extends string = never> = StateNode<
+  Ctx,
+  E,
+  unknown,
+  string,
+  string,
+  Tag
+>;
 
 /**
  * The root config passed to `defineMachine`. It takes the fields of a state and requires
- * `initial` and `states`. The root has no name and cannot be parallel.
+ * `initial` and `states`. The root has no name and cannot be parallel. `Tag` is the union of the
+ * machine's tag names. The `machine` a callback of a config typed this way receives takes any
+ * `string` path.
  */
-export type MachineConfig<Ctx, E extends EventObject> = CompoundState<
+export type MachineConfig<Ctx, E extends EventObject, Tag extends string = never> = CompoundState<
   Ctx,
   E,
   unknown,
   string,
-  string
+  string,
+  Tag
 > & {
   readonly initial: string;
-  readonly states: { readonly [name: string]: StateConfig<Ctx, E> };
+  readonly states: { readonly [name: string]: StateConfig<Ctx, E, Tag> };
 };
 
-type Guard<Ctx, E extends EventObject> = (ctx: Ctx, event: E) => boolean;
+type Guard<Ctx, E extends EventObject> = (ctx: Ctx, event: E, machine: MachineView) => boolean;
 
 interface Transition<Ctx, E extends EventObject> {
   readonly target: number;
   readonly when: Guard<Ctx, E> | undefined;
   readonly run: readonly MoveAction<Ctx, E>[];
+  // Set on an after timer only, whose sorted position is not its entry: the delay of a record
+  // entry, the index of a list entry.
+  key?: number;
 }
 
+/**
+ * How the core calls a `MoveListener`: the declared arguments, then the path of the state whose
+ * rule made the move and that rule's key. `MoveListener` declares neither.
+ * @noSelf
+ */
+type MoveReport<E extends EventObject> = (
+  from: string,
+  to: string | undefined,
+  cause: MoveCause,
+  event: E | undefined,
+  source: string | undefined,
+  key: number | undefined,
+) => void;
+
 type Delay<Ctx> = number | ((ctx: Ctx) => number);
 
 interface Compiled<Ctx, E extends EventObject> {
@@ -452,13 +863,18 @@ interface Compiled<Ctx, E extends EventObject> {
   readonly onIndex: { [type: string]: number }[];
   readonly transitions: Transition<Ctx, E>[][];
   readonly afterDelays: number[][];
-  readonly afterTargets: number[][];
+  readonly afterRules: Transition<Ctx, E>[][];
   // Set only for a state whose after list holds a delay function: its entries in list order,
   // for each instance to sort once the function is read.
   readonly afterListDelays: (Delay<Ctx>[] | undefined)[];
-  readonly afterListTargets: (number[] | undefined)[];
+  readonly afterListRules: (Transition<Ctx, E>[] | undefined)[];
+  // A state's every entries: the record form in delay order, a list in list order.
+  readonly everyDelays: Delay<Ctx>[][];
+  readonly everyRuns: RunAction<Ctx, E>[][][];
   readonly always: Transition<Ctx, E>[][];
   readonly pathIndex: { [path: string]: number };
+  // For each tag, the states that carry it.
+  readonly tagStates: { [tag: string]: number[] };
 }
 
 const ROOT = 0;
@@ -493,10 +909,13 @@ 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.
+// A structural cast keeps each read a plain method call: native in JavaScript, string.byte and
+// string.sub in Lua.
 interface StringUnits {
   charCodeAt(index: number): number;
   byte(index: number): number;
+  substring(start: number, end: number): string;
+  sub(first: number, last: number): string;
 }
 
 // JavaScript strings hold UTF-16 code units; Lua strings hold UTF-8 bytes.
@@ -510,6 +929,36 @@ function unitAt(text: string, index: number): number {
   return units.byte(index + 1);
 }
 
+const SLASH = 47;
+
+// The state at path, or at its closest parent that exists: the path loses its last name until
+// a state has it, and the root stands in when none does.
+function closestState<Ctx, E extends EventObject>(
+  compiled: Compiled<Ctx, E>,
+  path: string,
+): number {
+  let text = path;
+  while (true) {
+    const state = lookupPath(compiled, text);
+    if (state !== undefined) {
+      return state;
+    }
+    let cut = text.length - 1;
+    while (cut > 0 && unitAt(text, cut) !== SLASH) {
+      cut--;
+    }
+    if (cut <= 0) {
+      return ROOT;
+    }
+    const units = text as unknown as StringUnits;
+    if (UTF16_UNITS) {
+      text = units.substring(0, cut);
+    } else {
+      text = units.sub(1, cut);
+    }
+  }
+}
+
 // 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 {
@@ -553,6 +1002,18 @@ function registerState<Ctx, E extends EventObject>(
   compiled.levels[index] = 0;
   compiled.records[index] = false;
   compiled.pathIndex[path] = index;
+  const tags = config.tags as readonly string[] | undefined;
+  if (tags !== undefined) {
+    for (let i = 0; i < tags.length; i++) {
+      const tag = tags[i] as string;
+      let carriers = compiled.tagStates[tag];
+      if (carriers === undefined) {
+        carriers = [];
+        compiled.tagStates[tag] = carriers;
+      }
+      carriers.push(index);
+    }
+  }
   const children = config.states;
   if (children === undefined) {
     return;
@@ -682,6 +1143,20 @@ function compileRecords<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>):
   }
 }
 
+// A run is one function or a list of them; either way it compiles to a list.
+function collectRun<Action>(declared: Action | readonly Action[] | undefined): Action[] {
+  const run: Action[] = [];
+  if (typeof declared === "function") {
+    run.push(declared);
+  } else if (declared !== undefined) {
+    const list = declared as readonly Action[];
+    for (let i = 0; i < list.length; i++) {
+      run.push(list[i] as Action);
+    }
+  }
+  return run;
+}
+
 function compileTransition<Ctx, E extends EventObject>(
   compiled: Compiled<Ctx, E>,
   source: number,
@@ -694,19 +1169,10 @@ function compileTransition<Ctx, E extends EventObject>(
       run: [],
     };
   }
-  const run: MoveAction<Ctx, E>[] = [];
-  const declared = spec.run;
-  if (typeof declared === "function") {
-    run.push(declared);
-  } else if (declared !== undefined) {
-    for (let i = 0; i < declared.length; i++) {
-      run.push(declared[i] as MoveAction<Ctx, E>);
-    }
-  }
   return {
     target: spec.to === undefined ? NO_STATE : resolveTarget(compiled, source, spec.to),
     when: spec.when,
-    run,
+    run: collectRun<MoveAction<Ctx, E>>(spec.run),
   };
 }
 
@@ -750,18 +1216,18 @@ function compileAlways<Ctx, E extends EventObject>(
   // Read as an array type: the transpiler shifts an index to Lua's base 1 only on an array.
   const spec = (compiled.configs[index] as StateConfig<Ctx, E>).always as
     | string
-    | AlwaysConfig<Ctx>
-    | readonly AlwaysConfig<Ctx>[]
+    | AlwaysConfig<Ctx, string, E>
+    | readonly AlwaysConfig<Ctx, string, E>[]
     | undefined;
   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>[]);
+  const candidates: readonly (string | AlwaysConfig<Ctx, string, E>)[] =
+    typeof spec === "string" || (spec as readonly AlwaysConfig<Ctx, string, E>[])[0] === undefined
+      ? [spec as string | AlwaysConfig<Ctx, string, E>]
+      : (spec as readonly AlwaysConfig<Ctx, string, E>[]);
   for (let i = 0; i < candidates.length; i++) {
-    const candidate = candidates[i] as string | AlwaysConfig<Ctx>;
+    const candidate = candidates[i] as string | AlwaysConfig<Ctx, string, E>;
     if (typeof candidate !== "string" && candidate.to === undefined) {
       throw `hsm: state "${describePath(compiled.paths[index] as string)}" has an always transition with no "to"`;
     }
@@ -796,45 +1262,79 @@ function checkDelay(path: string, delay: unknown, written: unknown): void {
   }
 }
 
-// Keeps the delays ascending; timers with one delay stay in the order they were added.
-function insertTimer(delays: number[], targets: number[], delay: number, target: number): void {
+// Keeps the delays ascending; timers with one delay stay in the order they were added. Each
+// delay carries one item: a timer's rule, or the run of an every entry.
+function insertTimer<Item>(delays: number[], items: Item[], delay: number, item: Item): void {
   let slot = delays.length;
   while (slot > 0 && (delays[slot - 1] as number) > delay) {
     delays[slot] = delays[slot - 1] as number;
-    targets[slot] = targets[slot - 1] as number;
+    items[slot] = items[slot - 1] as Item;
     slot--;
   }
   delays[slot] = delay;
-  targets[slot] = target;
+  items[slot] = item;
+}
+
+// For each entry of an after list, the position of its rule among the sorted timers.
+function entryPositions<Ctx, E extends EventObject>(
+  list: Transition<Ctx, E>[],
+  sorted: Transition<Ctx, E>[],
+): number[] {
+  const positions: number[] = [];
+  for (let entry = 0; entry < list.length; entry++) {
+    let at = 0;
+    while (at < sorted.length && sorted[at] !== list[entry]) {
+      at++;
+    }
+    positions[entry] = at;
+  }
+  return positions;
+}
+
+function compileTimer<Ctx, E extends EventObject>(
+  compiled: Compiled<Ctx, E>,
+  index: number,
+  spec: string | AfterRule<Ctx, string, E>,
+  key: number,
+): Transition<Ctx, E> {
+  const rule = compileTransition(compiled, index, spec as string | TransitionConfig<Ctx, E>);
+  if (rule.target === NO_STATE && rule.run.length === 0) {
+    throw `hsm: state "${describePath(compiled.paths[index] as string)}" has an after timer with no "to" and no "run"`;
+  }
+  rule.key = key;
+  return rule;
 }
 
 function compileAfter<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, index: number): void {
   const delays: number[] = [];
-  const targets: number[] = [];
+  const rules: Transition<Ctx, E>[] = [];
   compiled.afterDelays[index] = delays;
-  compiled.afterTargets[index] = targets;
+  compiled.afterRules[index] = rules;
   const after = (compiled.configs[index] as StateConfig<Ctx, E>).after;
   if (after === undefined) {
     return;
   }
   const path = compiled.paths[index] as string;
   // Read as an array type: the transpiler shifts an index to Lua's base 1 only on an array.
-  const list = after as readonly AfterConfig<Ctx>[];
-  if (typeof list[0] !== "object") {
-    const byDelay = after as { readonly [seconds: number]: string };
+  const list = after as readonly AfterConfig<Ctx, string, E>[];
+  const first = list[0];
+  // A rule object under the delay 0, or under 1 in Lua where the read is shifted, is an object
+  // too, so the list form is the one whose first entry has a delay.
+  if (typeof first !== "object" || first.delay === undefined) {
+    const byDelay = after as { readonly [seconds: number]: string | AfterRule<Ctx, string, E> };
     for (const key in byDelay) {
       const delay = parseDelay(key);
       checkDelay(path, delay, key);
-      const target = resolveTarget(compiled, index, byDelay[key as unknown as number] as string);
-      insertTimer(delays, targets, delay, target);
+      const spec = byDelay[key as unknown as number] as string | AfterRule<Ctx, string, E>;
+      insertTimer(delays, rules, delay, compileTimer(compiled, index, spec, delay));
     }
     return;
   }
   const listDelays: Delay<Ctx>[] = [];
-  const listTargets: number[] = [];
+  const listRules: Transition<Ctx, E>[] = [];
   let perInstance = false;
   for (let i = 0; i < list.length; i++) {
-    const entry = list[i] as AfterConfig<Ctx>;
+    const entry = list[i] as AfterConfig<Ctx, string, E>;
     const delay = entry.delay;
     if (typeof delay === "function") {
       perInstance = true;
@@ -842,15 +1342,82 @@ function compileAfter<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, in
       checkDelay(path, delay, delay);
     }
     listDelays[i] = delay;
-    listTargets[i] = resolveTarget(compiled, index, entry.to);
+    listRules[i] = compileTimer(compiled, index, entry, i);
   }
   if (perInstance) {
     compiled.afterListDelays[index] = listDelays;
-    compiled.afterListTargets[index] = listTargets;
+    compiled.afterListRules[index] = listRules;
     return;
   }
   for (let i = 0; i < listDelays.length; i++) {
-    insertTimer(delays, targets, listDelays[i] as number, listTargets[i] as number);
+    insertTimer(delays, rules, listDelays[i] as number, listRules[i] as Transition<Ctx, E>);
+  }
+}
+
+// NaN fails the comparison, so it is rejected with zero and the negative numbers.
+function checkEveryDelay(path: string, delay: unknown, written: unknown): void {
+  if (typeof delay !== "number" || !(delay > 0)) {
+    throw `hsm: state "${describePath(path)}" has an every delay "${written}" that is not a positive number`;
+  }
+}
+
+// The first multiple of delay above clock. Rounding can leave the product at or below the
+// clock, and one more delay lifts it past.
+function nextRun(clock: number, delay: number): number {
+  const at = (Math.floor(clock / delay) + 1) * delay;
+  if (at > clock) {
+    return at;
+  }
+  return at + delay;
+}
+
+function compileEveryRun<Ctx, E extends EventObject>(
+  path: string,
+  declared: RunAction<Ctx, E> | readonly RunAction<Ctx, E>[] | undefined,
+): RunAction<Ctx, E>[] {
+  const run = collectRun<RunAction<Ctx, E>>(declared);
+  if (run.length === 0) {
+    throw `hsm: state "${describePath(path)}" has an every entry with no "run"`;
+  }
+  return run;
+}
+
+function compileEvery<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, index: number): void {
+  const delays: Delay<Ctx>[] = [];
+  const runs: RunAction<Ctx, E>[][] = [];
+  compiled.everyDelays[index] = delays;
+  compiled.everyRuns[index] = runs;
+  const every = (compiled.configs[index] as StateConfig<Ctx, E>).every;
+  if (every === undefined) {
+    return;
+  }
+  const path = compiled.paths[index] as string;
+  // Read as an array type: the transpiler shifts an index to Lua's base 1 only on an array.
+  const list = every as readonly EveryConfig<Ctx, E>[];
+  const first = list[0];
+  // A run list under the delay 0, or under 1 in Lua where the read is shifted, is an object
+  // too, so the list form is the one whose first entry has a delay.
+  if (typeof first !== "object" || first.delay === undefined) {
+    const byDelay = every as {
+      readonly [seconds: number]: RunAction<Ctx, E> | readonly RunAction<Ctx, E>[];
+    };
+    // Lua's pairs walks number keys in no fixed order, so the entries are sorted by delay.
+    for (const key in byDelay) {
+      const delay = parseDelay(key);
+      checkEveryDelay(path, delay, key);
+      const run = compileEveryRun(path, byDelay[key as unknown as number]);
+      insertTimer(delays as number[], runs, delay, run);
+    }
+    return;
+  }
+  for (let i = 0; i < list.length; i++) {
+    const entry = list[i] as EveryConfig<Ctx, E>;
+    const delay = entry.delay;
+    if (typeof delay !== "function") {
+      checkEveryDelay(path, delay, delay);
+    }
+    delays[i] = delay;
+    runs[i] = compileEveryRun(path, entry.run);
   }
 }
 
@@ -870,17 +1437,24 @@ function compile<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>): Com
     onIndex: [],
     transitions: [],
     afterDelays: [],
-    afterTargets: [],
+    afterRules: [],
     afterListDelays: [],
-    afterListTargets: [],
+    afterListRules: [],
+    everyDelays: [],
+    everyRuns: [],
     always: [],
     pathIndex: {},
+    // A JavaScript object inherits members such as `__proto__` and `constructor`, and a tag can
+    // be named like one. This literal has no prototype, so every string is an own key. In Lua
+    // the nil field leaves a plain table.
+    tagStates: { __proto__: null } as unknown as { [tag: string]: number[] },
   };
   registerState(compiled, config, NO_STATE, "");
   for (let index = 0; index < compiled.count; index++) {
     compileInitial(compiled, index);
     compileOn(compiled, index);
     compileAfter(compiled, index);
+    compileEvery(compiled, index);
     compileAlways(compiled, index);
   }
   compileRecords(compiled);
@@ -919,6 +1493,38 @@ function transitionDomain<Ctx, E extends EventObject>(
   return domain;
 }
 
+// Reads a start position: by state, the child a compound state enters, or NO_STATE where no
+// path names one. Each path, in list order, claims the child of every compound state above the
+// state it names. A path that needs a child an earlier path claimed differently is dropped
+// whole, before it claims anything, so the first in the list wins and a dropped path leaves
+// nothing behind. Every state has an entry, so neither runtime reads a list with holes.
+function startChildren<Ctx, E extends EventObject>(
+  compiled: Compiled<Ctx, E>,
+  at: readonly string[],
+): number[] {
+  const parent = compiled.parent;
+  const chosen: number[] = [];
+  for (let state = 0; state < compiled.count; state++) {
+    chosen[state] = NO_STATE;
+  }
+  for (let i = 0; i < at.length; i++) {
+    const target = closestState(compiled, at[i] as string);
+    let free = true;
+    for (let state = target; free && state !== ROOT; state = parent[state] as number) {
+      const claimed = chosen[parent[state] as number] as number;
+      free = claimed === NO_STATE || claimed === state;
+    }
+    for (let state = target; free && state !== ROOT; state = parent[state] as number) {
+      const owner = parent[state] as number;
+      // Every region of a parallel state is entered, so it holds no choice.
+      if (compiled.parallel[owner] !== true) {
+        chosen[owner] = state;
+      }
+    }
+  }
+  return chosen;
+}
+
 interface Definition<Ctx, E extends EventObject> {
   compiled: Compiled<Ctx, E>;
   generation: number;
@@ -948,10 +1554,35 @@ function fillPrivate(
   }
 }
 
+// Copy-on-write: a report walks the list it started with, so a listener removed mid-report
+// never makes it skip another.
+function withListener<L>(list: readonly L[], listener: L): L[] {
+  const added: L[] = [];
+  for (let i = 0; i < list.length; i++) {
+    added.push(list[i] as L);
+  }
+  added.push(listener);
+  return added;
+}
+
+function withoutListener<L>(list: readonly L[], listener: L): L[] {
+  const kept: L[] = [];
+  let skipped = false;
+  for (let i = 0; i < list.length; i++) {
+    const current = list[i] as L;
+    if (current !== listener || skipped) {
+      kept.push(current);
+    } else {
+      skipped = true;
+    }
+  }
+  return kept;
+}
+
 function createMachine<Ctx, E extends EventObject>(
   definition: Definition<Ctx, E>,
 ): Machine<Ctx, E> {
-  function start(ctx: Ctx): MachineInstance<Ctx, E> {
+  function start(ctx: Ctx, at?: readonly string[]): MachineInstance<Ctx, E> {
     let compiled = definition.compiled;
     let generation = definition.generation;
     let paths = compiled.paths;
@@ -965,23 +1596,31 @@ function createMachine<Ctx, E extends EventObject>(
     let onIndex = compiled.onIndex;
     let transitions = compiled.transitions;
     let afterDelays = compiled.afterDelays;
-    let afterTargets = compiled.afterTargets;
+    let afterRules = compiled.afterRules;
     let afterListDelays = compiled.afterListDelays;
-    let afterListTargets = compiled.afterListTargets;
+    let afterListRules = compiled.afterListRules;
+    let everyDelays = compiled.everyDelays;
+    let everyRuns = compiled.everyRuns;
     let always = compiled.always;
     const activeChild: number[] = [];
     const isActive: boolean[] = [];
     const elapsed: number[] = [];
-    const fired: number[] = [];
+    // For a state with timers, which of them fired during this stay, by position in delay order.
+    const fired: (boolean[] | undefined)[] = [];
     // The sorted timers of a state whose after list holds a delay function, read on each entry.
     const ownDelays: (number[] | undefined)[] = [];
-    const ownTargets: (number[] | undefined)[] = [];
+    const ownRules: (Transition<Ctx, E>[] | undefined)[] = [];
+    // For a state with every entries, by entry: the delay it counts in this stay, and the value
+    // of the state's clock at its next run.
+    const ownEvery: (number[] | undefined)[] = [];
+    const nextRuns: (number[] | undefined)[] = [];
     const entryId: number[] = [];
     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();
+    sizeFired();
     const leaves: string[] = [];
     let entryCount = 0;
     const queue: (E | undefined)[] = [];
@@ -992,47 +1631,68 @@ function createMachine<Ctx, E extends EventObject>(
     let stopRequested = false;
     let moved = false;
     let listeners: MoveListener<E>[] = [];
+    let unhandledListeners: UnhandledListener<E>[] = [];
 
     const instance = {
       ctx,
       path: undefined as string | undefined,
       leaves,
       matches,
+      hasTag,
+      can,
       send,
       update,
       stop,
       onMove,
+      onUnhandled,
     };
 
     function clearSlot(state: number): void {
       activeChild[state] = NO_STATE;
       isActive[state] = false;
       elapsed[state] = 0;
-      fired[state] = 0;
+      fired[state] = undefined;
       ownDelays[state] = undefined;
-      ownTargets[state] = undefined;
+      ownRules[state] = undefined;
+      ownEvery[state] = undefined;
+      nextRuns[state] = undefined;
       entryId[state] = 0;
       cleanup[state] = undefined;
     }
 
     function readDelays(state: number): void {
+      const own = ownEvery[state];
+      if (own !== undefined) {
+        const declared = everyDelays[state] as Delay<Ctx>[];
+        const runAt = nextRuns[state] as number[];
+        const clock = elapsed[state] as number;
+        for (let i = 0; i < own.length; i++) {
+          let delay = declared[i] as Delay<Ctx>;
+          if (typeof delay === "function") {
+            delay = delay(ctx);
+            checkEveryDelay(paths[state] as string, delay, delay);
+          }
+          own[i] = delay;
+          runAt[i] = nextRun(clock, delay);
+        }
+      }
       const list = afterListDelays[state];
       if (list === undefined) {
         return;
       }
-      const listTargets = afterListTargets[state] as number[];
+      const listRules = afterListRules[state] as Transition<Ctx, E>[];
       const delays: number[] = [];
-      const targets: number[] = [];
+      const rules: Transition<Ctx, E>[] = [];
       for (let i = 0; i < list.length; i++) {
         let delay = list[i] as Delay<Ctx>;
         if (typeof delay === "function") {
           delay = delay(ctx);
           checkDelay(paths[state] as string, delay, delay);
         }
-        insertTimer(delays, targets, delay, listTargets[i] as number);
+        insertTimer(delays, rules, delay, listRules[i] as Transition<Ctx, E>);
       }
       ownDelays[state] = delays;
-      ownTargets[state] = targets;
+      ownRules[state] = rules;
     }
 
     function growSlots(): void {
@@ -1042,6 +1702,33 @@ function createMachine<Ctx, E extends EventObject>(
       }
     }
 
+    // The flag lists and the two lists of a state's every entries are built here, once per
+    // compiled definition: an entry and an update only write them in place.
+    function sizeFired(): void {
+      for (let state = 0; state < compiled.count; state++) {
+        const list = afterListDelays[state];
+        const count = list === undefined ? (afterDelays[state] as number[]).length : list.length;
+        if (count > 0) {
+          const flags: boolean[] = [];
+          for (let i = 0; i < count; i++) {
+            flags[i] = false;
+          }
+          fired[state] = flags;
+        }
+        const entries = (everyDelays[state] as Delay<Ctx>[]).length;
+        if (entries > 0) {
+          const own: number[] = [];
+          const runAt: number[] = [];
+          for (let i = 0; i < entries; i++) {
+            own[i] = 0;
+            runAt[i] = 0;
+          }
+          ownEvery[state] = own;
+          nextRuns[state] = runAt;
+        }
+      }
+    }
+
     function collectActive(state: number, order: number[]): void {
       order.push(state);
       const list = children[state] as number[];
@@ -1061,14 +1748,19 @@ function createMachine<Ctx, E extends EventObject>(
       collectActive(ROOT, order);
       const keptPaths: string[] = [];
       const keptElapsed: number[] = [];
-      const keptFired: number[] = [];
+      const keptFired: (boolean[] | undefined)[] = [];
+      const keptAt: (number[] | undefined)[] = [];
       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;
+        keptFired[i] = fired[state];
+        const sorted = ownRules[state];
+        if (sorted !== undefined) {
+          keptAt[i] = entryPositions(afterListRules[state] as Transition<Ctx, E>[], sorted);
+        }
         keptEntryId[i] = entryId[state] as number;
         keptCleanup[i] = cleanup[state];
       }
@@ -1088,12 +1780,15 @@ function createMachine<Ctx, E extends EventObject>(
       onIndex = compiled.onIndex;
       transitions = compiled.transitions;
       afterDelays = compiled.afterDelays;
-      afterTargets = compiled.afterTargets;
+      afterRules = compiled.afterRules;
       afterListDelays = compiled.afterListDelays;
-      afterListTargets = compiled.afterListTargets;
+      afterListRules = compiled.afterListRules;
+      everyDelays = compiled.everyDelays;
+      everyRuns = compiled.everyRuns;
       always = compiled.always;
       fillPrivate(ctx as never, configs[ROOT], true);
       growSlots();
+      sizeFired();
       const dropped: number[] = [];
       for (let i = 0; i < order.length; i++) {
         const state = lookupPath(compiled, keptPaths[i] as string);
@@ -1112,10 +1807,30 @@ function createMachine<Ctx, E extends EventObject>(
           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];
+        // After the clock is restored: an every entry next runs at the first multiple of its
+        // delay above it.
         readDelays(state);
+        // By list entry where the old and the new definition both read a delay per instance,
+        // else by position in delay order: a timer the new definition lacks is dropped, and a
+        // new one starts unfired.
+        const before = keptFired[i];
+        const flags = fired[state];
+        if (before !== undefined && flags !== undefined) {
+          const was = keptAt[i];
+          const sorted = ownRules[state];
+          if (was !== undefined && sorted !== undefined) {
+            const at = entryPositions(afterListRules[state] as Transition<Ctx, E>[], sorted);
+            for (let entry = 0; entry < was.length && entry < at.length; entry++) {
+              flags[at[entry] as number] = before[was[entry] as number] as boolean;
+            }
+          } else {
+            for (let timer = 0; timer < before.length && timer < flags.length; timer++) {
+              flags[timer] = before[timer] as boolean;
+            }
+          }
+        }
       }
       for (let i = dropped.length - 1; i >= 0; i--) {
         const run = keptCleanup[dropped[i] as number];
@@ -1135,32 +1850,27 @@ function createMachine<Ctx, E extends EventObject>(
       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;
+      listeners = withListener(listeners, listener);
       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 = withoutListener(listeners, listener);
+      };
+    }
+
+    function onUnhandled(listener: UnhandledListener<E>): () => void {
+      unhandledListeners = withListener(unhandledListeners, listener);
+      let removed = false;
+      return () => {
+        if (removed) {
+          return;
         }
-        listeners = kept;
+        removed = true;
+        unhandledListeners = withoutListener(unhandledListeners, listener);
       };
     }
 
@@ -1169,10 +1879,12 @@ function createMachine<Ctx, E extends EventObject>(
       to: string | undefined,
       cause: MoveCause,
       event: E | undefined,
+      source?: string,
+      key?: number,
     ): void {
       const current = listeners;
       for (let i = 0; i < current.length; i++) {
-        (current[i] as MoveListener<E>)(from, to, cause, event);
+        (current[i] as MoveReport<E>)(from, to, cause, event, source, key);
       }
     }
 
@@ -1209,7 +1921,12 @@ function createMachine<Ctx, E extends EventObject>(
       isActive[state] = true;
       activeChild[state] = NO_STATE;
       elapsed[state] = 0;
-      fired[state] = 0;
+      const flags = fired[state];
+      if (flags !== undefined) {
+        for (let i = 0; i < flags.length; i++) {
+          flags[i] = false;
+        }
+      }
       entryCount++;
       const id = entryCount;
       entryId[state] = id;
@@ -1342,6 +2059,26 @@ function createMachine<Ctx, E extends EventObject>(
       }
     }
 
+    // For a state already entered, at a start with a list of paths: chosen is what
+    // startChildren read from the list.
+    function enterAt(state: number, chosen: 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);
+          enterAt(list[i] as number, chosen);
+        }
+        return;
+      }
+      const child = chosen[state] as number;
+      if (child === NO_STATE) {
+        enterDefaults(state, 0);
+        return;
+      }
+      enterState(child);
+      enterAt(child, chosen);
+    }
+
     function enterMissing(state: number): void {
       if (parallel[state] === true) {
         const list = children[state] as number[];
@@ -1384,6 +2121,7 @@ function createMachine<Ctx, E extends EventObject>(
       run: readonly MoveAction<Ctx, E>[] | undefined,
       event: E | undefined,
       cause: MoveCause,
+      key?: number,
     ): void {
       if (target === NO_STATE) {
         runActions(run, event);
@@ -1404,7 +2142,7 @@ function createMachine<Ctx, E extends EventObject>(
       refreshLeaves();
       moved = true;
       if (listeners.length > 0) {
-        report(from, firstLeaf(domain), cause, event);
+        report(from, firstLeaf(domain), cause, event, paths[source] as string, key);
       }
     }
 
@@ -1432,14 +2170,14 @@ function createMachine<Ctx, E extends EventObject>(
       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)) {
+        const when = candidate.when as ((ctx: Ctx, machine: MachineView) => boolean) | undefined;
+        if (when === undefined || when(ctx, instance)) {
           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");
+          transition(state, candidate.target, candidate.run, undefined, "always", i);
           return true;
         }
       }
@@ -1450,7 +2188,14 @@ function createMachine<Ctx, E extends EventObject>(
       run: readonly MoveAction<Ctx, E>[] | undefined,
       event: E | undefined,
     ): void {
-      if (run === undefined || event === undefined) {
+      if (run === undefined) {
+        return;
+      }
+      if (event === undefined) {
+        // Only a rule outside `on` runs with no event, and its entries are RunActions.
+        for (let i = 0; i < run.length; i++) {
+          (run[i] as unknown as RunAction<Ctx, E>)(ctx, instance);
+        }
         return;
       }
       for (let i = 0; i < run.length; i++) {
@@ -1466,8 +2211,8 @@ function createMachine<Ctx, E extends EventObject>(
       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");
+        if (candidate.when === undefined || candidate.when(ctx, event, instance)) {
+          transition(state, candidate.target, candidate.run, event, "event", i);
           return true;
         }
       }
@@ -1500,6 +2245,42 @@ function createMachine<Ctx, E extends EventObject>(
       return takeEvent(state, event);
     }
 
+    // offerEvent's walk with no transition: the first region that would take the event ends
+    // the question, and one that would not leaves the state the next region's guards read.
+    // A hook can ask while a parallel state is half entered or half left, so a region answers
+    // only once it is active.
+    function wouldTake(state: number, event: E): boolean {
+      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 && wouldTake(region, event)) {
+            return true;
+          }
+        }
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE && wouldTake(child, event)) {
+        return true;
+      }
+      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 when = (list[i] as Transition<Ctx, E>).when;
+        if (when === undefined || when(ctx, event, instance)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    function can(event: E): boolean {
+      return running && !stopRequested && wouldTake(ROOT, event);
+    }
+
     function clearQueue(): void {
       while (queueHead < queueTail) {
         queue[queueHead] = undefined;
@@ -1522,13 +2303,38 @@ function createMachine<Ctx, E extends EventObject>(
       }
     }
 
+    // No hook can move the machine, so the active states are the same from the first call to
+    // the last, and the walk checks neither stopRequested nor entryId.
+    function fireUnhandledHooks(state: number, event: E): void {
+      if (parallel[state] === true) {
+        const list = children[state] as number[];
+        for (let i = 0; i < list.length; i++) {
+          fireUnhandledHooks(list[i] as number, event);
+        }
+      }
+      const child = activeChild[state] as number;
+      if (child !== NO_STATE) {
+        fireUnhandledHooks(child, event);
+      }
+      const hook = (configs[state] as StateConfig<Ctx, E>).unhandled;
+      if (hook !== undefined) {
+        hook(ctx, event, instance);
+      }
+    }
+
     function endStep(): void {
       while (!stopRequested && queueHead < queueTail) {
         const event = queue[queueHead] as E;
         queue[queueHead] = undefined;
         queueHead++;
         moved = false;
-        offerEvent(ROOT, event);
+        if (!offerEvent(ROOT, event)) {
+          fireUnhandledHooks(ROOT, event);
+          const current = unhandledListeners;
+          for (let i = 0; i < current.length; i++) {
+            (current[i] as UnhandledListener<E>)(event);
+          }
+        }
         if (moved) {
           settleAlways();
         }
@@ -1616,13 +2422,50 @@ function createMachine<Ctx, E extends EventObject>(
       if (child !== NO_STATE && fireTimers(child)) {
         return true;
       }
+      const runAt = nextRuns[state];
+      if (runAt !== undefined) {
+        const own = ownEvery[state] as number[];
+        const runs = everyRuns[state] as RunAction<Ctx, E>[][];
+        const clock = elapsed[state] as number;
+        for (let i = 0; i < runAt.length; i++) {
+          if ((runAt[i] as number) <= clock) {
+            // Set before the run and from the clock, not from the last run: a call that covers
+            // several delays runs the entry once and leaves no drift.
+            runAt[i] = nextRun(clock, own[i] as number);
+            const run = runs[i] as RunAction<Ctx, E>[];
+            for (let action = 0; action < run.length; action++) {
+              (run[action] as RunAction<Ctx, E>)(ctx, instance);
+            }
+            if (stopRequested) {
+              return true;
+            }
+          }
+        }
+      }
+      const flags = fired[state];
+      if (flags === undefined) {
+        return false;
+      }
       const delays = ownDelays[state] || (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;
-        const targets = ownTargets[state] || (afterTargets[state] as number[]);
-        transition(state, targets[next] as number, undefined, undefined, "after");
-        return true;
+      const rules = ownRules[state] || (afterRules[state] as Transition<Ctx, E>[]);
+      const due = elapsed[state] as number;
+      for (let i = 0; i < delays.length && (delays[i] as number) <= due; i++) {
+        if (flags[i] !== true) {
+          const rule = rules[i] as Transition<Ctx, E>;
+          const when = rule.when as ((ctx: Ctx, machine: MachineView) => boolean) | undefined;
+          if (when === undefined || when(ctx, instance)) {
+            // Set before the move: a `to` naming this state re-enters it, which clears the flags.
+            flags[i] = true;
+            if (rule.target !== NO_STATE) {
+              transition(state, rule.target, rule.run, undefined, "after", rule.key);
+              return true;
+            }
+            runActions(rule.run, undefined);
+            if (stopRequested) {
+              return true;
+            }
+          }
+        }
       }
       return false;
     }
@@ -1662,10 +2505,32 @@ function createMachine<Ctx, E extends EventObject>(
       return state !== undefined && state !== ROOT && isActive[state] === true;
     }
 
+    function hasTag(tag: string): boolean {
+      const carriers = compiled.tagStates[tag];
+      if (carriers === undefined) {
+        return false;
+      }
+      for (let i = 0; i < carriers.length; i++) {
+        if (isActive[carriers[i] as number] === true) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    // The whole list is read before any hook runs, so a hook that changes it changes nothing.
+    let chosen: number[] | undefined;
+    if (at !== undefined) {
+      chosen = startChildren(compiled, at);
+    }
     busy = true;
     fillPrivate(ctx as never, configs[ROOT], false);
     enterState(ROOT);
-    enterDefaults(ROOT, 0);
+    if (chosen === undefined) {
+      enterDefaults(ROOT, 0);
+    } else {
+      enterAt(ROOT, chosen);
+    }
     refreshLeaves();
     settleAlways();
     endStep();
@@ -1710,19 +2575,83 @@ type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
  * definition under it puts its states into the machine already built, so every running instance
  * sees the edit; without one, each call builds a separate machine.
  *
+ * A third type argument, as in `defineMachine<Ctx, E, Tag>()`, is a union of tag names: a state's
+ * `tags` lists some of them, and `hasTag` asks whether an active state carries one. A machine
+ * defined without it has no tags.
+ *
  * The root config may hold `privateCtx`, for a machine that keeps fields of its own, such as a
  * counter, a heat level or a list it builds up. Every hook, `when`, `run`, `task` and `update`
  * then sees those fields beside `Ctx`, while `start` takes only `Ctx` and the instance it returns
  * shows only `Ctx` in its `ctx`. A machine without fields of its own leaves `privateCtx` out.
  */
-export function defineMachine<Ctx, E extends EventObject>(
+export function defineMachine<Ctx, E extends EventObject, Tag extends string = never>(
   key?: string,
-): <T, Priv extends object = never>(
-  config: RootState<WithPrivate<Ctx, Priv>, E, T> & PrivateCtxConfig<Ctx, Priv>,
-) => Machine<Ctx, E, TreePath<T>> {
+): <T, Priv extends object = never, NT = unknown, HT = unknown>(
+  config: RootState<WithPrivate<Ctx, Priv>, E, T, Tag, NT, HT> & PrivateCtxConfig<Ctx, Priv>,
+) => Machine<Ctx, E, TreePath<T>, Tag> {
   return ((config: MachineConfig<Ctx, E>) => define(key, config)) as never;
 }
 
+/**
+ * Makes a group that counts the engine work a `task` started and tells when all of it has
+ * finished. Each `add()` returns the callback to pass to one engine call, and `wait` runs its
+ * callback once every one of them has reported.
+ *
+ * @example
+ * ```ts
+ * loading: {
+ *   task: (ctx, finish) => {
+ *     const group = waitGroup();
+ *     http.request(ctx.url, "GET", group.add());
+ *     go.animate(
+ *       ctx.curtain,
+ *       "tint.w",
+ *       go.PLAYBACK_ONCE_FORWARD,
+ *       0,
+ *       go.EASING_LINEAR,
+ *       0.5,
+ *       0,
+ *       group.add(),
+ *     );
+ *     group.wait(() => finish({ type: "READY" }));
+ *   },
+ *   on: { READY: "/playing" },
+ * },
+ * ```
+ */
+export function waitGroup(): WaitGroup {
+  let pending = 0;
+  let waiting: (() => void)[] = [];
+  return {
+    add: () => {
+      pending++;
+      let reported = false;
+      return () => {
+        if (reported) {
+          return;
+        }
+        reported = true;
+        pending--;
+        if (pending === 0 && waiting.length > 0) {
+          // Taken before the calls: an add or a wait a callback makes belongs to the next round.
+          const ready = waiting;
+          waiting = [];
+          for (const callback of ready) {
+            callback();
+          }
+        }
+      };
+    },
+    wait: (callback) => {
+      if (pending === 0) {
+        callback();
+      } else {
+        waiting.push(callback);
+      }
+    },
+  };
+}
+
 /**
  * The optional key a `defineMachine` root config takes beside `initial` and `states`.
  * @noSelf