@defold-typescript/types 0.51.0 → 0.52.0

package/src/emit-dts.ts

@@ -1,5 +1,9 @@
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
-import { type ApiSymbolIdentity, normalizedFunctionSignature } from "./api-availability";
+import {
+  type ApiSymbolIdentity,
+  type Box2dBackend,
+  normalizedFunctionSignature,
+} from "./api-availability";
 import type {
   ApiConstant,
   ApiFunction,
@@ -36,6 +40,7 @@ import {
   type LualsPosition,
   mapLualsExpression,
   needsArrayParens,
+  splitTopLevel,
 } from "./luals-type-expr";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
@@ -86,8 +91,15 @@ export interface EmitOptions {
   // applies only when its key is here, so a surface with no vendored bindings
   // (absent) applies none of them.
   bindingEvidence?: ReadonlySet<string>;
+  // The 1-based parameter slots, keyed by function FQN, that the target's engine
+  // bindings let a call omit but raise on when passed nil. Each optional one
+  // splits its function into a call without the slot and a call requiring it,
+  // so a possibly-undefined value is a compile error. Absent for a surface with
+  // no vendored bindings (a ref-doc target), which keeps every `?`.
+  nilRaisingSlots?: ReadonlyMap<string, readonly number[]>;
   // The functions a target's skip rules removed from the module, read only to
-  // type an `OVERLOAD_SLOT_ALIASES` slot.
+  // type an `OVERLOAD_SLOT_ALIASES` slot and to resolve a
+  // `CONSTANT_SLOT_RESOLUTIONS` borrow from their docs.
   withheldFunctions?: readonly ApiFunction[];
 }
 
@@ -179,14 +191,12 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // runtime-owned passthrough: the table is filled by user code at runtime, never
   // by Defold's API contract. factory.create/collectionfactory.create `properties`
   // are spawn-time overrides keyed by the spawned object's own script-property
-  // names; bare `on_message`'s receive `message` is the pre-hashed, user-routed
-  // payload (mitigated for authored code by isMessage/onMessage). No static shape
-  // exists, so `Record<string | number, unknown>` is faithful, not a loss.
-  // collectionfactory.create curates the instance-id layer of `properties` as a
-  // mapping; each per-instance property table stays that faithful `Record`.
+  // names. No static shape exists, so `Record<string | number, unknown>` is
+  // faithful, not a loss. collectionfactory.create curates the instance-id layer
+  // of `properties` as a mapping; each per-instance property table stays that
+  // faithful `Record`.
   "factory.create",
   "collectionfactory.create",
-  "on_message",
   // engine-formatted blob: the engine produces the value at runtime and no
   // field list is documented, so the whole-slot `Record` is faithful, not a
   // loss. crash.get_backtrace is "table containing the backtrace",
@@ -259,6 +269,11 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "go.get",
   "go.set",
   "go.property",
+  // gui-overloads.d.ts closes the node property names and types each value per
+  // name, with a hash form for material constants.
+  "gui.animate",
+  "gui.get",
+  "gui.set",
   // msg-overloads.d.ts supplies the typed msg.post shape.
   "msg.post",
   // msg-overloads.d.ts supplies the typed msg.url shape (0 / 1-string / 3-arg
@@ -277,6 +292,7 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "vmath.slerp",
   "vmath.mul_per_elem",
   "vmath.normalize",
+  "vmath.dot",
   // sys-overloads.d.ts supplies the disabling form and the form that takes the
   // cooldown the engine requires when enabling.
   "sys.set_engine_throttle",
@@ -334,13 +350,10 @@ export const MAPPING_TABLE_SLOTS: ReadonlyMap<string, { key: string; value: stri
 ]);
 
 // FQN-keyed return-type overrides for functions whose doc `returnvalues` are
-// empty yet the engine returns a value. `gui.get`'s doc lists no return, but it
-// yields the property value (a vmath.vector4 or a number); `unknown` is the
-// honest, ts-defold-matching shape. Per-FQN, not a blanket "empty returnvalues
-// -> unknown" rule: `gui.set` also has empty returnvalues and `void` is correct
-// there.
+// empty yet the engine returns a value. Per-FQN, not a blanket "empty
+// returnvalues -> unknown" rule: most functions with empty returnvalues return
+// nothing, and `void` is correct there.
 export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
-  ["gui.get", "unknown"],
   // Upstream documents the returned transaction step in prose only — its
   // `returnvalues` is empty while every sibling `editor.tx.*` builder declares
   // one, and `editor.transact()` takes exactly that.
@@ -459,8 +472,8 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       slot: "code",
     },
   ],
-  // 1.13.2 declares `render_predicate`, whose TYPEDEF aliases `userdata`, and
-  // that still emits `number`.
+  // 1.13.2 retypes the return to `render_predicate`, whose TYPEDEF aliases
+  // `userdata`; its type mapping emits the same brand.
   [
     "render.predicate",
     {
@@ -538,6 +551,20 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       binding: tilemapEarlyNil("TileMap_GetTiles"),
     },
   ],
+  [
+    "bullet3d.shape.get_shape",
+    {
+      ts: "bullet3d.shape.definition | { type: typeof bullet3d.shape.SHAPE_TYPE_MESH }",
+      upstream: ["bullet3d.shape.definition"],
+      reason:
+        "script_bullet3d_shape.cpp:Shape_GetShape sets only `type` for a triangle mesh, which no shape definition arm matches",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/bullet3d/script_bullet3d_shape.cpp",
+        cFunction: "Shape_GetShape",
+        contains: "case TRIANGLE_MESH_SHAPE_PROXYTYPE: case GIMPACT_SHAPE_PROXYTYPE: break;",
+      },
+    },
+  ],
   [
     "collectionproxy.set_collection",
     {
@@ -757,6 +784,35 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
         },
       ] as const,
   ),
+  ...(
+    [
+      ["clone_tree", "LuaCloneTree"],
+      ["get_tree", "LuaGetTree"],
+    ] as const
+  ).map(
+    ([name, cFunction]) =>
+      [
+        `gui.${name}:param:node`,
+        {
+          adds: "undefined",
+          upstream: ["node"],
+          reason: `gui_script.cpp:${cFunction} pushes its result table before testing argument 1 with lua_isnil, so nil selects the whole scene and an absent argument reaches LuaCheckNodeInternal and raises`,
+        },
+      ] as const,
+  ),
+  ...(["get_slider_motor", "set_slider_motor"] as const).map(
+    (name) =>
+      [
+        `bullet3d.constraint.${name}:param:motor`,
+        {
+          adds: '"linear" | "angular"',
+          removes: ["string"],
+          upstream: ["string"],
+          reason:
+            "script_bullet3d_constraint.cpp:CheckSliderMotorAxis raises \"motor must be 'linear' or 'angular'\" on any other string",
+        },
+      ] as const,
+  ),
   [
     "sound.get_group_name:param:group",
     {
@@ -835,9 +891,10 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
     "render.disable_texture:param:binding",
     {
       adds: "number",
+      removes: ['Opaque<"texture">'],
       upstream: ["texture", "string", "hash"],
       reason:
-        '"texture binding, either by texture unit, string or hash"; example `render.disable_texture(0)`',
+        "render_script.cpp:RenderScript_DisableTexture reads a number as a texture unit with lua_isnumber and anything else with CheckHashOrString; a texture handle is a number, so it is read as a unit",
     },
   ],
   [
@@ -855,11 +912,42 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
       adds: 'Opaque<"render_predicate">',
       removes: ["number"],
       upstream: ["number"],
-      retypedUpstream: [["render_predicate"]],
       reason:
-        "render_script.cpp:RenderScript_Draw reads the predicate with RenderScriptPredicate_Check, the userdata render.predicate returns; 1.13.2's `render_predicate` still emits `number`",
+        "render_script.cpp:RenderScript_Draw reads the predicate with RenderScriptPredicate_Check, the userdata render.predicate returns; 1.13.2 types the slot `render_predicate`, whose type mapping is that brand",
     },
   ],
+  ...(["enable_state", "disable_state"] as const).map(
+    (name) =>
+      [
+        `render.${name}:param:state`,
+        {
+          adds: "graphics.State",
+          removes: ["graphics.STATE"],
+          upstream: ["graphics.STATE"],
+          reason: `render_script.cpp:RenderScript_${name === "enable_state" ? "Enable" : "Disable"}State raises "Invalid state" on any state but the six it lists, so graphics.STATE_SCISSOR_TEST and graphics.STATE_ALPHA_TEST_SUPPORTED are rejected`,
+        },
+      ] as const,
+  ),
+  ...(
+    [
+      "source_factor_color",
+      "destination_factor_color",
+      "source_factor_alpha",
+      "destination_factor_alpha",
+    ] as const
+  ).map(
+    (slot) =>
+      [
+        `render.set_blend_func_separate:param:${slot}`,
+        {
+          adds: "graphics.BlendFactor",
+          removes: ["number"],
+          upstream: ["number"],
+          reason:
+            'render_script.cpp:RenderScript_SetBlendFuncSeparate raises "Invalid blend factor" on any value CheckBlendFactor does not list',
+        },
+      ] as const,
+  ),
   [
     "go.delete:param:id",
     {
@@ -878,15 +966,6 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
       reason: 'sys.load_buffer example `buffer.get_bytes(my_buffer, "data")`',
     },
   ],
-  [
-    "gui.set:param:value",
-    {
-      adds: "Matrix4 | Hash",
-      upstream: ["number", "vector4", "vector3", "quaternion"],
-      reason:
-        'example `gui.set(node, "light_matrix", vmath.matrix4())` ("matrix4 is also supported"); example `gui.set(msg.url(), "textures", atlas_id, {key = "runtime_texture"})` passes the hash `resource.create_atlas` returns',
-    },
-  ],
   [
     "gui.set_rotation:param:rotation",
     {
@@ -1095,6 +1174,10 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     "render.set_render_target:param:render_target",
     "render_script.cpp:RenderScript_SetRenderTarget sets the default target when lua_gettop(L) == 0",
   ],
+  [
+    "buffer.get_bytes:param:stream_name",
+    "script_buffer.cpp:GetBytes reads only argument 1 with CheckBufferUnpack and returns every byte of the buffer",
+  ],
   ["socket.newtry:param:finalizer", "socket.protect's example `local try = socket.newtry()`"],
   ...(
     [
@@ -1237,13 +1320,6 @@ export const REQUIRED_SLOT_CORRECTIONS: ReadonlyMap<string, RequiredSlotCorrecti
       evidence: "gui_script.cpp:LuaSetParent reads a node from argument 2 unless lua_isnil(L, 2)",
     },
   ],
-  [
-    "gui.set:param:value",
-    {
-      nil: true,
-      evidence: "gui_script.cpp:LuaSet converts argument 3 with LuaToVar unless lua_isnil(L, 3)",
-    },
-  ],
   [
     "window.set_listener:param:callback",
     {
@@ -1333,6 +1409,335 @@ function firstSlotAlternative(
   return original === null ? null : { ...prepared, original };
 }
 
+// The calls a function splits into at its optional nil-raising slots
+// (`EmitOptions.nilRaisingSlots`): one ending before each such slot, then one
+// taking them all, every such slot before an arm's end declared required. A
+// required slot, or one a rest parameter folds in, splits nothing.
+function nilRaisingArms(
+  prepared: PreparedFunction,
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]>,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const firstVararg = parameters.findIndex(isVarargParameter);
+  const positional = firstVararg === -1 ? parameters.length : firstVararg;
+  const split = [...new Set(nilRaisingSlots.get(name) ?? [])]
+    .map((slot) => slot - 1)
+    .filter((index) => {
+      const p = parameters[index];
+      return index < positional && p !== undefined && isDocOptional(p, name);
+    })
+    .sort((a, b) => a - b);
+  if (split.length === 0) return [prepared];
+  const shorter = split.map((end, k) => ({
+    ...prepared,
+    original: { ...prepared.original, parameters: parameters.slice(0, end) },
+    required: new Set(split.slice(0, k)),
+  }));
+  return [...shorter, { ...prepared, required: new Set(split) }];
+}
+
+// Table fields a binding reads as required only when `argument` is non-nil,
+// keyed by FQN. A curated function splits into a call whose `table` slot requires
+// `fields`, with `argument` as declared, then a call whose `argument` is nil, so
+// a possibly-nil argument must carry them.
+export interface PresenceRequiredFields {
+  readonly argument: string;
+  readonly table: string;
+  readonly fields: readonly string[];
+  readonly reason: string;
+}
+
+const FRAME_B_FIELDS = ["frame_b_position", "frame_b_rotation"] as const;
+
+export const PRESENCE_REQUIRED_FIELDS: ReadonlyMap<string, PresenceRequiredFields> = new Map<
+  string,
+  PresenceRequiredFields
+>([
+  [
+    "bullet3d.constraint.create_point_to_point",
+    {
+      argument: "body_b",
+      table: "params",
+      fields: ["pivot_b"],
+      reason:
+        "script_bullet3d_constraint.cpp:Constraint_CreatePointToPoint reads pivot_b as required when input.m_BodyB != 0",
+    },
+  ],
+  ...(
+    [
+      ["create_hinge", "Constraint_CreateHinge"],
+      ["create_cone_twist", "Constraint_CreateConeTwist"],
+      ["create_generic_6dof", "Constraint_CreateGeneric6Dof"],
+      ["create_slider", "Constraint_CreateSlider"],
+    ] as const
+  ).map(
+    ([name, cFunction]) =>
+      [
+        `bullet3d.constraint.${name}`,
+        {
+          argument: "body_b",
+          table: "params",
+          fields: FRAME_B_FIELDS,
+          reason: `script_bullet3d_constraint.cpp:${cFunction} reads frame B as required under if (input.m_BodyB)`,
+        },
+      ] as const,
+  ),
+]);
+
+// The calls PRESENCE_REQUIRED_FIELDS splits `prepared` into: the declared one
+// with its fields required, then the one whose argument is nil.
+function presenceArms(
+  prepared: PreparedFunction,
+  structs: readonly ApiStruct[],
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const entry = PRESENCE_REQUIRED_FIELDS.get(name);
+  if (entry === undefined) return [prepared];
+  const argument = parameters.findIndex((p) => p.name === entry.argument);
+  const table = parameters.findIndex((p) => p.name === entry.table);
+  const struct = structs.find((s) => parameters[table]?.types.includes(s.name));
+  if (argument === -1 || struct === undefined) {
+    throw new Error(
+      `presence-required fields ${name}: no ${entry.argument} parameter or ${entry.table} table`,
+    );
+  }
+  const missing = entry.fields.filter((field) => !struct.members.some((m) => m.name === field));
+  if (missing.length > 0) {
+    throw new Error(`presence-required fields ${name}: ${struct.name} lacks ${missing.join(", ")}`);
+  }
+  const picked = entry.fields.map((field) => `"${field}"`).join(" | ");
+  const requireFields = (type: string): string => {
+    const operand = /^[\w$.]+$/.test(type) ? type : `(${type})`;
+    return `${operand} & Required<Pick<${operand}, ${picked}>>`;
+  };
+  const strict: PreparedFunction = { ...prepared, retype: new Map([[table, requireFields]]) };
+  // Declared required, the nil argument emits as `undefined` alone rather than
+  // gaining the `| undefined` of an interior optional slot.
+  const absent: PreparedFunction = {
+    ...prepared,
+    required: new Set([...(prepared.required ?? []), argument]),
+    retype: new Map([[argument, () => "undefined"]]),
+  };
+  return [strict, absent];
+}
+
+// A rule an engine binding enforces on one parameter that no ref-doc token
+// states, keyed `<fqn>:param:<name>`. Each rewrites the slot's mapped type, so
+// one entry holds on every target whatever token spelling produced that type.
+export type EngineSlotRule =
+  // `E[]` becomes `[E, ...E[]]`: the binding raises on an empty list.
+  | { readonly kind: "non-empty"; readonly reason: string }
+  // The constants the binding raises on leave the slot's type.
+  | { readonly kind: "excludes"; readonly constants: readonly string[]; readonly reason: string }
+  // With `flag` true the table must carry `fields`, which the binding then reads
+  // without a default.
+  | {
+      readonly kind: "flag-requires";
+      readonly flag: string;
+      readonly fields: readonly string[];
+      readonly reason: string;
+    }
+  // In each call that requires `slot`, this slot is required too and its
+  // top-level union loses `drops`.
+  | {
+      readonly kind: "alongside";
+      readonly slot: string;
+      readonly drops: readonly string[];
+      readonly reason: string;
+    };
+
+export const ENGINE_SLOT_RULES: ReadonlyMap<string, EngineSlotRule> = new Map<
+  string,
+  EngineSlotRule
+>([
+  [
+    "buffer.create:param:declaration",
+    {
+      kind: "non-empty",
+      reason:
+        'script_buffer.cpp:Create raises "You must specify at least one stream declaration" when the list holds fewer than one entry',
+    },
+  ],
+  [
+    "buffer.set_metadata:param:values",
+    {
+      kind: "non-empty",
+      reason:
+        'script_buffer.cpp:SetMetadata raises "invalid metadata" when lua_objlen of values is 0',
+    },
+  ],
+  [
+    "buffer.set_metadata:param:value_type",
+    {
+      kind: "excludes",
+      constants: ["buffer.VALUE_TYPE_INT64", "buffer.VALUE_TYPE_UINT64"],
+      reason:
+        'script_buffer.cpp:SetMetadata raises "64 bit integer metadata are not supported." on VALUE_TYPE_UINT64 and VALUE_TYPE_INT64',
+    },
+  ],
+  [
+    "resource.create_sound_data:param:options",
+    {
+      kind: "flag-requires",
+      flag: "partial",
+      fields: ["filesize"],
+      reason:
+        "script_resource.cpp:CreateSoundData reads filesize with the no-default CheckFieldValue<int> when partial is true, and CheckValue<int> raises on a non-number",
+    },
+  ],
+  [
+    "go.delete:param:id",
+    {
+      kind: "alongside",
+      slot: "recursive",
+      drops: ["boolean"],
+      reason:
+        "gameobject_script.cpp:Script_Delete raises on a boolean id with a second argument, and on a nil id once recursive is popped",
+    },
+  ],
+]);
+
+// `prepared` with `rewrite` applied after any rewrite it already makes at `index`.
+function withRetype(
+  prepared: PreparedFunction,
+  index: number,
+  rewrite: (type: string) => string,
+): PreparedFunction {
+  const retype = new Map(prepared.retype);
+  const prior = retype.get(index);
+  retype.set(index, prior === undefined ? rewrite : (type) => rewrite(prior(type)));
+  return { ...prepared, retype };
+}
+
+// `E[]` as `[E, ...E[]]`; the element keeps its own parentheses.
+function nonEmptyList(type: string, key: string): string {
+  const element = type.endsWith("[]") ? type.slice(0, -2) : "";
+  const single =
+    splitTopLevel(type, "|").length === 1 &&
+    splitTopLevel(type, "&").length === 1 &&
+    !isFunctionTypeText(type);
+  if (element === "" || !single) {
+    throw new Error(`engine slot rule ${key}: ${type} is not one array`);
+  }
+  return `[${element}, ...${element}[]]`;
+}
+
+function withoutMembers(type: string, drops: readonly string[], key: string): string {
+  const members = splitTopLevel(type, "|").map((member) => member.trim());
+  const missing = drops.filter((drop) => !members.includes(drop));
+  if (missing.length > 0) {
+    throw new Error(`engine slot rule ${key}: ${type} has no ${missing.join(", ")} to drop`);
+  }
+  return members.filter((member) => !drops.includes(member)).join(" | ");
+}
+
+// The field names a table slot declares: its STRUCT's members, else the fields
+// parsed from its own doc.
+function slotFieldNames(parameter: ApiParameter, structs: readonly ApiStruct[]): string[] {
+  const struct = structs.find((s) => parameter.types.includes(s.name));
+  if (struct !== undefined) return struct.members.map((member) => member.name);
+  const fields = parameter.fields ?? parseTableFields(parameter.doc) ?? [];
+  return fields.map((field) => field.name);
+}
+
+function engineSlotRuleArms(
+  prepared: PreparedFunction,
+  arms: readonly PreparedFunction[],
+  key: string,
+  rule: EngineSlotRule,
+  index: number,
+  structs: readonly ApiStruct[],
+  bindingsRead: boolean,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const takes = (arm: PreparedFunction): boolean => index < arm.original.parameters.length;
+  const rewriteEach = (rewrite: (type: string) => string): PreparedFunction[] =>
+    arms.map((arm) => (takes(arm) ? withRetype(arm, index, rewrite) : arm));
+  switch (rule.kind) {
+    case "non-empty":
+      return rewriteEach((type) => nonEmptyList(type, key));
+    case "excludes": {
+      const excluded = rule.constants.map((constant) => `typeof ${constant}`).join(" | ");
+      return rewriteEach((type) => `Exclude<${type}, ${excluded}>`);
+    }
+    case "flag-requires": {
+      const declared = slotFieldNames(parameters[index] as ApiParameter, structs);
+      const missing = [rule.flag, ...rule.fields].filter((field) => !declared.includes(field));
+      if (missing.length > 0) {
+        throw new Error(`engine slot rule ${key}: the table declares no ${missing.join(", ")}`);
+      }
+      const picked = rule.fields.map((field) => `"${field}"`).join(" | ");
+      return rewriteEach((type) => {
+        const operand =
+          splitTopLevel(type, "|").length > 1 || isFunctionTypeText(type) ? `(${type})` : type;
+        return `${operand} & ({ ${rule.flag}?: false } | ({ ${rule.flag}: true } & Required<Pick<${type}, ${picked}>>))`;
+      });
+    }
+    case "alongside": {
+      const partner = parameters.findIndex((p) => p.name === rule.slot);
+      const partnerParameter = parameters[partner];
+      const requires = (arm: PreparedFunction): boolean =>
+        partnerParameter !== undefined &&
+        partner < arm.original.parameters.length &&
+        (arm.required?.has(partner) === true || !isDocOptional(partnerParameter, name));
+      if (!arms.some(requires)) {
+        // Without the target's nil-raising slots no call was split out to
+        // require the partner, so there is no binding to have stopped marking it.
+        if (!bindingsRead) return [...arms];
+        throw new Error(
+          partnerParameter === undefined
+            ? `engine slot rule ${key}: ${name} has no ${rule.slot} parameter`
+            : `engine slot rule ${key}: no call of ${name} requires ${rule.slot}`,
+        );
+      }
+      return arms.map((arm) =>
+        requires(arm)
+          ? {
+              ...withRetype(arm, index, (type) => withoutMembers(type, rule.drops, key)),
+              required: new Set([...(arm.required ?? []), index]),
+            }
+          : arm,
+      );
+    }
+  }
+}
+
+// `arms` with every ENGINE_SLOT_RULES entry keyed to `prepared` applied.
+// `bindingsRead` says the emit was given the target's nil-raising slots.
+function applyEngineSlotRules(
+  prepared: PreparedFunction,
+  arms: readonly PreparedFunction[],
+  structs: readonly ApiStruct[],
+  bindingsRead: boolean,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const prefix = `${name}:param:`;
+  let ruled = [...arms];
+  for (const [key, rule] of ENGINE_SLOT_RULES) {
+    if (!key.startsWith(prefix)) continue;
+    const slot = key.slice(prefix.length);
+    const index = parameters.findIndex((p) => p.name === slot);
+    if (index === -1) {
+      throw new Error(`engine slot rule ${key}: ${name} has no ${slot} parameter`);
+    }
+    ruled = engineSlotRuleArms(prepared, ruled, key, rule, index, structs, bindingsRead);
+  }
+  return ruled;
+}
+
+// Every call a function declares, in order: its nil-raising arms, each split
+// at its presence-required fields, then narrowed by its engine slot rules.
+function callArms(
+  prepared: PreparedFunction,
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]> | undefined,
+  structs: readonly ApiStruct[],
+): PreparedFunction[] {
+  const arms = nilRaisingArms(prepared, nilRaisingSlots ?? new Map()).flatMap((arm) =>
+    presenceArms(arm, structs),
+  );
+  return applyEngineSlotRules(prepared, arms, structs, nilRaisingSlots !== undefined);
+}
+
 export type ConstantSlotResolution =
   | { readonly borrow: string }
   | { readonly family: string; readonly evidence: string }
@@ -1347,8 +1752,6 @@ export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResoluti
   string,
   ConstantSlotResolution
 >([
-  ["gui.get:param:property", { borrow: "gui.animate:param:property" }],
-  ["gui.set:param:property", { borrow: "gui.animate:param:property" }],
   ["gui.cancel_animations:param:property", { borrow: "gui.animate:param:property" }],
   [
     "buffer.set_metadata:param:value_type",
@@ -1477,6 +1880,29 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
       "go.PLAYBACK_LOOP_PINGPONG",
     ],
   },
+  // The factors render_script.cpp:CheckBlendFactor accepts, in its order. Every
+  // target defines the constants; only the newer ones name the union.
+  {
+    home: "graphics",
+    name: "BlendFactor",
+    members: [
+      "graphics.BLEND_FACTOR_ZERO",
+      "graphics.BLEND_FACTOR_ONE",
+      "graphics.BLEND_FACTOR_SRC_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_SRC_COLOR",
+      "graphics.BLEND_FACTOR_DST_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_DST_COLOR",
+      "graphics.BLEND_FACTOR_SRC_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA",
+      "graphics.BLEND_FACTOR_DST_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_DST_ALPHA",
+      "graphics.BLEND_FACTOR_SRC_ALPHA_SATURATE",
+      "graphics.BLEND_FACTOR_CONSTANT_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR",
+      "graphics.BLEND_FACTOR_CONSTANT_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA",
+    ],
+  },
   {
     home: "graphics",
     name: "BufferType",
@@ -1690,6 +2116,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
       "graphics.BUFFER_TYPE_STENCIL_BIT",
     ],
   },
+  // The render-target creator raises on any other texture type.
+  {
+    home: "render",
+    name: "RenderTargetTextureType",
+    members: ["graphics.TEXTURE_TYPE_2D", "graphics.TEXTURE_TYPE_CUBE_MAP"],
+  },
   {
     home: "sys",
     name: "NetworkConnectivity",
@@ -1801,9 +2233,14 @@ function constantSlotTokens(
   return documentedConstantTokens(entry.family, universe);
 }
 
-function slotDocLookup(module: ApiModule): SlotDocLookup {
+// A borrow reads the ref-doc, so a slot of a function the skip rules withheld
+// (`gui.animate`, which gui-overloads.d.ts declares) still lends its doc.
+function slotDocLookup(
+  module: ApiModule,
+  withheldFunctions: readonly ApiFunction[] = [],
+): SlotDocLookup {
   const docs = new Map<string, string>();
-  for (const fn of module.functions) {
+  for (const fn of [...module.functions, ...withheldFunctions]) {
     for (const p of fn.parameters) {
       const key = tableSlotKey(fn.name, "param", p.name);
       if (!docs.has(key)) docs.set(key, p.doc);
@@ -1823,8 +2260,9 @@ export function resolveConstantSlotTokens(
   module: ApiModule,
   slotKey: string,
   universe: ReadonlySet<string>,
+  withheldFunctions: readonly ApiFunction[] = [],
 ): string[] {
-  const lookupDoc = slotDocLookup(module);
+  const lookupDoc = slotDocLookup(module, withheldFunctions);
   return constantSlotTokens(lookupDoc(slotKey) ?? "", slotKey, lookupDoc, universe);
 }
 
@@ -1838,21 +2276,23 @@ type ConstantSlotTokens = (
 function constantSlotTokenResolver(
   module: ApiModule,
   universe: ReadonlySet<string>,
+  withheldFunctions: readonly ApiFunction[] = [],
 ): ConstantSlotTokens {
-  const lookupDoc = slotDocLookup(module);
+  const lookupDoc = slotDocLookup(module, withheldFunctions);
   return (elementName, slotKind, slotName, doc) =>
     constantSlotTokens(doc, tableSlotKey(elementName, slotKind, slotName), lookupDoc, universe);
 }
 
-// FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
-// argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
-// Emitting these as user-defined type guards (`var_ is Vector3`) is the only way
-// to narrow an engine userdata value, which `typeof` cannot. An allowlist, not a
-// blanket `is_*` match: `b2d.body.is_active`, `gui.is_enabled`,
-// `sound.is_music_playing`, `go.exists`, `sys.exists` are runtime-state /
-// existence checks on already-typed arguments and must stay `boolean`. An
-// unlisted future `types.is_*` also stays a visible `boolean` until curated here,
-// matching the ARBITRARY_TABLE_SLOTS deliberate-opt-in precedent.
+// FQN-keyed allowlist of the checks that genuinely narrow their argument, mapped
+// to the `DEFOLD_TYPE_MAP` token whose type they prove: the `types.is_*` checks,
+// and `bullet3d.collision_object.is_rigid_body`, whose binding is a
+// `btRigidBody::upcast` test. Emitting these as user-defined type guards
+// (`var_ is Vector3`) is the only way to narrow an engine userdata value, which
+// `typeof` cannot. An allowlist, not a blanket `is_*` match: `b2d.body.is_active`,
+// `gui.is_enabled`, `sound.is_music_playing`, `go.exists`, `sys.exists` are
+// runtime-state / existence checks on already-typed arguments and must stay
+// `boolean`. An unlisted future `types.is_*` also stays a visible `boolean` until
+// curated here, matching the ARBITRARY_TABLE_SLOTS deliberate-opt-in precedent.
 export const TYPE_PREDICATES: ReadonlyMap<string, string> = new Map([
   ["types.is_hash", "hash"],
   ["types.is_matrix4", "matrix4"],
@@ -1861,13 +2301,47 @@ export const TYPE_PREDICATES: ReadonlyMap<string, string> = new Map([
   ["types.is_vector", "vector"],
   ["types.is_vector3", "vector3"],
   ["types.is_vector4", "vector4"],
+  ["bullet3d.collision_object.is_rigid_body", "btRigidBody"],
 ]);
 
+// The merged ref-doc gives each Box2D backend's form of these queries one
+// parameter list, so the first (v2) arm always wins and a v3 hit is unreachable.
+// A type parameter tells them apart: v2/script_box2d_world_v2.cpp:PushCastHit
+// sets `fixture` and `shape` to one PushFixtureInfo table, while
+// v3/script_box2d_world_v3.cpp:PushCastHit sets `shape` alone from
+// PushShapeInfoForShape. The v2 arm is declared first, so a call with no type
+// argument keeps the v2 hits; its `= "v2"` default only states that. Keyed by
+// `box2dBackendArmKey`.
+export const BOX2D_BACKEND_ARMS: ReadonlyMap<string, Box2dBackend> = new Map<string, Box2dBackend>([
+  ["b2d.world.cast_ray:b2d.fixture_cast_hit[]", "v2"],
+  ["b2d.world.cast_ray:b2d.shape_cast_hit[]", "v3"],
+  ["b2d.world.cast_ray_closest:b2d.fixture_cast_hit", "v2"],
+  ["b2d.world.cast_ray_closest:b2d.shape_cast_hit", "v3"],
+  ["b2d.world.cast_shape:b2d.fixture_cast_hit[]", "v2"],
+  ["b2d.world.cast_shape:b2d.shape_cast_hit[]", "v3"],
+  ["b2d.world.overlap_aabb:b2d.fixture_info[]", "v2"],
+  ["b2d.world.overlap_aabb:b2d.shape_info[]", "v3"],
+  ["b2d.world.overlap_shape:b2d.fixture_info[]", "v2"],
+  ["b2d.world.overlap_shape:b2d.shape_info[]", "v3"],
+]);
+
+// `<fqn>:<first non-nil type of the first return>`: the two arms of each
+// `BOX2D_BACKEND_ARMS` query share every parameter and differ only there.
+export function box2dBackendArmKey(fn: ApiFunction): string {
+  const first = fn.returnValues[0]?.types.find((type) => type !== "nil") ?? "";
+  return `${fn.name}:${first}`;
+}
+
+function box2dBackendTypeParameters(fn: ApiFunction): string {
+  const backend = BOX2D_BACKEND_ARMS.get(box2dBackendArmKey(fn));
+  if (backend === undefined) return "";
+  return backend === "v2" ? '<Backend extends "v2" = "v2">' : '<Backend extends "v3">';
+}
+
 // Element names whose `table` slot is a prose-only `array/list/table of <T>` shape
 // the field-list parser cannot read, but whose element type a human curated from
 // the doc. The value is a single element token (`T[]`) or a token list when the
-// element is itself a union — `go.delete`'s "table of id's" is the id union
-// `string | hash | url`, emitted `(string | Hash | Url)[]`. Emitted as a plain
+// element is itself a union, emitted `(A | B)[]`. Emitted as a plain
 // array, never `LuaMap`: an array element carries no illegal-index-key problem so
 // no TSTL wiring is needed. The audit consults this map too, so the gate and the
 // emitted surface stay coupled; a slot not curated here still surfaces under
@@ -1882,7 +2356,6 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
   ["vmath.vector", "number"],
   ["sound.get_groups", "hash"],
   ["iap.list", "string"],
-  ["go.delete", ["string", "hash", "url"]],
   // push.register's `notifications` is a prose-only array of push.NOTIFICATION_*
   // bitmask constants (the ref example sums NOTIFICATION_BADGE/SOUND/ALERT). The
   // vendored push_doc.json fixture declares no NOTIFICATION_* constant elements, so
@@ -1905,7 +2378,11 @@ export type NestedMapping = { key: string; value: string };
 // for `collectionfactory.create`'s properties.
 export type TableSlotCuration = (
   | { kind: "mapping"; key: string; value: string | readonly TableField[] | NestedMapping }
-  | { kind: "array"; element: string | readonly string[] }
+  // `pairs` also admits any table whose values are the element, for a binding
+  // that walks the table with lua_next and reads only its values. The extra arm
+  // is `LuaPairsIterable`, which is covariant in its value; `LuaTable` is
+  // invariant through `set`, so it would reject a `LuaTable<Hash, Hash>`.
+  | { kind: "array"; element: string | readonly string[]; pairs?: true }
   | { kind: "object"; fields: readonly TableField[] }
   | { kind: "array-object"; fields: readonly TableField[] }
   // A `<key> -> <args table>` slot: the doc's `<dl>` describes the *value* shape,
@@ -2082,25 +2559,6 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   string,
   TableSlotCuration
 >([
-  // gui_script.cpp:LuaGet and LuaSet read the `key` and `keys` options. On a
-  // prose `table` slot TABLE_SLOT_FIELD_ADDITIONS supplies them; 1.13.2 types the
-  // slots as an inline record and a struct that omit them.
-  ...(
-    [
-      ["gui.get:param:options", "{ index?:integer }"],
-      ["gui.set:param:options", "gui.set_options"],
-    ] as const
-  ).map(
-    ([key, retyped]) =>
-      [
-        key,
-        {
-          kind: "verbatim",
-          ts: "{ index?: number; key?: string | Hash; keys?: (Hash | string)[] }",
-          retypedUpstream: [retyped],
-        },
-      ] as const,
-  ),
   // buffer.create's `declaration` is "a table where each entry (table) describes
   // a stream", and upstream's example passes a list of stream records whose
   // `type` is a buffer.VALUE_TYPE_* constant.
@@ -2128,6 +2586,19 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
     },
   ],
   ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
+  // go.delete's "table of id's": gameobject_script.cpp:DeleteGOTable walks any
+  // table with lua_next and resolves each value with ResolveURL, so the id table
+  // collectionfactory.create returns deletes as it is. 1.13.2 retypes the slot
+  // to an id array, which still rejects that table.
+  [
+    "go.delete:param:id",
+    {
+      kind: "array",
+      element: ["string", "hash", "url"],
+      pairs: true,
+      retypedUpstream: ["(string|hash|url)[]"],
+    },
+  ],
   // font.get_info's `info` return is a `<dl>` with `path: hash` and a nested
   // `fonts` field whose `<dd>` is itself a `<dl>` (`path: string`, `path_hash:
   // hash`). parseTableFields flattens the inner `<dl>` to the top level, which
@@ -2385,62 +2856,6 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
       value: "number | vector4",
     },
   ],
-  // go.on_input and gui.on_input share the same well-known InputAction shape
-  // (the on_input function description lists the well-known fields: value,
-  // pressed, released, repeated, x/y/screen_x/screen_y/dx/dy/screen_dx/screen_dy,
-  // plus gamepad/touch/text multi-touch fields). The doc markup carries no
-  // field list of its own, so the shape is curated verbatim from the prose.
-  // Param-side optional fields: each input kind (mouse/key/text/gamepad) sets a
-  // different subset, so the call site always sees an `?` on every field.
-  // `touch` stays `table` (the nested multi-touch table has no machine-readable
-  // field list; mirrors the render.set_render_target.transient recursive case).
-  // The element is the bare `on_input` script hook (no namespace prefix), the
-  // same form the `on_message` arbitrary-table entry uses. The doc carries a
-  // well-formed touch input table, so `touch` is curated as a nested
-  // array-of-touch-records (the field has its own `<table>` listing id,
-  // pressed, released, tap_count, x, y, dx, dy, acc_x/y/z).
-  [
-    "on_input:param:action",
-    {
-      kind: "object",
-      fields: [
-        { name: "value", types: ["number"], optional: true },
-        { name: "pressed", types: ["boolean"], optional: true },
-        { name: "released", types: ["boolean"], optional: true },
-        { name: "repeated", types: ["boolean"], optional: true },
-        { name: "x", types: ["number"], optional: true },
-        { name: "y", types: ["number"], optional: true },
-        { name: "screen_x", types: ["number"], optional: true },
-        { name: "screen_y", types: ["number"], optional: true },
-        { name: "dx", types: ["number"], optional: true },
-        { name: "dy", types: ["number"], optional: true },
-        { name: "screen_dx", types: ["number"], optional: true },
-        { name: "screen_dy", types: ["number"], optional: true },
-        { name: "gamepad", types: ["number"], optional: true },
-        { name: "gamepad_axis", types: ["vector3"], optional: true },
-        {
-          name: "touch",
-          types: ["table"],
-          optional: true,
-          isList: true,
-          fields: [
-            { name: "id", types: ["number"] },
-            { name: "pressed", types: ["boolean"] },
-            { name: "released", types: ["boolean"] },
-            { name: "tap_count", types: ["number"] },
-            { name: "x", types: ["number"] },
-            { name: "y", types: ["number"] },
-            { name: "dx", types: ["number"] },
-            { name: "dy", types: ["number"] },
-            { name: "acc_x", types: ["number"] },
-            { name: "acc_y", types: ["number"] },
-            { name: "acc_z", types: ["number"] },
-          ],
-        },
-        { name: "text", types: ["string"], optional: true },
-      ],
-    },
-  ],
   // physics.create_joint and physics.set_joint_properties both declare
   // `properties` as a joint-type-specific table; the only universal field is
   // `collide_connected` (parseTableFields already recovers it from the
@@ -2932,7 +3347,9 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
 // no `status`; typing it as its own shape needs a per-target authored overload,
 // so `status` stays required and the slot's `note` says how to tell the two
 // apart. Its typed form is the same signature: the typed reference names
-// `http.response`, which the runtime surface withholds.
+// `http.response`, which the runtime surface withholds. Both forms add the
+// `sender` no reference lists: comp_script.cpp delivers the response as a
+// message, with `PushURL(L, message->m_Sender)` then `PCall(L, 4, 0)`.
 // `model.play_anim`'s completion callback receives self, the message id and the
 // message only: script_model.cpp calls it with `PCall(L, 3, 0)`, so both forms
 // drop the `sender` every reference lists and type the message as the typed
@@ -2979,7 +3396,7 @@ export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, CallbackSignature
   [
     "http.request:param:callback",
     onBothForms(
-      "(self: unknown, id: Hash, response: { status: number; url: string; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_sent?: number; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void",
+      "(self: unknown, id: Hash, response: { status: number; url: string; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_sent?: number; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }, sender: Url) => void",
       "With `report_progress` set, the callback also receives progress events carrying `bytes_sent`, `bytes_received`, `bytes_total` and `url` but no `status`; `response.bytes_received !== undefined` marks a progress event, since a final response never carries it.",
     ),
   ],
@@ -3064,11 +3481,11 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["resource.set_atlas:param:table:animations[].playback", "go.Playback"],
   ["resource.create_atlas:param:table:animations[].playback", "go.Playback"],
   ["resource.get_atlas:return:data:animations[].playback", "go.Playback"],
-  ["gui.set:param:options:key", "string | Hash"],
   ["render.set_render_target:param:options:transient", "graphics.BufferType[]"],
   ["resource.create_sound_data:param:options:data", 'string | Opaque<"buffer">'],
-  // The same two slots where 1.13.2 types the option bag as a STRUCT, whose
-  // members still carry the narrower upstream types.
+  // The option bags 1.13.2 types as a STRUCT, whose members still carry the
+  // narrower upstream types: `gui.set`'s (its slot is declared in
+  // gui-overloads.d.ts) and `resource.create_sound_data`'s.
   ["gui.set_options:member:key", "string | Hash"],
   ["resource.sound_data_options:member:data", 'string | Opaque<"buffer">'],
   // Bitmasks typed as their flag enum: the create_texture example passes
@@ -3083,6 +3500,11 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
     ] as const
   ).map((struct) => [`${struct}:member:flags`, "graphics.TEXTURE_USAGE_FLAG | number"] as const),
   ["render.render_target_buffer_params:member:flags", "render.RENDER_TARGET_FLAG | number"],
+  // gamesys_script.cpp:PushSampler, behind both get_samplers, pushes the raw
+  // texture type; NormalizeBindableTextureType never runs there. A separate
+  // sampler reports TEXTURE_TYPE_SAMPLER (6) and a separate texture binding one
+  // of the four TEXTURE_TYPE_TEXTURE_* (7-10), none of which has a Lua constant.
+  ["material.sampler_info:member:type", "graphics.TEXTURE_TYPE | 6 | 7 | 8 | 9 | 10"],
 ]);
 
 // A field the engine accepts on an option bag whose `<dl>` upstream otherwise
@@ -3102,13 +3524,6 @@ export interface TableFieldAddition {
   readonly evidence: readonly string[];
 }
 
-const PROPERTY_OPTION_KEYS: TableField = {
-  name: "keys",
-  types: ["table"],
-  optional: true,
-  tsType: "(Hash | string)[]",
-};
-
 export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition> = new Map<
   string,
   TableFieldAddition
@@ -3123,24 +3538,6 @@ export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition>
       ],
     },
   ],
-  [
-    "gui.get:param:options",
-    {
-      fields: [{ name: "key", types: ["string", "hash"], optional: true }, PROPERTY_OPTION_KEYS],
-      evidence: [
-        "gui_script.cpp:LuaGet reads its options through dmGameObject::LuaToPropertyOptions, which reads index, key and keys",
-      ],
-    },
-  ],
-  [
-    "gui.set:param:options",
-    {
-      fields: [PROPERTY_OPTION_KEYS],
-      evidence: [
-        "gui_script.cpp:LuaSet reads its options through dmGameObject::LuaToPropertyOptions, which reads index, key and keys",
-      ],
-    },
-  ],
 ]);
 
 // A return-slot field upstream documents as platform-gated or nil-valued while
@@ -3890,6 +4287,58 @@ function groupFlattenedTableFields(fields: readonly TableField[]): TableField[]
   return grouped;
 }
 
+// A TYPEDEF whose aliased type the engine binding contradicts, replaced verbatim.
+// Member overrides reach only a STRUCT, and these alias inline LuaLS tables.
+// Each applies only while the typedef still aliases exactly its `upstream` tokens,
+// in order, so a changed upstream typedef is emitted as written rather than
+// shadowed; `typedef-correction-provenance.test.ts` pins every entry against the
+// retained ref-docs. Keyed by the typedef's ref-doc name.
+export interface TypedefAliasCorrection {
+  readonly upstream: readonly string[];
+  readonly ts: string;
+  readonly reason: string;
+}
+
+// One arm per shape a script can build, in upstream's order, each keyed by its
+// own shape-type constant.
+const BULLET3D_SHAPE_ARMS = [
+  ["SPHERE", "diameter: number"],
+  ["BOX", "dimensions: Vector3"],
+  ["CAPSULE", "diameter: number; height: number"],
+  ["HULL", "vertices: Vector3[]"],
+] as const;
+
+export const TYPEDEF_ALIAS_CORRECTIONS: ReadonlyMap<string, TypedefAliasCorrection> = new Map([
+  [
+    "render.render_target_params",
+    {
+      upstream: [
+        "{ type?:graphics.TEXTURE_TYPE, sample_count?:integer, [graphics.BUFFER_TYPE]:render.render_target_buffer_params }",
+      ],
+      ts: "{ type?: render.RenderTargetTextureType; sample_count?: number } & { [key: number]: render.render_target_buffer_params }",
+      reason:
+        'render_script.cpp:RenderScript_RenderTarget raises "Invalid render target texture type" on any `type` but graphics.TEXTURE_TYPE_2D and graphics.TEXTURE_TYPE_CUBE_MAP',
+    },
+  ],
+  [
+    "bullet3d.shape.definition",
+    {
+      upstream: [
+        "{ type:bullet3d.shape.SHAPE_TYPE, diameter:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, dimensions:vector3, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, diameter:number, height:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, vertices:vector3[], position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+      ],
+      ts: BULLET3D_SHAPE_ARMS.map(
+        ([kind, fields]) =>
+          `{ type: typeof bullet3d.shape.SHAPE_TYPE_${kind}; ${fields}; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion }`,
+      ).join(" | "),
+      reason:
+        'script_bullet3d_shape.cpp:CheckBullet3DShapeDef reads only the fields of the table\'s own `type` and raises "Unsupported shape type" on any other, a mesh included',
+    },
+  ],
+]);
+
 // A handle the type map widens (`constant_buffer` takes named constants) keeps
 // that shape, so annotating with the alias loses nothing the handle-returning
 // function yields.
@@ -3906,6 +4355,14 @@ function typedefAlias(
 ): string {
   const brand = `Opaque<"${typedef.name}">`;
   const aliasOf = typedef.aliasOf ?? [];
+  const correction = TYPEDEF_ALIAS_CORRECTIONS.get(typedef.name);
+  if (
+    correction !== undefined &&
+    aliasOf.length === correction.upstream.length &&
+    aliasOf.every((token, i) => token === correction.upstream[i])
+  ) {
+    return `type ${local} = ${correction.ts};`;
+  }
   if (aliasOf.length > 0 && !isHandleAlias(aliasOf)) {
     const armType: DefoldTypeMapper = DISCRIMINATED_MESSAGE_UNIONS.has(typedef.name)
       ? (token, position) => discriminatedMessageArm(token) ?? mapType(token, position)
@@ -4248,11 +4705,13 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   const translations = options?.translations ?? {};
   const urlParameters = options?.urlParameters ?? [];
   const bindingEvidence = options?.bindingEvidence ?? new Set<string>();
+  const nilRaisingSlots = options?.nilRaisingSlots;
   const baseNotes = indexBaseNoteResolver(options?.indexBaseSource ?? "engine");
   const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
     new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
+    options?.withheldFunctions,
   );
 
   const constants = module.constants
@@ -4385,18 +4844,20 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   for (const fn of functions) {
     const reserved = TS_RESERVED_NAMES.has(fn.name);
     const emitName = aliasName(fn.name, aliases);
-    for (const docLine of functionDocLines(fn.original, translations, baseNotes))
-      lines.push(docLine);
-    const line = emitFunction(
-      fn,
-      emitName,
-      mapType,
-      resolver,
-      constantTokens,
-      urlParameters,
-      bindingEvidence,
-    );
-    lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
+    for (const arm of callArms(fn, nilRaisingSlots, module.structs ?? [])) {
+      for (const docLine of functionDocLines(fn.original, translations, baseNotes))
+        lines.push(docLine);
+      const line = emitFunction(
+        arm,
+        emitName,
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+        bindingEvidence,
+      );
+      lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
+    }
     const alternative = firstSlotAlternative(fn, module.namespace);
     if (alternative !== null) {
       // The overload documents its own parameters, so its hover names the base
@@ -4620,10 +5081,12 @@ export function emitSymbolSignatures(
   const knownConstantFqns = options?.knownConstantFqns;
   const urlParameters = options?.urlParameters ?? [];
   const bindingEvidence = options?.bindingEvidence ?? new Set<string>();
+  const nilRaisingSlots = options?.nilRaisingSlots;
   const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
     new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
+    options?.withheldFunctions,
   );
   const resolver = buildTableDocResolver(
     module.functions.map((fn) => ({
@@ -4650,8 +5113,9 @@ export function emitSymbolSignatures(
     const prepared = prepareFunction(fn, prefix);
     if (prepared === null) continue;
     const slotTypes: Record<string, SlotType> = {};
+    const [first = prepared, ...later] = callArms(prepared, nilRaisingSlots, module.structs ?? []);
     const primary = emitFunction(
-      prepared,
+      first,
       emitName(prepared.name),
       mapType,
       resolver,
@@ -4661,18 +5125,18 @@ export function emitSymbolSignatures(
       slotTypes,
     );
     const alternative = firstSlotAlternative(prepared, module.namespace);
-    const tsSignature =
-      alternative === null
-        ? primary
-        : `${primary}\n${emitFunction(
-            alternative,
-            emitName(prepared.name),
-            mapType,
-            resolver,
-            constantTokens,
-            urlParameters,
-            bindingEvidence,
-          )}`;
+    const arms = [...later, ...(alternative === null ? [] : [alternative])].map((arm) =>
+      emitFunction(
+        arm,
+        emitName(prepared.name),
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+        bindingEvidence,
+      ),
+    );
+    const tsSignature = [primary, ...arms].join("\n");
     out.push({ identity: fnIdentity(fn), tsSignature, slotTypes });
   }
 
@@ -4829,6 +5293,12 @@ interface PreparedConstant {
 interface PreparedFunction {
   name: string;
   original: ApiFunction;
+  // Parameter positions declared required whatever their doc says: the
+  // nil-raising slots an arm of `nilRaisingArms` takes.
+  required?: ReadonlySet<number>;
+  // A rewrite of the mapped type at a parameter position: the fields an arm of
+  // `presenceArms` requires.
+  retype?: ReadonlyMap<number, (type: string) => string>;
 }
 
 interface PreparedVariable {
@@ -5112,10 +5582,13 @@ export const NIL_CONSTANTS: ReadonlyMap<string, string> = new Map([
 // `undocumented-constant-provenance.test.ts` reds an entry no committed target
 // still needs. `sameValueAs` names the documented constant the engine registers
 // with the same value; where the surface declares it, the back-fill takes its
-// type, so a value compares equal to either spelling.
+// type, so a value compares equal to either spelling. `memberOf` names the
+// ref-doc `ENUM` the engine returns the constant through; the back-fill joins it
+// only on a surface whose ref-doc declares that enum, so an older surface
+// without one keeps a plain constant.
 export const UNDOCUMENTED_CONSTANTS: ReadonlyMap<
   string,
-  { readonly doc: string; readonly sameValueAs?: string }
+  { readonly doc: string; readonly sameValueAs?: string; readonly memberOf?: string }
 > = new Map([
   [
     "render.CONTEXT_EVENT_CONTEXT_LOST",
@@ -5136,6 +5609,13 @@ export const UNDOCUMENTED_CONSTANTS: ReadonlyMap<
       sameValueAs: "window.WINDOW_EVENT_ICONIFIED",
     },
   ],
+  [
+    "liveupdate.LIVEUPDATE_NOT_INITIALIZED",
+    {
+      doc: "Live update is not initialized. `liveupdate.add_mount` and `liveupdate.remove_mount` return it while live update is disabled.",
+      memberOf: "liveupdate.LIVEUPDATE",
+    },
+  ],
 ]);
 
 function withUndocumentedConstants(
@@ -5145,7 +5625,8 @@ function withUndocumentedConstants(
   const prefix = `${module.namespace}.`;
   const documented = new Set(module.constants.map((c) => c.name));
   const backfill: ApiConstant[] = [];
-  for (const [fqn, { doc, sameValueAs }] of UNDOCUMENTED_CONSTANTS) {
+  const joined = new Map<string, string[]>();
+  for (const [fqn, { doc, sameValueAs, memberOf }] of UNDOCUMENTED_CONSTANTS) {
     if (!fqn.startsWith(prefix) || fqn.slice(prefix.length).includes(".")) continue;
     if (documented.has(fqn)) continue;
     if (registered !== undefined && !registered.has(fqn)) continue;
@@ -5157,10 +5638,18 @@ function withUndocumentedConstants(
       description: "",
       ...(aliasOf === undefined ? {} : { aliasOf }),
     });
+    if (memberOf !== undefined) joined.set(memberOf, [...(joined.get(memberOf) ?? []), fqn]);
   }
-  return backfill.length === 0
-    ? module
-    : { ...module, constants: [...module.constants, ...backfill] };
+  if (backfill.length === 0) return module;
+  const enums = module.enums?.map((e) => {
+    const members = joined.get(e.name);
+    return members === undefined ? e : { ...e, members: [...e.members, ...members] };
+  });
+  return {
+    ...module,
+    constants: [...module.constants, ...backfill],
+    ...(enums === undefined ? {} : { enums }),
+  };
 }
 
 // `constant` is the module's own element for `fqn`, absent for a constant another
@@ -5244,10 +5733,25 @@ function memberSignature(
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
-  const cutoff = trailingOptionalCutoff(original, elementName);
+  const required = prepared.required ?? new Set<number>();
+  const cutoff = Math.max(
+    trailingOptionalCutoff(original, elementName),
+    ...[...required].map((index) => index + 1),
+  );
   const varargIndex = original.findIndex(isVarargParameter);
   const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
-    emitParameter(p, i, i >= cutoff, mapType, resolver, constantTokens, elementName, urlParameters),
+    emitParameter(
+      p,
+      i,
+      i >= cutoff,
+      mapType,
+      resolver,
+      constantTokens,
+      elementName,
+      urlParameters,
+      required.has(i),
+      prepared.retype?.get(i),
+    ),
   );
   const rest =
     varargIndex === -1
@@ -5296,7 +5800,7 @@ function memberSignature(
   if (isPredicate && soleParam !== undefined && predicateToken !== undefined) {
     return `${name}(${params}): ${safeParamName(soleParam.name, 0)} is ${mapType(predicateToken)};`;
   }
-  return `${name}(${params}): ${ret.type};${ret.trailing}`;
+  return `${name}${box2dBackendTypeParameters(prepared.original)}(${params}): ${ret.type};${ret.trailing}`;
 }
 
 function emitFunction(
@@ -5367,6 +5871,7 @@ function functionDocLines(
     };
   });
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
+  const sparseNote = SPARSE_ARRAY_RETURNS.get(fn.name)?.note;
   const notedReturns =
     multiReturnDoc(fn, translations, baseNotes) ?? overrideReturnDoc(fn, baseNotes);
   const lua = htmlToCodeText(fn.examples ?? "");
@@ -5399,7 +5904,10 @@ function functionDocLines(
       ? {
           returns: appendNotes(
             translateProseFences(htmlToDocText(onlyReturn.doc), fn.name, translations),
-            baseNotes(fn.name, "return", onlyReturn.name),
+            [
+              ...baseNotes(fn.name, "return", onlyReturn.name),
+              ...(sparseNote === undefined ? [] : [sparseNote]),
+            ],
           ),
         }
       : notedReturns !== undefined
@@ -5661,15 +6169,19 @@ function emitParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
+  required = false,
+  retype: (type: string) => string = (type) => type,
 ): { text: string; type: string; optional: boolean } {
   const name = safeParamName(p.name, index);
-  const ts = parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters);
+  const ts = retype(
+    parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
+  );
   // An interior doc-optional param (a required param follows, so the trailing-`?`
   // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
   // `?` form; required params are untouched.
   const nilRequired = requiredSlotCorrection(p, elementName)?.nil === true;
-  const interiorOptional = !optional && (isDocOptional(p, elementName) || nilRequired);
+  const interiorOptional = !optional && !required && (isDocOptional(p, elementName) || nilRequired);
   // `(a) => void | undefined` reads as a function returning `void | undefined`.
   const operand = interiorOptional && isFunctionTypeText(ts) ? `(${ts})` : ts;
   const type = `${operand}${interiorOptional ? " | undefined" : ""}`;
@@ -5838,6 +6350,48 @@ function emitPropertyMembers(
   return keys.map((key) => `${modifier}${key}: ${ts};`);
 }
 
+// A function whose returned table the engine binding keys by a sparse integer,
+// so the sequence its reference declares is a map with holes: `ipairs` stops at
+// the first hole, and `#t` may return any border. Keyed by function name, since the return slot is named
+// `table` in 1.13.0/1.13.1 and `textures` from 1.13.2. The return's `T[]` member
+// emits as `LuaMap<number, T>`, which `for...of` lowers to `pairs`, and `note`
+// joins its `@returns`.
+export const SPARSE_ARRAY_RETURNS: ReadonlyMap<string, { note: string; reason: string }> = new Map([
+  [
+    "material.get_textures",
+    {
+      note: "Keyed by sampler slot from 1; a slot with no texture has no entry, so iterate with `for (const [slot, info] of textures)`.",
+      reason:
+        "script_material.cpp:Material_GetTextures pushes key i+1 only for a slot that has a texture, unlike Compute_GetTextures, which packs its keys",
+    },
+  ],
+]);
+
+function sparseArrayMap(ts: string, elementName: string): string {
+  const members = unionMembers(ts);
+  const arrays = members.filter((member) => member.endsWith("[]"));
+  if (arrays.length === 0) {
+    throw new Error(`SPARSE_ARRAY_RETURNS ${elementName}: the return emits no array (${ts})`);
+  }
+  return members
+    .map((member) => {
+      if (!member.endsWith("[]")) return member;
+      const element = member.slice(0, -2);
+      return `LuaMap<number, ${wrappedInParens(element) ? element.slice(1, -1) : element}>`;
+    })
+    .join(" | ");
+}
+
+function wrappedInParens(text: string): boolean {
+  if (!text.startsWith("(")) return false;
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "(") depth++;
+    else if (text[i] === ")" && --depth === 0) return i === text.length - 1;
+  }
+  return false;
+}
+
 // Like `unionFromTokens`, but a `table` token whose slot doc carries a parseable
 // `<dl>` field list emits an inline object type instead of the opaque `Record`
 // fallback. Other tokens in the union map unchanged. `optionalFields` marks the
@@ -5918,6 +6472,10 @@ function mapSlotUnion(
         }
       } else if (element !== undefined) {
         ts = arrayTypeFromTokens(element, mapType);
+        if (curation?.kind === "array" && curation.pairs === true) {
+          const tokens = typeof element === "string" ? [element] : element;
+          ts = `${ts} | LuaPairsIterable<AnyNotNil, ${unionFromTokens(tokens, mapType)}>`;
+        }
       } else if (curation?.kind === "verbatim") {
         ts = curation.ts;
       } else if (curation?.kind === "object" || curation?.kind === "array-object") {
@@ -5991,8 +6549,10 @@ function mapSlotUnion(
   // A genuine `unknown` member (an `any` slot, including `any | nil`) absorbs
   // every other union member, so collapse to exactly `unknown` rather than emit
   // a redundant `T | unknown` or `unknown | undefined`.
-  if (mapped.includes("unknown")) return "unknown";
-  return joinUnionArms(mapped);
+  const joined = mapped.includes("unknown") ? "unknown" : joinUnionArms(mapped);
+  return slotKind === "return" && SPARSE_ARRAY_RETURNS.has(elementName)
+    ? sparseArrayMap(joined, elementName)
+    : joined;
 }
 
 function tableSlotKey(elementName: string, slotKind: "param" | "return", slotName: string): string {