@defold-typescript/types 0.40.0 → 0.41.0

package/src/emit-dts.ts

@@ -1,3 +1,4 @@
+import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
 import { type ApiSymbolIdentity, normalizedFunctionSignature } from "./api-availability";
 import type {
   ApiConstant,
@@ -5,22 +6,41 @@ import type {
   ApiModule,
   ApiParameter,
   ApiProperty,
+  ApiStruct,
+  ApiStructMember,
+  ApiTypedef,
   ApiVariable,
 } from "./api-doc";
 import { DEFOLD_TYPE_MAP } from "./core-types";
+import { correctionPins, pinMatches, propertyCorrectionPins } from "./correction-pins";
 import {
   type DocCommentParts,
   htmlToCodeText,
   htmlToDocText,
   renderDocComment,
   splitExampleSources,
+  summaryFor,
 } from "./doc-comment";
 import type { TranslationStore } from "./example-store";
-import { hashExampleSource, lookupExampleTranslations, lookupTranslation } from "./example-store";
+import { lookupExampleSegments, translateProseFences } from "./example-store";
+import {
+  appendNotes,
+  type IndexBaseNoteResolver,
+  type IndexBaseSource,
+  indexBaseNoteResolver,
+  OVERRIDE_RETURN_SLOT,
+} from "./index-slot-classifications";
+import { type LualsPosition, mapLualsExpression, needsArrayParens } from "./luals-type-expr";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
+export { summaryFor };
+
+// Maps one ref-doc type token. `position` says whether the caller supplies the
+// value (a parameter) or the engine hands it back; see `LualsPosition`.
+export type DefoldTypeMapper = (token: string, position?: LualsPosition) => string;
+
 export interface EmitOptions {
-  mapType?: (defoldType: string) => string;
+  mapType?: DefoldTypeMapper;
   // Constant FQNs from *other* modules, so a foreign token like
   // `graphics.BUFFER_TYPE_COLOR0_BIT` used as a param type inside `render`
   // brands to the same FQN-keyed type its owning module's `const` emits,
@@ -38,6 +58,23 @@ export interface EmitOptions {
   // emit. `regen` supplies the committed `url-parameters.json`; the table
   // arrives as data so this module stays free of `node:fs` (bug-88).
   urlParameters?: UrlParameterTable;
+  // Which classification map the index-base notes read. Defaults to the engine
+  // map; a library or extension declaration passes its page keys (`[]` for one
+  // no page documents), so it never names Defold as the receiver.
+  indexBaseSource?: IndexBaseSource;
+  // The TS path of each `ENUM`, `STRUCT` and `TYPEDEF` another module declares
+  // (`declaredTypePaths`), so a token naming one resolves instead of widening to
+  // `unknown`. The module's own declarations resolve without it. Read only by the
+  // default engine mapper; a caller-supplied `mapType` keeps its own vocabulary.
+  declaredTypes?: ReadonlyMap<string, string>;
+  // Tokens a surface names that the engine vocabulary does not (the editor's
+  // handles), resolved ahead of it both as whole tokens and as leaves inside a
+  // composite. Read by the default mapper together with the declared types.
+  typeLeaves?: Readonly<Record<string, string>>;
+  // Constant FQNs the target's own engine bindings register, which gate the
+  // `UNDOCUMENTED_CONSTANTS` back-fill. Absent for a surface with no vendored
+  // bindings (a ref-doc target), where every entry the ref-doc omits is emitted.
+  registeredConstants?: ReadonlySet<string>;
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -174,11 +211,6 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
 // not a loss. The audit skips counting these; the emitter already leaves an
 // uncurated slot as `Record`. Add deliberately, one rationale per line.
 export const ARBITRARY_TABLE_SLOT_KEYS = new Set([
-  // "the chain definition" / "the shape definition" / "explosion definition" —
-  // create-side option tables with no documented field list at this slot.
-  "b2d.body.create_chain:param:definition",
-  "b2d.body.create_shape:param:definition",
-  "b2d.world.explode:param:definition",
   "b2d.joint.create_filter:param:definition", // "optional definition table"
   // opaque Box2D result structs: the doc names no fields.
   "b2d.chain.get_geometry:return:geometry", // "chain geometry table"
@@ -196,6 +228,18 @@ export const ARBITRARY_TABLE_SLOT_KEYS = new Set([
 // set to keep the `droppedMembers` count honest; an uncovered skip (e.g. a new
 // `skipFunctions` entry with no matching overload) still counts, so the gate
 // stays a real signal. Mirrors the ARBITRARY_TABLE_SLOTS audit-honesty pattern.
+// A slot the engine treats as omissible on a function OVERLOAD_COVERED_SKIPS
+// hands to a `*-overloads.d.ts` form without it, where no generated declaration
+// exists for OPTIONAL_SLOT_CORRECTIONS to reach. Availability identity reads it
+// as optional, so a ref-doc that starts marking it is no change. The value is
+// the evidence, as in OPTIONAL_SLOT_CORRECTIONS.
+export const HAND_DECLARED_OPTIONAL_SLOTS: ReadonlyMap<string, string> = new Map(
+  (["y", "z"] as const).map((slot) => [
+    `vmath.euler_to_quat:param:${slot}`,
+    "example `vmath.euler_to_quat(v)` passes a vector3 alone; vmath-overloads.d.ts declares that form",
+  ]),
+);
+
 export const OVERLOAD_COVERED_SKIPS = new Set([
   // go-overloads.d.ts supplies the typed go.get / go.set / go.property shapes.
   "go.get",
@@ -210,14 +254,55 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "render.render_target",
   // vmath-overloads.d.ts supplies the vector3 and three-number euler_to_quat arities.
   "vmath.euler_to_quat",
+  // vmath-overloads.d.ts supplies the empty form and the table form; the engine
+  // raises on an explicit nil, so no optional parameter admits undefined.
+  "vmath.vector",
   // vmath-overloads.d.ts supplies the generic covariant signatures.
   "vmath.clamp",
   "vmath.lerp",
   "vmath.slerp",
   "vmath.mul_per_elem",
   "vmath.normalize",
+  // sys-overloads.d.ts supplies the disabling form and the form that takes the
+  // cooldown the engine requires when enabling.
+  "sys.set_engine_throttle",
+  // sys-overloads.d.ts supplies the form without a default, which returns nil
+  // for a missing key, and the form with one, which always returns a string.
+  "sys.get_config_string",
+]);
+
+// A declaration upstream files under another function's name: its return slot
+// and prose are the named sibling's, so the element keeps only its own
+// declarations. Keyed `<fqn>:<first return name>`, which tells the misfiled
+// declaration from the real one. `return-correction-provenance.test.ts` reds
+// once no retained target still files it, and the entry is then deleted.
+export const MISFILED_DECLARATIONS: ReadonlyMap<string, string> = new Map([
+  // b2d_body_doc.json repeats `get_angle`'s `angle` return under `get_world_center`.
+  ["b2d.body.get_world_center:angle", "b2d.body.get_angle"],
+]);
+
+function isMisfiled(fn: ApiFunction): boolean {
+  return MISFILED_DECLARATIONS.has(`${fn.name}:${fn.returnValues[0]?.name ?? ""}`);
+}
+
+// skipFunction FQNs withheld because no engine binding registers them in the
+// target that documents them, so the declared call would raise. Like
+// OVERLOAD_COVERED_SKIPS, the audit leaves them out of `droppedMembers`: the
+// surface loses nothing a script could call. The engine-binding diff reports a
+// missing binding if one is declared again.
+export const UNBOUND_SKIPS = new Set([
+  "b2d.body.get_contact_list",
+  "b2d.body.get_user_data",
+  "b2d.body.set_user_data",
+  "b2d.body.reset_mass_data",
 ]);
 
+// skipFunction FQNs withheld because another lane's declaration takes the same
+// global name: the runtime `http.response` table beside the editor VM's
+// `http.response` handle. The audit leaves them out of `droppedMembers`, since
+// a slot that needs the shape types it inline.
+export const NAME_CLASH_SKIPS = new Set(["http.response"]);
+
 // Element names whose `table` slot is a prose-only `a table mapping X to Y`
 // shape the field-list parser cannot read, but whose key/value a human curated
 // from the doc. Emitted as `LuaMap<K, V>` because the key is a branded `Hash`,
@@ -246,6 +331,17 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   // `returnvalues` is empty while every sibling `editor.tx.*` builder declares
   // one, and `editor.transact()` takes exactly that.
   ["editor.tx.add", 'Opaque<"transaction_step">'],
+  // The engine binding pushes a value the ref-doc never documents:
+  // script_sys.cpp:Sys_Save pushes whether the write succeeded,
+  // script_tilemap.cpp:TileMap_SetTile pushes false for an unknown layer or an
+  // out-of-range cell, and script_box2d_body_v3.cpp:Body_CreateShape pushes the
+  // created shape's info table through PushShapeInfo.
+  ["sys.save", "boolean"],
+  ["tilemap.set_tile", "boolean"],
+  [
+    "b2d.body.create_shape",
+    '{ index: number; shape_id: Opaque<"b2Shape">; type: number; sensor: boolean; density: number; friction: number; restitution: number; material: number; child_count: number; is_chain_segment: boolean }',
+  ],
 ]);
 
 // A function whose `returnvalues` declare a concrete type while the same slot's
@@ -269,7 +365,12 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
 export interface ReturnTypeCorrection {
   readonly ts: string;
   readonly upstream: readonly string[];
+  // A later release's spelling of the same defect; see `correction-pins.ts`.
+  readonly retypedUpstream?: readonly (readonly string[])[];
   readonly reason: string;
+  // The named value of a multi-return the correction rewrites; `ts` is then
+  // that value's type. Absent, the correction rewrites a single return.
+  readonly slot?: string;
 }
 
 // Keyed by FQN, mirroring PROPERTY_TYPE_CORRECTIONS.
@@ -282,11 +383,50 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       reason: "the body if successful. Otherwise nil.",
     },
   ],
+  [
+    "b2d.shape.ray_cast",
+    {
+      ts: "{ point: Vector3; normal: Vector3; fraction: number; iterations: number } | undefined",
+      upstream: ["table"],
+      reason: "and iterations, or nil",
+    },
+  ],
+  [
+    "b2d.world.cast_ray_closest",
+    {
+      ts: "{ fixture: number; shape: number; point: Vector3; normal: Vector3; fraction: number; node_visits: number; leaf_visits: number } | undefined",
+      upstream: ["table"],
+      reason: "and leaf_visits, or nil",
+    },
+  ],
+  [
+    "gui.new_texture",
+    {
+      ts: "number | undefined",
+      upstream: ["number"],
+      reason: "codes if unsuccessful",
+      slot: "code",
+    },
+  ],
+  // 1.13.2 declares `render_predicate`, whose TYPEDEF aliases `userdata`, and
+  // that still emits `number`.
+  [
+    "render.predicate",
+    {
+      ts: 'Opaque<"render_predicate">',
+      upstream: ["number"],
+      retypedUpstream: [["render_predicate"]],
+      reason: "new predicate",
+    },
+  ],
+  // 1.13.2 declares both as `fun(...:any):any`, which emits
+  // `(...args: unknown[]) => unknown` and still drops the contract.
   [
     "socket.protect",
     {
       ts: "(...args: unknown[]) => LuaMultiReturn<[unknown, string | undefined]>",
       upstream: ["function(function())"],
+      retypedUpstream: [["fun(...:any):any"]],
       reason: "returns nil followed by an error message.",
     },
   ],
@@ -295,38 +435,172 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
     {
       ts: "<T>(value: T | undefined, ...rest: T extends { readonly __tstlMultiReturn: unknown } ? [boxedMultiReturn: never] : unknown[]) => T",
       upstream: ["function"],
+      retypedUpstream: [["fun(...:any):any"]],
       reason: "the customized try function.",
     },
   ],
 ]);
 
-// A parameter whose declared `types` reject what the same element's prose, or
-// an upstream example, demonstrably passes — a render target by resource name,
-// a texture unit, a Lua sequence where `table` is declared. Admission rule: only
-// a slot upstream's own prose or example contradicts; a slot that is merely
-// imprecise is not a candidate. Every such slot is too narrow, never wrong, so
-// `adds` is appended to the mapped union rather than replacing it: the URL
-// address alias, array curation and constant mapping stay live, and optionality
-// stays with `isDocOptional`. Each entry records the upstream tokens it
-// contradicts and `param-correction-provenance.test.ts` pins them against every
-// retained vendored ref-doc. Once no retained target still declares those
-// tokens the entry is deleted, never re-pinned.
+// A parameter whose declared `types` disagree with what the same element's
+// prose, an upstream example, or the engine binding demonstrably takes — a render
+// 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 adds?: string;
+  readonly removes?: readonly string[];
   readonly upstream: readonly string[];
+  readonly retypedUpstream?: readonly (readonly string[])[];
   readonly reason: 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";
+
+const CAMERA_SLOT_FUNCTIONS = [
+  "get_aspect_ratio",
+  "get_auto_aspect_ratio",
+  "get_enabled",
+  "get_far_z",
+  "get_fov",
+  "get_near_z",
+  "get_orthographic_auto_zoom",
+  "get_orthographic_mode",
+  "get_orthographic_zoom",
+  "get_projection",
+  "get_view",
+  "screen_to_world",
+  "screen_xy_to_world",
+  "set_aspect_ratio",
+  "set_auto_aspect_ratio",
+  "set_far_z",
+  "set_fov",
+  "set_near_z",
+  "set_orthographic_mode",
+  "set_orthographic_zoom",
+  "world_to_screen",
+] as const;
+
 // Keyed `<element>:param:<slot>` like OPTIONAL_SLOT_CORRECTIONS, so a
 // same-named slot on another element is untouched.
-export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> = new Map([
+export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> = new Map<
+  string,
+  ParamTypeCorrection
+>([
+  ...CAMERA_SLOT_FUNCTIONS.map(
+    (name) =>
+      [
+        `camera.${name}:param:camera`,
+        {
+          adds: "string | Hash",
+          upstream: ["url", "number", "nil"],
+          reason: CAMERA_ADDRESS_REASON,
+        },
+      ] as const,
+  ),
+  ...(["set_group", "get_maskbit", "set_maskbit"] as const).map(
+    (name) =>
+      [
+        `physics.${name}:param:group`,
+        {
+          adds: "Hash",
+          upstream: ["string"],
+          reason: `script_physics.cpp reads the ${name} group with CheckHashOrString(L, 2)`,
+        },
+      ] as const,
+  ),
+  [
+    "resource.get_text_metrics:param:url",
+    {
+      adds: "string",
+      upstream: ["hash"],
+      reason: "script_resource.cpp:GetTextMetrics reads the font path with CheckHashOrString(L, 1)",
+    },
+  ],
+  [
+    "collectionproxy.get_resources:param:collectionproxy",
+    {
+      adds: "string | Hash",
+      upstream: ["url"],
+      reason:
+        "script_collectionproxy.cpp:CollectionProxy_GetResourcesInternal resolves the proxy through GetComponentFromLua, which takes a string or a hash",
+    },
+  ],
+  ...(["screen_to_local", "set_screen_position"] as const).map(
+    (name) =>
+      [
+        `gui.${name}:param:screen_position`,
+        {
+          adds: "Vector4",
+          upstream: ["vector3"],
+          reason: "gui_script.cpp:GetPositionFromArgumentIndex takes a vector3 or a vector4",
+        },
+      ] as const,
+  ),
+  [
+    "particlefx.set_constant:param:value",
+    {
+      adds: "Matrix4",
+      upstream: ["vector4"],
+      reason: "script_particlefx.cpp:ParticleFX_SetConstant takes a vector4 or a matrix4 value",
+    },
+  ],
+  ...(["animate", "cancel_animations"] as const).map(
+    (name) =>
+      [
+        `gui.${name}:param:property`,
+        {
+          adds: "Hash",
+          upstream: name === "animate" ? ["string", "constant"] : ["nil", "string", "constant"],
+          reason: `gui_script.cpp reads the ${name} property with CheckHashOrString(L, 2)`,
+        },
+      ] as const,
+  ),
+  [
+    "sound.get_group_name:param:group",
+    {
+      removes: ["string"],
+      upstream: ["string", "hash"],
+      reason: "script_sound.cpp:Sound_GetGroupName reads CheckHash(L, 1), which refuses a string",
+    },
+  ],
+  ...(["get_mesh_enabled", "set_mesh_enabled"] as const).map(
+    (name) =>
+      [
+        `model.${name}:param:mesh_id`,
+        {
+          removes: ["Url"],
+          upstream: ["string", "hash", "url"],
+          reason: `script_model.cpp reads the ${name} mesh id with CheckHashOrString(L, 2), which refuses a url`,
+        },
+      ] as const,
+  ),
+  [
+    "resource.create_texture_async:param:path",
+    {
+      removes: ["Hash"],
+      upstream: ["string", "hash"],
+      reason:
+        "script_resource.cpp:CheckCreateTextureResourceParams reads the path with luaL_checkstring(L, 1), which refuses a hash",
+    },
+  ],
   [
     "render.set_render_target:param:render_target",
     {
       adds: "string | Hash | typeof render.RENDER_TARGET_DEFAULT",
       upstream: ["render_target"],
+      retypedUpstream: [["render_target", "string", "hash", "nil"]],
       reason:
-        "\"render.RENDER_TARGET_DEFAULT to set the default render target\"; example `render.set_render_target('my_rt_resource')`",
+        "\"render.RENDER_TARGET_DEFAULT to set the default render target\"; example `render.set_render_target('my_rt_resource')`; 1.13.2 adds the names but still omits the constant",
     },
   ],
   [
@@ -377,9 +651,21 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
   [
     "render.set_camera:param:camera",
     {
-      adds: "string",
+      adds: "string | Hash",
       upstream: ["url", "number", "nil"],
-      reason: 'example `render.set_camera("main:/my_go#camera")`',
+      reason:
+        'example `render.set_camera("main:/my_go#camera")`; render_script.cpp:RenderScript_SetCamera resolves a non-number camera through ResolveURL, which also takes a hash',
+    },
+  ],
+  [
+    "render.draw:param:predicate",
+    {
+      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`",
     },
   ],
   [
@@ -387,7 +673,9 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
     {
       adds: "boolean",
       upstream: ["string", "hash", "url", "table"],
-      reason: "example `go.delete(true)` deletes the script game object and its children",
+      retypedUpstream: [["string", "hash", "url", "(string|hash|url)[]"]],
+      reason:
+        "example `go.delete(true)` deletes the script game object and its children; 1.13.2 types the id list but still omits `boolean`",
     },
   ],
   [
@@ -420,8 +708,9 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
     {
       adds: "readonly unknown[]",
       upstream: ["table"],
+      retypedUpstream: [["table<any, any>"]],
       reason:
-        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.save`',
+        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.save`; 1.13.2\'s `table<any, any>` emits a `LuaTable`, which refuses an array',
     },
   ],
   [
@@ -429,46 +718,41 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
     {
       adds: "readonly unknown[]",
       upstream: ["table"],
+      retypedUpstream: [["table<any, any>"]],
       reason:
-        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.serialize`',
+        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.serialize`; 1.13.2\'s `table<any, any>` emits a `LuaTable`, which refuses an array',
+    },
+  ],
+  [
+    "window.set_dim_mode:param:mode",
+    {
+      removes: ["window.DIMMING"],
+      adds: "window.DimModeStateSettable",
+      upstream: ["window.DIMMING"],
+      reason:
+        'script_window.cpp:SetDimMode raises "The dim mode specified is not supported." for anything but DIMMING_ON and DIMMING_OFF',
+    },
+  ],
+  ...(["texture", "render_target"] as const).map((handle): [string, ParamTypeCorrection] => [
+    `resource.get_${handle}_info:param:path`,
+    {
+      adds: "number",
+      upstream: ["hash", "string", handle],
+      reason:
+        "script_resource.cpp reads any number in slot 1 as the handle, which `info.handle` returns and older targets declared as `number`",
+    },
+  ]),
+  [
+    "tilemap.set_tile:param:transform_bitmask",
+    {
+      adds: "number",
+      upstream: ["tilemap.TRANSFORM"],
+      reason:
+        "a bitmask: the ref-doc example passes tilemap.H_FLIP + tilemap.V_FLIP + tilemap.ROTATE_90, a sum no single TRANSFORM member names",
     },
   ],
 ]);
 
-// Parameter doc text whose upstream wording describes Lua rather than the
-// TypeScript a user writes. The transpiler adds one to a literal `options.index`
-// at these calls, so the 1-based wording would tell the author to be off by one.
-// The `.d.ts` emit and the API reference both apply it, and applying it throws
-// when `from` is absent: an upstream rewording fails the build instead of
-// shipping the stale text alongside the lowering.
-export interface ParamDocRewrite {
-  readonly from: string;
-  readonly to: string;
-}
-
-const ZERO_BASED_INDEX_OPTION_DOC: ParamDocRewrite = {
-  from: "index into array property (1 based)",
-  to: "zero-based index into array property; the transpiler emits Defold's 1-based index",
-};
-
-// Keyed `<element>:param:<slot>` like PARAM_TYPE_CORRECTIONS.
-export const PARAM_DOC_REWRITES: ReadonlyMap<string, ParamDocRewrite> = new Map([
-  ["go.get:param:options", ZERO_BASED_INDEX_OPTION_DOC],
-  ["go.set:param:options", ZERO_BASED_INDEX_OPTION_DOC],
-  ["gui.get:param:options", ZERO_BASED_INDEX_OPTION_DOC],
-  ["gui.set:param:options", ZERO_BASED_INDEX_OPTION_DOC],
-]);
-
-export function rewriteParamDoc(elementName: string, slotName: string, doc: string): string {
-  const key = tableSlotKey(elementName, "param", slotName);
-  const rewrite = PARAM_DOC_REWRITES.get(key);
-  if (rewrite === undefined) return doc;
-  if (!doc.includes(rewrite.from)) {
-    throw new Error(`PARAM_DOC_REWRITES ${key}: upstream doc no longer contains "${rewrite.from}"`);
-  }
-  return doc.replaceAll(rewrite.from, rewrite.to);
-}
-
 // A property whose upstream `<span class="type">` states a type the engine does
 // not use. Unlike every other override here, which fills a gap upstream left
 // empty, these contradict a token upstream explicitly declares — so each entry
@@ -482,6 +766,8 @@ export function rewriteParamDoc(elementName: string, slotName: string, doc: stri
 export interface PropertyTypeCorrection {
   readonly ts: string;
   readonly upstream: string;
+  // A later release's span for the same defect; see `correction-pins.ts`.
+  readonly retypedUpstream?: readonly string[];
   readonly reason: string;
 }
 
@@ -497,6 +783,24 @@ export const PROPERTY_TYPE_CORRECTIONS: ReadonlyMap<string, PropertyTypeCorrecti
         "a count of animation frames, which the prose confirms; `hash` is a copy-paste of the sibling animation-id spans",
     },
   ],
+  [
+    "go.scale",
+    {
+      ts: "number | Vector3",
+      upstream: "number",
+      reason:
+        "the engine reads a vector3 back from `go.get`, and `go.set` also takes a number, which it applies as a uniform scale",
+    },
+  ],
+  [
+    "label.scale",
+    {
+      ts: "Vector3",
+      upstream: "number | vector3",
+      reason:
+        'the engine reads a vector3 back from `go.get`, and `go.set` raises "must be a vmath.vector3" when given a number',
+    },
+  ],
   [
     "camera.projection",
     {
@@ -543,9 +847,10 @@ export const PROPERTY_KEY_RANGES: ReadonlyMap<string, PropertyKeyRange> = new Ma
 // examples skip — so the emitted declaration rejects the call the docs teach.
 //
 // Keyed `<element>:param:<slot>`, the shape `tableSlotKey` builds, so a
-// same-named slot on another element is untouched. The value is the upstream
-// evidence for that one entry: the example call that omits it, or the doc phrase
-// that names it optional. Both emitted shapes follow from one predicate — a
+// same-named slot on another element is untouched. The value is the evidence for
+// that one entry: the example call that omits it, the doc phrase that names it
+// optional, or the engine binding that reads it as omissible
+// (`<file>:<cFunction>`). Both emitted shapes follow from one predicate — a
 // trailing slot becomes `slot?:`, an interior one `slot: T | undefined`.
 //
 // Demonstrated omissions only. `resource.set_texture`'s buffer and
@@ -557,10 +862,6 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     'example `resource.create_texture("/my_custom_texture.texturec", tparams)`; "optional buffer of precreated pixel data"',
   ],
   ["resource.create_texture_async:param:buffer", '"optional buffer of precreated pixel data"'],
-  [
-    "resource.create_texture_async:param:callback",
-    'example `resource.create_texture_async("/my_texture.texturec", tparams, tbuffer)`',
-  ],
   [
     "gui.new_texture:param:flip",
     'example `gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h))`',
@@ -569,7 +870,6 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     "gui.set_texture_data:param:flip",
     'example `gui.set_texture_data("dynamic_tx", w, h, "rgb", string.rep(orange, w * h))`',
   ],
-  ["sys.set_engine_throttle:param:cooldown", "example `sys.set_engine_throttle(false)`"],
   [
     "b2d.fixture.set_shape:param:update_mass",
     '2 of 3 examples omit it; "The body mass is not updated unless update_mass is true"',
@@ -583,6 +883,26 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     '"optional maximum translation fraction, defaults to 1"',
   ],
   ["iap.buy:param:options", '"optional parameters as properties"'],
+  [
+    "go.world_to_local_position:param:url",
+    "gameobject_script.cpp:Script_WorldToLocalPosition resolves argument 2 with ResolveInstance, which takes the calling instance when it is absent",
+  ],
+  [
+    "go.world_to_local_transform:param:url",
+    "gameobject_script.cpp:Script_WorldToLocalTransfrom resolves argument 2 with ResolveInstance, which takes the calling instance when it is absent",
+  ],
+  [
+    "go.cancel_animations:param:url",
+    "gameobject_script.cpp:Script_CancelAnimations resolves argument 1 with ResolveURL, which takes the calling instance when it is absent",
+  ],
+  [
+    "b2d.fixture.set_density:param:update_mass",
+    "script_box2d_fixture_v2.cpp:Fixture_SetDensity reads argument 4 only when lua_gettop(L) >= 4",
+  ],
+  [
+    "render.set_render_target:param:render_target",
+    "render_script.cpp:RenderScript_SetRenderTarget sets the default target when lua_gettop(L) == 0",
+  ],
   ["socket.newtry:param:finalizer", "socket.protect's example `local try = socket.newtry()`"],
   ...(
     [
@@ -605,6 +925,159 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
   ),
 ]);
 
+// A parameter the ref-doc marks omissible — `[name]` or a `nil` type — that the
+// engine binding refuses to go without, so the emitted declaration accepts a call
+// that raises. It applies only where a ref-doc marks the slot, so it follows each
+// target's own markup, and it overrides OPTIONAL_SLOT_CORRECTIONS: the slot is
+// never emitted with `?`. `nil` records whether the binding still takes an
+// explicit nil there — `lua_isnil` answers false past the stack top, so such a
+// slot must be passed yet may be nil — which emits `slot: T | undefined`.
+//
+// Keyed `<element>:param:<slot>` like OPTIONAL_SLOT_CORRECTIONS. `evidence` is the
+// C++ binding, `<file>:<cFunction>`, and what it does with the slot;
+// `required-correction-provenance.test.ts` deletes an entry once no retained
+// target marks the slot omissible.
+export interface RequiredSlotCorrection {
+  readonly nil: boolean;
+  readonly evidence: string;
+}
+
+const COMPONENT_URL_EVIDENCE =
+  "resolves the url through GetComponentFromLua, which refuses the calling script's own url";
+
+export const REQUIRED_SLOT_CORRECTIONS: ReadonlyMap<string, RequiredSlotCorrection> = new Map<
+  string,
+  RequiredSlotCorrection
+>([
+  [
+    "resource.create_texture_async:param:callback",
+    {
+      nil: false,
+      evidence:
+        "script_resource.cpp:CreateTextureAsync hands argument 4 to dmScript::CreateCallback, which raises through luaL_checktype(L, 4, LUA_TFUNCTION)",
+    },
+  ],
+  ...(["factory", "collectionfactory"] as const).flatMap((namespace) => {
+    const file = namespace === "factory" ? "script_factory.cpp" : "script_collection_factory.cpp";
+    const prefix = namespace === "factory" ? "FactoryComp" : "CollectionFactoryComp";
+    return [
+      ...(
+        [
+          ["get_status", "GetStatus"],
+          ["unload", "Unload"],
+          ["set_prototype", "SetPrototype"],
+          ["load", "Load"],
+        ] as const
+      ).map(
+        ([name, cFunction]) =>
+          [
+            `${namespace}.${name}:param:url`,
+            { nil: false, evidence: `${file}:${prefix}_${cFunction} ${COMPONENT_URL_EVIDENCE}` },
+          ] as const,
+      ),
+      [
+        `${namespace}.load:param:complete_function`,
+        {
+          nil: false,
+          evidence: `${file}:${prefix}_Load raises unless argument 2 is a function`,
+        },
+      ] as const,
+      [
+        `${namespace}.set_prototype:param:prototype`,
+        {
+          nil: true,
+          evidence: `${file}:${prefix}_SetPrototype reads luaL_checkstring(L, 2) unless lua_isnil(L, 2)`,
+        },
+      ] as const,
+    ];
+  }),
+  [
+    "collectionproxy.set_collection:param:url",
+    {
+      nil: false,
+      evidence: `script_collectionproxy.cpp:CollectionProxy_SetCollection ${COMPONENT_URL_EVIDENCE}`,
+    },
+  ],
+  [
+    "collectionproxy.set_collection:param:prototype",
+    {
+      nil: true,
+      evidence:
+        "script_collectionproxy.cpp:CollectionProxy_SetCollection reads luaL_checkstring(L, 2) unless lua_isnil(L, 2)",
+    },
+  ],
+  [
+    "sound.set_gain:param:gain",
+    { nil: false, evidence: "script_sound.cpp:Sound_SetGain reads luaL_checknumber(L, 2)" },
+  ],
+  [
+    "sound.set_pan:param:pan",
+    { nil: false, evidence: "script_sound.cpp:Sound_SetPan reads luaL_checknumber(L, 2)" },
+  ],
+  [
+    "resource.create_buffer:param:table",
+    {
+      nil: false,
+      evidence: "script_resource.cpp:CreateBuffer checks luaL_checktype(L, 2, LUA_TTABLE)",
+    },
+  ],
+  [
+    "resource.create_sound_data:param:options",
+    {
+      nil: false,
+      evidence: "script_resource.cpp:CreateSoundData checks luaL_checktype(L, 2, LUA_TTABLE)",
+    },
+  ],
+  ...(["move_above", "move_below"] as const).map(
+    (name) =>
+      [
+        `gui.${name}:param:reference`,
+        {
+          nil: true,
+          evidence: `gui_script.cpp:Lua${name === "move_above" ? "MoveAbove" : "MoveBelow"} reads a node from argument 2 unless lua_isnil(L, 2)`,
+        },
+      ] as const,
+  ),
+  [
+    "gui.set_parent:param:parent",
+    {
+      nil: true,
+      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",
+    {
+      nil: true,
+      evidence: "script_window.cpp:SetListener checks luaL_checkany(L, 1); nil clears the listener",
+    },
+  ],
+  [
+    "html5.set_interaction_listener:param:callback",
+    {
+      nil: true,
+      evidence:
+        "script_html5_js.cpp:Html5_SetInteractionListener checks luaL_checkany(L, 1); nil clears the listener",
+    },
+  ],
+]);
+
+function requiredSlotCorrection(
+  p: ApiParameter,
+  elementName: string,
+): RequiredSlotCorrection | undefined {
+  return isMarkedOptional(p)
+    ? REQUIRED_SLOT_CORRECTIONS.get(tableSlotKey(elementName, "param", p.name))
+    : undefined;
+}
+
 // A first slot upstream documents as standing in for a second argument list:
 // every `b2d.shape` function takes a shape handle "or pass `body, shape_index`".
 // The element keeps its declared signature and gains an overload with
@@ -633,7 +1106,7 @@ export const FIRST_SLOT_ALTERNATIVES: ReadonlyMap<string, FirstSlotAlternative>
         },
         {
           name: "shape_index",
-          doc: "The shape's 1-based index on that body, as <code>b2d.body.get_shapes</code> lists them.",
+          doc: "The shape's position on that body, in the order <code>b2d.body.get_shapes</code> lists them.",
           types: ["number"],
           isOptional: false,
         },
@@ -1067,9 +1540,17 @@ export function constantUnionAlias(fqns: readonly string[]): ConstantUnionAlias
 export function constantUnionAliasDeclarations(namespace: string): string[] {
   return CONSTANT_UNION_ALIASES.filter((row) => row.home === namespace)
     .sort((a, b) => a.name.localeCompare(b.name))
-    .map(
-      (row) => `type ${row.name} = ${row.members.map((member) => `typeof ${member}`).join(" | ")};`,
-    );
+    .map((row) => unionAliasDeclaration(row.name, row.members));
+}
+
+function unionAliasDeclaration(
+  name: string,
+  members: readonly string[],
+  nilable: ReadonlySet<string> = new Set(),
+): string {
+  const arm = (member: string) =>
+    nilable.has(member) ? `NonNullable<typeof ${member}>` : `typeof ${member}`;
+  return `type ${name} = ${members.map(arm).join(" | ")};`;
 }
 
 const DOC_CONSTANT_TOKEN =
@@ -1219,7 +1700,11 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
 // (`tilemap.get_tiles` → `tiles[row][col]`).
 export type NestedMapping = { key: string; value: string };
 
-export type TableSlotCuration =
+// A curation applies where the slot declares the prose `table` token, or a later
+// spelling a newer release retypes the same slot to without fixing it
+// (`retypedUpstream`, matched whole): 1.13.2's `table<hash, table<string|hash, any>>`
+// for `collectionfactory.create`'s properties.
+export type TableSlotCuration = (
   | { kind: "mapping"; key: string; value: string | readonly TableField[] | NestedMapping }
   | { kind: "array"; element: string | readonly string[] }
   | { kind: "object"; fields: readonly TableField[] }
@@ -1228,7 +1713,11 @@ export type TableSlotCuration =
   // keyed by an arbitrary name (constant/sampler/attribute). The parser recovers
   // the inner args fields; emit wraps them as `Record<string, { <fields> }>`,
   // restoring the keyed-by-name layer the flat object curation drops.
-  | { kind: "keyed-object" };
+  | { kind: "keyed-object" }
+  // A slot whose faithful shape no field list can carry, such as a union
+  // discriminated on `type`. `ts` is emitted verbatim, already mapped.
+  | { kind: "verbatim"; ts: string }
+) & { readonly retypedUpstream?: readonly string[] };
 
 export const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const;
 
@@ -1237,8 +1726,10 @@ export const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const
 // b2d submodule curations below so a single shape is defined once.
 //
 // The shape table is a discriminated union of circle/edge/polygon/box/chain
-// forms keyed by `type` (a b2d.shape.SHAPE_TYPE_* constant); every kind-specific
-// field is optional because only one form's fields are present per value.
+// forms, plus the Box2D v3 capsule, keyed by `type` (a b2d.shape.SHAPE_TYPE_*
+// constant); every kind-specific field is optional because only one form's
+// fields are present per value. The capsule's `center1`/`center2` come from
+// script_box2d_shape_v3.cpp, which reads them; the ref-doc prose never names them.
 const B2D_SHAPE_TABLE_FIELDS: readonly TableField[] = [
   { name: "type", types: ["number"] },
   { name: "radius", types: ["number"], optional: true },
@@ -1254,7 +1745,56 @@ const B2D_SHAPE_TABLE_FIELDS: readonly TableField[] = [
   { name: "loop", types: ["boolean"], optional: true },
   { name: "prev_vertex", types: ["vector3"], optional: true },
   { name: "next_vertex", types: ["vector3"], optional: true },
+  { name: "center1", types: ["vector3"], optional: true },
+  { name: "center2", types: ["vector3"], optional: true },
 ];
+// The shape table a Box2D binding reads, one arm per `type`. CheckShapeDef
+// (v2/script_box2d_shape_v2.cpp, v3/script_box2d_shape_v3.cpp) raises without
+// `type` and without the fields that type reads with luaL_checknumber or
+// CheckVec2; the rest go through TryGet*Field. A polygon takes `hx`/`hy` or
+// `vertices`. `SHAPE_TYPE_BOX` is the polygon value and `SHAPE_TYPE_EDGE` the v3
+// segment value, so each shares its arm. Each backend raises "Unsupported shape
+// type" on the kinds it does not build: `create_fixture` and `fixture.set_shape`
+// are registered only by v2/script_box2d_*_v2.cpp and take B2D_V2_SHAPE_TS (no
+// capsule, and an edge typed `SHAPE_TYPE_EDGE` with optional ghost vertices);
+// `create_shape` and `shape.set_shape` are registered only by
+// v3/script_box2d_*_v3.cpp and take B2D_V3_SHAPE_TS (no chain, and a segment
+// that reads no ghost vertices). `world.cast_shape` and `world.overlap_shape`
+// are registered by both, so they keep the full union.
+// The box arm leads: a v2 fixture keeps its shape type, and the runtime probe
+// witnesses a union by its first arm against a box collision shape.
+const B2D_SHAPE = "typeof b2d.shape";
+const B2D_BOX_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_POLYGON | ${B2D_SHAPE}.SHAPE_TYPE_BOX; hx: number; hy: number; center?: Vector3; angle?: number }`;
+const B2D_POLYGON_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_POLYGON | ${B2D_SHAPE}.SHAPE_TYPE_BOX; vertices: Vector3[] }`;
+const B2D_CIRCLE_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_CIRCLE; radius: number; center?: Vector3 }`;
+const B2D_CAPSULE_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_CAPSULE; radius: number; center1: Vector3; center2: Vector3 }`;
+const B2D_EDGE_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_EDGE | ${B2D_SHAPE}.SHAPE_TYPE_SEGMENT; v1: Vector3; v2: Vector3; v0?: Vector3; v3?: Vector3 }`;
+const B2D_V2_EDGE_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_EDGE; v1: Vector3; v2: Vector3; v0?: Vector3; v3?: Vector3 }`;
+const B2D_V3_SEGMENT_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_EDGE | ${B2D_SHAPE}.SHAPE_TYPE_SEGMENT; v1: Vector3; v2: Vector3 }`;
+const B2D_CHAIN_ARM = `{ type: ${B2D_SHAPE}.SHAPE_TYPE_CHAIN; vertices: Vector3[]; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }`;
+const B2D_SHAPE_DEFINITION_TS = [
+  B2D_BOX_ARM,
+  B2D_POLYGON_ARM,
+  B2D_CIRCLE_ARM,
+  B2D_CAPSULE_ARM,
+  B2D_EDGE_ARM,
+  B2D_CHAIN_ARM,
+].join(" | ");
+const B2D_V2_SHAPE_TS = [
+  B2D_BOX_ARM,
+  B2D_POLYGON_ARM,
+  B2D_CIRCLE_ARM,
+  B2D_V2_EDGE_ARM,
+  B2D_CHAIN_ARM,
+].join(" | ");
+const B2D_V3_SHAPE_TS = [
+  B2D_BOX_ARM,
+  B2D_POLYGON_ARM,
+  B2D_CIRCLE_ARM,
+  B2D_CAPSULE_ARM,
+  B2D_V3_SEGMENT_ARM,
+].join(" | ");
+const B2D_SHAPE_DEFINITION: TableSlotCuration = { kind: "verbatim", ts: B2D_SHAPE_DEFINITION_TS };
 // A fixture info entry (index/type/sensor/density/friction/restitution/child_count).
 const B2D_FIXTURE_INFO_FIELDS: readonly TableField[] = [
   { name: "index", types: ["number"] },
@@ -1330,8 +1870,38 @@ const PHYSICS_SHAPE_TABLE_FIELDS: readonly TableField[] = [
   { name: "dimensions", types: ["vector3"], optional: true },
   { name: "height", types: ["number"], optional: true },
 ];
-
-export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map([
+// The same record as `physics.set_shape` takes it: script_physics.cpp:
+// Physics_SetShape reads `type` and then each field its kind needs with
+// luaL_checknumber or CheckVector3, so each kind is its own arm.
+const PHYSICS_SHAPE_DEFINITION_TS = [
+  "{ type: typeof physics.SHAPE_TYPE_SPHERE; diameter: number }",
+  "{ type: typeof physics.SHAPE_TYPE_BOX; dimensions: Vector3 }",
+  "{ type: typeof physics.SHAPE_TYPE_CAPSULE; diameter: number; height: number }",
+].join(" | ");
+
+export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map<
+  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.
@@ -1351,7 +1921,12 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // the object-literal form this slot accepted as a bare `table`.
   [
     "collectionfactory.create:param:properties",
-    { kind: "mapping", key: "hash | string", value: "table" },
+    {
+      kind: "mapping",
+      key: "hash | string",
+      value: "table",
+      retypedUpstream: ["table<hash, table<string|hash, any>>"],
+    },
   ],
   ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
   // font.get_info's `info` return is a `<dl>` with `path: hash` and a nested
@@ -1482,8 +2057,22 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   ],
   ["socket.select:param:recvt", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
   ["socket.select:param:sendt", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
-  ["socket.select:return:sockets_r", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
-  ["socket.select:return:sockets_w", { kind: "array", element: SOCKET_HANDLE_TOKENS }],
+  [
+    "socket.select:return:sockets_r",
+    {
+      kind: "array",
+      element: SOCKET_HANDLE_TOKENS,
+      retypedUpstream: ["table<integer|socket_selectable, socket_selectable|integer>"],
+    },
+  ],
+  [
+    "socket.select:return:sockets_w",
+    {
+      kind: "array",
+      element: SOCKET_HANDLE_TOKENS,
+      retypedUpstream: ["table<integer|socket_selectable, socket_selectable|integer>"],
+    },
+  ],
   [
     "tilemap.get_tile_info:return:tile_info",
     {
@@ -1575,8 +2164,10 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // `headers`; the sibling `options` table stays parser-recovered.
   ["http.request:param:headers", { kind: "mapping", key: "string", value: "string" }],
   // collectionproxy.get_resources returns "the resources, or an empty list", a
-  // homogeneous list of resource-path hashes (prose only, no field list).
-  ["collectionproxy.get_resources:return:resources", { kind: "array", element: "hash" }],
+  // homogeneous list of resource paths (prose only, no field list), each a
+  // hexadecimal string: script_collectionproxy.cpp:GetResourceHashCallback pushes
+  // every entry with lua_pushlstring.
+  ["collectionproxy.get_resources:return:resources", { kind: "array", element: "string" }],
   // render.predicate's `tags` is "table of tags ... can be of either hash or
   // string type", a homogeneous array whose element is the string|hash union.
   ["render.predicate:param:tags", { kind: "array", element: ["string", "hash"] }],
@@ -1589,6 +2180,7 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   [
     "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",
@@ -1780,14 +2372,63 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   [
     "b2d.body.create_fixture:param:definition",
     {
+      retypedUpstream: ["b2d.fixture_definition"],
       kind: "object",
       fields: [
-        { name: "shape", types: ["table"], fields: [...B2D_SHAPE_TABLE_FIELDS] },
+        { name: "shape", types: ["table"], tsType: B2D_V2_SHAPE_TS },
         { name: "friction", types: ["number"] },
         { name: "restitution", types: ["number"] },
         { name: "density", types: ["number"] },
         { name: "sensor", types: ["boolean"] },
+        // v2/script_box2d_fixture_v2.cpp:CheckFixtureDef reads is_sensor when
+        // sensor is absent.
+        { name: "is_sensor", types: ["boolean"] },
+        { name: "filter", types: ["table"], fields: [...B2D_FILTER_DATA_FIELDS] },
+      ],
+    },
+  ],
+  // The creation-time definitions the v3 bindings document in their C++ doc
+  // comments rather than the ref-doc: Body_CreateChain
+  // (v3/script_box2d_chain_v3.cpp), CheckShapeCreateDef
+  // (v3/script_box2d_shape_v3.cpp) and World_Explode
+  // (v3/script_box2d_world_v3.cpp).
+  [
+    "b2d.body.create_chain:param:definition",
+    {
+      kind: "object",
+      fields: [
+        { name: "vertices", types: ["table"], tsType: "Vector3[]" },
+        { name: "loop", types: ["boolean"] },
+        { name: "prev_vertex", types: ["vector3"] },
+        { name: "next_vertex", types: ["vector3"] },
+        { name: "friction", types: ["number"] },
+        { name: "restitution", types: ["number"] },
+        { name: "material", types: ["number"] },
         { name: "filter", types: ["table"], fields: [...B2D_FILTER_DATA_FIELDS] },
+        { name: "enable_sensor_events", types: ["boolean"] },
+      ],
+    },
+  ],
+  // The shape table sits in `definition.shape` or is the definition itself, and
+  // a filter, when given, needs all three members CheckFilterData reads.
+  [
+    "b2d.body.create_shape:param:definition",
+    {
+      retypedUpstream: ["b2d.shape_create_definition"],
+      kind: "verbatim",
+      ts: `({ shape: ${B2D_V3_SHAPE_TS} } | ${B2D_V3_SHAPE_TS}) & { density?: number; friction?: number; restitution?: number; material?: number; sensor?: boolean; is_sensor?: boolean; filter?: { category_bits: number; mask_bits: number; group_index: number } }`,
+    },
+  ],
+  [
+    "b2d.world.explode:param:definition",
+    {
+      kind: "object",
+      fields: [
+        { name: "position", types: ["vector3"] },
+        { name: "radius", types: ["number"] },
+        { name: "falloff", types: ["number"] },
+        { name: "impulse_per_length", types: ["number"] },
+        { name: "mask_bits", types: ["number"] },
       ],
     },
   ],
@@ -1825,10 +2466,16 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   ["b2d.fixture.get_filter_data:return:filter", { kind: "object", fields: B2D_FILTER_DATA_FIELDS }],
   ["b2d.fixture.set_filter_data:param:filter", { kind: "object", fields: B2D_FILTER_DATA_FIELDS }],
   ["b2d.fixture.get_shape:return:shape", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
-  ["b2d.fixture.set_shape:param:shape", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
+  [
+    "b2d.fixture.set_shape:param:shape",
+    { kind: "verbatim", ts: B2D_V2_SHAPE_TS, retypedUpstream: ["b2d.shape.definition"] },
+  ],
   // b2d.shape
   ["b2d.shape.get_shape:return:shape", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
-  ["b2d.shape.set_shape:param:definition", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
+  [
+    "b2d.shape.set_shape:param:definition",
+    { kind: "verbatim", ts: B2D_V3_SHAPE_TS, retypedUpstream: ["b2d.shape.definition"] },
+  ],
   ["b2d.shape.get_mass_data:return:data", { kind: "object", fields: B2D_MASS_DATA_FIELDS }],
   [
     "b2d.shape.get_sensor_overlaps:return:overlaps",
@@ -2011,7 +2658,10 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   ],
   ["b2d.world.overlap_aabb:return:hits", { kind: "array-object", fields: B2D_SHAPE_INFO_FIELDS }],
   ["b2d.world.overlap_aabb:return:stats", { kind: "object", fields: B2D_QUERY_STATS_FIELDS }],
-  ["b2d.world.overlap_shape:param:shape", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
+  [
+    "b2d.world.overlap_shape:param:shape",
+    { ...B2D_SHAPE_DEFINITION, retypedUpstream: ["b2d.shape.definition"] },
+  ],
   ["b2d.world.overlap_shape:param:filter", { kind: "object", fields: B2D_QUERY_FILTER_FIELDS }],
   [
     "b2d.world.overlap_shape:return:fixtures",
@@ -2038,7 +2688,10 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
       ],
     },
   ],
-  ["b2d.world.cast_shape:param:shape", { kind: "object", fields: B2D_SHAPE_TABLE_FIELDS }],
+  [
+    "b2d.world.cast_shape:param:shape",
+    { ...B2D_SHAPE_DEFINITION, retypedUpstream: ["b2d.shape.definition"] },
+  ],
   ["b2d.world.cast_shape:param:filter", { kind: "object", fields: B2D_QUERY_FILTER_FIELDS }],
   ["b2d.world.cast_shape:return:hits", { kind: "array-object", fields: B2D_CAST_HIT_FIELDS }],
   ["b2d.world.cast_shape:return:stats", { kind: "object", fields: B2D_QUERY_STATS_FIELDS }],
@@ -2047,14 +2700,15 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   ["b2d.world.collide_mover:param:capsule", { kind: "object", fields: B2D_CAPSULE_FIELDS }],
   ["b2d.world.collide_mover:param:filter", { kind: "object", fields: B2D_MOVER_FILTER_FIELDS }],
   ["physics.get_shape:return:table", { kind: "object", fields: PHYSICS_SHAPE_TABLE_FIELDS }],
-  ["physics.set_shape:param:table", { kind: "object", fields: PHYSICS_SHAPE_TABLE_FIELDS }],
+  ["physics.set_shape:param:table", { kind: "verbatim", ts: PHYSICS_SHAPE_DEFINITION_TS }],
 ]);
 
 // Slot-keyed (`element:param:name`, mirroring TABLE_SLOT_CURATIONS) replacements
 // for a callback parameter's recovered signature, used where the generic
 // `recoverCallbackSignature` `unknown`-everywhere form leaves real engine type
 // information on the table. The value is the full emitted function type. Honest
-// only: `window.set_listener` discriminates `event` by a known constant union and
+// only: `window.set_listener` discriminates `event` by the union of the
+// `WINDOW_EVENT_*` constants the surface's own `window` namespace declares, and
 // its `data` is a bare record (only resize carries fields — `isWindowEvent` is the
 // path to typed `data`), mirroring the `msg.post` (send, typed) / `isMessage`
 // (receive, narrow) split.
@@ -2071,7 +2725,8 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
 export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, string> = new Map([
   [
     "window.set_listener:param:callback",
-    "(self: unknown, event: typeof WINDOW_EVENT_FOCUS_LOST | typeof WINDOW_EVENT_FOCUS_GAINED | typeof WINDOW_EVENT_RESIZED | typeof WINDOW_EVENT_ICONFIED | typeof WINDOW_EVENT_DEICONIFIED, data: Record<string | number, unknown>) => void",
+    // 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: Record<string | number, unknown>) => void",
   ],
   [
     "http.request:param:callback",
@@ -2096,9 +2751,11 @@ export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, string> = new Map
 // hand-curated. Each geometry is the triangle data (the create-input form
 // get_atlas mirrors via its cross-ref), and `vertices`/`uvs`/`indices` are
 // brace-form number-lists, hence `numberList: true` (emitted `number[]`).
-// Injected onto the already-parsed field list (every sibling stays
-// parser-authoritative), so this is a nested-field curation, not a whole-slot
-// object curation.
+// resource.create_atlas documents a geometry's `id`/`width`/`height`/pivot
+// members, so the three arrays join those: script_resource.cpp reads them from
+// each `geometries` entry. Injected onto the already-parsed field list (every
+// sibling stays parser-authoritative), so this is a nested-field curation, not a
+// whole-slot object curation.
 const ATLAS_GEOMETRY_MEMBERS: readonly TableField[] = [
   { name: "vertices", types: ["table"], numberList: true },
   { name: "uvs", types: ["table"], numberList: true },
@@ -2107,6 +2764,7 @@ const ATLAS_GEOMETRY_MEMBERS: readonly TableField[] = [
 
 export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]> = new Map([
   ["resource.set_atlas:param:table:geometries", ATLAS_GEOMETRY_MEMBERS],
+  ["resource.create_atlas:param:table:geometries", ATLAS_GEOMETRY_MEMBERS],
   ["resource.get_atlas:return:data:geometries", ATLAS_GEOMETRY_MEMBERS],
 ]);
 
@@ -2130,6 +2788,9 @@ export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]>
 // `render.set_render_target`'s `options.transient` is documented as `table`
 // with the prose "a list of buffer types", and upstream's example passes
 // graphics.BUFFER_TYPE_* constants.
+//
+// `resource.create_sound_data`'s `options.data` is documented as `string`, while
+// 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([
@@ -2142,6 +2803,23 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["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">'],
+  // 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.
+  ...(
+    [
+      "resource.texture_creation_params",
+      "resource.texture_info",
+      "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"],
 ]);
 
 // A field the engine accepts on an option bag whose `<dl>` upstream otherwise
@@ -2150,27 +2828,56 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
 // upstream omits, leaving the documented fields parser-authoritative so an
 // upstream edit to any of them lands without a hand-maintained restatement.
 //
-// `evidence` pins where upstream itself shows the field. applyFieldAdditions
-// throws once the parse recovers it, so upstream documenting the field reds
-// here and the entry is deleted rather than re-pinned.
+// `evidence` pins where upstream itself shows each field, or the engine binding
+// that reads it. applyFieldAdditions throws once the parse recovers one, so
+// upstream documenting a field reds here and the entry is deleted rather than
+// re-pinned.
 //
 // Keyed `<element>:<kind>:<slot>`, the TABLE_SLOT_CURATIONS shape.
 export interface TableFieldAddition {
-  readonly field: TableField;
+  readonly fields: readonly TableField[];
   readonly evidence: readonly string[];
 }
 
-export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition> = new Map([
+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
+>([
   [
     "resource.create_texture:param:table",
     {
-      field: { name: "page_count", types: ["number"], optional: true },
+      fields: [{ name: "page_count", types: ["number"], optional: true }],
       evidence: [
         "the array-texture example on this element creates with `page_count = 5`",
         "resource.get_texture_info documents `page_count` as the texture array's page count",
       ],
     },
   ],
+  [
+    "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
@@ -2262,6 +2969,247 @@ export function applyFieldOptionalityCorrections(
   return corrected;
 }
 
+// A param-side table field the engine binding refuses to go without. A `<dl>`
+// carries no per-field optionality, so every field of an input option bag is
+// emitted `?`; an entry here keeps one field required. Keyed
+// `<element>:param:<slot>:<field>`, the TABLE_FIELD_TYPE_OVERRIDES shape, with
+// `<field>.<member>` or `<field>[].<member>` one level down. A `STRUCT` member
+// is keyed `<struct>:member:<field>`, for a target whose slot names that struct
+// (`field-correction-coverage.ts` pairs the two). The value is the evidence: the
+// C++ binding, `<file>:<cFunction>`, and how it reads the field.
+const CHECK_SHAPE_DEF = "CheckShapeDef reads the shape table with luaL_checkinteger(type)";
+const V2_FILTER_DATA =
+  "v2/script_box2d_fixture_v2.cpp:CheckFilterData reads each with luaL_checkinteger";
+const TEXTURE_PARAMS =
+  "script_resource.cpp:CheckCreateTextureResourceParams reads CheckTableInteger";
+const ATLAS_ARGUMENTS =
+  "script_resource.cpp:CheckAtlasArguments raises unless the atlas has at least one geometry and one animation";
+
+const filterDataFields = (slot: string, evidence: string) =>
+  (["category_bits", "mask_bits", "group_index"] as const).map(
+    (field) => [`${slot}:filter.${field}`, evidence] as const,
+  );
+
+// A `STRUCT` member upstream marks required while the engine binding reads it
+// only when present, keyed `<struct>:member:<field>` like REQUIRED_FIELD_CORRECTIONS
+// and valued with the same binding evidence.
+export const OPTIONAL_MEMBER_CORRECTIONS: ReadonlyMap<string, string> = new Map([
+  [
+    "sound.stop_properties:member:play_id",
+    "script_sound.cpp:Sound_Stop reads play_id with luaL_checknumber only when it is not nil",
+  ],
+]);
+
+export const REQUIRED_FIELD_CORRECTIONS: ReadonlyMap<string, string> = new Map<string, string>([
+  ...(["mass", "center", "inertia"] as const).map(
+    (field) =>
+      [
+        `b2d.body.set_mass_data:param:data:${field}`,
+        "script_box2d_body_v2/v3.cpp:CheckMassData reads mass and inertia with luaL_checknumber and center with CheckVec2",
+      ] as const,
+  ),
+  ...(["category_bits", "mask_bits", "group_index"] as const).map(
+    (field) => [`b2d.fixture.set_filter_data:param:filter:${field}`, V2_FILTER_DATA] as const,
+  ),
+  [
+    "b2d.body.create_fixture:param:definition:shape",
+    `v2/script_box2d_fixture_v2.cpp:CheckFixtureDef passes definition.shape to ${CHECK_SHAPE_DEF}`,
+  ],
+  ...filterDataFields("b2d.body.create_fixture:param:definition", V2_FILTER_DATA),
+  [
+    "b2d.body.create_chain:param:definition:vertices",
+    "v3/script_box2d_chain_v3.cpp:Body_CreateChain reads vertices with CheckVerticesTable, at least 2 (4 for a loop)",
+  ],
+  ...(["cast_mover", "collide_mover"] as const).flatMap((name) =>
+    (["center1", "center2", "radius"] as const).map(
+      (field) =>
+        [
+          `b2d.world.${name}:param:capsule:${field}`,
+          "v3/script_box2d_world_v3.cpp:CheckCapsule reads center1 and center2 with CheckVec2 and radius with luaL_checknumber",
+        ] as const,
+    ),
+  ),
+  ...(["lower", "upper"] as const).map(
+    (field) =>
+      [
+        `b2d.world.overlap_aabb:param:aabb:${field}`,
+        "script_box2d_world_v2/v3.cpp:CheckAABB reads lower and upper with CheckVec2",
+      ] as const,
+  ),
+  ...(["position", "radius", "falloff", "impulse_per_length"] as const).map(
+    (field) =>
+      [
+        `b2d.world.explode:param:definition:${field}`,
+        "v3/script_box2d_world_v3.cpp:World_Explode reads position with CheckVec2 and the rest with luaL_checknumber",
+      ] as const,
+  ),
+  [
+    "buffer.create:param:declaration:type",
+    "script_buffer.cpp:ParseStreamDeclaration raises on a stream with no value type",
+  ],
+  ...(["create_texture", "create_texture_async"] as const).flatMap((name) =>
+    (["type", "format", "width", "height"] as const).map(
+      (field) => [`resource.${name}:param:table:${field}`, TEXTURE_PARAMS] as const,
+    ),
+  ),
+  ...(["type", "format", "width", "height"] as const).map(
+    (field) =>
+      [
+        `resource.set_texture:param:table:${field}`,
+        "script_resource.cpp:SetTexture reads CheckTableInteger",
+      ] as const,
+  ),
+  ...(["create_atlas", "set_atlas"] as const).flatMap((name) => [
+    [
+      `resource.${name}:param:table:texture`,
+      "script_resource.cpp:CheckTextureResource reads the texture with CheckHashOrString",
+    ] as const,
+    [`resource.${name}:param:table:geometries`, ATLAS_ARGUMENTS] as const,
+    [`resource.${name}:param:table:animations`, ATLAS_ARGUMENTS] as const,
+    ...(["vertices", "uvs", "indices"] as const).map(
+      (field) =>
+        [
+          `resource.${name}:param:table:geometries[].${field}`,
+          "script_resource.cpp:CheckAtlasArguments checks each geometry stream with luaL_checktype(LUA_TTABLE)",
+        ] as const,
+    ),
+    ...(["id", "width", "height"] as const).map(
+      (field) =>
+        [
+          `resource.${name}:param:table:animations[].${field}`,
+          "script_resource.cpp:CheckAtlasArguments raises on an animation with no id, width or height",
+        ] as const,
+    ),
+  ]),
+  [
+    "resource.create_buffer:param:table:buffer",
+    "script_resource.cpp:CreateBuffer reads the buffer with dmScript::CheckBuffer",
+  ],
+  [
+    "resource.create_sound_data:param:options:data",
+    "script_resource.cpp:CreateSoundData reads the data with CheckBufferOrString",
+  ],
+  [
+    "resource.sound_data_options:member:data",
+    "script_resource.cpp:CreateSoundData reads the data with CheckBufferOrString",
+  ],
+]);
+
+// Mark the fields REQUIRED_FIELD_CORRECTIONS names for this slot required,
+// leaving every other field and every type untouched. An entry keyed to this
+// slot that names no field throws, so a renamed field cannot leave a stale
+// correction looking applied. Returns a new array; never mutates its input.
+export function applyRequiredFieldCorrections(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind !== "param" || slotName === undefined) return [...fields];
+  const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
+  const applied = new Set<string>();
+  const mark = (field: TableField, path: string): TableField => {
+    if (!REQUIRED_FIELD_CORRECTIONS.has(`${prefix}${path}`)) return field;
+    applied.add(path);
+    return { ...field, required: true };
+  };
+  const corrected = fields.map((field) => {
+    const own = mark(field, field.name);
+    if (own.fields === undefined) return own;
+    const parent = `${field.name}${field.isList === true ? "[]" : ""}`;
+    return { ...own, fields: own.fields.map((child) => mark(child, `${parent}.${child.name}`)) };
+  });
+  const stale = [...REQUIRED_FIELD_CORRECTIONS.keys()].filter(
+    (key) => key.startsWith(prefix) && !applied.has(key.slice(prefix.length)),
+  );
+  if (stale.length > 0) {
+    throw new Error(
+      `required-field correction names no recovered field: ${stale.sort().join(", ")}`,
+    );
+  }
+  return corrected;
+}
+
+// A param-side list field the engine binding refuses empty. Every entry emits
+// the list as `[E, ...E[]]`; `replaces` drops members the binding reads only as
+// one of several alternatives, and `alternatives` restores them as a union the
+// element is intersected with. Keyed `<element>:param:<slot>:<field>` or
+// `<struct>:member:<field>`, the REQUIRED_FIELD_CORRECTIONS shapes.
+export interface ListFieldCorrection {
+  readonly evidence: string;
+  readonly replaces?: readonly string[];
+  readonly alternatives?: string;
+}
+
+const ATLAS_FRAMES =
+  "script_resource.cpp:CheckAtlasArguments reads a non-empty frames table, else both frame_start and frame_end with CheckFieldValue<int>";
+
+const ATLAS_GEOMETRIES: ListFieldCorrection = { evidence: ATLAS_ARGUMENTS };
+const ATLAS_ANIMATIONS: ListFieldCorrection = {
+  evidence: `${ATLAS_ARGUMENTS}; ${ATLAS_FRAMES}`,
+  replaces: ["frame_start", "frame_end"],
+  alternatives: "{ frames: [number, ...number[]] } | { frame_start: number; frame_end: number }",
+};
+
+export const LIST_FIELD_CORRECTIONS: ReadonlyMap<string, ListFieldCorrection> = new Map<
+  string,
+  ListFieldCorrection
+>([
+  ...(["create_atlas", "set_atlas"] as const).flatMap((name) => [
+    [`resource.${name}:param:table:geometries`, ATLAS_GEOMETRIES] as const,
+    [`resource.${name}:param:table:animations`, ATLAS_ANIMATIONS] as const,
+  ]),
+  ["resource.atlas:member:geometries", ATLAS_GEOMETRIES],
+  ["resource.atlas:member:animations", ATLAS_ANIMATIONS],
+]);
+
+// Apply LIST_FIELD_CORRECTIONS to this slot's fields. An entry keyed to this
+// slot that names no field, names a field that is not a list, or replaces a
+// member the field does not carry throws, so a renamed field or member cannot
+// leave a stale correction looking applied. Returns a new array; never mutates
+// its input.
+export function applyListFieldCorrections(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind !== "param" || slotName === undefined) return [...fields];
+  const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
+  const applied = new Set<string>();
+  const corrected = fields.map((field): TableField => {
+    const key = `${prefix}${field.name}`;
+    const correction = LIST_FIELD_CORRECTIONS.get(key);
+    if (correction === undefined) return field;
+    applied.add(field.name);
+    if (field.isList !== true) {
+      throw new Error(`list-field correction names a field that is not a list: ${key}`);
+    }
+    const replaces = correction.replaces ?? [];
+    const missing = replaces.filter(
+      (name) => !(field.fields ?? []).some((member) => member.name === name),
+    );
+    if (missing.length > 0) {
+      throw new Error(`list-field correction ${key} replaces no member: ${missing.join(", ")}`);
+    }
+    return {
+      ...field,
+      nonEmpty: true,
+      ...(field.fields === undefined
+        ? {}
+        : { fields: field.fields.filter((member) => !replaces.includes(member.name)) }),
+      ...(correction.alternatives === undefined ? {} : { alternatives: correction.alternatives }),
+    };
+  });
+  const stale = [...LIST_FIELD_CORRECTIONS.keys()].filter(
+    (key) => key.startsWith(prefix) && !applied.has(key.slice(prefix.length)),
+  );
+  if (stale.length > 0) {
+    throw new Error(`list-field correction names no recovered field: ${stale.sort().join(", ")}`);
+  }
+  return corrected;
+}
+
 // Append the member TABLE_SLOT_FIELD_ADDITIONS supplies for this slot, after
 // every field the parser recovered. Throws on an addition whose field the parse
 // already produced: upstream has documented it, and the entry is stale.
@@ -2276,10 +3224,12 @@ export function applyFieldAdditions(
   const key = tableSlotKey(elementName, slotKind, slotName);
   const addition = TABLE_SLOT_FIELD_ADDITIONS.get(key);
   if (addition === undefined) return [...fields];
-  if (fields.some((field) => field.name === addition.field.name)) {
-    throw new Error(`field addition names a recovered field: ${key}:${addition.field.name}`);
+  for (const added of addition.fields) {
+    if (fields.some((field) => field.name === added.name)) {
+      throw new Error(`field addition names a recovered field: ${key}:${added.name}`);
+    }
   }
-  return [...fields, addition.field];
+  return [...fields, ...addition.fields];
 }
 
 // Pin a parser-recovered field's TS type from TABLE_FIELD_TYPE_OVERRIDES,
@@ -2448,6 +3398,14 @@ export interface TableField {
   isList?: boolean;
   numberList?: boolean;
   optional?: boolean;
+  // Set only by REQUIRED_FIELD_CORRECTIONS: the engine raises without the field,
+  // so it keeps no `?` even on a param-side option bag.
+  required?: boolean;
+  // Set only by LIST_FIELD_CORRECTIONS: the engine raises on an empty list, so
+  // the list emits as `[E, ...E[]]`, and its element is intersected with the
+  // alternative field sets the binding accepts.
+  nonEmpty?: boolean;
+  alternatives?: string;
   // A hand-curated field whose faithful TS shape is not a plain token union
   // (e.g. a nested vector array, or a documented value union with an array
   // branch): inlineTableType emits this verbatim and the audit treats it as
@@ -2639,27 +3597,349 @@ function groupFlattenedTableFields(fields: readonly TableField[]): TableField[]
 // 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.
-function typedefAlias(name: string, mapType: (token: string) => string): string {
-  const brand = `Opaque<"${name}">`;
-  const mapped = mapType(name);
-  return `type ${name} = ${mapped.startsWith(brand) ? mapped : brand};`;
+//
+// An engine typedef that names its aliased type: a `userdata`/`number` handle the
+// type map resolves (`vector`, `socket_client`) aliases that mapping, an
+// unresolved one keeps the brand, and any other aliased type (a union, literals, a
+// record) aliases the type itself.
+function typedefAlias(
+  typedef: ApiTypedef,
+  local: string,
+  rawMapType: (token: string) => string,
+  mapType: DefoldTypeMapper,
+): string {
+  const brand = `Opaque<"${typedef.name}">`;
+  const aliasOf = typedef.aliasOf ?? [];
+  if (aliasOf.length > 0 && !isHandleAlias(aliasOf)) {
+    return `type ${local} = ${unionFromTokens(aliasOf, mapType)};`;
+  }
+  const mapped = rawMapType(typedef.name);
+  if (mapped.startsWith(brand)) return `type ${local} = ${mapped};`;
+  const resolved = aliasOf.length > 0 && mapped !== "unknown" && mapped !== local;
+  return `type ${local} = ${resolved ? mapped : brand};`;
+}
+
+function isHandleAlias(aliasOf: readonly string[]): boolean {
+  return aliasOf.length === 1 && (aliasOf[0] === "userdata" || aliasOf[0] === "number");
 }
 
-export function emitDeclarations(module: ApiModule, options?: EmitOptions): string {
+// A `STRUCT` or aliasing `TYPEDEF` placed at its local path (`shape_data`,
+// `on_input.action`) under the module that emits it.
+interface TypeDeclaration {
+  name: string;
+  path: string;
+  // The declaration's lines at `indent`, its keyword line led by `decl`.
+  lines: (indent: string, decl: string) => string[];
+  signature: string;
+}
+
+// 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.
+function collectTypeDeclarations(
+  module: ApiModule,
+  skip: ReadonlySet<string>,
+  rawMapType: (token: string) => string,
+  mapType: DefoldTypeMapper,
+): TypeDeclaration[] {
   const prefix = `${module.namespace}.`;
+  const out: TypeDeclaration[] = [];
+  const localOf = (name: string): string | null => {
+    const local = stripPrefix(name, prefix);
+    return local.split(".").every((segment) => TS_IDENTIFIER.test(segment)) ? local : null;
+  };
+  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);
+    const signature = typedefAlias(t, name, rawMapType, mapType);
+    out.push({
+      name,
+      path: local,
+      lines: (indent, decl) => [`${indent}${decl}${signature}`],
+      signature,
+    });
+  }
+  for (const struct of module.structs ?? []) {
+    const local = localOf(struct.name);
+    if (local === null || skip.has(local)) continue;
+    out.push(structDeclaration(struct, local, mapType, module.structs ?? []));
+  }
+  return out;
+}
+
+export function memberCorrectionKey(struct: string, field: string): string {
+  return `${struct}:member:${field}`;
+}
 
-  const constantFqns = new Set(module.constants.map((c) => c.name));
+// A member-keyed LIST_FIELD_CORRECTIONS entry over a `T[]` member: `T` with the
+// replaced members omitted, rendered by the prose-field list renderer.
+function correctedListMemberType(
+  struct: ApiStruct,
+  member: ApiStructMember,
+  correction: ListFieldCorrection,
+  structs: readonly ApiStruct[],
+  mapType: DefoldTypeMapper,
+): string {
+  const key = memberCorrectionKey(struct.name, member.name);
+  const element = member.type.endsWith("[]") ? member.type.slice(0, -2) : undefined;
+  if (element === undefined || element.length === 0) {
+    throw new Error(`list-field correction names a member that is not a list: ${key}`);
+  }
+  const replaces = correction.replaces ?? [];
+  const elementStruct = structs.find((candidate) => candidate.name === element);
+  const missing = replaces.filter(
+    (name) => !(elementStruct?.members ?? []).some((candidate) => candidate.name === name),
+  );
+  if (missing.length > 0) {
+    throw new Error(`list-field correction ${key} replaces no member: ${missing.join(", ")}`);
+  }
+  const mapped = mapType(element);
+  const object =
+    replaces.length === 0
+      ? mapped
+      : `Omit<${mapped}, ${replaces.map((name) => JSON.stringify(name)).join(" | ")}>`;
+  return nestedFieldType(
+    {
+      name: member.name,
+      types: [],
+      isList: true,
+      nonEmpty: true,
+      ...(correction.alternatives === undefined ? {} : { alternatives: correction.alternatives }),
+    },
+    object,
+  );
+}
+
+function structDeclaration(
+  struct: ApiStruct,
+  path: string,
+  mapType: DefoldTypeMapper,
+  structs: readonly ApiStruct[],
+): TypeDeclaration {
+  const name = path.slice(path.lastIndexOf(".") + 1);
+  const memberPrefix = memberCorrectionKey(struct.name, "");
+  const declared = new Set(struct.members.map((member) => member.name));
+  const stale = [
+    ...REQUIRED_FIELD_CORRECTIONS.keys(),
+    ...LIST_FIELD_CORRECTIONS.keys(),
+    ...TABLE_FIELD_TYPE_OVERRIDES.keys(),
+    ...OPTIONAL_MEMBER_CORRECTIONS.keys(),
+  ].filter((key) => key.startsWith(memberPrefix) && !declared.has(key.slice(memberPrefix.length)));
+  if (stale.length > 0) {
+    throw new Error(`member-keyed field correction names no member: ${stale.sort().join(", ")}`);
+  }
+  const members = struct.members.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 optional =
+      (member.isOptional || OPTIONAL_MEMBER_CORRECTIONS.has(key)) &&
+      !REQUIRED_FIELD_CORRECTIONS.has(key);
+    const type =
+      list !== undefined
+        ? correctedListMemberType(struct, member, list, structs, mapType)
+        : retyped !== undefined
+          ? retyped
+          : member.type === ""
+            ? "unknown"
+            : mapType(member.type);
+    return {
+      doc: member.doc,
+      line: `${TS_IDENTIFIER.test(member.name) ? member.name : JSON.stringify(member.name)}${optional ? "?" : ""}: ${type};`,
+    };
+  });
+  return {
+    name,
+    path,
+    lines: (indent, decl) => {
+      const memberIndent = `${indent}${INDENT}`;
+      return [
+        ...summaryDocLines(struct.brief, struct.description, indent),
+        `${indent}${decl}interface ${name} {`,
+        ...members.flatMap((member) => [
+          ...summaryDocLines(member.doc, "", memberIndent),
+          `${memberIndent}${member.line}`,
+        ]),
+        `${indent}}`,
+      ];
+    },
+    signature: `interface ${name} { ${members.map((member) => `${member.line} `).join("")}}`,
+  };
+}
+
+// Nested declarations join the group at their path, which is created when no
+// member lives there; the flat ones are returned in name order.
+function placeTypeDeclarations(
+  declarations: readonly TypeDeclaration[],
+  nestedRoot: Map<string, NestedGroup>,
+): TypeDeclaration[] {
+  const byName = (a: TypeDeclaration, b: TypeDeclaration) => a.name.localeCompare(b.name);
+  const topLevel: TypeDeclaration[] = [];
+  for (const declaration of declarations) {
+    if (declaration.path === declaration.name) {
+      topLevel.push(declaration);
+      continue;
+    }
+    const group = nestedGroupAt(nestedRoot, declaration.path.split(".").slice(0, -1));
+    group.typeDeclarations.push(declaration);
+    group.typeDeclarations.sort(byName);
+  }
+  return topLevel.sort(byName);
+}
+
+// The mappers both emit surfaces read. `mapType` is the engine vocabulary with
+// the surface's leaves, the module's own declared types, those `declaredTypes`
+// names from other modules, and constant tokens branded. `rawMapType`, read only
+// for a typedef's own name, leaves the declared paths out: a handle typedef
+// (`editor.schema`) would otherwise map to its own path and alias itself.
+function moduleTypeMappers(
+  module: ApiModule,
+  constantsByFqn: ReadonlyMap<string, ApiConstant>,
+  options: EmitOptions | undefined,
+): { rawMapType: (token: string) => string; mapType: DefoldTypeMapper } {
+  const leaves = options?.typeLeaves;
+  const rawMapType = options?.mapType ?? mapTypeWithVocabulary({ leaves });
+  const baseMapType =
+    options?.mapType ??
+    mapTypeWithVocabulary({
+      leaves,
+      declared: new Map([...declaredTypePaths([module]), ...(options?.declaredTypes ?? [])]),
+    });
+  const knownConstantFqns = options?.knownConstantFqns;
+  const mapType: DefoldTypeMapper = (token, position) =>
+    constantsByFqn.has(token) || knownConstantFqns?.has(token)
+      ? brandType(token, constantsByFqn.get(token))
+      : baseMapType(token, position);
+  return { rawMapType, mapType };
+}
+
+/**
+ * Move each `STRUCT` and aliasing `TYPEDEF` to the module whose namespace is the
+ * longest prefix of its name (`b2d.joint.revolute_definition`, declared in the
+ * `b2d` doc, moves to `b2d.joint`). A name no module prefixes stays with the
+ * module that declares it. A declaration the home already declares under the
+ * same kind and name, or that an earlier module already routed there, is
+ * 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.
+ */
+export function routeTypeDeclarations(modules: readonly ApiModule[]): ApiModule[] {
+  const homeOf = (name: string, declaring: string): string => {
+    let home = declaring;
+    let longest = -1;
+    for (const { namespace } of modules) {
+      if (name.startsWith(`${namespace}.`) && namespace.length > longest) {
+        home = namespace;
+        longest = namespace.length;
+      }
+    }
+    return home;
+  };
+  const incoming = new Map<
+    string,
+    { structs: ApiStruct[]; typedefs: ApiTypedef[]; functions: ApiFunction[] }
+  >();
+  const into = (namespace: string) => {
+    let bucket = incoming.get(namespace);
+    if (bucket === undefined) {
+      bucket = { structs: [], typedefs: [], functions: [] };
+      incoming.set(namespace, bucket);
+    }
+    return bucket;
+  };
+  const kept = modules.map((module) => {
+    const structs = (module.structs ?? []).filter((struct) => {
+      const home = homeOf(struct.name, module.namespace);
+      if (home === module.namespace) return true;
+      into(home).structs.push(struct);
+      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);
+      return false;
+    });
+    const functions = module.functions.filter((fn) => {
+      const home = homeOf(fn.name, module.namespace);
+      if (home === module.namespace) return true;
+      into(home).functions.push(fn);
+      return false;
+    });
+    return structs.length === (module.structs ?? []).length &&
+      typedefs.length === module.typedefs.length &&
+      functions.length === module.functions.length
+      ? module
+      : { ...module, structs, typedefs, functions };
+  });
+  return kept.map((module) => {
+    const bucket = incoming.get(module.namespace);
+    if (bucket === undefined) return module;
+    const unclaimed = (names: Set<string>) => (declaration: { name: string }) => {
+      if (names.has(declaration.name)) return false;
+      names.add(declaration.name);
+      return true;
+    };
+    const structNames = new Set((module.structs ?? []).map((struct) => struct.name));
+    const typedefNames = new Set(module.typedefs.map((typedef) => typedef.name));
+    // A function keeps every overload one doc files, so the home's own name wins
+    // over another doc's copy of it without collapsing the incoming overloads.
+    const functionNames = new Set(module.functions.map((fn) => fn.name));
+    return {
+      ...module,
+      structs: [...(module.structs ?? []), ...bucket.structs.filter(unclaimed(structNames))],
+      typedefs: [...module.typedefs, ...bucket.typedefs.filter(unclaimed(typedefNames))],
+      functions: [
+        ...module.functions,
+        ...bucket.functions.filter((fn) => !functionNames.has(fn.name)),
+      ],
+    };
+  });
+}
+
+/**
+ * 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`).
+ */
+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}`,
+      );
+    }
+  }
+  return paths;
+}
+
+export function emitDeclarations(documented: ApiModule, options?: EmitOptions): string {
+  const module = withUndocumentedConstants(documented, options?.registeredConstants);
+  const prefix = `${module.namespace}.`;
+
+  const constantsByFqn = new Map(module.constants.map((c) => [c.name, c]));
   const knownConstantFqns = options?.knownConstantFqns;
   const translations = options?.translations ?? {};
   const urlParameters = options?.urlParameters ?? [];
-  const baseMapType = options?.mapType ?? defaultMapType;
-  const mapType = (token: string): string =>
-    constantFqns.has(token) || knownConstantFqns?.has(token)
-      ? brandType(token)
-      : baseMapType(token);
+  const baseNotes = indexBaseNoteResolver(options?.indexBaseSource ?? "engine");
+  const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
-    new Set([...constantFqns, ...(knownConstantFqns ?? [])]),
+    new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
   );
 
   const constants = module.constants
@@ -2673,6 +3953,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     .sort((a, b) => a.name.localeCompare(b.name));
 
   const functions = module.functions
+    .filter((fn) => !isMisfiled(fn))
     .map((fn) => prepareFunction(fn, prefix))
     .filter((entry): entry is PreparedFunction => entry !== null)
     .sort((a, b) =>
@@ -2689,6 +3970,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   // segment. One or two leading identifier segments qualify; anything deeper,
   // and any non-identifier segment, stays dropped.
   const nestedRoot = collectNestedGroups(module, prefix);
+  const enumAliases = collectEnumAliases(module, constants, nestedRoot);
 
   // Colon methods (`client:send`) are FUNCTION elements named `<receiver>:<method>`
   // and are NOT namespace-prefixed, so they fail the flat-identifier test in
@@ -2706,9 +3988,12 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     })),
   );
 
-  const typedefs = module.typedefs
-    .filter((t) => TS_IDENTIFIER.test(t.name))
-    .sort((a, b) => a.name.localeCompare(b.name));
+  // 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),
+    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
@@ -2716,28 +4001,29 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   // keyword is otherwise omitted to keep every alias-free module byte-identical.
   const hasAliases =
     variables.some((v) => TS_RESERVED_NAMES.has(v.name)) ||
-    functions.some((fn) => TS_RESERVED_NAMES.has(fn.name));
+    functions.some((fn) => TS_RESERVED_NAMES.has(fn.name)) ||
+    [...nestedRoot.keys()].some((segment) => TS_RESERVED_NAMES.has(segment));
   const decl = hasAliases ? "export " : "";
 
   const lines: string[] = [];
-  for (const docLine of namespaceDocLines(module)) lines.push(docLine);
+  for (const docLine of namespaceDocLines(module, translations)) lines.push(docLine);
   lines.push(`declare namespace ${module.namespace} {`);
 
-  for (const t of typedefs) {
-    // A typedef that also has colon methods is emitted as a method-bearing
-    // interface below, not an opaque brand alias.
-    if (handleGroups.has(t.name)) continue;
-    lines.push(`${INDENT}${decl}${typedefAlias(t.name, baseMapType)}`);
-  }
+  for (const declaration of typeDeclarations) lines.push(...declaration.lines(INDENT, decl));
   for (const aliasDecl of constantUnionAliasDeclarations(module.namespace)) {
     lines.push(`${INDENT}${decl}${aliasDecl}`);
   }
+  for (const alias of enumAliases.topLevel) {
+    lines.push(
+      `${INDENT}${decl}${unionAliasDeclaration(alias.name, alias.members, alias.nilable)}`,
+    );
+  }
   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 docLine of functionDocLines(fn.original, translations, handleIndent)) {
+      for (const docLine of functionDocLines(fn.original, translations, baseNotes, handleIndent)) {
         lines.push(docLine);
       }
       lines.push(
@@ -2750,7 +4036,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     for (const docLine of summaryDocLines(c.original.brief, c.original.description, INDENT)) {
       lines.push(docLine);
     }
-    lines.push(`${INDENT}${decl}const ${c.name}: ${brandType(c.fqn)};`);
+    lines.push(`${INDENT}${decl}const ${c.name}: ${constantType(c)};`);
   }
   const aliases: { internal: string; public: string }[] = [];
   for (const v of variables) {
@@ -2770,11 +4056,17 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   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)) lines.push(docLine);
+    for (const docLine of functionDocLines(fn.original, translations, baseNotes))
+      lines.push(docLine);
     const line = emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters);
     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
+      // of the index it takes. Its examples are the primary signature's.
+      const { examples: _examples, ...overloadDoc } = alternative.original;
+      for (const docLine of functionDocLines(overloadDoc, translations, baseNotes))
+        lines.push(docLine);
       const overload = emitFunction(
         alternative,
         emitName,
@@ -2787,6 +4079,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     }
   }
 
+  aliasReservedSegments(nestedRoot.keys(), aliases);
   for (const alias of [...aliases].sort((a, b) => a.public.localeCompare(b.public))) {
     lines.push(`${INDENT}export { ${alias.internal} as ${alias.public} };`);
   }
@@ -2802,14 +4095,38 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
       // A reserved-name member inside a nested namespace gets the same recovery as
       // a top-level one: emitted un-exported as `_<name>` and re-exported under the
       // reserved name. The alias switches this namespace out of implicit-export mode,
-      // so its siblings then need an explicit `export` to stay reachable.
+      // so its siblings then need an explicit `export` to stay reachable. A
+      // reserved segment is itself declared as `_<segment>`, merging with a
+      // same-named function, and reached through the parent's alias.
       const segmentAliases: { internal: string; public: string }[] = [];
       const segmentDecl =
         group.variables.some((v) => TS_RESERVED_NAMES.has(v.name)) ||
-        group.functions.some((fn) => TS_RESERVED_NAMES.has(fn.name))
+        group.functions.some((fn) => TS_RESERVED_NAMES.has(fn.name)) ||
+        [...group.children.keys()].some((child) => TS_RESERVED_NAMES.has(child))
           ? "export "
           : "";
-      lines.push(`${indent}${outerDecl}namespace ${segment} {`);
+      const reservedSegment = TS_RESERVED_NAMES.has(segment);
+      lines.push(
+        `${indent}${reservedSegment ? "" : outerDecl}namespace ${reservedSegment ? `_${segment}` : segment} {`,
+      );
+      for (const declaration of group.typeDeclarations) {
+        lines.push(...declaration.lines(bodyIndent, segmentDecl));
+      }
+      for (const alias of group.enumAliases) {
+        lines.push(
+          `${bodyIndent}${segmentDecl}${unionAliasDeclaration(alias.name, alias.members, alias.nilable)}`,
+        );
+      }
+      for (const c of group.constants) {
+        for (const docLine of summaryDocLines(
+          c.original.brief,
+          c.original.description,
+          bodyIndent,
+        )) {
+          lines.push(docLine);
+        }
+        lines.push(`${bodyIndent}${segmentDecl}const ${c.name}: ${constantType(c)};`);
+      }
       for (const v of group.variables) {
         const reserved = TS_RESERVED_NAMES.has(v.name);
         const emitName = aliasName(v.name, segmentAliases);
@@ -2827,13 +4144,14 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
       for (const fn of group.functions) {
         const reserved = TS_RESERVED_NAMES.has(fn.name);
         const emitName = aliasName(fn.name, segmentAliases);
-        for (const docLine of functionDocLines(fn.original, translations, bodyIndent)) {
+        for (const docLine of functionDocLines(fn.original, translations, baseNotes, bodyIndent)) {
           lines.push(docLine);
         }
         lines.push(
           `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters)}`,
         );
       }
+      aliasReservedSegments(group.children.keys(), segmentAliases);
       for (const alias of [...segmentAliases].sort((a, b) => a.public.localeCompare(b.public))) {
         lines.push(`${bodyIndent}export { ${alias.internal} as ${alias.public} };`);
       }
@@ -2862,14 +4180,22 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
 }
 
 /**
- * Every documented slot's rendered TS type, keyed `param|return:<position>:<raw
- * ref-doc name>`. The position is part of the key because a multi-return can
- * carry several unnamed slots (`push.schedule` renders two), which a name-only
- * key would collapse into one. Each value appears verbatim inside the symbol's
- * own `tsSignature`, so a consumer rendering a slot's type beside that signature
- * cannot contradict it.
+ * Every documented slot's rendered TS type and optionality, keyed
+ * `param|return:<position>:<raw ref-doc name>`. The position is part of the key
+ * because a multi-return can carry several unnamed slots (`push.schedule`
+ * renders two), which a name-only key would collapse into one. Each `type`
+ * appears verbatim inside the symbol's own `tsSignature` as the slot's printed
+ * operand (an interior omissible slot keeps its `| undefined` arm), and
+ * `optional` is whether the name carries `?` there, so a consumer rendering a
+ * slot beside that signature cannot contradict it. Returns and slots folded into
+ * a rest element are never `optional`.
  */
-export type SlotTypes = Readonly<Record<string, string>>;
+export interface SlotType {
+  readonly type: string;
+  readonly optional: boolean;
+}
+
+export type SlotTypes = Readonly<Record<string, SlotType>>;
 
 function slotKey(kind: "param" | "return", position: number, name: string): string {
   return `${kind}:${position}:${name}`;
@@ -2897,19 +4223,19 @@ export interface SymbolSignature {
  * line, primary first, the same convention as the authored fold; its
  * `slotTypes` describe the primary arm only.
  */
-export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions): SymbolSignature[] {
+export function emitSymbolSignatures(
+  documented: ApiModule,
+  options?: EmitOptions,
+): SymbolSignature[] {
+  const module = withUndocumentedConstants(documented, options?.registeredConstants);
   const prefix = `${module.namespace}.`;
-  const constantFqns = new Set(module.constants.map((c) => c.name));
+  const constantsByFqn = new Map(module.constants.map((c) => [c.name, c]));
   const knownConstantFqns = options?.knownConstantFqns;
   const urlParameters = options?.urlParameters ?? [];
-  const baseMapType = options?.mapType ?? defaultMapType;
-  const mapType = (token: string): string =>
-    constantFqns.has(token) || knownConstantFqns?.has(token)
-      ? brandType(token)
-      : baseMapType(token);
+  const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
-    new Set([...constantFqns, ...(knownConstantFqns ?? [])]),
+    new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
   );
   const resolver = buildTableDocResolver(
     module.functions.map((fn) => ({
@@ -2932,9 +4258,10 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   const NO_SLOTS: SlotTypes = {};
 
   for (const fn of module.functions) {
+    if (isMisfiled(fn)) continue;
     const prepared = prepareFunction(fn, prefix);
     if (prepared === null) continue;
-    const slotTypes: Record<string, string> = {};
+    const slotTypes: Record<string, SlotType> = {};
     const primary = emitFunction(
       prepared,
       emitName(prepared.name),
@@ -2959,7 +4286,20 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     out.push({ identity: fnIdentity(fn), tsSignature, slotTypes });
   }
 
-  const nested = flattenNestedGroups(collectNestedGroups(module, prefix));
+  const nestedRoot = collectNestedGroups(module, prefix);
+  const nested = flattenNestedGroups(nestedRoot);
+  for (const c of nested.constants) {
+    out.push({
+      identity: {
+        namespace: module.namespace,
+        kind: "CONSTANT",
+        name: c.fqn,
+        signature: "",
+      },
+      tsSignature: `const ${c.name}: ${constantType(c)};`,
+      slotTypes: NO_SLOTS,
+    });
+  }
   for (const v of nested.variables) {
     out.push({
       identity: {
@@ -2973,7 +4313,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     });
   }
   for (const fn of nested.functions) {
-    const slotTypes: Record<string, string> = {};
+    const slotTypes: Record<string, SlotType> = {};
     out.push({
       identity: fnIdentity(fn.original),
       tsSignature: emitFunction(
@@ -2992,7 +4332,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   const handleGroups = collectHandleMethodGroups(module);
   for (const group of handleGroups.values()) {
     for (const prepared of group) {
-      const slotTypes: Record<string, string> = {};
+      const slotTypes: Record<string, SlotType> = {};
       out.push({
         identity: fnIdentity(prepared.original),
         tsSignature: emitMethod(
@@ -3008,12 +4348,14 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     }
   }
 
+  const constants: PreparedConstant[] = [];
   for (const c of module.constants) {
     const prepared = prepareConstant(c, prefix);
     if (prepared === null) continue;
+    constants.push(prepared);
     out.push({
       identity: { namespace: module.namespace, kind: "CONSTANT", name: c.name, signature: "" },
-      tsSignature: `const ${prepared.name}: ${brandType(prepared.fqn)};`,
+      tsSignature: `const ${prepared.name}: ${constantType(prepared)};`,
       slotTypes: NO_SLOTS,
     });
   }
@@ -3040,11 +4382,22 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     });
   }
 
-  for (const t of module.typedefs) {
-    if (!TS_IDENTIFIER.test(t.name) || handleGroups.has(t.name)) continue;
+  // A struct signs as its interface on one line; each member line is verbatim in
+  // the declarations.
+  for (const declaration of collectTypeDeclarations(
+    module,
+    new Set(handleGroups.keys()),
+    rawMapType,
+    mapType,
+  )) {
     out.push({
-      identity: { namespace: module.namespace, kind: "TYPEDEF", name: t.name, signature: "" },
-      tsSignature: typedefAlias(t.name, baseMapType),
+      identity: {
+        namespace: module.namespace,
+        kind: "TYPEDEF",
+        name: declaration.path,
+        signature: "",
+      },
+      tsSignature: declaration.signature,
       slotTypes: NO_SLOTS,
     });
   }
@@ -3055,9 +4408,18 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   for (const row of CONSTANT_UNION_ALIASES.filter((r) => r.home === module.namespace)) {
     out.push({
       identity: { namespace: module.namespace, kind: "TYPEDEF", name: row.name, signature: "" },
-      tsSignature: `type ${row.name} = ${row.members
-        .map((member) => `typeof ${member}`)
-        .join(" | ")};`,
+      tsSignature: unionAliasDeclaration(row.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);
+  for (const alias of enumAliases.all) {
+    out.push({
+      identity: { namespace: module.namespace, kind: "TYPEDEF", name: alias.path, signature: "" },
+      tsSignature: unionAliasDeclaration(alias.name, alias.members, alias.nilable),
       slotTypes: NO_SLOTS,
     });
   }
@@ -3084,35 +4446,67 @@ interface PreparedVariable {
 // One level of the nested-member tree: the members declared directly under a
 // segment, plus the segments declared beneath it.
 interface NestedGroup {
+  constants: PreparedConstant[];
   variables: PreparedVariable[];
   functions: PreparedFunction[];
+  enumAliases: EnumAlias[];
+  typeDeclarations: TypeDeclaration[];
   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.
+interface EnumAlias {
+  name: string;
+  path: string;
+  members: readonly string[];
+  // Members typed `<ENUM>|nil`, whose arm drops the `undefined` their `const`
+  // admits, as a slot naming one does.
+  nilable: ReadonlySet<string>;
+}
+
 // A stripped local carrying one or two leading identifier segments before the
 // member name (`dns.toip`, `COLOR.TEXT`, `schema.integer`). Three levels deep is
 // beyond anything the vendored documents describe, so it stays dropped rather
 // than half-emitted.
 const NESTED_MEMBER_LOCAL = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*){1,2}$/;
 
+// The group at `segments` under `root`, creating each missing level.
+function nestedGroupAt(root: Map<string, NestedGroup>, segments: readonly string[]): NestedGroup {
+  let level = root;
+  let group: NestedGroup | undefined;
+  for (const segment of segments) {
+    let next = level.get(segment);
+    if (next === undefined) {
+      next = {
+        constants: [],
+        variables: [],
+        functions: [],
+        enumAliases: [],
+        typeDeclarations: [],
+        children: new Map(),
+      };
+      level.set(segment, next);
+    }
+    group = next;
+    level = next.children;
+  }
+  return group as NestedGroup;
+}
+
 function collectNestedGroups(module: ApiModule, prefix: string): Map<string, NestedGroup> {
   const root = new Map<string, NestedGroup>();
-  const groupAt = (segments: readonly string[]): NestedGroup => {
-    let level = root;
-    let group: NestedGroup | undefined;
-    for (const segment of segments) {
-      let next = level.get(segment);
-      if (next === undefined) {
-        next = { variables: [], functions: [], children: new Map() };
-        level.set(segment, next);
-      }
-      group = next;
-      level = next.children;
-    }
-    return group as NestedGroup;
-  };
+  const groupAt = (segments: readonly string[]): NestedGroup => nestedGroupAt(root, segments);
   const pathOf = (local: string): string[] => local.split(".").slice(0, -1);
 
+  for (const c of module.constants) {
+    const local = stripPrefix(c.name, prefix);
+    if (!NESTED_MEMBER_LOCAL.test(local)) continue;
+    const segments = pathOf(local);
+    const prepared = prepareConstant(c, `${module.namespace}.${segments.join(".")}.`);
+    if (prepared === null) continue;
+    groupAt(segments).constants.push(prepared);
+  }
   for (const v of module.variables) {
     const local = stripPrefix(v.name, prefix);
     if (!NESTED_MEMBER_LOCAL.test(local)) continue;
@@ -3132,6 +4526,7 @@ function collectNestedGroups(module: ApiModule, prefix: string): Map<string, Nes
 
   const sortLevel = (level: Map<string, NestedGroup>): void => {
     for (const group of level.values()) {
+      group.constants.sort((a, b) => a.name.localeCompare(b.name));
       group.variables.sort((a, b) => a.name.localeCompare(b.name));
       group.functions.sort((a, b) =>
         a.name === b.name
@@ -3150,21 +4545,71 @@ function collectNestedGroups(module: ApiModule, prefix: string): Map<string, Nes
 // children). Callers that need no per-segment container read the tree through
 // this rather than re-deriving which members are nested and how deep.
 function flattenNestedGroups(level: ReadonlyMap<string, NestedGroup>): {
+  constants: PreparedConstant[];
   variables: PreparedVariable[];
   functions: PreparedFunction[];
 } {
+  const constants: PreparedConstant[] = [];
   const variables: PreparedVariable[] = [];
   const functions: PreparedFunction[] = [];
   const walk = (current: ReadonlyMap<string, NestedGroup>): void => {
     for (const segment of [...current.keys()].sort((a, b) => a.localeCompare(b))) {
       const group = current.get(segment) as NestedGroup;
+      constants.push(...group.constants);
       variables.push(...group.variables);
       functions.push(...group.functions);
       walk(group.children);
     }
   };
   walk(level);
-  return { variables, functions };
+  return { constants, variables, functions };
+}
+
+// Each `ENUM`'s union alias, placed where its name lands: a flat local
+// (`STATUS`) at the top of the namespace, a nested one (`ui.COLOR`) in the
+// nested group `ui`, which the tree already holds when the members are nested
+// beside it. An enum is aliased only when every member is declared, so the
+// alias never names a constant the module does not emit. The nested groups
+// gain their aliases in place; `topLevel` and `all` are in name order.
+function collectEnumAliases(
+  module: ApiModule,
+  topLevelConstants: readonly PreparedConstant[],
+  nestedRoot: Map<string, NestedGroup>,
+): { topLevel: EnumAlias[]; all: EnumAlias[] } {
+  const prefix = `${module.namespace}.`;
+  const declared = new Set([
+    ...topLevelConstants.map((c) => c.fqn),
+    ...flattenNestedGroups(nestedRoot).constants.map((c) => c.fqn),
+  ]);
+  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));
+  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 };
+      topLevel.push(alias);
+      all.push(alias);
+      continue;
+    }
+    if (!NESTED_MEMBER_LOCAL.test(path)) continue;
+    const segments = path.split(".");
+    const name = segments.pop() as string;
+    let level = nestedRoot;
+    let group: NestedGroup | undefined;
+    for (const segment of segments) {
+      group = level.get(segment);
+      if (group === undefined) break;
+      level = group.children;
+    }
+    if (group === undefined) continue;
+    const alias = { name, path, members: e.members, nilable };
+    group.enumAliases.push(alias);
+    all.push(alias);
+  }
+  return { topLevel, all };
 }
 
 function prepareFunction(fn: ApiFunction, prefix: string): PreparedFunction | null {
@@ -3210,8 +4655,137 @@ function prepareConstant(c: ApiConstant, prefix: string): PreparedConstant | nul
   return { name: stripped, fqn: c.name, original: c };
 }
 
-function brandType(fqn: string): string {
-  return `number & { readonly __brand: "${fqn}" }`;
+// Where the engine registers a constant as a string: the vendored binding file
+// and the call there whose macro pushes the literal.
+export interface StringConstantSource {
+  readonly binding: string;
+  readonly macro: string;
+  readonly call: string;
+}
+
+const GUI_SCRIPT = "engine/gui/src/gui_script.cpp";
+const IMAGE_SCRIPT = "engine/gamesys/src/gamesys/scripts/script_image.cpp";
+
+// Constants the engine registers with `lua_pushliteral`, keyed by FQN. The
+// ref-docs give constants no type, and every other constant is a number;
+// `string-constant-provenance.test.ts` reds when a vendored binding stops
+// pushing one as a string.
+export const STRING_CONSTANTS: ReadonlyMap<string, StringConstantSource> = new Map([
+  ...[
+    "position",
+    "rotation",
+    "euler",
+    "scale",
+    "color",
+    "outline",
+    "shadow",
+    "size",
+    "fill_angle",
+    "inner_radius",
+    "leading",
+    "tracking",
+    "slice9",
+  ].map((prop): [string, StringConstantSource] => {
+    const name = prop.toUpperCase();
+    const call = `SETPROP(${prop}, ${name})`;
+    return [`gui.PROP_${name}`, { binding: GUI_SCRIPT, macro: "SETPROP", call }];
+  }),
+  ...(
+    [
+      ["TYPE_RGB", "rgb"],
+      ["TYPE_RGBA", "rgba"],
+      ["TYPE_LUMINANCE", "l"],
+      ["TYPE_LUMINANCE_ALPHA", "la"],
+    ] as const
+  ).map(([name, value]): [string, StringConstantSource] => [
+    `image.${name}`,
+    { binding: IMAGE_SCRIPT, macro: "SETCONSTANT", call: `SETCONSTANT(${name}, "${value}")` },
+  ]),
+]);
+
+// Documented constants the engine never registers, keyed by FQN with the
+// reason, so Lua reads each as nil. `nil-constant-provenance.test.ts` pins the
+// keys to the accepted `constant-missing-binding` binding verdicts.
+export const NIL_CONSTANTS: ReadonlyMap<string, string> = new Map([
+  [
+    "render.RENDER_TARGET_DEFAULT",
+    "render_script.cpp registers no such field; render.set_render_target reads the nil as the default target",
+  ],
+]);
+
+// Constants the engine registers but some release's ref-doc omits, keyed by FQN
+// with the doc the emit carries. A surface gains an entry only where its ref-doc
+// leaves the constant out and its engine bindings register it.
+// `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.
+export const UNDOCUMENTED_CONSTANTS: ReadonlyMap<
+  string,
+  { readonly doc: string; readonly sameValueAs?: string }
+> = new Map([
+  [
+    "render.CONTEXT_EVENT_CONTEXT_LOST",
+    {
+      doc: "The rendering context was lost. Rendering is paused and all graphics resources become invalid. Passed to the `render.set_listener` callback.",
+    },
+  ],
+  [
+    "render.CONTEXT_EVENT_CONTEXT_RESTORED",
+    {
+      doc: "The rendering context was restored. Rendering is still paused and graphics resources are still invalid, but can be reloaded. Passed to the `render.set_listener` callback.",
+    },
+  ],
+  [
+    "window.WINDOW_EVENT_ICONFIED",
+    {
+      doc: "Deprecated misspelling of `window.WINDOW_EVENT_ICONIFIED`, with the same value. The engine still registers it.",
+      sameValueAs: "window.WINDOW_EVENT_ICONIFIED",
+    },
+  ],
+]);
+
+function withUndocumentedConstants(
+  module: ApiModule,
+  registered: ReadonlySet<string> | undefined,
+): ApiModule {
+  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) {
+    if (!fqn.startsWith(prefix) || fqn.slice(prefix.length).includes(".")) continue;
+    if (documented.has(fqn)) continue;
+    if (registered !== undefined && !registered.has(fqn)) continue;
+    const aliasOf =
+      sameValueAs !== undefined && documented.has(sameValueAs) ? sameValueAs : undefined;
+    backfill.push({
+      name: fqn,
+      brief: doc,
+      description: "",
+      ...(aliasOf === undefined ? {} : { aliasOf }),
+    });
+  }
+  return backfill.length === 0
+    ? module
+    : { ...module, constants: [...module.constants, ...backfill] };
+}
+
+// `constant` is the module's own element for `fqn`, absent for a constant another
+// module declares; an `ENUM` member's value type rides on it.
+function brandType(fqn: string, constant?: ApiConstant): string {
+  // `undefined & { __brand }` collapses to `never`, so a nil constant takes no brand.
+  if (NIL_CONSTANTS.has(fqn)) return "undefined";
+  const base = constant?.valueType === "string" || STRING_CONSTANTS.has(fqn) ? "string" : "number";
+  return `${base} & { readonly __brand: "${fqn}" }`;
+}
+
+// A declared constant's type. A nilable `ENUM` member admits `undefined` here
+// only: a slot naming it still takes the brand, as the value it is documented to
+// accept.
+function constantType(c: PreparedConstant): string {
+  if (c.original.aliasOf !== undefined) return `typeof ${c.original.aliasOf}`;
+  const brand = brandType(c.fqn, c.original);
+  return c.original.nilable === true && brand !== "undefined" ? `${brand} | undefined` : brand;
 }
 
 function prepareVariable(v: ApiVariable, prefix: string): PreparedVariable | null {
@@ -3235,26 +4809,44 @@ function aliasName(name: string, aliases: { internal: string; public: string }[]
   return internal;
 }
 
-function emitVariable(
-  prepared: PreparedVariable,
-  name: string,
-  mapType: (t: string) => string,
-): string {
+// A nested namespace named by a reserved word is emitted as `_<segment>`; its
+// parent re-exports it under the reserved name, sharing the alias a same-named
+// function already recorded.
+function aliasReservedSegments(
+  segments: Iterable<string>,
+  aliases: { internal: string; public: string }[],
+): void {
+  for (const segment of segments) {
+    if (!TS_RESERVED_NAMES.has(segment)) continue;
+    if (aliases.some((alias) => alias.public === segment)) continue;
+    aliases.push({ internal: `_${segment}`, public: segment });
+  }
+}
+
+// A variable whose ref-doc states its type only in prose, keyed by FQN. Each
+// entry fills a slot upstream left empty; `emit-dts.test.ts` reds once the
+// default target's ref-doc types it.
+export const VARIABLE_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
+  // "A `string`, either:" followed by the four platform ids.
+  ["editor.platform", '"x86_64-win32" | "x86_64-macos" | "arm64-macos" | "x86_64-linux"'],
+]);
+
+function emitVariable(prepared: PreparedVariable, name: string, mapType: DefoldTypeMapper): string {
   const ts =
     prepared.original.types.length > 0
       ? unionFromTokens(prepared.original.types, mapType)
-      : "unknown";
+      : (VARIABLE_TYPE_OVERRIDES.get(prepared.original.name) ?? "unknown");
   return `const ${name}: ${ts};`;
 }
 
 function memberSignature(
   prepared: PreparedFunction,
   name: string,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
-  slotSink?: Record<string, string>,
+  slotSink?: Record<string, SlotType>,
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
@@ -3293,16 +4885,16 @@ function memberSignature(
   if (slotSink !== undefined) {
     for (const [i, p] of positional.entries()) {
       const raw = original[i];
-      if (raw) slotSink[slotKey("param", i, raw.name)] = p.ts;
+      if (raw) slotSink[slotKey("param", i, raw.name)] = { type: p.type, optional: p.optional };
     }
     for (const slot of rest?.slots ?? []) {
-      slotSink[slotKey("param", slot.position, slot.name)] = slot.ts;
+      slotSink[slotKey("param", slot.position, slot.name)] = { type: slot.ts, optional: false };
     }
     // A predicate renders `arg is T` in place of the mapped `boolean`, so its
     // return slot has no text in the signature to stand on and is not reported.
     if (!isPredicate) {
       for (const slot of ret.slots) {
-        slotSink[slotKey("return", slot.position, slot.name)] = slot.ts;
+        slotSink[slotKey("return", slot.position, slot.name)] = { type: slot.ts, optional: false };
       }
     }
   }
@@ -3315,11 +4907,11 @@ function memberSignature(
 function emitFunction(
   prepared: PreparedFunction,
   name: string,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
-  slotSink?: Record<string, string>,
+  slotSink?: Record<string, SlotType>,
 ): string {
   return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters, slotSink)}`;
 }
@@ -3329,11 +4921,11 @@ function emitFunction(
 // member carries no `self` parameter.
 function emitMethod(
   prepared: PreparedFunction,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
-  slotSink?: Record<string, string>,
+  slotSink?: Record<string, SlotType>,
 ): string {
   return memberSignature(
     prepared,
@@ -3352,57 +4944,103 @@ function emitMethod(
 // fallback applies to non-identifier names and a vararg drops its dots, matching
 // `emitParameter` and `emitRestParameter`) so the tag resolves on hover; a
 // parameter folded into a rest element union keeps its own tag, so the prose
-// documenting it survives. A single documented return becomes `@returns`. Returns `[]`
-// for a fully-undocumented function, leaving its emission byte-identical.
+// documenting it survives. A single documented return becomes `@returns`; a
+// multi-return function gains one only when a slot carries a classified index
+// (see `multiReturnDoc`). A return authored in `RETURN_TYPE_OVERRIDES` has no
+// ref-doc slot, so it gains `@returns` only for the base notes of its classified
+// fields (see `overrideReturnDoc`). Returns `[]` for a fully-undocumented
+// function, leaving its emission byte-identical.
 function functionDocLines(
   fn: ApiFunction,
   translations: TranslationStore,
+  baseNotes: IndexBaseNoteResolver,
   indent: string = INDENT,
 ): string[] {
   const params = fn.parameters.map((p, index) => ({
     name: emittedParamName(p, index),
-    doc: rewriteParamDoc(fn.name, p.name, htmlToDocText(p.doc)),
+    doc: appendNotes(
+      translateProseFences(htmlToDocText(p.doc), fn.name, translations),
+      baseNotes(fn.name, "param", p.name),
+    ),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
+  const notedReturns =
+    multiReturnDoc(fn, translations, baseNotes) ?? overrideReturnDoc(fn, baseNotes);
   const lua = htmlToCodeText(fn.examples ?? "");
-  // A blob carrying several examples documents them as several, but only when
-  // every segment has an authored body: a partial resolve would drop the rest.
-  // Otherwise the whole-blob ladder stands — a hand-authored TS translation
-  // pinned to this exact Lua flips the fence to ```ts; any hash mismatch (or
-  // absent translation) keeps the Lua fallback.
+  // Each example resolves by its own segment hash, a single-example element's
+  // one segment being the whole blob with no prose. The blob documents its
+  // examples as TypeScript only when every segment has an authored body: a
+  // partial resolve would drop the rest, so any miss keeps the Lua fallback.
   const segments = splitExampleSources(fn.examples ?? "");
-  const perSegment =
-    segments.length > 1
-      ? lookupExampleTranslations(
-          translations,
-          fn.name,
-          segments.map((segment) => hashExampleSource(segment.code)),
-        )
-      : null;
-  const ts = lua === "" ? null : lookupTranslation(translations, fn.name, hashExampleSource(lua));
+  const resolved = lookupExampleSegments(translations, fn.name, segments);
   const exampleParts: Pick<DocCommentParts, "examples"> =
-    perSegment !== null
+    resolved !== null
       ? {
-          examples: perSegment.map((text, index) => ({
+          examples: resolved.map(({ ts: text, prose }) => ({
             text,
             lang: "ts" as const,
-            ...(segments[index]?.prose ? { prose: segments[index]?.prose } : {}),
+            ...(prose ? { prose } : {}),
           })),
         }
-      : ts !== null
-        ? { examples: [{ text: ts, lang: "ts" }] }
-        : lua !== ""
-          ? { examples: [{ text: lua, lang: "lua" }] }
-          : {};
+      : lua !== ""
+        ? { examples: [{ text: lua, lang: "lua" }] }
+        : {};
   const parts: DocCommentParts = {
-    summary: htmlToDocText(summaryFor(fn.brief, fn.description)),
+    summary: translateProseFences(
+      htmlToDocText(summaryFor(fn.brief, fn.description)),
+      fn.name,
+      translations,
+    ),
     params,
-    ...(onlyReturn ? { returns: htmlToDocText(onlyReturn.doc) } : {}),
+    ...(onlyReturn
+      ? {
+          returns: appendNotes(
+            translateProseFences(htmlToDocText(onlyReturn.doc), fn.name, translations),
+            baseNotes(fn.name, "return", onlyReturn.name),
+          ),
+        }
+      : notedReturns !== undefined
+        ? { returns: notedReturns }
+        : {}),
     ...exampleParts,
   };
   return indentDocLines(parts, indent);
 }
 
+// A multi-return function documents its tuple slot by slot, in tuple order, so
+// the hover can name each classified index's base. Every other multi-return
+// function keeps no `@returns`, leaving its emission byte-identical.
+function multiReturnDoc(
+  fn: ApiFunction,
+  translations: TranslationStore,
+  baseNotes: IndexBaseNoteResolver,
+): string | undefined {
+  if (fn.returnValues.length < 2) return undefined;
+  const classified = fn.returnValues.some(
+    (slot) => baseNotes(fn.name, "return", slot.name).length > 0,
+  );
+  if (!classified) return undefined;
+  const bullets = fn.returnValues.map((slot) => {
+    const doc = appendNotes(
+      translateProseFences(htmlToDocText(slot.doc), fn.name, translations),
+      baseNotes(fn.name, "return", slot.name),
+    );
+    const [first = "", ...rest] = doc.split("\n");
+    return [
+      `- \`${slot.name}\` — ${first}`,
+      ...rest.map((line) => (line === "" ? "" : `  ${line}`)),
+    ];
+  });
+  const names = fn.returnValues.map((slot) => slot.name).join(", ");
+  return [`\`[${names}]\`:`, ...bullets.flat()].join("\n");
+}
+
+function overrideReturnDoc(fn: ApiFunction, baseNotes: IndexBaseNoteResolver): string | undefined {
+  if (fn.returnValues.length > 0 || !RETURN_TYPE_OVERRIDES.has(fn.name)) return undefined;
+  const notes = baseNotes(fn.name, "return", OVERRIDE_RETURN_SLOT);
+  return notes.length > 0 ? notes.join(" ") : undefined;
+}
+
 // Summary-only doc lines for a member that carries no params or returns
 // (constants, variables, `properties` members). Reuses the same renderer and
 // summary precedence as functions; returns `[]` for an undocumented member so
@@ -3412,11 +5050,11 @@ function summaryDocLines(brief: string, description: string, indent: string): st
   return indentDocLines({ summary: htmlToDocText(summaryFor(brief, description)) }, indent);
 }
 
-function namespaceDocLines(module: ApiModule): string[] {
+function namespaceDocLines(module: ApiModule, translations: TranslationStore): string[] {
   const official = summaryFor(module.brief, module.description).trim();
   const summary =
     official.length > 0
-      ? htmlToDocText(official)
+      ? translateProseFences(htmlToDocText(official), module.namespace, translations)
       : `(synthesized)\nDefold \`${module.namespace}\` API namespace.`;
   return indentDocLines({ summary }, "");
 }
@@ -3425,13 +5063,6 @@ function indentDocLines(parts: DocCommentParts, indent: string): string[] {
   return renderDocComment(parts).map((line) => `${indent}${line}`);
 }
 
-// Prefer the full `description`; fall back to the one-line `brief` when prose is
-// absent. Shared by every documented member kind so the summary source is
-// consistent across functions, constants, variables, and properties.
-export function summaryFor(brief: string, description: string): string {
-  return description.trim() !== "" ? description : brief;
-}
-
 export function isMarkedOptional(p: ApiParameter): boolean {
   return p.isOptional || p.types.includes("nil");
 }
@@ -3445,6 +5076,7 @@ export function isMarkedOptional(p: ApiParameter): boolean {
 // second copy of the rule. The fidelity audit reads it too, to tell which slots
 // the emitted surface still makes required.
 export function isDocOptional(p: ApiParameter, elementName: string): boolean {
+  if (requiredSlotCorrection(p, elementName)) return false;
   if (isMarkedOptional(p)) return true;
   return OPTIONAL_SLOT_CORRECTIONS.has(tableSlotKey(elementName, "param", p.name));
 }
@@ -3472,7 +5104,7 @@ const SCENE_ADDRESS_ALIASES: Readonly<Record<string, string>> = {
 // becomes the matching scene-derived alias. Wrapping `mapType` rather than
 // rewriting the finished union leaves `mapSlotUnion`'s member ordering and
 // de-duplication in charge, so only the one token moves.
-function addressMapType(mapType: (t: string) => string, alias: string): (t: string) => string {
+function addressMapType(mapType: DefoldTypeMapper, alias: string): (t: string) => string {
   return (token) => (token === "string" ? alias : mapType(token));
 }
 
@@ -3481,17 +5113,20 @@ function addressMapType(mapType: (t: string) => string, alias: string): (t: stri
 // type alone.
 function parameterType(
   p: ApiParameter,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
 ): string {
   const concrete = p.types.filter((t) => t !== "nil");
+  // The caller supplies a parameter, so a string-keyed table in it also takes an
+  // object literal.
+  const inputMapType = (token: string): string => mapType(token, "input");
   // The table is keyed by the *raw* ref-doc parameter name, not the emitted
   // `safeParamName` fallback.
   const alias = SCENE_ADDRESS_ALIASES[classifyUrlParameter(urlParameters, elementName, p.name)];
-  const slotMapType = alias === undefined ? mapType : addressMapType(mapType, alias);
+  const slotMapType = alias === undefined ? inputMapType : addressMapType(inputMapType, alias);
   const mapped =
     concrete.length > 0
       ? mapSlotUnion(
@@ -3507,7 +5142,55 @@ function parameterType(
         )
       : "unknown";
   const correction = PARAM_TYPE_CORRECTIONS.get(tableSlotKey(elementName, "param", p.name));
-  return correction === undefined ? mapped : `${mapped} | ${correction.adds}`;
+  if (correction === undefined || !pinMatches(p.types, correctionPins(correction))) return mapped;
+  const kept =
+    correction.removes === undefined ? mapped : withoutUnionMembers(mapped, correction.removes);
+  if (correction.adds === undefined) return kept;
+  if (kept === "") return correction.adds;
+  const present = new Set(unionMembers(kept));
+  const added = unionMembers(correction.adds).filter((member) => !present.has(member));
+  return added.length === 0 ? kept : `${kept} | ${added.join(" | ")}`;
+}
+
+function isFunctionTypeText(ts: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < ts.length - 1; i++) {
+    const c = ts[i];
+    if (c === "(" || c === "[" || c === "{" || c === "<") depth++;
+    else if (c === ")" || c === "]" || c === "}" || (c === ">" && ts[i - 1] !== "=")) depth--;
+    else if (c === "=" && ts[i + 1] === ">" && depth === 0) return true;
+  }
+  return false;
+}
+
+// The top-level members of a rendered union, leaving nested unions inside
+// brackets, braces or generics whole.
+function unionMembers(union: string): string[] {
+  const members: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < union.length; i++) {
+    const c = union[i];
+    if (c === "(" || c === "[" || c === "{" || c === "<") depth++;
+    else if (c === ")" || c === "]" || c === "}" || (c === ">" && union[i - 1] !== "=")) depth--;
+    else if (c === "|" && depth === 0) {
+      members.push(union.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  members.push(union.slice(start).trim());
+  return members;
+}
+
+// Drops whole top-level members from a rendered union. Called only once the
+// slot's pin matched, so a removal that finds nothing is a real defect.
+function withoutUnionMembers(union: string, removed: readonly string[]): string {
+  const members = unionMembers(union);
+  const kept = members.filter((member) => !removed.includes(member));
+  if (kept.length === members.length) {
+    throw new Error(`withoutUnionMembers: none of ${removed.join(", ")} is a member of ${union}`);
+  }
+  return kept.join(" | ");
 }
 
 const VARARG_PREFIX = "...";
@@ -3536,7 +5219,7 @@ function emittedParamName(p: ApiParameter, index: number): string {
 function emitRestParameter(
   params: readonly ApiParameter[],
   varargIndex: number,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
@@ -3570,25 +5253,29 @@ function emitParameter(
   p: ApiParameter,
   index: number,
   optional: boolean,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
-): { text: string; ts: string } {
+): { text: string; type: string; optional: boolean } {
   const name = safeParamName(p.name, index);
   const ts = parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters);
   // An interior doc-optional param (a required param follows, so the trailing-`?`
   // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
   // `?` form; required params are untouched.
-  const interiorOptional = !optional && isDocOptional(p, elementName) ? " | undefined" : "";
-  return { text: `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`, ts };
+  const nilRequired = requiredSlotCorrection(p, elementName)?.nil === true;
+  const interiorOptional = !optional && (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" : ""}`;
+  return { text: `${name}${optional ? "?" : ""}: ${type}`, type, optional };
 }
 
 function emitReturn(
   returnValues: ApiParameter[],
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
@@ -3610,19 +5297,23 @@ function emitReturn(
       position: index,
       name: rv.name,
       ts:
-        rv.types.length > 0
-          ? mapSlotUnion(
-              rv.types,
-              rv.doc,
-              mapType,
-              false,
-              resolver,
-              constantTokens,
-              elementName,
-              "return",
-              rv.name,
-            )
-          : "unknown",
+        correction?.slot !== undefined &&
+        correction.slot === rv.name &&
+        pinMatches(rv.types, correctionPins(correction))
+          ? correction.ts
+          : rv.types.length > 0
+            ? mapSlotUnion(
+                rv.types,
+                rv.doc,
+                mapType,
+                false,
+                resolver,
+                constantTokens,
+                elementName,
+                "return",
+                rv.name,
+              )
+            : "unknown",
     }));
     return {
       type: `LuaMultiReturn<[${emitted.map((slot) => slot.ts).join(", ")}]>`,
@@ -3632,7 +5323,11 @@ function emitReturn(
   }
   const first = returnValues[0];
   if (!first) return { type: "void", trailing: "", slots: [] };
-  if (correction !== undefined) {
+  if (
+    correction !== undefined &&
+    correction.slot === undefined &&
+    pinMatches(first.types, correctionPins(correction))
+  ) {
     return {
       type: correction.ts,
       trailing: "",
@@ -3653,12 +5348,22 @@ function emitReturn(
           first.name,
         )
       : "unknown";
+  // A LuaLS vararg return (`...`) is every value the call returns, however many.
+  if (first.name === "...") {
+    const type = `LuaMultiReturn<${needsArrayParens(ts) ? `(${ts})` : ts}[]>`;
+    return { type, trailing: "", slots: [{ position: 0, name: first.name, ts }] };
+  }
   return { type: ts, trailing: "", slots: [{ position: 0, name: first.name, ts }] };
 }
 
+// The mark upstream opens a property's description with when the engine refuses
+// to write it: `go.set` raises "Unable to set the property ... since it is read
+// only".
+const READ_ONLY_MARK = /^\s*<span class="mark">READ ONLY<\/span>/;
+
 function emitPropertyMembers(
   p: ApiProperty,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   namespace: string,
 ): readonly string[] {
   const keyRange = PROPERTY_KEY_RANGES.get(`${namespace}.${p.name}`);
@@ -3671,12 +5376,13 @@ function emitPropertyMembers(
   }
   const correction = PROPERTY_TYPE_CORRECTIONS.get(`${namespace}.${p.name}`);
   const ts =
-    correction !== undefined
+    correction !== undefined && pinMatches(p.types, propertyCorrectionPins(correction))
       ? correction.ts
       : p.types.length > 0
         ? unionFromTokens(p.types, mapType)
         : "unknown";
-  return keys.map((key) => `${key}: ${ts};`);
+  const modifier = READ_ONLY_MARK.test(p.description) ? "readonly " : "";
+  return keys.map((key) => `${modifier}${key}: ${ts};`);
 }
 
 // Like `unionFromTokens`, but a `table` token whose slot doc carries a parseable
@@ -3689,7 +5395,7 @@ function emitPropertyMembers(
 function mapSlotUnion(
   types: readonly string[],
   doc: string,
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   optionalFields: boolean,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
@@ -3713,11 +5419,12 @@ function mapSlotUnion(
       }
     }
     let ts: string;
-    if (token === "table") {
-      const curation =
-        slotKind !== undefined && slotName !== undefined
-          ? TABLE_SLOT_CURATIONS.get(tableSlotKey(elementName, slotKind, slotName))
-          : undefined;
+    const slotCuration =
+      slotKind !== undefined && slotName !== undefined
+        ? TABLE_SLOT_CURATIONS.get(tableSlotKey(elementName, slotKind, slotName))
+        : undefined;
+    if (token === "table" || slotCuration?.retypedUpstream?.includes(token) === true) {
+      const curation = slotCuration;
       const mapping =
         curation?.kind === "mapping" ? curation : MAPPING_TABLE_SLOTS.get(elementName);
       const element =
@@ -3758,8 +5465,16 @@ function mapSlotUnion(
         }
       } else if (element !== undefined) {
         ts = arrayTypeFromTokens(element, mapType);
+      } else if (curation?.kind === "verbatim") {
+        ts = curation.ts;
       } else if (curation?.kind === "object" || curation?.kind === "array-object") {
-        const object = inlineTableType(curation.fields, mapType, optionalFields);
+        const fields = applyRequiredFieldCorrections(
+          elementName,
+          slotKind,
+          slotName,
+          curation.fields,
+        );
+        const object = inlineTableType(fields, mapType, optionalFields);
         ts = curation.kind === "array-object" ? `${object}[]` : object;
       } else if (curation?.kind === "keyed-object") {
         // The doc's `<dl>` describes the value shape; parse it and re-key by an
@@ -3785,7 +5500,13 @@ function mapSlotUnion(
           const added = applyFieldAdditions(elementName, slotKind, slotName, parsed);
           const nested = applyNestedFieldCurations(elementName, slotKind, slotName, added);
           const typed = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
-          const fields = applyFieldOptionalityCorrections(elementName, slotKind, slotName, typed);
+          const required = applyRequiredFieldCorrections(
+            elementName,
+            slotKind,
+            slotName,
+            applyFieldOptionalityCorrections(elementName, slotKind, slotName, typed),
+          );
+          const fields = applyListFieldCorrections(elementName, slotKind, slotName, required);
           const object = inlineTableType(fields, mapType, optionalFields);
           ts = isSlotLevelList(doc) ? `${object}[]` : object;
         } else {
@@ -3840,18 +5561,21 @@ export function applyNestedFieldCurations(
 ): TableField[] {
   if (slotKind === undefined || slotName === undefined) return [...fields];
   return fields.map((field) => {
-    if (field.fields !== undefined) return field;
     const curated = NESTED_FIELD_CURATIONS.get(
       nestedFieldKey(elementName, slotKind, slotName, field.name),
     );
     if (curated === undefined) return field;
-    return { ...field, fields: [...curated], isList: true };
+    // A parsed member list keeps its members; the curation supplies the ones
+    // upstream flattened to the slot's top level.
+    const parsed = field.fields ?? [];
+    const missing = curated.filter((member) => !parsed.some((p) => p.name === member.name));
+    return { ...field, fields: [...parsed, ...missing], isList: true };
   });
 }
 
 function arrayTypeFromTokens(
   element: string | readonly string[],
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
 ): string {
   const tokens = typeof element === "string" ? [element] : element;
   return tokens.length > 1
@@ -3861,7 +5585,7 @@ function arrayTypeFromTokens(
 
 export function inlineTableType(
   fields: readonly TableField[],
-  mapType: (t: string) => string,
+  mapType: DefoldTypeMapper,
   optionalFields: boolean,
 ): string {
   const members = fields.map((field) => {
@@ -3879,7 +5603,7 @@ export function inlineTableType(
       field.tsType !== undefined
         ? field.tsType
         : field.fields !== undefined
-          ? `${inlineTableType(field.fields, mapType, optionalFields)}${field.isList ? "[]" : ""}`
+          ? nestedFieldType(field, inlineTableType(field.fields, mapType, optionalFields))
           : field.numberList === true
             ? "number[]"
             : field.types.length > 0
@@ -3888,12 +5612,21 @@ export function inlineTableType(
     // A field is optional when the whole slot is param-side (optionalFields) or
     // when the curation marks that individual field optional (a return-side
     // variant field present only for some shape kinds, e.g. a b2d shape table).
-    return `${key}${optionalFields || field.optional === true ? "?" : ""}: ${ts}`;
+    // A param-side field the engine requires stays required.
+    const optional = (optionalFields && field.required !== true) || field.optional === true;
+    return `${key}${optional ? "?" : ""}: ${ts}`;
   });
   return `{ ${members.join("; ")} }`;
 }
 
-function unionFromTokens(tokens: readonly string[], mapType: (t: string) => string): string {
+function nestedFieldType(field: TableField, object: string): string {
+  const element = field.alternatives === undefined ? object : `${object} & (${field.alternatives})`;
+  if (field.isList !== true) return element;
+  const rest = field.alternatives === undefined ? element : `(${element})`;
+  return field.nonEmpty === true ? `[${element}, ...${rest}[]]` : `${rest}[]`;
+}
+
+function unionFromTokens(tokens: readonly string[], mapType: DefoldTypeMapper): string {
   const mapped: string[] = [];
   const seen = new Set<string>();
   for (const token of tokens) {
@@ -3905,7 +5638,7 @@ function unionFromTokens(tokens: readonly string[], mapType: (t: string) => stri
   return joinUnionArms(mapped);
 }
 
-const BRAND_ARM = /^number & \{ readonly __brand: "([^"]+)" \}$/;
+const BRAND_ARM = /^(?:number|string) & \{ readonly __brand: "([^"]+)" \}$/;
 
 // 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
@@ -3934,20 +5667,70 @@ function joinUnionArms(mapped: readonly string[]): string {
   return out.join(" | ");
 }
 
-export function isKnownDefoldTypeToken(token: string): boolean {
-  return (
-    token === "nil" ||
-    Object.hasOwn(DEFOLD_TYPE_MAP, token) ||
-    recoverCallbackSignature(token) !== null
-  );
+const BUILTIN_MESSAGE_NAMES: ReadonlySet<string> = new Set(
+  messagesDoc.messages.map((message) => message.name),
+);
+const MESSAGE_REFERENCE = /^message\.[a-z_]+\.([a-z_]+)$/;
+
+// The leaf vocabulary the LuaLS grammar resolves an engine type expression
+// against. `message.<ns>.<name>` names a documented message payload, typed only
+// when `<name>` is one `BuiltinMessages` declares.
+function resolveDefoldLeaf(leaf: string): string | undefined {
+  if (leaf === "nil") return "undefined";
+  if (Object.hasOwn(DEFOLD_TYPE_MAP, leaf)) return DEFOLD_TYPE_MAP[leaf];
+  const message = MESSAGE_REFERENCE.exec(leaf);
+  const name = message?.[1];
+  if (name !== undefined && BUILTIN_MESSAGE_NAMES.has(name)) return `BuiltinMessages["${name}"]`;
+  return undefined;
 }
 
-export function defaultMapType(token: string): string {
+// Whole-token lookup and callback recovery run first, so the grammar sees only
+// what they miss; every pre-1.13.2 token resolves before it is reached.
+function wholeTokenMapping(token: string): string | undefined {
   if (Object.hasOwn(DEFOLD_TYPE_MAP, token)) {
     const mapped = DEFOLD_TYPE_MAP[token];
     if (typeof mapped === "string") return mapped;
   }
-  const callback = recoverCallbackSignature(token);
-  if (callback !== null) return callback;
-  return "unknown";
+  return recoverCallbackSignature(token) ?? undefined;
+}
+
+/** The leaves of `token` that resolve to nothing; empty when the whole token maps. */
+export function unknownDefoldTypeLeaves(token: string): string[] {
+  if (token === "nil" || wholeTokenMapping(token) !== undefined) return [];
+  if (token.trim() === "") return [token];
+  return mapLualsExpression(token, resolveDefoldLeaf).unknowns;
+}
+
+export function isKnownDefoldTypeToken(token: string): boolean {
+  return unknownDefoldTypeLeaves(token).length === 0;
+}
+
+export function defaultMapType(token: string, position?: LualsPosition): string {
+  return wholeTokenMapping(token) ?? mapLualsExpression(token, resolveDefoldLeaf, position).ts;
+}
+
+/**
+ * The engine mapper extended with `leaves`, resolved ahead of the engine
+ * vocabulary, and `declared` (Lua name -> TS path), consulted after it. A whole
+ * token checks `leaves`, the engine's whole-token mapping, then `declared`; a
+ * leaf inside a composite checks `leaves`, the engine leaves, then `declared`.
+ * So a surface's handle brand (`editor.message`) outranks any declared path.
+ */
+export function mapTypeWithVocabulary(vocabulary: {
+  leaves?: Readonly<Record<string, string>> | undefined;
+  declared?: ReadonlyMap<string, string> | undefined;
+}): DefoldTypeMapper {
+  const leaves = vocabulary.leaves ?? {};
+  const declared = vocabulary.declared ?? new Map<string, string>();
+  if (Object.keys(leaves).length === 0 && declared.size === 0) return defaultMapType;
+  const resolveLeaf = (leaf: string): string | undefined =>
+    Object.hasOwn(leaves, leaf) ? leaves[leaf] : (resolveDefoldLeaf(leaf) ?? declared.get(leaf));
+  return (token, position) => {
+    if (Object.hasOwn(leaves, token)) return leaves[token] as string;
+    return (
+      wholeTokenMapping(token) ??
+      declared.get(token) ??
+      mapLualsExpression(token, resolveLeaf, position).ts
+    );
+  };
 }