@defold-typescript/transpiler 0.44.1 → 0.46.0

package/dist/hsm/async.ts

@@ -1,8 +1,20 @@
 import type { EventObject, TaskStart } from "./index";
 
-/** @noSelf */
+/**
+ * The second argument of a `sequence` function: a wait that leaving the state cancels, and a flag
+ * that tells the state was left.
+ * @noSelf
+ */
 export interface SequenceSignal {
+  /**
+   * Turns `true` once the state is left. Check it after awaiting anything other than `wait`: such
+   * a promise can still resolve after the state is left, and the code after it then runs.
+   */
   readonly aborted: boolean;
+  /**
+   * Resolves after `seconds`, counted by `timer.delay` rather than by `update(dt)`. A wait still
+   * pending when the state is left never resolves, so the code after it does not run.
+   */
   readonly wait: (seconds: number) => Promise<void>;
 }
 
@@ -32,6 +44,12 @@ function rethrow(reason: unknown): void {
 
 // The sequence plugs into the state's task, so its cleanup cancels the pending
 // waits on every way out of the state; a wait left pending is never resolved.
+/**
+ * Turns an `async` function into a state's `task`. The function gets the context and a
+ * `SequenceSignal`, and the event it returns is sent to the machine; one returned after the state
+ * is left is ignored. An error thrown inside it leaves the machine where it is and is raised
+ * again from a timer callback, so it shows in the engine console.
+ */
 export function sequence<Ctx, E extends EventObject>(
   // biome-ignore lint/suspicious/noConfusingVoidType: `void` lets a sequence end without returning an event.
   run: (ctx: Ctx, signal: SequenceSignal) => Promise<NoInfer<E> | void>,

package/dist/hsm/debug.ts

@@ -1,7 +1,15 @@
 import type { EventObject, MachineInstance } from "./index";
 
-/** @noSelf */
+/**
+ * Returned by `inspect`. Keep it on `self` and call its `draw` from `update`.
+ * @noSelf
+ */
 export interface MachineInspector {
+  /**
+   * Draws the label and the active leaves as debug text, 40 units above `target`'s world
+   * position. Each call also advances the frame number the console lines show. In a release
+   * build it does nothing.
+   */
   readonly draw: (target: Hash | Url | string) => void;
 }
 
@@ -86,6 +94,12 @@ function shownLeaves(leaves: readonly string[]): string {
   return leaves.length === 0 ? "(stopped)" : shownList(leaves, raw);
 }
 
+/**
+ * Prints one line when it is called, then one line for each move `instance` makes, each starting
+ * with `hsm` and the label. Call it once after `start`. A label another `inspect` call already
+ * used gets an ordinal, such as `enemy#2`. In a release build it registers nothing and returns an
+ * inspector whose `draw` does nothing, so the calls can stay in shipped code.
+ */
 export function inspect<Ctx, E extends EventObject, P extends string>(
   instance: MachineInstance<Ctx, E, P>,
   label: string,

package/dist/hsm/defold.ts

@@ -1,9 +1,27 @@
+/**
+ * The event `messageEvents` builds from the Defold message `K`, for a machine's event union. It
+ * holds the message id as `type`, the payload fields declared through `BuiltinMessages` and
+ * `CustomMessages`, and the `sender`.
+ */
 export type MessageEvent<K extends MessageId> = K extends MessageId
-  ? { readonly type: K; readonly sender: Url } & Omit<MessagePayload<K>, "type" | "sender">
+  ? {
+      /** The message id. A payload field named `type` never overrides it. */
+      readonly type: K;
+      /** The URL the message came from. A payload field named `sender` never overrides it. */
+      readonly sender: Url;
+    } & Omit<MessagePayload<K>, "type" | "sender">
   : never;
 
-/** @noSelf */
+/**
+ * Returned by `messageEvents`. Build it once at module scope: it hashes the ids when it is
+ * created.
+ * @noSelf
+ */
 export interface MessageEventMapper<K extends MessageId> {
+  /**
+   * Turns the parameters of `on_message` into the event for that message, a new table on each
+   * call. Returns `undefined` for a message id that `messageEvents` was not given.
+   */
   readonly toEvent: (
     message_id: Hash,
     message: Record<string | number, unknown>,
@@ -11,6 +29,11 @@ export interface MessageEventMapper<K extends MessageId> {
   ) => MessageEvent<K> | undefined;
 }
 
+/**
+ * Builds a mapper that turns the Defold messages listed in `ids` into typed machine events of
+ * the shape `{ type: id, ...payload, sender }`. Call it once at module scope: the ids are hashed
+ * here.
+ */
 export function messageEvents<const K extends MessageId>(ids: readonly K[]): MessageEventMapper<K> {
   const hashes: Hash[] = [];
   for (let i = 0; i < ids.length; i++) {

package/dist/hsm/index.ts

@@ -1,10 +1,25 @@
+/**
+ * An event a machine handles: an object with a string `type`, plus any payload fields. A
+ * machine's event type is a union of these.
+ */
 export interface EventObject {
+  /** Names the event. A state's `on` takes these values as its keys. */
   readonly type: string;
 }
 
+/**
+ * What made a move happen: `event` for a sent event, `after` for a timer, `update` for a path an
+ * `update` hook returned, `always` for an `always` rule, `stop` for `stop()`, and `reload` for a
+ * hot reload that changed the current state.
+ */
 export type MoveCause = "event" | "after" | "update" | "stop" | "reload" | "always";
 
-/** @noSelf */
+/**
+ * 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.
+ * @noSelf
+ */
 export type MoveListener<E extends EventObject, P extends string = string> = (
   from: P,
   to: P | undefined,
@@ -12,14 +27,41 @@ export type MoveListener<E extends EventObject, P extends string = string> = (
   event: E | undefined,
 ) => void;
 
-/** @noSelf */
+/**
+ * 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.
+ * @noSelf
+ */
 export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
+  /** The context passed to `start`. */
   readonly ctx: Ctx;
+  /**
+   * The full path of the deepest active state, or `undefined` once stopped. In a parallel state
+   * it is the first region's leaf.
+   */
   readonly path: P | undefined;
+  /**
+   * The full path of every active leaf, in region order: one path without parallel states, empty
+   * once stopped. It is the same array on every read, updated in place.
+   */
   readonly leaves: readonly P[];
+  /** Whether the state at the full path `path` is active. Ancestors of the current state count. */
   readonly matches: (path: P) => 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.
+   */
   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.
+   */
   readonly update: (dt: number) => void;
+  /**
+   * Exits every active state, deepest first, and sets `path` to `undefined`. Called during a
+   * step, it lets that step finish and drops the queued events.
+   */
   readonly stop: () => void;
   /**
    * Adds a listener called after each move completes, with the leaf left, the leaf entered and
@@ -30,19 +72,41 @@ export interface MachineInstance<Ctx, E extends EventObject, P extends string =
   readonly onMove: (listener: MoveListener<E, P>) => () => 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.
+ */
 export type MoveAction<Ctx, E extends EventObject, V extends E = E> = (
   ctx: Ctx,
   event: V,
   machine: MachineInstance<Ctx, E>,
 ) => void;
 
-/** @noSelf */
-export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E> {
+// 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
+// `to` in the object form on that `to` only when the spec union holds no array type.
+interface RuleList<Rule> {
+  readonly 0: Rule;
+  readonly [index: number]: Rule;
+  readonly length: number;
+}
+
+/**
+ * The object form of a rule under `on`: a `to`, a `when` and a `run`, each optional. A rule with
+ * no `to` runs its `run` and nothing else: no state exits or enters.
+ * @noSelf
+ */
+export interface TransitionConfig<
+  Ctx,
+  E extends EventObject,
+  V extends E = E,
+  To extends string = string,
+> {
   /**
    * 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;
+  readonly to?: To;
   /**
    * 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.
@@ -65,15 +129,28 @@ export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E> {
   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 transition with no to.
-  | readonly [TransitionConfig<Ctx, E, V>, ...TransitionConfig<Ctx, E, V>[]];
+/**
+ * What an `on` key maps to: a target path, a `TransitionConfig`, or a non-empty list of them
+ * tried in order. The first rule with no `when`, or whose `when` returns `true`, is taken.
+ */
+export type TransitionSpec<
+  Ctx,
+  E extends EventObject,
+  V extends E = E,
+  To extends string = string,
+> = To | TransitionConfig<Ctx, E, V, To> | RuleList<TransitionConfig<Ctx, E, V, To>>;
 
-/** @noSelf */
-export interface AlwaysConfig<Ctx> {
-  readonly to: string;
+/**
+ * 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`.
+ * @noSelf
+ */
+export interface AlwaysConfig<Ctx, To 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;
   /** Renamed to `to`. */
@@ -82,13 +159,21 @@ export interface AlwaysConfig<Ctx> {
   readonly guard?: never;
 }
 
-export type AlwaysSpec<Ctx> =
-  | string
-  | AlwaysConfig<Ctx>
-  | readonly [AlwaysConfig<Ctx>, ...AlwaysConfig<Ctx>[]];
+/**
+ * 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> =
+  | To
+  | AlwaysConfig<Ctx, To>
+  | RuleList<AlwaysConfig<Ctx, To>>;
 
-export type OnConfig<Ctx, E extends EventObject> = {
-  readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, { type: K }>>;
+/**
+ * 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>;
 };
 
 /**
@@ -101,11 +186,16 @@ export type StateHook<Ctx, E extends EventObject> = (
   machine: MachineInstance<Ctx, E>,
 ) => void;
 
-export type UpdateHook<Ctx, E extends EventObject> = (
+/**
+ * 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`.
+ */
+export type UpdateHook<Ctx, E extends EventObject, To extends string = string> = (
   ctx: Ctx,
   dt: number,
   machine: MachineInstance<Ctx, E>,
-) => string | undefined;
+) => To | undefined;
 
 /**
  * Starts work that lives as long as the state. `finish` sends one event and is ignored after the
@@ -119,122 +209,203 @@ export type TaskStart<Ctx, E extends EventObject> = (
   // 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>;
-  /** 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> {
-  readonly initial: string;
-  readonly states: { readonly [name: string]: StateConfig<Ctx, E> };
-}
-
-/** @noSelf */
+/**
+ * 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> {
+  /**
+   * 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.
+   */
   readonly start: (ctx: Ctx) => MachineInstance<Ctx, E, P>;
 }
 
 type PathDepth = [never, 0, 1, 2, 3];
 
-type PathsBelow<S, D extends number> = S extends { readonly states: infer Children }
-  ? {
-      [K in keyof Children & string]:
+type NextCount = [never, 2, 3, 4, 5, 6];
+
+// The paths a started machine can be in. A node with no children is `unknown`.
+type TreePathsBelow<T, D extends number> = {
+  [K in keyof T & string]:
+    | K
+    | `${K}/${D extends 1
+        ? keyof T[K] extends never
+          ? never
+          : string
+        : TreePathsBelow<T[K], PathDepth[D]>}`;
+}[keyof T & string];
+
+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
-            ? Children[K] extends { readonly states: object }
-              ? string
-              : never
-            : PathsBelow<Children[K], PathDepth[D]>}`;
-    }[keyof Children & string]
-  : never;
+        | `${K}/${D extends 1 ? string : SlotPathsBelow<T[K], PathDepth[D]>}`;
+    }[keyof T & string];
 
-export type StatePath<C> = `/${PathsBelow<C, 4>}`;
+type SlotPath<T> = `/${SlotPathsBelow<T, 4>}`;
 
-type NextCount = [never, 2, 3, 4, 5, 6];
+type TreeOf<C> = C extends { readonly states: infer Children }
+  ? { readonly [K in keyof Children]: TreeOf<Children[K]> }
+  : unknown;
 
-type RestoreCountBelow<Children, D extends number> = {
-  [K in keyof Children]: RestoreCount<Children[K], D>;
-}[keyof Children];
+/**
+ * The union of a config's state paths, each with its leading `/`. Paths are spelled out four
+ * levels deep; below that, any string under a fourth-level path is accepted.
+ */
+export type StatePath<C> = TreePath<TreeOf<C>>;
 
-// 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]
+// The levels of child states below a node. It counts tree levels, so above a parallel state
+// it is an upper bound on the counts restoreDepth takes.
+type TreeDepth<T, D extends number> = unknown extends T
+  ? number
+  : [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 to?: T;
-  readonly when?: unknown;
-  readonly run?: unknown;
+    :
+        | 1
+        | ({
+            [K in keyof T]: unknown extends T[K] ? never : TreeDepth<T[K], PathDepth[D]>;
+          }[keyof T] extends infer N
+            ? N extends number
+              ? number extends N
+                ? number
+                : NextCount[N]
+              : never
+            : never);
+
+type AnyChild<Ctx, E extends EventObject, T, To extends string> = unknown extends T
+  ? { readonly [name: string]: StateNode<Ctx, E, unknown, string, To> }
+  : unknown;
+
+// `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.
+/** @noSelf */
+interface StateBase<Ctx, E extends EventObject, T, Self extends string, To extends 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>>;
+  /**
+   * 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>>;
+  /**
+   * Targets by delay in seconds of game time. 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.
+   */
+  readonly after?: NoInfer<{ readonly [seconds: number]: To }>;
+  /**
+   * 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.
+   */
+  readonly always?: AlwaysSpec<Ctx, To>;
+  /**
+   * 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>;
+  /**
+   * 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>;
+  /**
+   * 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>>;
+  /** Started on each entry; see `TaskStart`. */
+  readonly task?: TaskStart<Ctx, E>;
+  /** Renamed to `task`. */
+  readonly invoke?: never;
 }
 
-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 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>;
-      }
-    : unknown;
-  readonly on?: S extends { readonly on: infer On }
-    ? { readonly [K in keyof On]: K extends Ev ? SpecCheck<All> : never }
-    : unknown;
-  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 task?: unknown;
-};
+/** @noSelf */
+interface CompoundState<Ctx, E extends EventObject, T, Self extends string, To extends string>
+  extends StateBase<Ctx, E, T, Self, To> {
+  /**
+   * `"parallel"` keeps every child active at once, each as a region with its own active state.
+   * Not allowed on the root.
+   */
+  readonly type?: never;
+  /**
+   * The full path of the child entered with this state, such as `/on/bright` inside `on`.
+   * Required when `states` is set, unless the state is parallel.
+   */
+  readonly initial?: NoInfer<unknown extends T ? string : `${Self}/${keyof T & string}`>;
+  /**
+   * Makes the state remember which child was active when it was last left, and enter it again
+   * instead of `initial`. The count is how many levels down to restore, and `"all"` restores
+   * every level below the state. The first entry uses `initial`, and a move that targets a state
+   * inside this one lands on that target.
+   */
+  readonly restoreDepth?: NoInfer<TreeDepth<T, 4> | "all">;
+}
 
-export interface MachineConfigError {
-  readonly "hsm: an initial or a to names an unknown state path, or an on key an unknown event": never;
+/** @noSelf */
+interface ParallelState<Ctx, E extends EventObject, T, Self extends string, To extends string>
+  extends StateBase<Ctx, E, T, Self, To> {
+  /**
+   * `"parallel"` keeps every child active at once, each as a region with its own active state.
+   * Not allowed on the root.
+   */
+  readonly type: "parallel";
+  readonly initial?: never;
+  readonly restoreDepth?: never;
 }
 
-export type DefinedMachine<Ctx, E extends EventObject, C> =
-  C extends PathCheck<C, "", StatePath<C>, E["type"]>
-    ? Machine<Ctx, E, StatePath<C>>
-    : MachineConfigError;
+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<
+  Ctx,
+  E,
+  T,
+  "",
+  NoInfer<SlotPath<T>>
+> & {
+  readonly initial: string;
+  readonly states: object;
+};
+
+/**
+ * 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.
+ */
+export type StateConfig<Ctx, E extends EventObject> = StateNode<Ctx, E, unknown, string, string>;
+
+/**
+ * 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.
+ */
+export type MachineConfig<Ctx, E extends EventObject> = CompoundState<
+  Ctx,
+  E,
+  unknown,
+  string,
+  string
+> & {
+  readonly initial: string;
+  readonly states: { readonly [name: string]: StateConfig<Ctx, E> };
+};
 
 type Guard<Ctx, E extends EventObject> = (ctx: Ctx, event: E) => boolean;
 
@@ -550,7 +721,12 @@ function compileAlways<Ctx, E extends EventObject>(
 ): void {
   const list: Transition<Ctx, E>[] = [];
   compiled.always[index] = list;
-  const spec = (compiled.configs[index] as StateConfig<Ctx, E>).always;
+  // 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>[]
+    | undefined;
   if (spec === undefined) {
     return;
   }
@@ -1411,8 +1587,15 @@ function define<Ctx, E extends EventObject>(
 
 // Ctx and E are given explicitly and the config is inferred, so the config takes a second call.
 // A key makes a later definition under it (a hot-reloaded module re-running) rebind live instances.
+/**
+ * Defines a machine in two calls: `defineMachine<Ctx, E>()` fixes the context and event types and
+ * takes an optional hot-reload key, and the second call takes the config. The config is checked
+ * when that call runs, and a mistake throws, naming the state path. With a key, a later
+ * 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.
+ */
 export function defineMachine<Ctx, E extends EventObject>(
   key?: string,
-): <const C extends MachineConfig<Ctx, E>>(config: C) => DefinedMachine<Ctx, E, C> {
+): <T>(config: RootState<Ctx, E, T>) => Machine<Ctx, E, TreePath<T>> {
   return ((config: MachineConfig<Ctx, E>) => define(key, config)) as never;
 }

package/dist/index.js

@@ -3150,6 +3150,14 @@ function resolvedRequirePaths(sourceFile, checker) {
   }
   return paths;
 }
+var NO_RESOLUTION_MARKER = "@NoResolution:";
+function companionRequirePath(argument, paths) {
+  const resolved = paths.get(argument);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+  return argument.startsWith(NO_RESOLUTION_MARKER) ? argument.slice(NO_RESOLUTION_MARKER.length) : argument;
+}
 function resolveMovedRequires(statements, paths) {
   for (const statement of statements) {
     forEachLuaNode(statement, (node) => {
@@ -3163,10 +3171,7 @@ function resolveMovedRequires(statements, paths) {
       if (argument === undefined || !isStringLiteral7(argument)) {
         return;
       }
-      const resolved = paths.get(argument.value);
-      if (resolved !== undefined) {
-        argument.value = resolved;
-      }
+      argument.value = companionRequirePath(argument.value, paths);
     });
   }
 }
@@ -3186,8 +3191,8 @@ function withResolvedRequire(statement, paths) {
   if (argument === undefined || !isStringLiteral7(argument)) {
     return statement;
   }
-  const resolved = paths.get(argument.value);
-  if (resolved === undefined) {
+  const resolved = companionRequirePath(argument.value, paths);
+  if (resolved === argument.value) {
     return statement;
   }
   return createVariableDeclarationStatement3(createIdentifier4(name.text), createCallExpression4(createIdentifier4("require"), [createStringLiteral3(resolved)]));
@@ -3655,7 +3660,7 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     ...hsm !== undefined ? { hsmModules: hsm } : {}
   };
 }
-function transpileVirtual(files, companionEmit) {
+function transpileVirtual(files, companionEmit, overrides = {}) {
   return tstl2.transpileVirtualProject({ ...AMBIENT_FILES, ...files }, {
     luaTarget: tstl2.LuaTarget.Lua51,
     sourceMap: true,
@@ -3672,7 +3677,8 @@ function transpileVirtual(files, companionEmit) {
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin }
-    ]
+    ],
+    ...overrides
   });
 }
 function transpileProject(input) {
@@ -3697,7 +3703,7 @@ function compileHsmModules() {
     nameByKey.set(key, name);
     files[key] = readFileSync(path3.join(sourceDir, `${name}.ts`), "utf8");
   }
-  const result = transpileVirtual(files, createCompanionEmitPlugin());
+  const result = transpileVirtual(files, createCompanionEmitPlugin(), { removeComments: true });
   const problems = result.diagnostics.map((d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`);
   const lua = {};
   for (const file of result.transpiledFiles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.44.1",
+  "version": "0.46.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.44.1",
+    "@defold-typescript/types": "0.46.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"

package/src/companion-emit.ts

@@ -290,6 +290,27 @@ function resolvedRequirePaths(
   return paths;
 }
 
+/**
+ * The prefix a lowering puts on the require of a runtime module with no source in
+ * the program (`hsm`, the timers), which TSTL's resolver strips from the script.
+ */
+const NO_RESOLUTION_MARKER = "@NoResolution:";
+
+/**
+ * How the companion spells the require the Lua AST spells `argument`: a project
+ * source by its resolved path, and a marked runtime module without the marker.
+ * Left on, the marker is a path Defold cannot load and Windows cannot even name.
+ */
+function companionRequirePath(argument: string, paths: ReadonlyMap<string, string>): string {
+  const resolved = paths.get(argument);
+  if (resolved !== undefined) {
+    return resolved;
+  }
+  return argument.startsWith(NO_RESOLUTION_MARKER)
+    ? argument.slice(NO_RESOLUTION_MARKER.length)
+    : argument;
+}
+
 /**
  * Rewrites every `require` a moved statement carries, at whatever depth — a
  * re-export's is nested in the `do … end` block TSTL emits for it.
@@ -313,10 +334,7 @@ function resolveMovedRequires(
       if (argument === undefined || !isStringLiteral(argument)) {
         return;
       }
-      const resolved = paths.get(argument.value);
-      if (resolved !== undefined) {
-        argument.value = resolved;
-      }
+      argument.value = companionRequirePath(argument.value, paths);
     });
   }
 }
@@ -339,8 +357,8 @@ function withResolvedRequire(statement: Statement, paths: ReadonlyMap<string, st
   if (argument === undefined || !isStringLiteral(argument)) {
     return statement;
   }
-  const resolved = paths.get(argument.value);
-  if (resolved === undefined) {
+  const resolved = companionRequirePath(argument.value, paths);
+  if (resolved === argument.value) {
     return statement;
   }
   return createVariableDeclarationStatement(

package/src/transpile.ts

@@ -327,6 +327,7 @@ export function collectOutputs(
 function transpileVirtual(
   files: Readonly<Record<string, string>>,
   companionEmit: ReturnType<typeof createCompanionEmitPlugin>,
+  overrides: Pick<tstl.CompilerOptions, "removeComments"> = {},
 ): tstl.TranspileVirtualProjectResult {
   return tstl.transpileVirtualProject(
     { ...AMBIENT_FILES, ...files },
@@ -354,6 +355,7 @@ function transpileVirtual(
         { plugin: typeApplicationErasurePlugin },
         { plugin: companionEmit.plugin },
       ],
+      ...overrides,
     },
   );
 }
@@ -398,7 +400,9 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
     nameByKey.set(key, name);
     files[key] = readFileSync(path.join(sourceDir, `${name}.ts`), "utf8");
   }
-  const result = transpileVirtual(files, createCompanionEmitPlugin());
+  // The source's doc comments are for the editor, which reads the declarations; the Lua a
+  // project gets carries none of them.
+  const result = transpileVirtual(files, createCompanionEmitPlugin(), { removeComments: true });
 
   const problems = result.diagnostics.map(
     (d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`,