@defold-typescript/types 0.51.0 → 0.53.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,
@@ -11,7 +15,7 @@ import type {
   ApiTypedef,
   ApiVariable,
 } from "./api-doc";
-import { DEFOLD_TYPE_MAP } from "./core-types";
+import { DEFOLD_TYPE_MAP, SOCKET_HANDLE_NAMES, type SocketHandleReceiver } from "./core-types";
 import { correctionPins, pinMatches, propertyCorrectionPins } from "./correction-pins";
 import {
   type DocCommentParts,
@@ -22,6 +26,7 @@ import {
   summaryFor,
 } from "./doc-comment";
 import { applyMessageOverlays, parseMessagesDoc } from "./emit-messages";
+import { engineTypeName } from "./engine-type-name";
 import type { TranslationStore } from "./example-store";
 import { lookupExampleSegments, translateProseFences } from "./example-store";
 import {
@@ -36,6 +41,7 @@ import {
   type LualsPosition,
   mapLualsExpression,
   needsArrayParens,
+  splitTopLevel,
 } from "./luals-type-expr";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
@@ -82,12 +88,20 @@ export interface EmitOptions {
   // bindings (a ref-doc target), where every entry the ref-doc omits is emitted.
   registeredConstants?: ReadonlySet<string>;
   // The `RETURN_TYPE_CORRECTIONS` and `STRUCT_MEMBER_ADDITIONS` keys whose binding
-  // pin holds in the target's vendored engine source. A binding-pinned entry
-  // applies only when its key is here, so a surface with no vendored bindings
-  // (absent) applies none of them.
+  // pin holds in the target's vendored engine source, and the
+  // `PROPERTY_KEY_RANGES` keys whose `engine` pins all hold there. A pinned
+  // entry 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 +193,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 +271,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 +294,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 +352,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 +474,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 +553,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",
     {
@@ -631,6 +660,36 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
         },
       ] as const,
   ),
+  [
+    "gui.get_xanchor",
+    {
+      ts: "Exclude<gui.Anchor, typeof gui.ANCHOR_BOTTOM | typeof gui.ANCHOR_TOP>",
+      upstream: ["constant"],
+      retypedUpstream: [["gui.ANCHOR"]],
+      reason:
+        "gui_script.cpp:LuaGetXAnchor pushes GetNodeXAnchor, an x anchor: XANCHOR_NONE, XANCHOR_LEFT, or XANCHOR_RIGHT",
+      binding: {
+        file: "gui/src/gui_script.cpp",
+        cFunction: "LuaGetXAnchor",
+        contains: "lua_pushnumber(L, GetNodeXAnchor(scene, hnode));",
+      },
+    },
+  ],
+  [
+    "gui.get_yanchor",
+    {
+      ts: "Exclude<gui.Anchor, typeof gui.ANCHOR_LEFT | typeof gui.ANCHOR_RIGHT>",
+      upstream: ["constant"],
+      retypedUpstream: [["gui.ANCHOR"]],
+      reason:
+        "gui_script.cpp:LuaGetYAnchor pushes GetNodeYAnchor, a y anchor: YANCHOR_NONE, YANCHOR_TOP, or YANCHOR_BOTTOM",
+      binding: {
+        file: "gui/src/gui_script.cpp",
+        cFunction: "LuaGetYAnchor",
+        contains: "lua_pushnumber(L, GetNodeYAnchor(scene, hnode));",
+      },
+    },
+  ],
 ]);
 
 // A parameter whose declared `types` disagree with what the same element's
@@ -638,23 +697,29 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
 // target by resource name, a texture unit, a Lua sequence where `table` is
 // declared, a hash the binding refuses as a string. Admission rule: only a slot
 // that evidence contradicts; a slot that is merely imprecise is not a candidate.
-// The correction edits the mapped union rather than replacing it: `adds` appends
-// what the slot also takes and `removes` drops members the binding raises on, so
-// the URL address alias, array curation and constant mapping stay live, and
-// optionality stays with `isDocOptional`. Each entry records the upstream tokens
-// it contradicts, plus any later spelling of the same defect in
-// `retypedUpstream`, and applies only to a slot still declaring one of them;
-// `param-correction-provenance.test.ts` pins them against every retained
-// vendored ref-doc. Once no retained target still declares any of them the
-// entry is deleted, never re-pinned.
-export interface ParamTypeCorrection {
-  readonly adds?: string;
-  readonly removes?: readonly string[];
+// A correction either replaces the mapped type exactly with `ts`, or edits the
+// mapped union: `adds` appends what the slot also takes and `removes` drops
+// members the binding raises on. Union edits keep the URL address alias, array
+// curation and constant mapping live; optionality stays with `isDocOptional`.
+// Each entry records the upstream tokens it contradicts, plus any later spelling
+// of the same defect in `retypedUpstream`, and applies only to a slot still
+// declaring one of them. An entry with a `binding` also requires its exact
+// `EmitOptions.bindingEvidence` key. `param-correction-provenance.test.ts` pins
+// the ref-doc tokens against every retained target; once no target declares a
+// pin, the entry is deleted rather than re-pinned.
+interface ParamTypeCorrectionBase {
   readonly upstream: readonly string[];
   readonly retypedUpstream?: readonly (readonly string[])[];
   readonly reason: string;
+  readonly binding?: BindingPin;
 }
 
+export type ParamTypeCorrection = ParamTypeCorrectionBase &
+  (
+    | { readonly ts: string; readonly adds?: undefined; readonly removes?: undefined }
+    | { readonly ts?: undefined; readonly adds?: string; readonly removes?: readonly string[] }
+  );
+
 const CAMERA_ADDRESS_REASON =
   "render_script_camera.cpp:CheckRenderCamera resolves anything but a number handle through ResolveURL, which takes a string or a hash";
 
@@ -688,6 +753,58 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
   string,
   ParamTypeCorrection
 >([
+  [
+    "gui.set_xanchor:param:anchor",
+    {
+      ts: "Exclude<gui.Anchor, typeof gui.ANCHOR_BOTTOM | typeof gui.ANCHOR_TOP>",
+      upstream: ["constant"],
+      retypedUpstream: [["gui.ANCHOR"]],
+      reason:
+        "gui_script.cpp:LuaSetXAnchor rejects every value except XANCHOR_NONE, XANCHOR_LEFT, and XANCHOR_RIGHT",
+      binding: {
+        file: "gui/src/gui_script.cpp",
+        cFunction: "LuaSetXAnchor",
+        contains: "anchor != XANCHOR_NONE && anchor != XANCHOR_LEFT && anchor != XANCHOR_RIGHT",
+      },
+    },
+  ],
+  [
+    "gui.set_yanchor:param:anchor",
+    {
+      ts: "Exclude<gui.Anchor, typeof gui.ANCHOR_LEFT | typeof gui.ANCHOR_RIGHT>",
+      upstream: ["constant"],
+      retypedUpstream: [["gui.ANCHOR"]],
+      reason:
+        "gui_script.cpp:LuaSetYAnchor rejects every value except YANCHOR_NONE, YANCHOR_TOP, and YANCHOR_BOTTOM",
+      binding: {
+        file: "gui/src/gui_script.cpp",
+        cFunction: "LuaSetYAnchor",
+        contains: "anchor != YANCHOR_NONE && anchor != YANCHOR_TOP && anchor != YANCHOR_BOTTOM",
+      },
+    },
+  ],
+  [
+    "go.animate:param:playback",
+    {
+      ts: "go.Playback",
+      upstream: [
+        "go.PLAYBACK_ONCE_FORWARD",
+        "go.PLAYBACK_ONCE_BACKWARD",
+        "go.PLAYBACK_ONCE_PINGPONG",
+        "go.PLAYBACK_LOOP_FORWARD",
+        "go.PLAYBACK_LOOP_BACKWARD",
+        "go.PLAYBACK_LOOP_PINGPONG",
+      ],
+      retypedUpstream: [["go.PLAYBACK"]],
+      reason:
+        "gameobject_script.cpp:Script_Animate accepts every playback value below PLAYBACK_COUNT, including PLAYBACK_NONE",
+      binding: {
+        file: "gameobject/src/gameobject/gameobject_script.cpp",
+        cFunction: "Script_Animate",
+        contains: "if (playback >= PLAYBACK_COUNT)",
+      },
+    },
+  ],
   ...CAMERA_SLOT_FUNCTIONS.map(
     (name) =>
       [
@@ -757,6 +874,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 +981,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 +1002,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: "Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>",
+          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 +1056,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",
     {
@@ -918,8 +1087,8 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
   [
     "window.set_dim_mode:param:mode",
     {
-      removes: ["window.DIMMING"],
-      adds: "window.DimModeStateSettable",
+      removes: ["window.Dimming"],
+      adds: "Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN>",
       upstream: ["window.DIMMING"],
       reason:
         'script_window.cpp:SetDimMode raises "The dim mode specified is not supported." for anything but DIMMING_ON and DIMMING_OFF',
@@ -1021,16 +1190,70 @@ export const PROPERTY_TYPE_CORRECTIONS: ReadonlyMap<string, PropertyTypeCorrecti
 // saying it, or when the phrase stops stating `first-last`. Curated rather than
 // matched on a trailing `N`, so each new upstream placeholder is a deliberate
 // addition.
+//
+// `engine.last` replaces `last` on a target whose vendored engine source shows
+// every one of `engine.pins` (the `EmitOptions.bindingEvidence` keys); every
+// other surface, including one generated from a ref-doc alone, keeps the range
+// `evidence` states.
 export interface PropertyKeyRange {
   readonly prefix: string;
   readonly first: number;
   readonly last: number;
   readonly evidence: string;
+  readonly engine?: { readonly last: number; readonly pins: readonly EngineSourcePin[] };
 }
 
-// Keyed `<namespace>.<property>`, mirroring PROPERTY_TYPE_CORRECTIONS.
+// A token snippet the target's vendored engine evidence must contain. With
+// `cFunction` it is matched in that function's body, without it anywhere in
+// the file.
+export interface EngineSourcePin {
+  // Relative to the target's vendored `engine/` tree, as `BindingPin.file` is.
+  readonly file: string;
+  readonly cFunction?: string;
+  readonly contains: string;
+}
+
+const MODEL_TEXTURE_LOOP =
+  "for (uint32_t i = 0; i < dmRender::RenderObject::MAX_TEXTURE_COUNT; ++i) { if (params.m_PropertyId == PROP_TEXTURE[i])";
+
+// Keyed `<namespace>.<property>`, mirroring PROPERTY_TYPE_CORRECTIONS; a key
+// with an `engine` field is also an `EmitOptions.bindingEvidence` key.
 export const PROPERTY_KEY_RANGES: ReadonlyMap<string, PropertyKeyRange> = new Map([
-  ["model.textureN", { prefix: "texture", first: 0, last: 7, evidence: "textureN where N is 0-7" }],
+  [
+    "model.textureN",
+    {
+      prefix: "texture",
+      first: 0,
+      last: 7,
+      evidence: "textureN where N is 0-7",
+      engine: {
+        last: 15,
+        pins: [
+          {
+            file: "render/src/dmsdk/render/render.h",
+            contains: "static const uint32_t MAX_TEXTURE_COUNT = 16;",
+          },
+          {
+            file: "gamesys/src/gamesys/gamesys.cpp",
+            contains: `const dmhash_t PROP_TEXTURE[dmRender::RenderObject::MAX_TEXTURE_COUNT] = { ${Array.from(
+              { length: 16 },
+              (_, unit) => `dmHashString64("texture${unit}"),`,
+            ).join(" ")} };`,
+          },
+          {
+            file: "gamesys/src/gamesys/components/comp_model.cpp",
+            cFunction: "CompModelGetProperty",
+            contains: MODEL_TEXTURE_LOOP,
+          },
+          {
+            file: "gamesys/src/gamesys/components/comp_model.cpp",
+            cFunction: "CompModelSetProperty",
+            contains: MODEL_TEXTURE_LOOP,
+          },
+        ],
+      },
+    },
+  ],
 ]);
 
 // A parameter the ref-doc metadata marks required while the same element's prose
@@ -1095,6 +1318,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 +1464,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 +1553,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 +1896,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",
@@ -1366,7 +1913,7 @@ export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResoluti
   ],
 ]);
 
-export interface ConstantUnionAlias {
+export interface ConstantUnionNamedRow {
   // The namespace the alias is declared in. It is the namespace the union
   // *means*, which is not always the one its constants live in: the three
   // buffer keys `render.clear` accepts are `graphics.BUFFER_TYPE_*` constants,
@@ -1377,11 +1924,22 @@ export interface ConstantUnionAlias {
   readonly members: readonly string[];
 }
 
-// A documented constant union gets a public name so a caller can spell the type
-// their own wrapper takes. Identity is the *member set*, never a name prefix:
-// `gui.ANCHOR_*` splits into two rows because the x and y slots accept
-// different thirds of it, and `graphics.BUFFER_TYPE_*` splits because
-// `render.clear` accepts three of the six.
+// A union that is a strict subset of a named row in the same home. It declares
+// nothing: each slot spells it `Exclude<<home>.<parent>, ...>`, so one namespace
+// never carries two names for overlapping sets.
+export interface ConstantUnionSubsetRow {
+  readonly home: string;
+  readonly parent: string;
+  readonly members: readonly string[];
+}
+
+export type ConstantUnionAlias = ConstantUnionNamedRow | ConstantUnionSubsetRow;
+
+// A documented constant union gets a public spelling so a caller can write the
+// type their own wrapper takes. Identity is the *member set*, never a name
+// prefix: the x and y anchor slots accept different thirds of `gui.ANCHOR_*`,
+// so each is its own subset row of `gui.ANCHOR`, and `graphics.BUFFER_TYPE_*`
+// splits because `render.clear` accepts three of the six.
 //
 // The table is the only thing the emitter reads, and every name in it has been
 // reviewed: a longest-common-prefix rule proposes, a human disposes. A union
@@ -1391,7 +1949,7 @@ export interface ConstantUnionAlias {
 export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   {
     home: "buffer",
-    name: "ValueType",
+    name: "VALUE_TYPE",
     members: [
       "buffer.VALUE_TYPE_FLOAT32",
       "buffer.VALUE_TYPE_INT16",
@@ -1406,7 +1964,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "collectionfactory",
-    name: "Status",
+    name: "STATUS",
     members: [
       "collectionfactory.STATUS_UNLOADED",
       "collectionfactory.STATUS_LOADING",
@@ -1415,12 +1973,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "factory",
-    name: "Status",
+    name: "STATUS",
     members: ["factory.STATUS_UNLOADED", "factory.STATUS_LOADING", "factory.STATUS_LOADED"],
   },
   {
     home: "go",
-    name: "Easing",
+    name: "EASING",
     members: [
       "go.EASING_INBACK",
       "go.EASING_INBOUNCE",
@@ -1467,7 +2025,20 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "go",
-    name: "Playback",
+    name: "PLAYBACK",
+    members: [
+      "go.PLAYBACK_LOOP_BACKWARD",
+      "go.PLAYBACK_LOOP_FORWARD",
+      "go.PLAYBACK_LOOP_PINGPONG",
+      "go.PLAYBACK_NONE",
+      "go.PLAYBACK_ONCE_BACKWARD",
+      "go.PLAYBACK_ONCE_FORWARD",
+      "go.PLAYBACK_ONCE_PINGPONG",
+    ],
+  },
+  {
+    home: "go",
+    parent: "PLAYBACK",
     members: [
       "go.PLAYBACK_ONCE_FORWARD",
       "go.PLAYBACK_ONCE_BACKWARD",
@@ -1477,9 +2048,32 @@ 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: "BLEND_FACTOR",
+    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",
+    name: "BUFFER_TYPE",
     members: [
       "graphics.BUFFER_TYPE_COLOR0_BIT",
       "graphics.BUFFER_TYPE_COLOR1_BIT",
@@ -1491,7 +2085,22 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "graphics",
-    name: "State",
+    name: "STATE",
+    members: [
+      "graphics.STATE_ALPHA_TEST",
+      "graphics.STATE_ALPHA_TEST_SUPPORTED",
+      "graphics.STATE_BLEND",
+      "graphics.STATE_CULL_FACE",
+      "graphics.STATE_DEPTH_TEST",
+      "graphics.STATE_POLYGON_OFFSET_FILL",
+      "graphics.STATE_SCISSOR_TEST",
+      "graphics.STATE_STENCIL_TEST",
+    ],
+  },
+  // The six render_script.cpp:RenderScript_EnableState accepts.
+  {
+    home: "graphics",
+    parent: "STATE",
     members: [
       "graphics.STATE_DEPTH_TEST",
       "graphics.STATE_STENCIL_TEST",
@@ -1503,12 +2112,33 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "AdjustMode",
+    name: "ADJUST",
     members: ["gui.ADJUST_FIT", "gui.ADJUST_ZOOM", "gui.ADJUST_STRETCH"],
   },
   {
     home: "gui",
-    name: "BlendMode",
+    name: "ANCHOR",
+    members: [
+      "gui.ANCHOR_BOTTOM",
+      "gui.ANCHOR_LEFT",
+      "gui.ANCHOR_NONE",
+      "gui.ANCHOR_RIGHT",
+      "gui.ANCHOR_TOP",
+    ],
+  },
+  {
+    home: "gui",
+    parent: "ANCHOR",
+    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_LEFT", "gui.ANCHOR_RIGHT"],
+  },
+  {
+    home: "gui",
+    parent: "ANCHOR",
+    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_TOP", "gui.ANCHOR_BOTTOM"],
+  },
+  {
+    home: "gui",
+    name: "BLEND",
     members: [
       "gui.BLEND_ALPHA",
       "gui.BLEND_ADD",
@@ -1519,12 +2149,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "ClippingMode",
+    name: "CLIPPING_MODE",
     members: ["gui.CLIPPING_MODE_NONE", "gui.CLIPPING_MODE_STENCIL"],
   },
   {
     home: "gui",
-    name: "Easing",
+    name: "EASING",
     members: [
       "gui.EASING_INBACK",
       "gui.EASING_INBOUNCE",
@@ -1571,7 +2201,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "KeyboardType",
+    name: "KEYBOARD_TYPE",
     members: [
       "gui.KEYBOARD_TYPE_DEFAULT",
       "gui.KEYBOARD_TYPE_EMAIL",
@@ -1581,7 +2211,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "NodeType",
+    name: "TYPE",
     members: [
       "gui.TYPE_BOX",
       "gui.TYPE_TEXT",
@@ -1592,12 +2222,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "PieBounds",
+    name: "PIEBOUNDS",
     members: ["gui.PIEBOUNDS_RECTANGLE", "gui.PIEBOUNDS_ELLIPSE"],
   },
   {
     home: "gui",
-    name: "Pivot",
+    name: "PIVOT",
     members: [
       "gui.PIVOT_CENTER",
       "gui.PIVOT_N",
@@ -1612,7 +2242,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "Playback",
+    name: "PLAYBACK",
     members: [
       "gui.PLAYBACK_ONCE_FORWARD",
       "gui.PLAYBACK_ONCE_BACKWARD",
@@ -1624,7 +2254,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "Property",
+    name: "PROP",
     members: [
       "gui.PROP_POSITION",
       "gui.PROP_ROTATION",
@@ -1643,7 +2273,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "SafeAreaMode",
+    name: "SAFE_AREA",
     members: [
       "gui.SAFE_AREA_NONE",
       "gui.SAFE_AREA_LONG",
@@ -1653,22 +2283,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "gui",
-    name: "SizeMode",
+    name: "SIZE_MODE",
     members: ["gui.SIZE_MODE_MANUAL", "gui.SIZE_MODE_AUTO"],
   },
-  {
-    home: "gui",
-    name: "XAnchor",
-    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_LEFT", "gui.ANCHOR_RIGHT"],
-  },
-  {
-    home: "gui",
-    name: "YAnchor",
-    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_TOP", "gui.ANCHOR_BOTTOM"],
-  },
   {
     home: "profiler",
-    name: "Mode",
+    name: "MODE",
     members: [
       "profiler.MODE_RUN",
       "profiler.MODE_PAUSE",
@@ -1678,7 +2298,7 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "profiler",
-    name: "ViewMode",
+    name: "VIEW_MODE",
     members: ["profiler.VIEW_MODE_FULL", "profiler.VIEW_MODE_MINIMIZED"],
   },
   {
@@ -1690,9 +2310,15 @@ 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",
+    name: "NETWORK",
     members: [
       "sys.NETWORK_DISCONNECTED",
       "sys.NETWORK_CONNECTED_CELLULAR",
@@ -1701,12 +2327,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
   },
   {
     home: "window",
-    name: "DimModeState",
+    name: "DIMMING",
     members: ["window.DIMMING_UNKNOWN", "window.DIMMING_ON", "window.DIMMING_OFF"],
   },
   {
     home: "window",
-    name: "DimModeStateSettable",
+    parent: "DIMMING",
     members: ["window.DIMMING_ON", "window.DIMMING_OFF"],
   },
 ];
@@ -1726,11 +2352,45 @@ export function constantUnionAlias(fqns: readonly string[]): ConstantUnionAlias
   return CONSTANT_UNION_ALIAS_BY_MEMBERS.get(constantUnionAliasKey(fqns));
 }
 
-// The alias declarations a module owns, in name order. A row is declared in its
-// home whether or not that module references it, so a cross-namespace row is
-// reachable from the module whose signatures spell it.
-export function constantUnionAliasDeclarations(namespace: string): string[] {
-  return CONSTANT_UNION_ALIASES.filter((row) => row.home === namespace)
+// What a slot taking exactly the row's members is written as: a named row's
+// qualified name, or a subset row's parent minus the parent's other members,
+// listed in the parent's order.
+export function constantUnionSpelling(row: ConstantUnionAlias): string {
+  if ("name" in row) return `${row.home}.${engineTypeName(row.name)}`;
+  const parent = CONSTANT_UNION_ALIASES.find(
+    (candidate): candidate is ConstantUnionNamedRow =>
+      "name" in candidate && candidate.home === row.home && candidate.name === row.parent,
+  );
+  if (parent === undefined) {
+    throw new Error(`constant union subset of ${row.home}.${row.parent}: no such named row`);
+  }
+  const kept = new Set(row.members);
+  const excluded = parent.members.filter((member) => !kept.has(member));
+  return `Exclude<${row.home}.${engineTypeName(row.parent)}, ${excluded.map((m) => `typeof ${m}`).join(" | ")}>`;
+}
+
+// The named rows a module owns; a subset row declares nothing. A row is
+// declared in its home whether or not that module references it, so a
+// cross-namespace row is reachable from the module whose signatures spell it.
+// A row whose name the module's own `ENUM` already declares is left to that
+// `ENUM`, which carries the reference's member order and nilable arms.
+function ownedConstantUnionAliases(
+  namespace: string,
+  enumDeclared: ReadonlySet<string>,
+): ConstantUnionNamedRow[] {
+  return CONSTANT_UNION_ALIASES.filter(
+    (row): row is ConstantUnionNamedRow =>
+      "name" in row && row.home === namespace && !enumDeclared.has(row.name),
+  );
+}
+
+// The alias declarations a module owns, in name order.
+export function constantUnionAliasDeclarations(
+  namespace: string,
+  enumDeclared: ReadonlySet<string> = new Set(),
+): string[] {
+  return ownedConstantUnionAliases(namespace, enumDeclared)
+    .map((row) => ({ name: engineTypeName(row.name), members: row.members }))
     .sort((a, b) => a.name.localeCompare(b.name))
     .map((row) => unionAliasDeclaration(row.name, row.members));
 }
@@ -1746,10 +2406,12 @@ function unionAliasDeclaration(
 }
 
 // A slot of a function the authored-overload lane declares, published under
-// one alias on every target so the version-independent overload file can
-// name the type each target's own reference gives that slot.
+// one name on every target so the version-independent overload file can name
+// the type each target's own reference gives that slot. The name is the
+// PascalCase name of the newest reference's own declaration for the slot; a
+// target that declares it emits no alias.
 export const OVERLOAD_SLOT_ALIASES: ReadonlyMap<string, string> = new Map([
-  ["render.render_target:param:parameters", "RenderTargetParams"],
+  ["render.render_target:param:parameters", engineTypeName("render_target_params")],
 ]);
 
 const DOC_CONSTANT_TOKEN =
@@ -1801,9 +2463,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 +2490,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 +2506,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 +2531,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 +2586,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 +2608,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,
@@ -1918,7 +2625,34 @@ export type TableSlotCuration = (
   | { kind: "verbatim"; ts: string }
 ) & { readonly retypedUpstream?: readonly string[] };
 
-export const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const;
+// The interface a module's component properties are declared on; its PROPERTY
+// entries carry its members, so it signs no TYPEDEF of its own.
+export const PROPERTIES_INTERFACE = engineTypeName("properties");
+
+// The ref-doc tokens of the handles `socket.select` takes and returns, in their
+// 1.13.2 TYPEDEF spelling, which the type map resolves to each handle's interface.
+export const SOCKET_HANDLE_TOKENS = (["client", "master", "unconnected"] as const).map(
+  (receiver) => `socket_${receiver}`,
+);
+
+// The interface a module's `<receiver>:<method>` colon methods are emitted on:
+// the socket handles take their `Socket<Receiver>` name, any other receiver
+// keeps its own.
+export function handleInterfaceName(namespace: string, receiver: string): string {
+  return namespace === "socket" && Object.hasOwn(SOCKET_HANDLE_NAMES, receiver)
+    ? SOCKET_HANDLE_NAMES[receiver as SocketHandleReceiver]
+    : receiver;
+}
+
+// The typedef names a module's handle interfaces stand for, which emit as the
+// interface rather than an alias: each receiver (1.13.1 `client`) and each
+// interface name, which the 1.13.2 `socket_client` takes once renamed
+// (`SocketClient`).
+function handleTypedefNames(namespace: string, receivers: Iterable<string>): Set<string> {
+  return new Set(
+    [...receivers].flatMap((receiver) => [receiver, handleInterfaceName(namespace, receiver)]),
+  );
+}
 
 // Shared Box2D (b2d.*) table shapes, curated from the ref-doc prose (the docs
 // name fields in running text, not a machine-readable `<dl>`). Reused across the
@@ -2082,25 +2816,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 +2843,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
@@ -2375,70 +3103,14 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // depth/stencil. Both sides are union tokens the mapping string branch splits,
   // so the key emits the three branded constants and the value `number | Vector4`.
   // The key set is a CONSTANT_UNION_ALIASES row, so the signature carries the
-  // `render.ClearBufferKey` alias rather than the three branded arms.
-  [
-    "render.clear:param:buffers",
-    {
-      retypedUpstream: ["table<graphics.BUFFER_TYPE, number|vector4>"],
-      kind: "mapping",
-      key: "graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT",
-      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 },
-      ],
+  // `render.ClearBufferKey` alias rather than the three branded arms.
+  [
+    "render.clear:param:buffers",
+    {
+      retypedUpstream: ["table<graphics.BUFFER_TYPE, number|vector4>"],
+      kind: "mapping",
+      key: "graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT",
+      value: "number | vector4",
     },
   ],
   // physics.create_joint and physics.set_joint_properties both declare
@@ -2932,7 +3604,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
@@ -2973,13 +3647,13 @@ export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, CallbackSignature
         "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: Record<string | number, unknown>) => void",
       typed:
         // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted verbatim as a TS template literal type
-        "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.event_data) => void",
+        "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.EventData) => void",
     },
   ],
   [
     "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.",
     ),
   ],
@@ -3041,9 +3715,11 @@ export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]>
 // `<element>:<kind>:<slot>:<field>`, mirroring NESTED_FIELD_CURATIONS; a field
 // one level down is `<field>.<member>`, or `<field>[].<member>` inside a list.
 //
-// The atlas animation `playback` field is documented as `constant` with the
-// prose "the default value is go.PLAYBACK_ONCE_FORWARD", which names the enum
-// the bare token cannot.
+// Unpinned records below rest on ref-doc tokens or prose. The atlas animation
+// `playback` field is documented as `constant` with the prose "the default value
+// is go.PLAYBACK_ONCE_FORWARD", which names the enum the bare token cannot; its
+// records also carry engine binding pins and apply only when the matching
+// `EmitOptions.bindingEvidence` key holds for the target.
 //
 // `gui.set`'s `options.key` is documented as `hash`, while upstream's own
 // example sets a named font with `{ key = "my_font_name" }`.
@@ -3056,21 +3732,47 @@ export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]>
 // script_resource.cpp:CreateSoundData reads it with CheckBufferOrString.
 const CONSTANT_VALUE_TS = "Vector4 | Vector3 | Matrix4 | number | (Vector4 | Matrix4)[]";
 const ATTRIBUTE_VALUE_TS = "Vector4 | Vector3 | Matrix4 | number | number[]";
-export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
-  ["compute.set_constants:param:constants:value", CONSTANT_VALUE_TS],
-  ["material.set_constants:param:constants:value", CONSTANT_VALUE_TS],
-  ["material.set_vertex_attributes:param:attributes:value", ATTRIBUTE_VALUE_TS],
-  ["material.get_vertex_attributes:return:table:value", ATTRIBUTE_VALUE_TS],
-  ["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.
-  ["gui.set_options:member:key", "string | Hash"],
-  ["resource.sound_data_options:member:data", 'string | Opaque<"buffer">'],
+const ATLAS_BINDING_FILE = "gamesys/src/gamesys/scripts/script_resource.cpp";
+const ATLAS_INPUT_PLAYBACK_BINDING: BindingPin = {
+  file: ATLAS_BINDING_FILE,
+  cFunction: "MakeTextureSetFromLua",
+  contains: "GameObjectPlaybackToDDFPlayback((dmGameObject::Playback) lua_tointeger(L,-1))",
+};
+const ATLAS_OUTPUT_PLAYBACK_BINDING: BindingPin = {
+  file: ATLAS_BINDING_FILE,
+  cFunction: "GetAtlas",
+  contains: "(lua_Integer) DDFPlaybackToGameObjectPlayback(anim.m_Playback)",
+};
+
+export interface TableFieldTypeOverride {
+  readonly ts: string;
+  readonly binding?: BindingPin;
+}
+
+export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, TableFieldTypeOverride> = new Map([
+  ["compute.set_constants:param:constants:value", { ts: CONSTANT_VALUE_TS }],
+  ["material.set_constants:param:constants:value", { ts: CONSTANT_VALUE_TS }],
+  ["material.set_vertex_attributes:param:attributes:value", { ts: ATTRIBUTE_VALUE_TS }],
+  ["material.get_vertex_attributes:return:table:value", { ts: ATTRIBUTE_VALUE_TS }],
+  [
+    "resource.set_atlas:param:table:animations[].playback",
+    { ts: "go.Playback", binding: ATLAS_INPUT_PLAYBACK_BINDING },
+  ],
+  [
+    "resource.create_atlas:param:table:animations[].playback",
+    { ts: "go.Playback", binding: ATLAS_INPUT_PLAYBACK_BINDING },
+  ],
+  [
+    "resource.get_atlas:return:data:animations[].playback",
+    { ts: "go.Playback", binding: ATLAS_OUTPUT_PLAYBACK_BINDING },
+  ],
+  ["render.set_render_target:param:options:transient", { ts: "graphics.BufferType[]" }],
+  ["resource.create_sound_data:param:options:data", { ts: 'string | Opaque<"buffer">' }],
+  // 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", { ts: "string | Hash" }],
+  ["resource.sound_data_options:member:data", { ts: 'string | Opaque<"buffer">' }],
   // Bitmasks typed as their flag enum: the create_texture example passes
   // TEXTURE_USAGE_FLAG_STORAGE + TEXTURE_USAGE_FLAG_SAMPLE, a sum no single member
   // names, and a reported value combines them the same way.
@@ -3081,8 +3783,15 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
       "resource.render_target_attachment_info",
       "material.texture_info",
     ] 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"],
+  ).map(
+    (struct) => [`${struct}:member:flags`, { ts: "graphics.TextureUsageFlag | number" }] as const,
+  ),
+  ["render.render_target_buffer_params:member:flags", { ts: "render.RenderTargetFlag | 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", { ts: "graphics.TextureType | 6 | 7 | 8 | 9 | 10" }],
 ]);
 
 // A field the engine accepts on an option bag whose `<dl>` upstream otherwise
@@ -3102,13 +3811,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 +3825,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
@@ -3538,12 +4222,16 @@ export function applyFieldTypeOverrides(
   slotKind: "param" | "return" | undefined,
   slotName: string | undefined,
   fields: readonly TableField[],
+  bindingEvidence: ReadonlySet<string>,
 ): TableField[] {
   if (slotKind === undefined || slotName === undefined) return [...fields];
   const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
   const typed = (field: TableField, path: string): TableField => {
-    const override = TABLE_FIELD_TYPE_OVERRIDES.get(`${prefix}${path}`);
-    return override === undefined ? field : { ...field, tsType: override };
+    const key = `${prefix}${path}`;
+    const override = TABLE_FIELD_TYPE_OVERRIDES.get(key);
+    return override === undefined || (override.binding !== undefined && !bindingEvidence.has(key))
+      ? field
+      : { ...field, tsType: override.ts };
   };
   return fields.map((field) => {
     const own = typed(field, field.name);
@@ -3890,22 +4578,84 @@ 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.RenderTargetBufferParams }",
+      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.
 //
 // An engine typedef that names its aliased type: a `userdata`/`number` handle the
-// type map resolves (`vector`, `socket_client`) aliases that mapping, an
+// type map resolves (`timer_handle`, `buffer_data`) aliases that mapping, an
 // unresolved one keeps the brand, and any other aliased type (a union, literals, a
-// record) aliases the type itself.
+// record) aliases the type itself. A handle the type map resolves to a core
+// global (`vector` -> `Vector`, `resource_data` -> `Hash`) declares nothing, since
+// its slots already name the global: `null`.
 function typedefAlias(
   typedef: ApiTypedef,
   local: string,
   rawMapType: (token: string) => string,
   mapType: DefoldTypeMapper,
-): string {
+): string | null {
   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)
@@ -3914,10 +4664,23 @@ function typedefAlias(
   }
   const mapped = rawMapType(typedef.name);
   if (mapped.startsWith(brand)) return `type ${local} = ${mapped};`;
+  if (aliasOf.length > 0 && CORE_GLOBAL_TYPES.has(mapped)) return null;
   const resolved = aliasOf.length > 0 && mapped !== "unknown" && mapped !== local;
   return `type ${local} = ${resolved ? mapped : brand};`;
 }
 
+// The global types `core-types.ts` declares that the engine vocabulary maps a
+// handle to.
+const CORE_GLOBAL_TYPES: ReadonlySet<string> = new Set([
+  "Hash",
+  "Matrix4",
+  "Quaternion",
+  "Url",
+  "Vector",
+  "Vector3",
+  "Vector4",
+]);
+
 function isHandleAlias(aliasOf: readonly string[]): boolean {
   return aliasOf.length === 1 && (aliasOf[0] === "userdata" || aliasOf[0] === "number");
 }
@@ -3934,8 +4697,9 @@ interface TypeDeclaration {
 
 // A typedef with no aliased type keeps the flat-name rule it always had; one that
 // names its aliased type, and every struct, sits at its name less the module
-// prefix, nested when that local is dotted. Typedefs come before structs, each in
-// document order.
+// prefix, nested when that local is dotted. Every leaf goes through
+// `engineTypeName`, and `skip` matches a typedef by its reference local or its
+// renamed path. Typedefs come before structs, each in document order.
 function collectTypeDeclarations(
   module: ApiModule,
   skip: ReadonlySet<string>,
@@ -3952,12 +4716,15 @@ function collectTypeDeclarations(
   for (const t of module.typedefs) {
     const local =
       t.aliasOf === undefined ? (TS_IDENTIFIER.test(t.name) ? t.name : null) : localOf(t.name);
-    if (local === null || skip.has(local)) continue;
-    const name = local.slice(local.lastIndexOf(".") + 1);
+    if (local === null) continue;
+    const path = renamedLeaf(local);
+    if (skip.has(local) || skip.has(path)) continue;
+    const name = path.slice(path.lastIndexOf(".") + 1);
     const signature = typedefAlias(t, name, rawMapType, mapType);
+    if (signature === null) continue;
     out.push({
       name,
-      path: local,
+      path,
       lines: (indent, decl) => [`${indent}${decl}${signature}`],
       signature,
     });
@@ -4015,11 +4782,12 @@ function correctedListMemberType(
 
 function structDeclaration(
   struct: ApiStruct,
-  path: string,
+  local: string,
   mapType: DefoldTypeMapper,
   structs: readonly ApiStruct[],
   bindingEvidence: ReadonlySet<string>,
 ): TypeDeclaration {
+  const path = renamedLeaf(local);
   const name = path.slice(path.lastIndexOf(".") + 1);
   const memberPrefix = memberCorrectionKey(struct.name, "");
   const declared = new Set(struct.members.map((member) => member.name));
@@ -4046,7 +4814,9 @@ function structDeclaration(
   const members = [...struct.members, ...added].map((member) => {
     const key = memberCorrectionKey(struct.name, member.name);
     const list = LIST_FIELD_CORRECTIONS.get(key);
-    const retyped = TABLE_FIELD_TYPE_OVERRIDES.get(key);
+    const listedRetype = TABLE_FIELD_TYPE_OVERRIDES.get(key);
+    const retyped =
+      listedRetype?.binding === undefined || bindingEvidence.has(key) ? listedRetype : undefined;
     const optional =
       (member.isOptional || OPTIONAL_MEMBER_CORRECTIONS.has(key)) &&
       !REQUIRED_FIELD_CORRECTIONS.has(key);
@@ -4054,7 +4824,7 @@ function structDeclaration(
       list !== undefined
         ? correctedListMemberType(struct, member, list, structs, mapType)
         : retyped !== undefined
-          ? retyped
+          ? retyped.ts
           : member.type === ""
             ? "unknown"
             : mapType(member.type);
@@ -4078,7 +4848,10 @@ function structDeclaration(
         `${indent}}`,
       ];
     },
-    signature: `interface ${name} { ${members.map((member) => `${member.line} `).join("")}}`,
+    signature: interfaceSignature(
+      name,
+      members.map((member) => member.line),
+    ),
   };
 }
 
@@ -4137,8 +4910,9 @@ function moduleTypeMappers(
  * dropped, so the home's own copy wins; a type sharing a value's name
  * (`resource.atlas`) is untouched. A function moves the same way (1.13.2 files
  * `bullet3d.collision_object.get_shapes` in the shape doc), since the emitter
- * declares only the functions under a module's own namespace. Modules with
- * nothing moved in or out are returned as-is.
+ * declares only the functions under a module's own namespace. A moved type
+ * records the module that declared it as `declaredIn`. Modules with nothing
+ * moved in or out are returned as-is.
  */
 export function routeTypeDeclarations(modules: readonly ApiModule[]): ApiModule[] {
   const homeOf = (name: string, declaring: string): string => {
@@ -4168,14 +4942,14 @@ export function routeTypeDeclarations(modules: readonly ApiModule[]): ApiModule[
     const structs = (module.structs ?? []).filter((struct) => {
       const home = homeOf(struct.name, module.namespace);
       if (home === module.namespace) return true;
-      into(home).structs.push(struct);
+      into(home).structs.push({ ...struct, declaredIn: module.namespace });
       return false;
     });
     const typedefs = module.typedefs.filter((typedef) => {
       if (typedef.aliasOf === undefined) return true;
       const home = homeOf(typedef.name, module.namespace);
       if (home === module.namespace) return true;
-      into(home).typedefs.push(typedef);
+      into(home).typedefs.push({ ...typedef, declaredIn: module.namespace });
       return false;
     });
     const functions = module.functions.filter((fn) => {
@@ -4218,27 +4992,32 @@ export function routeTypeDeclarations(modules: readonly ApiModule[]): ApiModule[
 /**
  * The TS path of every `ENUM`, `STRUCT` and aliasing `TYPEDEF` the (routed)
  * modules declare, keyed by its Lua name: the name itself when it sits under its
- * module's namespace, else that name nested under the module
- * (`on_input.action` in `go` is `go.on_input.action`).
+ * module's namespace, else that name nested under the module, with its leaf
+ * through `engineTypeName` (`on_input.action` in `go` is `go.on_input.Action`).
  */
 export function declaredTypePaths(modules: readonly ApiModule[]): Map<string, string> {
   const paths = new Map<string, string>();
   for (const module of modules) {
-    const names = [
-      ...(module.enums ?? []).map((e) => e.name),
-      ...(module.structs ?? []).map((struct) => struct.name),
-      ...module.typedefs.filter((t) => t.aliasOf !== undefined).map((t) => t.name),
-    ];
-    for (const name of names) {
-      paths.set(
-        name,
-        name.startsWith(`${module.namespace}.`) ? name : `${module.namespace}.${name}`,
-      );
+    const qualified = (name: string): string =>
+      name.startsWith(`${module.namespace}.`) ? name : `${module.namespace}.${name}`;
+    for (const { name } of [
+      ...(module.enums ?? []),
+      ...(module.structs ?? []),
+      ...module.typedefs.filter((t) => t.aliasOf !== undefined),
+    ]) {
+      paths.set(name, renamedLeaf(qualified(name)));
     }
   }
   return paths;
 }
 
+// A dotted type path with its last segment through `engineTypeName`: the
+// namespace segments mirror the engine's functions and stay as they are.
+function renamedLeaf(path: string): string {
+  const dot = path.lastIndexOf(".");
+  return `${path.slice(0, dot + 1)}${engineTypeName(path.slice(dot + 1))}`;
+}
+
 export function emitDeclarations(documented: ApiModule, options?: EmitOptions): string {
   const module = withUndocumentedConstants(documented, options?.registeredConstants);
   const prefix = `${module.namespace}.`;
@@ -4248,11 +5027,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
@@ -4285,6 +5066,13 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   const nestedRoot = collectNestedGroups(module, prefix);
   const enumAliases = collectEnumAliases(module, constants, nestedRoot);
 
+  const resolver = buildTableDocResolver(
+    module.functions.map((fn) => ({
+      name: fn.name,
+      slots: [...fn.parameters, ...fn.returnValues],
+    })),
+  );
+
   // Colon methods (`client:send`) are FUNCTION elements named `<receiver>:<method>`
   // and are NOT namespace-prefixed, so they fail the flat-identifier test in
   // prepareFunction (the colon) and are absent from `functions`. A returned handle
@@ -4292,27 +5080,26 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   // interface, the same non-flat recovery the dns nested-namespace pass does one
   // container shape shallower.
   const handleGroups = collectHandleMethodGroups(module);
-  const handleReceivers = [...handleGroups.keys()].sort((a, b) => a.localeCompare(b));
-
-  const resolver = buildTableDocResolver(
-    module.functions.map((fn) => ({
-      name: fn.name,
-      slots: [...fn.parameters, ...fn.returnValues],
-    })),
+  const handleInterfaces = collectHandleInterfaces(
+    module.namespace,
+    handleGroups,
+    mapType,
+    resolver,
+    constantTokens,
+    urlParameters,
+    bindingEvidence,
   );
 
   // A typedef that also has colon methods is emitted as a method-bearing
   // interface below, not an opaque brand alias.
-  const typeDeclarations = placeTypeDeclarations(
-    collectTypeDeclarations(
-      module,
-      new Set(handleGroups.keys()),
-      rawMapType,
-      mapType,
-      bindingEvidence,
-    ),
-    nestedRoot,
+  const collectedTypes = collectTypeDeclarations(
+    module,
+    handleTypedefNames(module.namespace, handleGroups.keys()),
+    rawMapType,
+    mapType,
+    bindingEvidence,
   );
+  const typeDeclarations = placeTypeDeclarations(collectedTypes, nestedRoot);
 
   // A re-export alias (`export { _x as x }`) switches the ambient namespace out
   // of its implicit-export mode, so once any alias is present every sibling
@@ -4329,18 +5116,22 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   lines.push(`declare namespace ${module.namespace} {`);
 
   for (const declaration of typeDeclarations) lines.push(...declaration.lines(INDENT, decl));
-  for (const aliasDecl of constantUnionAliasDeclarations(module.namespace)) {
+  for (const aliasDecl of constantUnionAliasDeclarations(
+    module.namespace,
+    new Set(enumAliases.all.map((alias) => alias.path)),
+  )) {
     lines.push(`${INDENT}${decl}${aliasDecl}`);
   }
-  for (const aliasDecl of overloadSlotAliasDeclarations(
+  for (const { declaration } of overloadSlotAliasDeclarations(
     [...module.functions, ...(options?.withheldFunctions ?? [])],
+    collectedTypes,
     prefix,
     mapType,
     constantTokens,
     urlParameters,
     bindingEvidence,
   )) {
-    lines.push(`${INDENT}${decl}${aliasDecl}`);
+    lines.push(`${INDENT}${decl}${declaration}`);
   }
   for (const alias of enumAliases.topLevel) {
     lines.push(
@@ -4348,16 +5139,13 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
     );
   }
   const handleIndent = `${INDENT}${INDENT}`;
-  for (const receiver of handleReceivers) {
-    const group = handleGroups.get(receiver) ?? [];
-    lines.push(`${INDENT}${decl}interface ${receiver} {`);
-    for (const fn of group) {
+  for (const { name, members } of handleInterfaces) {
+    lines.push(`${INDENT}${decl}interface ${name} {`);
+    for (const { fn, text } of members) {
       for (const docLine of functionDocLines(fn.original, translations, baseNotes, handleIndent)) {
         lines.push(docLine);
       }
-      lines.push(
-        `${handleIndent}${emitMethod(fn, mapType, resolver, constantTokens, urlParameters, bindingEvidence)}`,
-      );
+      lines.push(`${handleIndent}${text}`);
     }
     lines.push(`${INDENT}}`);
   }
@@ -4385,18 +5173,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
@@ -4501,9 +5291,9 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
 
   if (module.properties.length > 0) {
     const members = [...module.properties].sort((a, b) => a.name.localeCompare(b.name));
-    lines.push(`${INDENT}${decl}interface properties {`);
+    lines.push(`${INDENT}${decl}interface ${PROPERTIES_INTERFACE} {`);
     for (const p of members) {
-      for (const member of emitPropertyMembers(p, mapType, module.namespace)) {
+      for (const member of emitPropertyMembers(p, mapType, module.namespace, bindingEvidence)) {
         for (const docLine of summaryDocLines(p.brief, p.description, `${INDENT}${INDENT}`)) {
           lines.push(docLine);
         }
@@ -4518,17 +5308,25 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
 }
 
 // One `type <alias> = <slot type>;` per `OVERLOAD_SLOT_ALIASES` slot these
-// functions carry, in alias order. The type is the one `emitFunction` reports
-// for the slot, so it reads as the function's own signature would. The
-// resolver spans these functions alone, leaving the module's own untouched.
+// functions carry, in alias order, skipping an alias one of the module's
+// top-level type `declarations` already names. The type is the one
+// `emitFunction` reports for the slot, so it reads as the function's own
+// signature would. The resolver spans these functions alone, leaving the
+// module's own untouched.
 function overloadSlotAliasDeclarations(
   functions: readonly ApiFunction[],
+  declarations: readonly TypeDeclaration[],
   prefix: string,
   mapType: DefoldTypeMapper,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
   bindingEvidence: ReadonlySet<string>,
-): string[] {
+): { name: string; declaration: string }[] {
+  const declared = new Set(
+    declarations
+      .filter((declaration) => declaration.path === declaration.name)
+      .map((declaration) => declaration.name),
+  );
   const resolver = buildTableDocResolver(
     functions.map((fn) => ({ name: fn.name, slots: [...fn.parameters, ...fn.returnValues] })),
   );
@@ -4536,7 +5334,7 @@ function overloadSlotAliasDeclarations(
   for (const fn of functions) {
     for (const [position, p] of fn.parameters.entries()) {
       const alias = OVERLOAD_SLOT_ALIASES.get(tableSlotKey(fn.name, "param", p.name));
-      if (alias === undefined) continue;
+      if (alias === undefined || declared.has(alias)) continue;
       const prepared = prepareFunction(fn, prefix);
       if (prepared === null) continue;
       const slots: Record<string, SlotType> = {};
@@ -4563,7 +5361,51 @@ function overloadSlotAliasDeclarations(
   }
   return [...types]
     .sort(([a], [b]) => a.localeCompare(b))
-    .map(([alias, type]) => `type ${alias} = ${type};`);
+    .map(([name, type]) => ({ name, declaration: `type ${name} = ${type};` }));
+}
+
+// A method of a handle interface: the member text the declarations print inside
+// the interface, which its FUNCTION entry signs too.
+interface HandleMember {
+  fn: PreparedFunction;
+  text: string;
+  slotTypes: SlotTypes;
+}
+
+// Each handle interface a module's colon methods declare, sorted by name, with
+// its methods in group order.
+function collectHandleInterfaces(
+  namespace: string,
+  handleGroups: ReadonlyMap<string, readonly PreparedFunction[]>,
+  mapType: DefoldTypeMapper,
+  resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
+  urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
+): { name: string; members: HandleMember[] }[] {
+  return [...handleGroups]
+    .map(([receiver, group]) => ({
+      name: handleInterfaceName(namespace, receiver),
+      members: group.map((fn): HandleMember => {
+        const slotTypes: Record<string, SlotType> = {};
+        const text = emitMethod(
+          fn,
+          mapType,
+          resolver,
+          constantTokens,
+          urlParameters,
+          bindingEvidence,
+          slotTypes,
+        );
+        return { fn, text, slotTypes };
+      }),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// An interface signed on one line, each member line followed by a space.
+function interfaceSignature(name: string, members: readonly string[]): string {
+  return `interface ${name} { ${members.map((member) => `${member} `).join("")}}`;
 }
 
 /**
@@ -4620,10 +5462,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 +5494,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 +5506,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 });
   }
 
@@ -4720,24 +5565,29 @@ export function emitSymbolSignatures(
     });
   }
 
+  // A handle interface signs as one line, as a struct does; each member is the
+  // text its method's FUNCTION entry signs.
   const handleGroups = collectHandleMethodGroups(module);
-  for (const group of handleGroups.values()) {
-    for (const prepared of group) {
-      const slotTypes: Record<string, SlotType> = {};
-      out.push({
-        identity: fnIdentity(prepared.original),
-        tsSignature: emitMethod(
-          prepared,
-          mapType,
-          resolver,
-          constantTokens,
-          urlParameters,
-          bindingEvidence,
-          slotTypes,
-        ),
-        slotTypes,
-      });
+  for (const { name, members } of collectHandleInterfaces(
+    module.namespace,
+    handleGroups,
+    mapType,
+    resolver,
+    constantTokens,
+    urlParameters,
+    bindingEvidence,
+  )) {
+    for (const { fn, text, slotTypes } of members) {
+      out.push({ identity: fnIdentity(fn.original), tsSignature: text, slotTypes });
     }
+    out.push({
+      identity: { namespace: module.namespace, kind: "TYPEDEF", name, signature: "" },
+      tsSignature: interfaceSignature(
+        name,
+        members.map((member) => member.text),
+      ),
+      slotTypes: NO_SLOTS,
+    });
   }
 
   const constants: PreparedConstant[] = [];
@@ -4766,7 +5616,7 @@ export function emitSymbolSignatures(
   // carries the first, which is verbatim in the `.d.ts` and is what the `/api`
   // render layer reduces to `<placeholder>: <type>`.
   for (const p of module.properties) {
-    const [firstMember = ""] = emitPropertyMembers(p, mapType, module.namespace);
+    const [firstMember = ""] = emitPropertyMembers(p, mapType, module.namespace, bindingEvidence);
     out.push({
       identity: { namespace: module.namespace, kind: "PROPERTY", name: p.name, signature: "" },
       tsSignature: firstMember,
@@ -4776,13 +5626,14 @@ export function emitSymbolSignatures(
 
   // A struct signs as its interface on one line; each member line is verbatim in
   // the declarations.
-  for (const declaration of collectTypeDeclarations(
+  const typeDeclarations = collectTypeDeclarations(
     module,
-    new Set(handleGroups.keys()),
+    handleTypedefNames(module.namespace, handleGroups.keys()),
     rawMapType,
     mapType,
     bindingEvidence,
-  )) {
+  );
+  for (const declaration of typeDeclarations) {
     out.push({
       identity: {
         namespace: module.namespace,
@@ -4795,23 +5646,50 @@ export function emitSymbolSignatures(
     });
   }
 
+  // An overload-slot alias is declared exactly where the declarations carry it,
+  // so it signs from the same functions and the same declared set.
+  for (const { name, declaration } of overloadSlotAliasDeclarations(
+    [...module.functions, ...(options?.withheldFunctions ?? [])],
+    typeDeclarations,
+    prefix,
+    mapType,
+    constantTokens,
+    urlParameters,
+    bindingEvidence,
+  )) {
+    out.push({
+      identity: { namespace: module.namespace, kind: "TYPEDEF", name, signature: "" },
+      tsSignature: declaration,
+      slotTypes: NO_SLOTS,
+    });
+  }
+
   // The module's constant-union aliases travel as typedefs too: a signature that
   // names one carries no member list of its own, so the docs read the members
   // from here rather than from the emitter's table.
-  for (const row of CONSTANT_UNION_ALIASES.filter((r) => r.home === module.namespace)) {
+  const enumAliases = collectEnumAliases(module, constants, nestedRoot);
+  for (const row of ownedConstantUnionAliases(
+    module.namespace,
+    new Set(enumAliases.all.map((alias) => alias.path)),
+  )) {
+    const name = engineTypeName(row.name);
     out.push({
-      identity: { namespace: module.namespace, kind: "TYPEDEF", name: row.name, signature: "" },
-      tsSignature: unionAliasDeclaration(row.name, row.members),
+      identity: { namespace: module.namespace, kind: "TYPEDEF", name, signature: "" },
+      tsSignature: unionAliasDeclaration(name, row.members),
       slotTypes: NO_SLOTS,
     });
   }
 
-  // An enum alias is keyed by its local path (`STATUS`, `ui.COLOR`), as the
-  // constant-union aliases above are keyed by their local name.
-  const enumAliases = collectEnumAliases(module, constants, nestedRoot);
+  // An enum alias is keyed by its declared local path (`Status`, `ui.Color`),
+  // as the constant-union aliases above are keyed by their declared name.
   for (const alias of enumAliases.all) {
     out.push({
-      identity: { namespace: module.namespace, kind: "TYPEDEF", name: alias.path, signature: "" },
+      identity: {
+        namespace: module.namespace,
+        kind: "TYPEDEF",
+        name: renamedLeaf(alias.path),
+        signature: "",
+      },
       tsSignature: unionAliasDeclaration(alias.name, alias.members, alias.nilable),
       slotTypes: NO_SLOTS,
     });
@@ -4829,6 +5707,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 {
@@ -4847,8 +5731,9 @@ interface NestedGroup {
   children: Map<string, NestedGroup>;
 }
 
-// One `ENUM`'s union alias: `name` is the declared identifier, `path` the local
-// path under the module namespace (`ui.COLOR`), `members` the member FQNs.
+// One `ENUM`'s union alias: `name` is the declared identifier (`Color`), `path`
+// the reference's local path under the module namespace (`ui.COLOR`), `members`
+// the member FQNs.
 interface EnumAlias {
   name: string;
   path: string;
@@ -4977,12 +5862,14 @@ function collectEnumAliases(
   const nilable = new Set(module.constants.filter((c) => c.nilable).map((c) => c.name));
   const topLevel: EnumAlias[] = [];
   const all: EnumAlias[] = [];
-  const enums = [...(module.enums ?? [])].sort((a, b) => a.name.localeCompare(b.name));
+  const enums = [...(module.enums ?? [])].sort((a, b) =>
+    renamedLeaf(a.name).localeCompare(renamedLeaf(b.name)),
+  );
   for (const e of enums) {
     if (e.members.length === 0 || !e.members.every((m) => declared.has(m))) continue;
     const path = stripPrefix(e.name, prefix);
     if (TS_IDENTIFIER.test(path)) {
-      const alias = { name: path, path, members: e.members, nilable };
+      const alias = { name: engineTypeName(path), path, members: e.members, nilable };
       topLevel.push(alias);
       all.push(alias);
       continue;
@@ -4998,7 +5885,7 @@ function collectEnumAliases(
       level = group.children;
     }
     if (group === undefined) continue;
-    const alias = { name, path, members: e.members, nilable };
+    const alias = { name: engineTypeName(name), path, members: e.members, nilable };
     group.enumAliases.push(alias);
     all.push(alias);
   }
@@ -5112,10 +5999,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 +6026,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 +6042,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 +6055,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 +6150,26 @@ 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,
+      bindingEvidence,
+      required.has(i),
+      prepared.retype?.get(i),
+    ),
   );
   const rest =
     varargIndex === -1
@@ -5260,6 +6182,7 @@ function memberSignature(
           constantTokens,
           elementName,
           urlParameters,
+          bindingEvidence,
         );
   const params = [...positional.map((p) => p.text), ...(rest ? [rest.text] : [])].join(", ");
   const ret = emitReturn(
@@ -5296,7 +6219,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 +6290,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 +6323,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
@@ -5521,6 +6448,7 @@ function parameterType(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
 ): string {
   const concrete = p.types.filter((t) => t !== "nil");
   // The caller supplies a parameter, so a string-keyed table in it also takes an
@@ -5542,10 +6470,19 @@ function parameterType(
           elementName,
           "param",
           p.name,
+          bindingEvidence,
         )
       : "unknown";
-  const correction = PARAM_TYPE_CORRECTIONS.get(tableSlotKey(elementName, "param", p.name));
-  if (correction === undefined || !pinMatches(p.types, correctionPins(correction))) return mapped;
+  const key = tableSlotKey(elementName, "param", p.name);
+  const correction = PARAM_TYPE_CORRECTIONS.get(key);
+  if (
+    correction === undefined ||
+    !pinMatches(p.types, correctionPins(correction)) ||
+    (correction.binding !== undefined && !bindingEvidence.has(key))
+  ) {
+    return mapped;
+  }
+  if (correction.ts !== undefined) return correction.ts;
   const kept =
     correction.removes === undefined ? mapped : withoutUnionMembers(mapped, correction.removes);
   if (correction.adds === undefined) return kept;
@@ -5627,13 +6564,22 @@ function emitRestParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
 ): { text: string; slots: EmittedSlot[] } {
   const vararg = params[varargIndex];
   if (vararg === undefined) return { text: "", slots: [] };
   const folded = params.slice(varargIndex).map((p, offset) => ({
     position: varargIndex + offset,
     name: p.name,
-    ts: parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
+    ts: parameterType(
+      p,
+      mapType,
+      resolver,
+      constantTokens,
+      elementName,
+      urlParameters,
+      bindingEvidence,
+    ),
   }));
   const members = [...new Set(folded.map((slot) => slot.ts))];
   const first = members[0] ?? "unknown";
@@ -5661,15 +6607,28 @@ function emitParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
+  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,
+      bindingEvidence,
+    ),
+  );
   // 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" : ""}`;
@@ -5734,6 +6693,7 @@ function emitReturn(
                 elementName,
                 "return",
                 rv.name,
+                bindingEvidence,
               )
             : "unknown"),
       };
@@ -5772,6 +6732,7 @@ function emitReturn(
           elementName,
           "return",
           first.name,
+          bindingEvidence,
         )
       : "unknown";
   // A LuaLS vararg return (`...`) is every value the call returns, however many.
@@ -5811,12 +6772,17 @@ function emitPropertyMembers(
   p: ApiProperty,
   mapType: DefoldTypeMapper,
   namespace: string,
+  bindingEvidence: ReadonlySet<string>,
 ): readonly string[] {
-  const keyRange = PROPERTY_KEY_RANGES.get(`${namespace}.${p.name}`);
+  const rangeKey = `${namespace}.${p.name}`;
+  const keyRange = PROPERTY_KEY_RANGES.get(rangeKey);
   const keys: string[] = [];
   if (keyRange !== undefined) {
-    for (let unit = keyRange.first; unit <= keyRange.last; unit++)
-      keys.push(`${keyRange.prefix}${unit}`);
+    const last =
+      keyRange.engine !== undefined && bindingEvidence.has(rangeKey)
+        ? keyRange.engine.last
+        : keyRange.last;
+    for (let unit = keyRange.first; unit <= last; unit++) keys.push(`${keyRange.prefix}${unit}`);
   } else {
     keys.push(TS_IDENTIFIER.test(p.name) ? p.name : JSON.stringify(p.name));
   }
@@ -5838,6 +6804,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
@@ -5853,8 +6861,9 @@ function mapSlotUnion(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
-  slotKind?: "param" | "return",
-  slotName?: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  bindingEvidence: ReadonlySet<string>,
 ): string {
   const mapped: string[] = [];
   const seen = new Set<string>();
@@ -5918,6 +6927,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") {
@@ -5943,6 +6956,7 @@ function mapSlotUnion(
             slotKind,
             slotName,
             parseTableFields(doc, resolver, slotName) ?? [],
+            bindingEvidence,
           ),
         );
         const object = inlineTableType(parsed, mapType, optionalFields);
@@ -5952,7 +6966,13 @@ function mapSlotUnion(
         if (parsed !== null) {
           const added = applyFieldAdditions(elementName, slotKind, slotName, parsed);
           const nested = applyNestedFieldCurations(elementName, slotKind, slotName, added);
-          const typed = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
+          const typed = applyFieldTypeOverrides(
+            elementName,
+            slotKind,
+            slotName,
+            nested,
+            bindingEvidence,
+          );
           const required = applyRequiredFieldCorrections(
             elementName,
             slotKind,
@@ -5991,8 +7011,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 {
@@ -6120,8 +7142,8 @@ function withoutSubsumedOpaqueArms(mapped: readonly string[]): string[] {
   });
 }
 
-// Joins already-mapped arms, collapsing the branded ones to their alias when
-// they are exactly a `CONSTANT_UNION_ALIASES` member set. The alias takes the
+// Joins already-mapped arms, collapsing the branded ones to their row's spelling
+// when they are exactly a `CONSTANT_UNION_ALIASES` member set. The spelling takes the
 // position of the first branded arm, so a mixed union keeps its reading order
 // (`gui.Easing | Vector`). Arms that are not constants are untouched, and a set
 // with no row keeps every arm inline.
@@ -6139,7 +7161,7 @@ function joinUnionArms(mapped: readonly string[]): string {
   for (const arm of arms) {
     if (BRAND_ARM.test(arm)) {
       if (placed) continue;
-      out.push(`${alias.home}.${alias.name}`);
+      out.push(constantUnionSpelling(alias));
       placed = true;
       continue;
     }