@defold-typescript/types 0.58.0 → 0.60.0

package/dist/cli-runtime.js

@@ -7672,12 +7672,20 @@ function slotList(value) {
     return value.filter(isRecord3);
   return isRecord3(value) ? [value] : [];
 }
+function slotName(item) {
+  return stringOr3(item.name, "").replace(REQUIRED_SUFFIX, "");
+}
+function isBracketed(item) {
+  return BRACKETED_NAME.test(slotName(item));
+}
 function isFunctionName(name) {
   return name !== "None" && FUNCTION_NAME.test(name);
 }
 function mapSlot(item) {
+  const name = slotName(item);
+  const bracketed = BRACKETED_NAME.exec(name);
   const slot = {
-    name: stringOr3(item.name, "").replace(REQUIRED_SUFFIX, ""),
+    name: bracketed ? (bracketed[1] ?? "").trim() : name,
     doc: stringOr3(item.desc, ""),
     types: splitTypeTokens2(item.type)
   };
@@ -7688,18 +7696,15 @@ function mapSlot(item) {
   ];
   if (nested.length > 0)
     slot.fields = nested.map(mapSlot);
-  if (item.optional === true)
+  if (item.optional === true || bracketed)
     slot.is_optional = "True";
   return slot;
 }
+function callSlots(raw) {
+  return slotList(raw).filter((item) => stringOr3(item.name, "") !== "self");
+}
 function mapParameters(raw) {
-  const out = [];
-  for (const item of slotList(raw)) {
-    if (stringOr3(item.name, "") === "self")
-      continue;
-    out.push(mapSlot(item));
-  }
-  return out;
+  return callSlots(raw).map(mapSlot);
 }
 function escapeHtml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -7750,17 +7755,27 @@ function scriptApiToRefDoc(parsed) {
   const members = Array.isArray(table.members) ? table.members : [];
   const elements = [];
   const fnElement = (name, member) => {
+    const raw = callSlots(member.parameters ?? member.params ?? member.members);
+    const parameters = raw.map(mapSlot);
     const element = {
       type: "FUNCTION",
       name,
       description: stringOr3(member.desc, ""),
-      parameters: mapParameters(member.parameters ?? member.params ?? member.members),
+      parameters,
       returnvalues: mapParameters(member.returns ?? member.return)
     };
     const examples = examplesHtml(member.examples);
     if (examples !== "")
       element.examples = examples;
-    return element;
+    const omissible = new Set(raw.flatMap((item, index) => isBracketed(item) && parameters.slice(index + 1).some((p) => p.is_optional === undefined) ? [index] : []));
+    if (omissible.size === 0)
+      return [element];
+    const { examples: _examples, ...withoutExamples } = element;
+    const omitted = {
+      ...withoutExamples,
+      parameters: parameters.filter((_, index) => !omissible.has(index))
+    };
+    return [omitted, element];
   };
   const constantElement = (name, member) => ({
     type: "CONSTANT",
@@ -7775,7 +7790,7 @@ function scriptApiToRefDoc(parsed) {
     if (member.type === "function") {
       if (!isFunctionName(stringOr3(member.name, "")))
         continue;
-      elements.push(fnElement(`${namespace}.${stringOr3(member.name, "")}`, member));
+      elements.push(...fnElement(`${namespace}.${stringOr3(member.name, "")}`, member));
       continue;
     }
     if (isScalar(member)) {
@@ -7793,7 +7808,7 @@ function scriptApiToRefDoc(parsed) {
         const name = `${namespace}.${sub}.${stringOr3(subMember.name, "")}`;
         if (subMember.type === "function") {
           if (isFunctionName(stringOr3(subMember.name, "")))
-            elements.push(fnElement(name, subMember));
+            elements.push(...fnElement(name, subMember));
         } else if (isScalar(subMember)) {
           elements.push(constantElement(name, subMember));
         }
@@ -7809,10 +7824,11 @@ function scriptApiToRefDoc(parsed) {
 function parseScriptApi(yamlText) {
   return scriptApiToRefDoc(parse(yamlText));
 }
-var TYPE_TOKEN_ALIASES, REQUIRED_SUFFIX, FUNCTION_NAME, FENCED_BLOCK;
+var TYPE_TOKEN_ALIASES, REQUIRED_SUFFIX, BRACKETED_NAME, FUNCTION_NAME, FENCED_BLOCK;
 var init_script_api = __esm(() => {
   TYPE_TOKEN_ALIASES = new Map([["enum", "constant"]]);
   REQUIRED_SUFFIX = /\s*\(required\)$/i;
+  BRACKETED_NAME = /^\[([^[\]]+)\]$/;
   FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
   FENCED_BLOCK = /^```([\w+#.-]*)[^\n]*\n([\s\S]*?)^```[ \t]*$/gm;
 });
@@ -8891,7 +8907,7 @@ var init_regen = __esm(async () => {
       extraModules: ["../../src/editor-overloads", "../../src/editor-vm-globals"],
       factory: "defineEditorScript",
       extraExports: ["defineEditorCommand"],
-      extraTypeExports: ["EditorCommandQuery", "EditorNode"],
+      extraTypeExports: ["EditorCommand", "EditorCommandQuery", "EditorNode", "EditorScriptModule"],
       factoryFrom: "../../src/editor",
       propertyTypes: false,
       jit: false

package/dist/src/index.d.ts

@@ -3,8 +3,7 @@ export type { ApiFunction, ApiModule, ApiParameter, ApiVariable, SkipOverloadRul
 export { parseDefoldApiDoc, withholdOverloads } from "./api-doc";
 export { DEFOLD_TYPE_MAP, type Hash, type Matrix4, type Quaternion, type Url, type Vector, type Vector3, type Vector4, } from "./core-types";
 export { type DocCommentParts, type ExampleSegment, type ExampleSegmentation, examplesHtmlToMarkdown, htmlToCodeText, htmlToDocText, renderDocComment, segmentExampleRegions, splitExampleSources, } from "./doc-comment";
-export { defineEditorScript, type EditorCommand, type EditorScriptModule, } from "./editor";
-export { type EmitOptions, emitDeclarations, emitSymbolSignatures, firstSlotAlternativeOf, routeTypeDeclarations, type SlotType, type SlotTypes, type SymbolSignature, TS_IDENTIFIER, TS_RESERVED_NAMES, } from "./emit-dts";
+export { type EmitOptions, emitDeclarations, emitSymbolSignatures, firstSlotAlternativeOf, isFunctionTypeText, routeTypeDeclarations, type SlotType, type SlotTypes, type SymbolSignature, TS_IDENTIFIER, TS_RESERVED_NAMES, } from "./emit-dts";
 export { ENGINE_TYPE_NAME_OVERRIDES, engineTypeName } from "./engine-type-name";
 export { hashExampleSource, lookupExampleSegments, lookupExampleTranslations, lookupTranslation, proseLuaFences, type Translation, type TranslationStore, translateProseFences, } from "./example-store";
 export { type EngineIndexBaseRow, engineIndexBaseRows, engineIndexBaseTable, } from "./index-base-table";

package/generated/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../src/editor-overloads";
 import "../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../src/editor";

package/generated/versions/defold-1.13.0/kinds/editor-script.d.ts

@@ -10,4 +10,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/generated/versions/defold-1.13.1/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/generated/versions/defold-1.13.2/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/hsm/builder.d.ts

@@ -0,0 +1,194 @@
+// Generated from packages/hsm/src/builder.ts by `bun run --cwd packages/transpiler declarations`; do not edit.
+import { type AfterRule, type AlwaysConfig, type EventObject, type Machine, type MachineSkeleton, type MoveAction, type PrivateCtxConfig, type RunAction, type StateHook, type TaskStart, type TransitionConfig, type TreePath, type UnhandledHook, type UpdateHook, type WithPrivate } from "./index";
+type Delay<Ctx> = number | ((ctx: Readonly<Ctx>) => number);
+type EventGuard<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> = NonNullable<TransitionConfig<Ctx, E, V, P, Tag, P>["when"]>;
+type TimerGuard<Ctx, E extends EventObject, P extends string, Tag extends string> = NonNullable<AfterRule<Ctx, P, E, Tag, P>["when"]>;
+type AlwaysGuard<Ctx, E extends EventObject, P extends string, Tag extends string> = NonNullable<AlwaysConfig<Ctx, P, E, Tag, P>["when"]>;
+/**
+ * Adds behavior to a machine whose structure is a skeleton, returned by the second `buildMachine`
+ * call. `P` is the union of the skeleton's state paths, and every path a statement takes is one
+ * of them.
+ * @noSelf
+ */
+export interface MachineBuilder<Ctx, E extends EventObject, P extends string, Tag extends string = never, Priv = never> {
+    /**
+     * The builder of the state at the full path `path`, such as `/on/bright`. A path the skeleton
+     * lacks throws.
+     */
+    readonly state: (path: P) => StateBuilder<WithPrivate<Ctx, Priv>, E, P, Tag>;
+    /** The builder of the root, whose rules take an event no state below it takes. */
+    readonly root: StateBuilder<WithPrivate<Ctx, Priv>, E, P, Tag>;
+    /**
+     * Writes the statements onto the skeleton's own state objects, in list form, and passes the
+     * skeleton and the key to `defineMachine`, returning its machine. It throws, naming the state,
+     * on a rule left without its ending, and a second call throws.
+     */
+    readonly build: () => Machine<Ctx, E, P, Tag>;
+}
+/**
+ * Adds behavior to one state. Each `on`, `after`, `every` and `always` call adds one entry, in
+ * call order. A state's `on`, `every` and `always` entries are tried in that order, and its
+ * `after` timers in delay order, call order breaking ties. `enter`, `exit`, `update`, `task` and
+ * `unhandled` each take one function: a second call on the same state throws. Every call throws
+ * after `build()`.
+ * @noSelf
+ */
+export interface StateBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Adds a rule for events of type `type`, whose `when` and `run` see that variant. End it with
+     * `to`, `run` or `ignore`.
+     */
+    readonly on: <K extends E["type"]>(type: K) => EventRuleBuilder<Ctx, E, Extract<E, {
+        type: K;
+    }>, P, Tag>;
+    /**
+     * Adds a timer that fires once `delay` seconds of game time have passed in the state: a number,
+     * or a function of the context read each time the state is entered. A state's timers are tried
+     * in delay order, call order breaking ties. End it with `to` or `run`.
+     */
+    readonly after: (delay: Delay<Ctx>) => TimerRuleBuilder<Ctx, E, P, Tag>;
+    /**
+     * Adds functions run each time `delay` seconds of game time pass in the state: a number, or a
+     * function of the context read each time the state is entered. End it with `run`.
+     */
+    readonly every: (delay: Delay<Ctx>) => RunBuilder<Ctx, E, P, Tag>;
+    /** Adds a rule taken right after any move that leaves the state active. End it with `to`. */
+    readonly always: () => AlwaysRuleBuilder<Ctx, E, P, Tag>;
+    /** Sets the function run each time the state is entered. */
+    readonly enter: (hook: StateHook<Ctx, E, Tag, P>) => void;
+    /** Sets the function run each time the state is left. */
+    readonly exit: (hook: StateHook<Ctx, E, Tag, P>) => void;
+    /**
+     * Sets the function run on every `update(dt)` while the state is active, which returns a full
+     * path to move there, or `undefined` to stay.
+     */
+    readonly update: (hook: UpdateHook<Ctx, E, P, Tag, P>) => void;
+    /** Sets the work started on each entry; see `TaskStart`. */
+    readonly task: (start: TaskStart<Ctx, E, Tag, P>) => void;
+    /** Sets the function run when the machine drops an event while the state is active. */
+    readonly unhandled: (hook: UnhandledHook<Ctx, E, Tag, P>) => void;
+    /** Adds tag names that hold while the state is active, read with `hasTag`. */
+    readonly tags: (...names: Tag[]) => void;
+}
+/**
+ * The rule an `on` call added, before its ending. `build()` throws on a rule left without `to`,
+ * `run` or `ignore`.
+ * @noSelf
+ */
+export interface EventRuleBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /**
+     * Takes the rule only when `guard` returns `true`. It reads `ctx` and `event` and changes
+     * neither.
+     */
+    readonly when: (guard: EventGuard<Ctx, E, V, P, Tag>) => GuardedEventRuleBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => EventRunBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with functions run in order, with no move: no state exits or enters. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+    /**
+     * Ends the rule with nothing to do: the state takes the event, so it stops there and no rule
+     * of a parent sees it.
+     */
+    readonly ignore: () => void;
+}
+/**
+ * An `on` rule after its `when`, before its ending.
+ * @noSelf
+ */
+export interface GuardedEventRuleBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => EventRunBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with functions run in order, with no move: no state exits or enters. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+}
+/**
+ * An `on` rule after its `to`.
+ * @noSelf
+ */
+export interface EventRunBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /** Adds functions run in order during the move, after the `exit` hooks and before `enter`. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+}
+/**
+ * The timer an `after` call added, before its ending. `build()` throws on a timer left without
+ * `to` or `run`.
+ * @noSelf
+ */
+export interface TimerRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Fires the timer only when `guard` returns `true`, checked once the delay has passed and then
+     * on every `update` call until it passes. It reads `ctx` and changes nothing.
+     */
+    readonly when: (guard: TimerGuard<Ctx, E, P, Tag>) => GuardedTimerRuleBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with functions run in order when it fires, with no move. */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * An `after` timer after its `when`, before its ending.
+ * @noSelf
+ */
+export interface GuardedTimerRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Ends the timer with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with functions run in order when it fires, with no move. */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * An `every` entry, or an `after` timer or `always` rule after its `to`.
+ * @noSelf
+ */
+export interface RunBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Adds functions run in order: each time the delay passes for an `every` entry, and during the
+     * move for a timer or an `always` rule.
+     */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * The rule an `always` call added, before its `to`. `build()` throws on a rule left without one.
+ * @noSelf
+ */
+export interface AlwaysRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Takes the rule only when `guard` returns `true`. It reads `ctx` and changes nothing. */
+    readonly when: (guard: AlwaysGuard<Ctx, E, P, Tag>) => GuardedAlwaysRuleBuilder<Ctx, E, P, Tag>;
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+}
+/**
+ * An `always` rule after its `when`, before its `to`.
+ * @noSelf
+ */
+export interface GuardedAlwaysRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+}
+/**
+ * Defines a machine as a skeleton plus statements, in three steps. `buildMachine<Ctx, E>()` fixes
+ * the context and event types and takes an optional hot reload key, as `defineMachine` does; a
+ * third type argument is the union of tag names. The second call takes the skeleton: the root's
+ * `initial` and `states`, an optional `privateCtx`, and on each state only `initial`, `states`,
+ * `type` and `restoreDepth`. It returns a `MachineBuilder`, whose `state(path)` and `root` add
+ * behavior one statement at a time, and whose `build()` defines the machine.
+ *
+ * @example
+ * ```ts
+ * type LampEvent = { type: "TOGGLE" } | { type: "DIM" };
+ *
+ * const m = buildMachine<object, LampEvent>("lamp")({
+ *   initial: "/off",
+ *   states: {
+ *     off: {},
+ *     on: { initial: "/on/bright", states: { bright: {}, dim: {} } },
+ *   },
+ * });
+ * m.state("/off").on("TOGGLE").to("/on");
+ * m.state("/on").on("TOGGLE").to("/off");
+ * m.state("/on/bright").on("DIM").to("/on/dim");
+ *
+ * export const lamp = m.build();
+ * ```
+ */
+export declare function buildMachine<Ctx, E extends EventObject, Tag extends string = never>(key?: string): <T, Priv extends object = never>(skeleton: MachineSkeleton<T> & PrivateCtxConfig<Ctx, Priv>) => MachineBuilder<Ctx, E, TreePath<T>, Tag, Priv>;
+export {};

package/hsm/index.d.ts

@@ -345,7 +345,12 @@ type NextCount = [never, 2, 3, 4, 5, 6];
 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 union of the state paths of the tree `T`, each with its leading `/`: `T` holds one key per
+ * state name, and a leaf is `unknown`. Paths are spelled out four levels deep; below that, any
+ * string under a fourth-level path is accepted.
+ */
+export type TreePath<T> = `/${TreePathsBelow<T, 4>}`;
 type TreeOf<C> = C extends {
     readonly states: infer Children;
 } ? {
@@ -515,7 +520,87 @@ export type MachineConfig<Ctx, E extends EventObject, Tag extends string = never
         readonly [name: string]: StateConfig<Ctx, E, Tag>;
     };
 };
-type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
+interface SkeletonBehavior {
+    /** Not taken in a skeleton: add tags with the state builder's `tags`. */
+    readonly tags?: never;
+    /** Not taken in a skeleton: add rules with the state builder's `on`. */
+    readonly on?: never;
+    /** Not taken in a skeleton: add timers with the state builder's `after`. */
+    readonly after?: never;
+    /** Not taken in a skeleton: add repeated runs with the state builder's `every`. */
+    readonly every?: never;
+    /** Not taken in a skeleton: add rules with the state builder's `always`. */
+    readonly always?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `enter`. */
+    readonly enter?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `exit`. */
+    readonly exit?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `update`. */
+    readonly update?: never;
+    /** Not taken in a skeleton: add the task with the state builder's `task`. */
+    readonly task?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `unhandled`. */
+    readonly unhandled?: never;
+}
+interface SkeletonState<T, Self extends string> extends SkeletonBehavior {
+    /** Child states, by name. A name is non-empty and contains no `/`. */
+    readonly states?: {
+        readonly [K in keyof T]: SkeletonNode<T[K], `${Self}/${K & string}`>;
+    };
+}
+interface CompoundSkeleton<T, Self extends string> extends SkeletonState<T, Self> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     */
+    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. Not taken on a leaf.
+     */
+    readonly initial?: NoInfer<unknown extends T ? never : `${Self}/${keyof T & string}`>;
+    /**
+     * Makes the state remember which child was active when it was last left, and enter it again
+     * instead of `initial`; see `restoreDepth` on a state config. Not taken on a leaf.
+     */
+    readonly restoreDepth?: NoInfer<unknown extends T ? never : TreeDepth<T, 4> | "all">;
+}
+interface ParallelSkeleton<T, Self extends string> extends SkeletonState<T, Self> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     */
+    readonly type: "parallel";
+    /** Not taken on a parallel state: every child is entered. */
+    readonly initial?: never;
+    /** Not taken on a parallel state: only a compound state resumes a child. */
+    readonly restoreDepth?: never;
+}
+type SkeletonNode<T, Self extends string> = CompoundSkeleton<T, Self> | ParallelSkeleton<T, Self>;
+/**
+ * The skeleton `buildMachine` takes: the structure of a machine with no behavior. The root holds
+ * `initial` and `states`, and each state only `initial`, `states`, `type` and `restoreDepth`, each
+ * checked as in a `defineMachine` config. `T` is the state tree read from the `states` keys, and
+ * fixes the paths every statement takes.
+ */
+export type MachineSkeleton<T> = SkeletonBehavior & {
+    /** The full path of the child entered at `start`, such as `/idle`. */
+    readonly initial: NoInfer<`/${keyof T & string}`>;
+    /** The machine's states, by name. A name is non-empty and contains no `/`. */
+    readonly states: {
+        readonly [K in keyof T]: SkeletonNode<T[K], `/${K & string}`>;
+    };
+    /** Not allowed on the root: put the regions in a child state. */
+    readonly type?: never;
+    /**
+     * Makes every state the count reaches remember its last child; see `restoreDepth` on a state
+     * config.
+     */
+    readonly restoreDepth?: NoInfer<TreeDepth<T, 4> | "all">;
+};
+/**
+ * The context a machine's hooks see: `Ctx` for a machine without `privateCtx`, and `Ctx & Priv`
+ * for one whose `privateCtx` returns `Priv`.
+ */
+export type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,9 @@
     "./hsm/async": {
       "types": "./hsm/async.d.ts"
     },
+    "./hsm/builder": {
+      "types": "./hsm/builder.d.ts"
+    },
     "./hsm/debug": {
       "types": "./hsm/debug.d.ts"
     },

package/scripts/regen.ts

@@ -1145,7 +1145,7 @@ export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
     extraModules: ["../../src/editor-overloads", "../../src/editor-vm-globals"],
     factory: "defineEditorScript",
     extraExports: ["defineEditorCommand"],
-    extraTypeExports: ["EditorCommandQuery", "EditorNode"],
+    extraTypeExports: ["EditorCommand", "EditorCommandQuery", "EditorNode", "EditorScriptModule"],
     factoryFrom: "../../src/editor",
     propertyTypes: false,
     jit: false,

package/src/emit-dts.ts

@@ -6503,7 +6503,7 @@ function parameterType(
   return added.length === 0 ? kept : `${kept} | ${added.join(" | ")}`;
 }
 
-function isFunctionTypeText(ts: string): boolean {
+export function isFunctionTypeText(ts: string): boolean {
   let depth = 0;
   for (let i = 0; i < ts.length - 1; i++) {
     const c = ts[i];

package/src/index.ts

@@ -50,16 +50,12 @@ export {
   segmentExampleRegions,
   splitExampleSources,
 } from "./doc-comment";
-export {
-  defineEditorScript,
-  type EditorCommand,
-  type EditorScriptModule,
-} from "./editor";
 export {
   type EmitOptions,
   emitDeclarations,
   emitSymbolSignatures,
   firstSlotAlternativeOf,
+  isFunctionTypeText,
   routeTypeDeclarations,
   type SlotType,
   type SlotTypes,

package/src/script-api.ts

@@ -71,6 +71,18 @@ function slotList(value: unknown): Record<string, unknown>[] {
 // every slot is already required unless flagged optional, so the suffix is noise.
 const REQUIRED_SUFFIX = /\s*\(required\)$/i;
 
+// Upstream writes an omissible slot in call-syntax brackets (`[options]`), the
+// same convention its own `desc` prose uses for an optional argument.
+const BRACKETED_NAME = /^\[([^[\]]+)\]$/;
+
+function slotName(item: Record<string, unknown>): string {
+  return stringOr(item.name, "").replace(REQUIRED_SUFFIX, "");
+}
+
+function isBracketed(item: Record<string, unknown>): boolean {
+  return BRACKETED_NAME.test(slotName(item));
+}
+
 // Generators emit placeholder or C-signature names (`None`, `int JoinRandomRoom`)
 // that cannot form a Lua member access, so no page or declaration can carry them.
 const FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -80,8 +92,10 @@ function isFunctionName(name: string): boolean {
 }
 
 function mapSlot(item: Record<string, unknown>): RefDocParameter {
+  const name = slotName(item);
+  const bracketed = BRACKETED_NAME.exec(name);
   const slot: RefDocParameter = {
-    name: stringOr(item.name, "").replace(REQUIRED_SUFFIX, ""),
+    name: bracketed ? (bracketed[1] ?? "").trim() : name,
     doc: stringOr(item.desc, ""),
     types: splitTypeTokens(item.type),
   };
@@ -94,19 +108,18 @@ function mapSlot(item: Record<string, unknown>): RefDocParameter {
     ...slotList(item.members),
   ];
   if (nested.length > 0) slot.fields = nested.map(mapSlot);
-  if (item.optional === true) slot.is_optional = "True";
+  if (item.optional === true || bracketed) slot.is_optional = "True";
   return slot;
 }
 
+// The script_api lists the implicit `self` the engine passes; the emitter
+// stamps @noSelfInFile, so generated signatures must not declare it.
+function callSlots(raw: unknown): Record<string, unknown>[] {
+  return slotList(raw).filter((item) => stringOr(item.name, "") !== "self");
+}
+
 function mapParameters(raw: unknown): RefDocParameter[] {
-  const out: RefDocParameter[] = [];
-  for (const item of slotList(raw)) {
-    // The script_api lists the implicit `self` the engine passes; the emitter
-    // stamps @noSelfInFile, so generated signatures must not declare it.
-    if (stringOr(item.name, "") === "self") continue;
-    out.push(mapSlot(item));
-  }
-  return out;
+  return callSlots(raw).map(mapSlot);
 }
 
 function escapeHtml(text: string): string {
@@ -166,7 +179,11 @@ function isScalar(member: Record<string, unknown>): boolean {
  * present of `parameters:`, `params:` or `members:` and its returns from
  * `returns:` or `return:`, any slot list may be a single mapping, a table slot's
  * `members:` nest like `fields:`, a `(REQUIRED)` name suffix is dropped, and a
- * function named `None` or not a Lua identifier is skipped.
+ * function named `None` or not a Lua identifier is skipped. A slot or field
+ * named in brackets (`[options]`) takes the bare name and `is_optional`, and a
+ * function with such a slot before a slot that is not optional is also
+ * converted, first and without its examples, as a form that leaves out every
+ * such bracketed slot.
  */
 export function scriptApiToRefDoc(parsed: unknown): RefDoc {
   if (!Array.isArray(parsed)) {
@@ -188,17 +205,35 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
   }
   const members = Array.isArray(table.members) ? table.members : [];
   const elements: RefDocElement[] = [];
-  const fnElement = (name: string, member: Record<string, unknown>): RefDocFunctionElement => {
+  const fnElement = (name: string, member: Record<string, unknown>): RefDocFunctionElement[] => {
+    const raw = callSlots(member.parameters ?? member.params ?? member.members);
+    const parameters = raw.map(mapSlot);
     const element: RefDocFunctionElement = {
       type: "FUNCTION",
       name,
       description: stringOr(member.desc, ""),
-      parameters: mapParameters(member.parameters ?? member.params ?? member.members),
+      parameters,
       returnvalues: mapParameters(member.returns ?? member.return),
     };
     const examples = examplesHtml(member.examples);
     if (examples !== "") element.examples = examples;
-    return element;
+    // A bracketed slot a required one follows can only be left out by a call
+    // that skips it, so that call gets its own form; an explicit
+    // `optional: true` slot reads as passable-nil instead and gets none.
+    const omissible = new Set(
+      raw.flatMap((item, index) =>
+        isBracketed(item) && parameters.slice(index + 1).some((p) => p.is_optional === undefined)
+          ? [index]
+          : [],
+      ),
+    );
+    if (omissible.size === 0) return [element];
+    const { examples: _examples, ...withoutExamples } = element;
+    const omitted: RefDocFunctionElement = {
+      ...withoutExamples,
+      parameters: parameters.filter((_, index) => !omissible.has(index)),
+    };
+    return [omitted, element];
   };
   const constantElement = (
     name: string,
@@ -214,7 +249,7 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
     if (!isRecord(member)) continue;
     if (member.type === "function") {
       if (!isFunctionName(stringOr(member.name, ""))) continue;
-      elements.push(fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
+      elements.push(...fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
       continue;
     }
     if (isScalar(member)) {
@@ -233,7 +268,7 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
         const name = `${namespace}.${sub}.${stringOr(subMember.name, "")}`;
         if (subMember.type === "function") {
           if (isFunctionName(stringOr(subMember.name, "")))
-            elements.push(fnElement(name, subMember));
+            elements.push(...fnElement(name, subMember));
         } else if (isScalar(subMember)) {
           elements.push(constantElement(name, subMember));
         }