@defold-typescript/types 0.35.0 → 0.37.0

package/src/emit-dts.ts

@@ -222,7 +222,9 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
 // is the TSTL non-string-key Lua-table idiom and resolves the same way the
 // already-emitted `LuaMultiReturn` does. The audit consults this map too, so the
 // gate and the emitted surface stay coupled; a slot not curated here still
-// surfaces under `recordTables` until a human adds it.
+// surfaces under `recordTables` until a human adds it. Key and value are both
+// `A | B` union tokens split per token, so a key whose doc names constants
+// brands each of them rather than widening to `number`.
 export const MAPPING_TABLE_SLOTS: ReadonlyMap<string, { key: string; value: string }> = new Map([
   ["gui.clone_tree", { key: "hash", value: "node" }],
   ["gui.get_tree", { key: "hash", value: "node" }],
@@ -243,6 +245,32 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["editor.tx.add", 'Opaque<"transaction_step">'],
 ]);
 
+// A function whose `returnvalues` declare a concrete type while the same slot's
+// prose documents a `nil` alternative. Distinct from RETURN_TYPE_OVERRIDES
+// above, which fills an *empty* `returnvalues`: these contradict a token
+// upstream explicitly declares, so each entry records it and
+// `return-correction-provenance.test.ts` pins it against every vendored
+// ref-doc. Upstream adding `nil` to `types` hands the case to the top-level
+// `nil` projection in `mapSlotUnion` and reds the entry, which is then deleted
+// rather than re-pinned.
+export interface ReturnTypeCorrection {
+  readonly ts: string;
+  readonly upstream: readonly string[];
+  readonly reason: string;
+}
+
+// Keyed by FQN, mirroring PROPERTY_TYPE_CORRECTIONS.
+export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection> = new Map([
+  [
+    "b2d.get_body",
+    {
+      ts: 'Opaque<"b2Body"> | undefined',
+      upstream: ["b2Body"],
+      reason: "the body if successful. Otherwise nil.",
+    },
+  ],
+]);
+
 // 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
@@ -408,6 +436,18 @@ export function documentedConstantTokens(text: string, universe: ReadonlySet<str
   return [...out];
 }
 
+// The constants a `table` slot's doc names as the table's *keys*, as opposed to
+// the far commoner shape where a field's *value* is a constant
+// (`physics.get_shape`'s `type`, `resource.create_texture`'s `format`). Upstream
+// marks the difference in prose — render.clear reads "table with keys specifying
+// which buffers to clear ... Available keys are:" — so a key mention alongside a
+// named constant is the discriminator. Empty means the slot has no documented
+// constant keys, which is true of every `table` slot but one today.
+export function documentedConstantKeyTokens(doc: string, universe: ReadonlySet<string>): string[] {
+  if (!/\bkeys?\b/i.test(doc.replace(/<[^>]*>/g, ""))) return [];
+  return documentedConstantTokens(doc, universe);
+}
+
 type SlotDocLookup = (slotKey: string) => string | undefined;
 
 function constantSlotTokens(
@@ -805,6 +845,38 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
       ],
     },
   ],
+  // resource.get_render_target_info's return `<dl>` writes one key as
+  // `<dt>'attachments'</dt>` — quoted rather than wrapped in `<code>` — so
+  // TABLE_FIELD drops it and parseTableFields hoists the seven per-attachment
+  // fields to the top level, contradicting the `info.attachments[0].handle`
+  // access in the doc's own `@example`. Same shape and same remedy as
+  // font.get_info:return:info above: replace the mis-parsed field list with the
+  // faithful nested isList object. `texture` is documented "only available if
+  // the render target passed in is a resource", hence optional.
+  [
+    "resource.get_render_target_info:return:table",
+    {
+      kind: "object",
+      fields: [
+        { name: "handle", types: ["number"] },
+        {
+          name: "attachments",
+          types: ["table"],
+          isList: true,
+          fields: [
+            { name: "handle", types: ["number"] },
+            { name: "width", types: ["number"] },
+            { name: "height", types: ["number"] },
+            { name: "depth", types: ["number"] },
+            { name: "mipmaps", types: ["number"] },
+            { name: "type", types: ["number"] },
+            { name: "buffer_type", types: ["number"] },
+            { name: "texture", types: ["hash"], optional: true },
+          ],
+        },
+      ],
+    },
+  ],
   // profiler.view_recorded_frame's `frame_index` is a typed `<ul>` "specify one
   // of the following": `distance` and `frame`, both numeric frame offsets. The
   // <li> items carry no `<span class="type">`, so parseTableFields recovers
@@ -830,11 +902,20 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // 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"] }],
-  // render.clear's `buffers` maps the numeric graphics.BUFFER_* constants to
-  // their clear value: vector4 for the color buffer, number for depth/stencil.
-  // The mapping value is the `number | vector4` union; the mapping string branch
-  // splits the union token, so the value emits `number | Vector4`.
-  ["render.clear:param:buffers", { kind: "mapping", key: "number", value: "number | vector4" }],
+  // render.clear's `buffers` maps the graphics.BUFFER_TYPE_* constants its doc
+  // names as keys to their clear value: vector4 for the color buffer, number for
+  // depth/stencil. Both sides are union tokens the mapping string branch splits,
+  // so the key emits the three branded constants and the value `number | Vector4`.
+  // The key is branded rather than `number`, which is the narrowing users migrate
+  // to via the authored `render.ClearBufferKey` alias.
+  [
+    "render.clear:param:buffers",
+    {
+      kind: "mapping",
+      key: "graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT",
+      value: "number | vector4",
+    },
+  ],
   // go.on_input and gui.on_input share the same well-known InputAction shape
   // (the on_input function description lists the well-known fields: value,
   // pressed, released, repeated, x/y/screen_x/screen_y/dx/dy/screen_dx/screen_dy,
@@ -1346,6 +1427,95 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["material.get_vertex_attributes:return:table:value", ATTRIBUTE_VALUE_TS],
 ]);
 
+// A return-slot field upstream documents as platform-gated or nil-valued while
+// declaring it like any other. Lua removes a key assigned `nil`, so "might be
+// nil if not available" and "only available on iOS and Android" describe the
+// same runtime state — the key is absent — and the correction is always `?`,
+// never a required field widened to `| undefined`.
+//
+// Separate from TABLE_FIELD_TYPE_OVERRIDES because presence is the other axis:
+// the parser reads these fields' types correctly and stays authoritative for
+// them, so an entry here restates no type and cannot drift when upstream
+// retypes a field. `upstream` is pinned rather than consumed, and `evidence` is
+// the decoded prose `return-correction-provenance.test.ts` searches the slot doc
+// for; both red the entry once upstream marks the field or drops the gate.
+//
+// Keyed `<element>:<kind>:<slot>:<field>`, the TABLE_FIELD_TYPE_OVERRIDES shape.
+export interface ReturnFieldOptionalityCorrection {
+  readonly upstream: readonly string[];
+  readonly evidence: string;
+}
+
+// The platform-gate markers upstream renders as `<span class="icon-*">` decode
+// to `[ios]`, `[android]`, `[html5]` — `user_agent` states its gate through the
+// marker alone, with no availability sentence to pin.
+export const RETURN_FIELD_OPTIONALITY_CORRECTIONS: ReadonlyMap<
+  string,
+  ReturnFieldOptionalityCorrection
+> = new Map([
+  [
+    "sys.get_sys_info:return:sys_info:device_model",
+    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:manufacturer",
+    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:device_ident",
+    {
+      upstream: ["string"],
+      evidence: '[ios] "identifierForVendor" on iOS. [android] "android_id" on Android.',
+    },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:user_agent",
+    { upstream: ["string"], evidence: "[html5] The HTTP user agent" },
+  ],
+  [
+    "sys.get_ifaddrs:return:ifaddrs:address",
+    { upstream: ["string"], evidence: "might be nil if not available." },
+  ],
+  [
+    "sys.get_ifaddrs:return:ifaddrs:mac",
+    { upstream: ["string"], evidence: "might be nil if not available." },
+  ],
+]);
+
+// Mark a parser-recovered field optional from RETURN_FIELD_OPTIONALITY_CORRECTIONS,
+// leaving every other field — and every field's type — untouched. Sets the
+// `optional` flag `TableField` already carries and `inlineTableType` already
+// reads, so no `mapType` is needed and no correction can change a type.
+//
+// A correction keyed to this slot that matches no recovered field throws rather
+// than no-opping: a field upstream renamed would otherwise leave a stale entry
+// looking applied while the emitted declaration silently re-widened.
+// Returns a new array; never mutates the parser's result.
+export function applyFieldOptionalityCorrections(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind === undefined || slotName === undefined) return [...fields];
+  const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
+  const corrected = fields.map((field) =>
+    RETURN_FIELD_OPTIONALITY_CORRECTIONS.has(`${prefix}${field.name}`)
+      ? { ...field, optional: true }
+      : field,
+  );
+  const recovered = new Set(fields.map((field) => field.name));
+  const stale = [...RETURN_FIELD_OPTIONALITY_CORRECTIONS.keys()].filter(
+    (key) => key.startsWith(prefix) && !recovered.has(key.slice(prefix.length)),
+  );
+  if (stale.length > 0) {
+    throw new Error(
+      `field-optionality correction names no recovered field: ${stale.sort().join(", ")}`,
+    );
+  }
+  return corrected;
+}
+
 // Pin a parser-recovered field's TS type from TABLE_FIELD_TYPE_OVERRIDES,
 // leaving every other field parser-authoritative. A field the override does not
 // name is returned unchanged; a field it names gains a `tsType` (emitted
@@ -1582,7 +1752,11 @@ export function buildTableDocResolver(sources: readonly TableDocSource[]): Table
   return (elementName) => docByName.get(elementName);
 }
 
-export function parseTableFields(doc: string, resolver?: TableDocResolver): TableField[] | null {
+export function parseTableFields(
+  doc: string,
+  resolver?: TableDocResolver,
+  slotName?: string,
+): TableField[] | null {
   const fields: TableField[] = [];
   for (const match of doc.matchAll(TABLE_FIELD)) {
     const name = (match[1] ?? "").trim();
@@ -1601,14 +1775,20 @@ export function parseTableFields(doc: string, resolver?: TableDocResolver): Tabl
   }
   // Nested recovery, scoped to the one unambiguous shape: a `<dl>` declaring a
   // single `table`-typed field whose keys sit in an immediately-following
-  // top-level `<ul>` typed-field list (`window.get_safe_area`). Attach the
-  // `<ul>` fields as that field's nested shape so the slot recovers as a nested
-  // object instead of a `Record`.
+  // top-level `<ul>` typed-field list. Attach the `<ul>` fields as that field's
+  // nested shape so the slot recovers as a nested object instead of a `Record`.
+  //
+  // Unless the header restates the slot it describes (`window.get_safe_area`'s
+  // `safe_area` return documented under a `safe_area` header): that is a
+  // restatement, not a nesting level, and wrapping it emits a level the engine
+  // never returns. Only a caller that knows the slot name can tell the two
+  // apart, so the `<ul>` keys are returned directly when they match.
   if (fields.length === 1) {
     const only = fields[0];
     if (only && only.types.length === 1 && only.types[0] === "table") {
       const nested = parseUlFields(doc);
       if (nested.length > 0) {
+        if (slotName !== undefined && slotName === only.name) return nested;
         only.fields = nested;
         return [only];
       }
@@ -1883,10 +2063,25 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * 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.
+ */
+export type SlotTypes = Readonly<Record<string, string>>;
+
+function slotKey(kind: "param" | "return", position: number, name: string): string {
+  return `${kind}:${position}:${name}`;
+}
+
 /** One emitted symbol's identity paired with its rendered TS signature text. */
 export interface SymbolSignature {
   readonly identity: ApiSymbolIdentity;
   readonly tsSignature: string;
+  readonly slotTypes: SlotTypes;
 }
 
 /**
@@ -1931,9 +2126,14 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   });
   const emitName = (name: string): string => (TS_RESERVED_NAMES.has(name) ? `_${name}` : name);
 
+  // A member with no call list (constant, variable, property, typedef) documents
+  // no slot, so it reports an empty map rather than being absent from the ledger.
+  const NO_SLOTS: SlotTypes = {};
+
   for (const fn of module.functions) {
     const prepared = prepareFunction(fn, prefix);
     if (prepared === null) continue;
+    const slotTypes: Record<string, string> = {};
     out.push({
       identity: fnIdentity(fn),
       tsSignature: emitFunction(
@@ -1943,7 +2143,9 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
         resolver,
         constantTokens,
         urlParameters,
+        slotTypes,
       ),
+      slotTypes,
     });
   }
 
@@ -1957,9 +2159,11 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
         signature: "",
       },
       tsSignature: emitVariable(v, emitName(v.name), mapType),
+      slotTypes: NO_SLOTS,
     });
   }
   for (const fn of nested.functions) {
+    const slotTypes: Record<string, string> = {};
     out.push({
       identity: fnIdentity(fn.original),
       tsSignature: emitFunction(
@@ -1969,16 +2173,27 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
         resolver,
         constantTokens,
         urlParameters,
+        slotTypes,
       ),
+      slotTypes,
     });
   }
 
   const handleGroups = collectHandleMethodGroups(module);
   for (const group of handleGroups.values()) {
     for (const prepared of group) {
+      const slotTypes: Record<string, string> = {};
       out.push({
         identity: fnIdentity(prepared.original),
-        tsSignature: emitMethod(prepared, mapType, resolver, constantTokens, urlParameters),
+        tsSignature: emitMethod(
+          prepared,
+          mapType,
+          resolver,
+          constantTokens,
+          urlParameters,
+          slotTypes,
+        ),
+        slotTypes,
       });
     }
   }
@@ -1989,6 +2204,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     out.push({
       identity: { namespace: module.namespace, kind: "CONSTANT", name: c.name, signature: "" },
       tsSignature: `const ${prepared.name}: ${brandType(prepared.fqn)};`,
+      slotTypes: NO_SLOTS,
     });
   }
 
@@ -1998,6 +2214,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     out.push({
       identity: { namespace: module.namespace, kind: "VARIABLE", name: v.name, signature: "" },
       tsSignature: emitVariable(prepared, emitName(prepared.name), mapType),
+      slotTypes: NO_SLOTS,
     });
   }
 
@@ -2005,6 +2222,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     out.push({
       identity: { namespace: module.namespace, kind: "PROPERTY", name: p.name, signature: "" },
       tsSignature: emitPropertyMember(p, mapType, module.namespace),
+      slotTypes: NO_SLOTS,
     });
   }
 
@@ -2013,6 +2231,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     out.push({
       identity: { namespace: module.namespace, kind: "TYPEDEF", name: t.name, signature: "" },
       tsSignature: `type ${t.name} = Opaque<"${t.name}">;`,
+      slotTypes: NO_SLOTS,
     });
   }
 
@@ -2208,6 +2427,7 @@ function memberSignature(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
@@ -2216,22 +2436,19 @@ function memberSignature(
   const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
     emitParameter(p, i, i >= cutoff, mapType, resolver, constantTokens, elementName, urlParameters),
   );
-  const params = (
+  const rest =
     varargIndex === -1
-      ? positional
-      : [
-          ...positional,
-          emitRestParameter(
-            original,
-            varargIndex,
-            mapType,
-            resolver,
-            constantTokens,
-            elementName,
-            urlParameters,
-          ),
-        ]
-  ).join(", ");
+      ? null
+      : emitRestParameter(
+          original,
+          varargIndex,
+          mapType,
+          resolver,
+          constantTokens,
+          elementName,
+          urlParameters,
+        );
+  const params = [...positional.map((p) => p.text), ...(rest ? [rest.text] : [])].join(", ");
   const ret = emitReturn(
     prepared.original.returnValues,
     mapType,
@@ -2241,12 +2458,28 @@ function memberSignature(
   );
   const predicateToken = TYPE_PREDICATES.get(elementName);
   const soleParam = original[0];
-  if (
+  const isPredicate =
     predicateToken !== undefined &&
     soleParam !== undefined &&
     original.length === 1 &&
-    ret.type === "boolean"
-  ) {
+    ret.type === "boolean";
+  if (slotSink !== undefined) {
+    for (const [i, p] of positional.entries()) {
+      const raw = original[i];
+      if (raw) slotSink[slotKey("param", i, raw.name)] = p.ts;
+    }
+    for (const slot of rest?.slots ?? []) {
+      slotSink[slotKey("param", slot.position, slot.name)] = slot.ts;
+    }
+    // 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;
+      }
+    }
+  }
+  if (isPredicate && soleParam !== undefined && predicateToken !== undefined) {
     return `${name}(${params}): ${safeParamName(soleParam.name, 0)} is ${mapType(predicateToken)};`;
   }
   return `${name}(${params}): ${ret.type};${ret.trailing}`;
@@ -2259,8 +2492,9 @@ function emitFunction(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
-  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters)}`;
+  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters, slotSink)}`;
 }
 
 // A colon-method member of a handle interface: identical signature machinery to a
@@ -2272,8 +2506,17 @@ function emitMethod(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
-  return memberSignature(prepared, prepared.name, mapType, resolver, constantTokens, urlParameters);
+  return memberSignature(
+    prepared,
+    prepared.name,
+    mapType,
+    resolver,
+    constantTokens,
+    urlParameters,
+    slotSink,
+  );
 }
 
 // Build the indented JSDoc lines for a function from its ref-doc prose. The
@@ -2444,21 +2687,29 @@ function emitRestParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
-): string {
+): { text: string; slots: EmittedSlot[] } {
   const vararg = params[varargIndex];
-  if (vararg === undefined) return "";
-  const members = [
-    ...new Set(
-      params
-        .slice(varargIndex)
-        .map((p) =>
-          parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
-        ),
-    ),
-  ];
+  if (vararg === undefined) return { text: "", slots: [] };
+  const folded = params.slice(varargIndex).map((p, offset) => ({
+    position: varargIndex + offset,
+    name: p.name,
+    ts: parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
+  }));
+  const members = [...new Set(folded.map((slot) => slot.ts))];
   const first = members[0] ?? "unknown";
   const element = members.length > 1 ? `(${members.join(" | ")})` : first;
-  return `...${varargParamName(vararg.name, varargIndex)}: ${element}[]`;
+  return {
+    text: `...${varargParamName(vararg.name, varargIndex)}: ${element}[]`,
+    slots: folded,
+  };
+}
+
+// A slot's rendered type paired with the position and raw ref-doc name that
+// identify it, so the signature text and the per-slot map come out of one call.
+interface EmittedSlot {
+  readonly position: number;
+  readonly name: string;
+  readonly ts: string;
 }
 
 function emitParameter(
@@ -2470,7 +2721,7 @@ function emitParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
-): string {
+): { text: string; ts: string } {
   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-`?`
@@ -2478,7 +2729,7 @@ function emitParameter(
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
   // `?` form; required params are untouched.
   const interiorOptional = !optional && isDocOptional(p, elementName) ? " | undefined" : "";
-  return `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`;
+  return { text: `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`, ts };
 }
 
 function emitReturn(
@@ -2487,33 +2738,53 @@ function emitReturn(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
-): { type: string; trailing: string } {
+): { type: string; trailing: string; slots: EmittedSlot[] } {
+  // An authored whole-return override is not a per-slot render, so it reports no
+  // slots and leaves the consumer on its token-derived fallback.
   const override = RETURN_TYPE_OVERRIDES.get(elementName);
-  if (override !== undefined) return { type: override, trailing: "" };
-  if (returnValues.length === 0) return { type: "void", trailing: "" };
+  if (override !== undefined) return { type: override, trailing: "", slots: [] };
+  // Kept beside the override lookup so the two stay visibly distinct: this one
+  // contradicts a declared token rather than filling an empty `returnvalues`,
+  // and it is a per-slot render, so it reports its slot.
+  const correction = RETURN_TYPE_CORRECTIONS.get(elementName);
+  if (returnValues.length === 0) return { type: "void", trailing: "", slots: [] };
   if (returnValues.length > 1) {
     // Defold multi-returns are positional and always present; each slot maps
     // straight through (unknown when the doc lists no type) into a tuple that
     // typescript-to-lua erases to `local a, b = fn()`.
-    const slots = returnValues.map((rv) =>
-      rv.types.length > 0
-        ? mapSlotUnion(
-            rv.types,
-            rv.doc,
-            mapType,
-            false,
-            resolver,
-            constantTokens,
-            elementName,
-            "return",
-            rv.name,
-          )
-        : "unknown",
-    );
-    return { type: `LuaMultiReturn<[${slots.join(", ")}]>`, trailing: "" };
+    const emitted = returnValues.map((rv, index) => ({
+      position: index,
+      name: rv.name,
+      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(", ")}]>`,
+      trailing: "",
+      slots: emitted,
+    };
   }
   const first = returnValues[0];
-  if (!first) return { type: "void", trailing: "" };
+  if (!first) return { type: "void", trailing: "", slots: [] };
+  if (correction !== undefined) {
+    return {
+      type: correction.ts,
+      trailing: "",
+      slots: [{ position: 0, name: first.name, ts: correction.ts }],
+    };
+  }
   const ts =
     first.types.length > 0
       ? mapSlotUnion(
@@ -2528,7 +2799,7 @@ function emitReturn(
           first.name,
         )
       : "unknown";
-  return { type: ts, trailing: "" };
+  return { type: ts, trailing: "", slots: [{ position: 0, name: first.name, ts }] };
 }
 
 function emitPropertyMember(
@@ -2606,7 +2877,14 @@ function mapSlotUnion(
           const nested = mapping.value as NestedMapping;
           value = `LuaMap<${mapType(nested.key)}, ${mapType(nested.value)}>`;
         }
-        ts = `LuaMap<${mapType(mapping.key)}, ${value}>`;
+        // A mapping key may be a `A | B` union token too (render.clear's three
+        // documented graphics.BUFFER_TYPE_* constants); split it the same way
+        // the value above is split. A single-token key (no `|`) is unaffected.
+        const key = unionFromTokens(
+          mapping.key.split("|").map((token) => token.trim()),
+          mapType,
+        );
+        ts = `LuaMap<${key}, ${value}>`;
       } else if (element !== undefined) {
         ts = arrayTypeFromTokens(element, mapType);
       } else if (curation?.kind === "object" || curation?.kind === "array-object") {
@@ -2617,19 +2895,25 @@ function mapSlotUnion(
         // arbitrary name. Reusing the parser keeps the inner fields in lockstep
         // with the doc instead of a hand-listed drift-prone copy; a documented
         // array-form field is pinned via TABLE_FIELD_TYPE_OVERRIDES.
-        const parsed = applyFieldTypeOverrides(
+        const parsed = applyFieldOptionalityCorrections(
           elementName,
           slotKind,
           slotName,
-          parseTableFields(doc, resolver) ?? [],
+          applyFieldTypeOverrides(
+            elementName,
+            slotKind,
+            slotName,
+            parseTableFields(doc, resolver, slotName) ?? [],
+          ),
         );
         const object = inlineTableType(parsed, mapType, optionalFields);
         ts = `Record<string, ${object}>`;
       } else {
-        const parsed = parseTableFields(doc, resolver);
+        const parsed = parseTableFields(doc, resolver, slotName);
         if (parsed !== null) {
           const nested = applyNestedFieldCurations(elementName, slotKind, slotName, parsed);
-          const fields = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
+          const typed = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
+          const fields = applyFieldOptionalityCorrections(elementName, slotKind, slotName, typed);
           const object = inlineTableType(fields, mapType, optionalFields);
           ts = isSlotLevelList(doc) ? `${object}[]` : object;
         } else {

package/src/index.ts

@@ -49,6 +49,7 @@ export {
   type EmitOptions,
   emitDeclarations,
   emitSymbolSignatures,
+  type SlotTypes,
   type SymbolSignature,
   TS_IDENTIFIER,
   TS_RESERVED_NAMES,