@defold-typescript/types 0.34.0 → 0.36.0

package/src/emit-dts.ts

@@ -151,11 +151,10 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   "socket.dns.toip",
   "socket.dns.getaddrinfo",
   "socket.dns.getnameinfo",
-  // engine-built render-target tables: the "see the description" cross-refs
-  // are dead (the function's own description is empty) or carry a typed
+  // engine-built render-target tables: the "see the description" cross-ref is
+  // dead (the function's own description is empty) or carries a typed
   // `transient: table` field whose sub-doc is prose-only, so the nested table
   // is opaque to the field-list parser and the whole-slot `Record` is faithful.
-  "render.render_target",
   "render.set_render_target",
   // reserved-but-undocumented options bag: `collectionproxy.load`'s `options`
   // slot is documented verbatim as "options table, currently unused" and accepts
@@ -204,6 +203,10 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   // msg-overloads.d.ts supplies the typed msg.url shape (0 / 1-string / 3-arg
   // arities; the runtime-invalid two-arg form is intentionally omitted).
   "msg.url",
+  // render-overloads.d.ts supplies the name-less and named render_target arities.
+  "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 generic covariant signatures.
   "vmath.clamp",
   "vmath.lerp",
@@ -219,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" }],
@@ -351,6 +356,131 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
   ),
 ]);
 
+export type ConstantSlotResolution =
+  | { readonly borrow: string }
+  | { readonly family: string; readonly evidence: string }
+  | { readonly residual: string };
+
+// A top-level `constant` slot takes the constants its own doc names. This table
+// fills only a slot whose own doc names none: a `borrow` reads another slot's doc
+// (same key shape), a `family` expands a `<prefix>*` wildcard evidenced by the
+// named element's example, and a `residual` records why nothing can brand it.
+// Constants always come from the brand universe, never from a hand-typed list.
+export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResolution> = new Map<
+  string,
+  ConstantSlotResolution
+>([
+  ["gui.get:param:property", { borrow: "gui.animate:param:property" }],
+  ["gui.set:param:property", { borrow: "gui.animate:param:property" }],
+  ["gui.cancel_animations:param:property", { borrow: "gui.animate:param:property" }],
+  [
+    "buffer.set_metadata:param:value_type",
+    { family: "buffer.VALUE_TYPE_*", evidence: "buffer.set_metadata" },
+  ],
+  [
+    "buffer.get_metadata:return:value_type",
+    { family: "buffer.VALUE_TYPE_*", evidence: "buffer.set_metadata" },
+  ],
+  ["gui.new_texture:param:type", { residual: "the doc lists texture type strings only" }],
+  ["gui.set_texture_data:param:type", { residual: "the doc lists texture type strings only" }],
+  [
+    "iap.get_provider_id:return:provider_id",
+    { residual: "the doc names iap.PROVIDER_ID_*, which no ref-doc defines as a constant" },
+  ],
+]);
+
+const DOC_CONSTANT_TOKEN =
+  /(?<![A-Za-z0-9_.])([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*\.[A-Z][A-Z0-9_]*)(\*)?/g;
+
+// The constant FQNs a piece of ref-doc text names, in doc order: exact tokens kept
+// only when they are in `universe`, and each `<prefix>*` wildcard expanded to every
+// universe FQN with that prefix, sorted.
+export function documentedConstantTokens(text: string, universe: ReadonlySet<string>): string[] {
+  const out = new Set<string>();
+  for (const match of text.replace(/<[^>]*>/g, "").matchAll(DOC_CONSTANT_TOKEN)) {
+    const token = match[1] as string;
+    if (match[2] === undefined) {
+      if (universe.has(token)) out.add(token);
+      continue;
+    }
+    for (const fqn of [...universe].filter((candidate) => candidate.startsWith(token)).sort()) {
+      out.add(fqn);
+    }
+  }
+  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(
+  ownDoc: string,
+  slotKey: string,
+  lookupDoc: SlotDocLookup,
+  universe: ReadonlySet<string>,
+): string[] {
+  const own = documentedConstantTokens(ownDoc, universe);
+  if (own.length > 0) return own;
+  const entry = CONSTANT_SLOT_RESOLUTIONS.get(slotKey);
+  if (entry === undefined || "residual" in entry) return [];
+  if ("borrow" in entry) return documentedConstantTokens(lookupDoc(entry.borrow) ?? "", universe);
+  return documentedConstantTokens(entry.family, universe);
+}
+
+function slotDocLookup(module: ApiModule): SlotDocLookup {
+  const docs = new Map<string, string>();
+  for (const fn of module.functions) {
+    for (const p of fn.parameters) {
+      const key = tableSlotKey(fn.name, "param", p.name);
+      if (!docs.has(key)) docs.set(key, p.doc);
+    }
+    for (const rv of fn.returnValues) {
+      const key = tableSlotKey(fn.name, "return", rv.name);
+      if (!docs.has(key)) docs.set(key, rv.doc);
+    }
+  }
+  return (slotKey) => docs.get(slotKey);
+}
+
+// The constants a module's top-level `constant` slot expands into: its own doc
+// first, then its CONSTANT_SLOT_RESOLUTIONS entry. Empty means the slot keeps
+// `Opaque<"constant">`.
+export function resolveConstantSlotTokens(
+  module: ApiModule,
+  slotKey: string,
+  universe: ReadonlySet<string>,
+): string[] {
+  const lookupDoc = slotDocLookup(module);
+  return constantSlotTokens(lookupDoc(slotKey) ?? "", slotKey, lookupDoc, universe);
+}
+
+type ConstantSlotTokens = (
+  elementName: string,
+  slotKind: "param" | "return",
+  slotName: string,
+  doc: string,
+) => readonly string[];
+
+function constantSlotTokenResolver(
+  module: ApiModule,
+  universe: ReadonlySet<string>,
+): ConstantSlotTokens {
+  const lookupDoc = slotDocLookup(module);
+  return (elementName, slotKind, slotName, doc) =>
+    constantSlotTokens(doc, tableSlotKey(elementName, slotKind, slotName), lookupDoc, universe);
+}
+
 // FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
 // argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
 // Emitting these as user-defined type guards (`var_ is Vector3`) is the only way
@@ -714,11 +844,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,
@@ -1580,6 +1719,10 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     constantFqns.has(token) || knownConstantFqns?.has(token)
       ? brandType(token)
       : baseMapType(token);
+  const constantTokens = constantSlotTokenResolver(
+    module,
+    new Set([...constantFqns, ...(knownConstantFqns ?? [])]),
+  );
 
   const constants = module.constants
     .map((c) => prepareConstant(c, prefix))
@@ -1656,7 +1799,9 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
       for (const docLine of functionDocLines(fn.original, translations, handleIndent)) {
         lines.push(docLine);
       }
-      lines.push(`${handleIndent}${emitMethod(fn, mapType, resolver, urlParameters)}`);
+      lines.push(
+        `${handleIndent}${emitMethod(fn, mapType, resolver, constantTokens, urlParameters)}`,
+      );
     }
     lines.push(`${INDENT}}`);
   }
@@ -1685,7 +1830,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     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);
-    const line = emitFunction(fn, emitName, mapType, resolver, urlParameters);
+    const line = emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters);
     lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
   }
 
@@ -1733,7 +1878,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
           lines.push(docLine);
         }
         lines.push(
-          `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, urlParameters)}`,
+          `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters)}`,
         );
       }
       for (const alias of [...segmentAliases].sort((a, b) => a.public.localeCompare(b.public))) {
@@ -1761,10 +1906,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;
 }
 
 /**
@@ -1789,6 +1949,10 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     constantFqns.has(token) || knownConstantFqns?.has(token)
       ? brandType(token)
       : baseMapType(token);
+  const constantTokens = constantSlotTokenResolver(
+    module,
+    new Set([...constantFqns, ...(knownConstantFqns ?? [])]),
+  );
   const resolver = buildTableDocResolver(
     module.functions.map((fn) => ({
       name: fn.name,
@@ -1805,9 +1969,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(
@@ -1815,8 +1984,11 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
         emitName(prepared.name),
         mapType,
         resolver,
+        constantTokens,
         urlParameters,
+        slotTypes,
       ),
+      slotTypes,
     });
   }
 
@@ -1830,21 +2002,41 @@ 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(fn, emitName(fn.name), mapType, resolver, urlParameters),
+      tsSignature: emitFunction(
+        fn,
+        emitName(fn.name),
+        mapType,
+        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, urlParameters),
+        tsSignature: emitMethod(
+          prepared,
+          mapType,
+          resolver,
+          constantTokens,
+          urlParameters,
+          slotTypes,
+        ),
+        slotTypes,
       });
     }
   }
@@ -1855,6 +2047,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,
     });
   }
 
@@ -1864,6 +2057,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,
     });
   }
 
@@ -1871,6 +2065,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,
     });
   }
 
@@ -1879,6 +2074,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,
     });
   }
 
@@ -2072,32 +2268,61 @@ function memberSignature(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
   const cutoff = trailingOptionalCutoff(original, elementName);
   const varargIndex = original.findIndex(isVarargParameter);
   const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
-    emitParameter(p, i, i >= cutoff, mapType, resolver, elementName, urlParameters),
+    emitParameter(p, i, i >= cutoff, mapType, resolver, constantTokens, elementName, urlParameters),
   );
-  const params = (
+  const rest =
     varargIndex === -1
-      ? positional
-      : [
-          ...positional,
-          emitRestParameter(original, varargIndex, mapType, resolver, elementName, urlParameters),
-        ]
-  ).join(", ");
-  const ret = emitReturn(prepared.original.returnValues, mapType, resolver, elementName);
+      ? 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,
+    resolver,
+    constantTokens,
+    elementName,
+  );
   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}`;
@@ -2108,9 +2333,11 @@ function emitFunction(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
-  return `function ${memberSignature(prepared, name, mapType, resolver, urlParameters)}`;
+  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters, slotSink)}`;
 }
 
 // A colon-method member of a handle interface: identical signature machinery to a
@@ -2120,9 +2347,19 @@ function emitMethod(
   prepared: PreparedFunction,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  slotSink?: Record<string, string>,
 ): string {
-  return memberSignature(prepared, prepared.name, mapType, resolver, 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
@@ -2238,6 +2475,7 @@ function parameterType(
   p: ApiParameter,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
 ): string {
@@ -2247,13 +2485,25 @@ function parameterType(
   const alias = SCENE_ADDRESS_ALIASES[classifyUrlParameter(urlParameters, elementName, p.name)];
   const slotMapType = alias === undefined ? mapType : addressMapType(mapType, alias);
   return concrete.length > 0
-    ? mapSlotUnion(concrete, p.doc, slotMapType, true, resolver, elementName, "param", p.name)
+    ? mapSlotUnion(
+        concrete,
+        p.doc,
+        slotMapType,
+        true,
+        resolver,
+        constantTokens,
+        elementName,
+        "param",
+        p.name,
+      )
     : "unknown";
 }
 
 const VARARG_PREFIX = "...";
 
-function isVarargParameter(p: ApiParameter): boolean {
+// Exported because the fidelity audit must ask the same question about the
+// same input: what the emitted declaration accepts is the emitter's to decide.
+export function isVarargParameter(p: ApiParameter): boolean {
   return p.name.startsWith(VARARG_PREFIX);
 }
 
@@ -2277,21 +2527,32 @@ function emitRestParameter(
   varargIndex: number,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  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, 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(
@@ -2300,41 +2561,62 @@ function emitParameter(
   optional: boolean,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
-): string {
+): { text: string; ts: string } {
   const name = safeParamName(p.name, index);
-  const ts = parameterType(p, mapType, resolver, elementName, urlParameters);
+  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 `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`;
+  return { text: `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`, ts };
 }
 
 function emitReturn(
   returnValues: ApiParameter[],
   mapType: (t: string) => string,
   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: [] };
+  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, 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: [] };
   const ts =
     first.types.length > 0
       ? mapSlotUnion(
@@ -2343,12 +2625,13 @@ function emitReturn(
           mapType,
           false,
           resolver,
+          constantTokens,
           elementName,
           "return",
           first.name,
         )
       : "unknown";
-  return { type: ts, trailing: "" };
+  return { type: ts, trailing: "", slots: [{ position: 0, name: first.name, ts }] };
 }
 
 function emitPropertyMember(
@@ -2380,13 +2663,26 @@ function mapSlotUnion(
   mapType: (t: string) => string,
   optionalFields: boolean,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   slotKind?: "param" | "return",
   slotName?: string,
 ): string {
   const mapped: string[] = [];
   const seen = new Set<string>();
+  const push = (ts: string): void => {
+    if (seen.has(ts)) return;
+    seen.add(ts);
+    mapped.push(ts);
+  };
   for (const token of types) {
+    if (token === "constant" && slotKind !== undefined && slotName !== undefined) {
+      const expanded = constantTokens(elementName, slotKind, slotName, doc);
+      if (expanded.length > 0) {
+        for (const fqn of expanded) push(mapType(fqn));
+        continue;
+      }
+    }
     let ts: string;
     if (token === "table") {
       const curation =
@@ -2413,7 +2709,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") {
@@ -2457,9 +2760,7 @@ function mapSlotUnion(
           : undefined;
       ts = curated ?? mapType(token);
     }
-    if (seen.has(ts)) continue;
-    seen.add(ts);
-    mapped.push(ts);
+    push(ts);
   }
   // A genuine `unknown` member (an `any` slot, including `any | nil`) absorbs
   // every other union member, so collapse to exactly `unknown` rather than emit