@defold-typescript/types 0.33.1 → 0.35.0

package/scripts/signature-store-fs.ts

@@ -24,6 +24,7 @@ export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures
 export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
 export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
 export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
+export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/scripts/sync-api-docs.ts

@@ -109,9 +109,9 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("zlib", "doc/src-script_zlib.cpp_doc.json"),
 ];
 
-// Checklist namespaces with no machine-readable doc anywhere (neither core
-// ref-doc.zip nor a published extension `.script_api`). Currently empty: the
-// four extension-only surfaces are wired via EXTENSION_MANIFEST below.
+// Checklist namespaces with no machine-readable doc anywhere in core
+// ref-doc.zip. Currently empty: extension namespaces are not engine surfaces;
+// they are typed through `resolve` from each extension's own `.script_api`.
 export const UNMAPPED: ReadonlyMap<string, string> = new Map();
 
 // A Lua script namespace is a lowercase, dot-separated identifier (`sys`,
@@ -211,53 +211,18 @@ function entry(
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
 }
 
-export interface ExtensionManifestEntry {
-  readonly namespace: string;
-  readonly repo: string;
-  readonly tag: string;
-  readonly path: string;
-  readonly fixture: string;
-}
-
-// Extension-only namespaces: each ships a single `.script_api` (YAML) doc in
-// its own repo rather than appearing in core ref-doc.zip. Pinned to a release
-// tag and converted to the core ref-doc JSON shape via parseScriptApi so they
-// flow through MODULE_MANIFEST and the drift guard like every core namespace.
-export const EXTENSION_MANIFEST: readonly ExtensionManifestEntry[] = [
-  ext("iac", "defold/extension-iac", "1.4.0", "extension-iac/api/iac.script_api"),
-  ext("iap", "defold/extension-iap", "8.4.0", "extension-iap/api/iap.script_api"),
-  ext("push", "defold/extension-push", "4.1.0", "extension-push/api/push.script_api"),
-  ext("webview", "defold/extension-webview", "1.5.0", "webview/api/webview.script_api"),
-];
-
-function ext(namespace: string, repo: string, tag: string, path: string): ExtensionManifestEntry {
-  return {
-    namespace,
-    repo,
-    tag,
-    path,
-    fixture: `fixtures/defold-1.13.1/${namespace}_doc.json`,
-  };
-}
-
 // Every vendored fixture set the coverage report audits, and the namespaces it
 // counts as reached from upstream. Composed once here so the `--check` run and
 // the guard over it cannot disagree about which sets are in scope.
 export const COVERAGE_MANIFEST: readonly { readonly namespace: string }[] = [
   ...SYNC_MANIFEST,
-  ...EXTENSION_MANIFEST,
   ...EDITOR_MANIFEST,
 ];
 
 export const UPSTREAM_MAPPED_NAMESPACES: ReadonlySet<string> = new Set(
-  [...SYNC_MANIFEST, ...EXTENSION_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map(
-    (e) => e.namespace,
-  ),
+  [...SYNC_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map((e) => e.namespace),
 );
 
-export const extensionRawUrl = (e: ExtensionManifestEntry): string =>
-  `https://raw.githubusercontent.com/${e.repo}/${e.tag}/${e.path}`;
-
 // Convert a raw `.script_api` YAML doc to the core ref-doc JSON string written
 // to fixtures/<ns>_doc.json. The result is byte-compared by the same drift
 // semantics core fixtures use.
@@ -265,6 +230,12 @@ export function scriptApiToFixtureJson(text: string): string {
   return JSON.stringify(parseScriptApi(text));
 }
 
+// The docs-only variant: the same ref-doc JSON with constants kept, for pages
+// that render a module's full surface rather than feed the emitter.
+export function scriptApiToDocsJson(text: string): string {
+  return JSON.stringify(parseScriptApi(text, { complete: true }));
+}
+
 // The types-api-coverage `What` checklist in vision.md lists every namespace as
 // a backtick-quoted token on the "Concrete breadth checklist" line. Reading it
 // here keeps SYNC_MANIFEST + UNMAPPED honest against the source of truth: the
@@ -486,25 +457,6 @@ export function syncExtractedFixtures(
   return results;
 }
 
-export async function downloadExtensionFixtures(
-  manifest: readonly ExtensionManifestEntry[] = EXTENSION_MANIFEST,
-): Promise<ExtractedFixture[]> {
-  const out: ExtractedFixture[] = [];
-  for (const e of manifest) {
-    const url = extensionRawUrl(e);
-    const res = await fetch(url);
-    if (!res.ok) {
-      throw new Error(`extension doc download failed: ${url} -> ${res.status} ${res.statusText}`);
-    }
-    out.push({
-      namespace: e.namespace,
-      fixture: e.fixture,
-      contents: scriptApiToFixtureJson(await res.text()),
-    });
-  }
-  return out;
-}
-
 function readFixtureOrNull(path: string): string | null {
   try {
     return readFileSync(path, "utf8");
@@ -675,18 +627,16 @@ if (import.meta.main) {
   const zip = zipPath ? readZip(zipPath) : await downloadZip();
 
   const coreFixtures = extractFixtures(zip);
-  const extensionFixtures = await downloadExtensionFixtures();
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
   const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
-    ...syncExtractedFixtures(extensionFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
     ...syncExtractedFixtures(editorFixtures, { check }),
     ...syncExtractedFixtures(editorVmFixtures, { check }),
   ];
-  const syncedDocs = [...coreFixtures, ...extensionFixtures].map((f) => ({
+  const syncedDocs = coreFixtures.map((f) => ({
     namespace: f.namespace,
     doc: JSON.parse(f.contents),
   }));

package/src/doc-comment.ts

@@ -73,10 +73,12 @@ export function htmlToCodeText(html: string): string {
 /**
  * Convert a ref-doc `examples` HTML fragment — prose interleaved with one or
  * more `<div class="codehilite">…</div>` syntax-highlight blocks — into Markdown:
- * prose runs become `htmlToDocText`, each highlight block becomes a ` ```lua `
- * fence via `htmlToCodeText`. A fragment with no `codehilite` block is wrapped
- * whole as a single ` ```lua ` fence (back-compat for plain-code examples).
- * Returns `""` for empty / whitespace-only input.
+ * prose runs become `htmlToDocText`, each highlight block becomes a fence via
+ * `htmlToCodeText`. The fence language comes from a `class="language-X"` on the
+ * block's `<code>` (as converted extension `.script_api` examples carry), else
+ * `lua`, since engine ref-doc blocks carry no language class. A fragment with no
+ * `codehilite` block is wrapped whole as a single ` ```lua ` fence (back-compat
+ * for plain-code examples). Returns `""` for empty / whitespace-only input.
  */
 export function examplesHtmlToMarkdown(html: string): string {
   if (html.trim() === "") return "";
@@ -89,8 +91,10 @@ export function examplesHtmlToMarkdown(html: string): string {
     matched = true;
     const prose = htmlToDocText(html.slice(lastIndex, match.index));
     if (prose !== "") parts.push(prose);
-    const code = htmlToCodeText(match[1] ?? "");
-    if (code !== "") parts.push(`\`\`\`lua\n${code}\n\`\`\``);
+    const inner = match[1] ?? "";
+    const lang = /<code\b[^>]*\bclass="language-([^"\s]+)"/i.exec(inner)?.[1] ?? "lua";
+    const code = htmlToCodeText(inner);
+    if (code !== "") parts.push(`\`\`\`${lang}\n${code}\n\`\`\``);
     lastIndex = match.index + match[0].length;
   }
 

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",
@@ -351,6 +354,119 @@ 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];
+}
+
+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
@@ -1580,6 +1696,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 +1776,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 +1807,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 +1855,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))) {
@@ -1789,6 +1911,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,
@@ -1815,6 +1941,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
         emitName(prepared.name),
         mapType,
         resolver,
+        constantTokens,
         urlParameters,
       ),
     });
@@ -1835,7 +1962,14 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   for (const fn of nested.functions) {
     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,
+      ),
     });
   }
 
@@ -1844,7 +1978,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     for (const prepared of group) {
       out.push({
         identity: fnIdentity(prepared.original),
-        tsSignature: emitMethod(prepared, mapType, resolver, urlParameters),
+        tsSignature: emitMethod(prepared, mapType, resolver, constantTokens, urlParameters),
       });
     }
   }
@@ -2072,6 +2206,7 @@ function memberSignature(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
 ): string {
   const original = prepared.original.parameters;
@@ -2079,17 +2214,31 @@ function memberSignature(
   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 = (
     varargIndex === -1
       ? positional
       : [
           ...positional,
-          emitRestParameter(original, varargIndex, mapType, resolver, elementName, urlParameters),
+          emitRestParameter(
+            original,
+            varargIndex,
+            mapType,
+            resolver,
+            constantTokens,
+            elementName,
+            urlParameters,
+          ),
         ]
   ).join(", ");
-  const ret = emitReturn(prepared.original.returnValues, mapType, resolver, elementName);
+  const ret = emitReturn(
+    prepared.original.returnValues,
+    mapType,
+    resolver,
+    constantTokens,
+    elementName,
+  );
   const predicateToken = TYPE_PREDICATES.get(elementName);
   const soleParam = original[0];
   if (
@@ -2108,9 +2257,10 @@ function emitFunction(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
 ): string {
-  return `function ${memberSignature(prepared, name, mapType, resolver, urlParameters)}`;
+  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters)}`;
 }
 
 // A colon-method member of a handle interface: identical signature machinery to a
@@ -2120,9 +2270,10 @@ function emitMethod(
   prepared: PreparedFunction,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
 ): string {
-  return memberSignature(prepared, prepared.name, mapType, resolver, urlParameters);
+  return memberSignature(prepared, prepared.name, mapType, resolver, constantTokens, urlParameters);
 }
 
 // Build the indented JSDoc lines for a function from its ref-doc prose. The
@@ -2238,6 +2389,7 @@ function parameterType(
   p: ApiParameter,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
 ): string {
@@ -2247,13 +2399,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,6 +2441,7 @@ function emitRestParameter(
   varargIndex: number,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
 ): string {
@@ -2286,7 +2451,9 @@ function emitRestParameter(
     ...new Set(
       params
         .slice(varargIndex)
-        .map((p) => parameterType(p, mapType, resolver, elementName, urlParameters)),
+        .map((p) =>
+          parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
+        ),
     ),
   ];
   const first = members[0] ?? "unknown";
@@ -2300,11 +2467,12 @@ function emitParameter(
   optional: boolean,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
 ): 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
@@ -2317,6 +2485,7 @@ function emitReturn(
   returnValues: ApiParameter[],
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  constantTokens: ConstantSlotTokens,
   elementName: string,
 ): { type: string; trailing: string } {
   const override = RETURN_TYPE_OVERRIDES.get(elementName);
@@ -2328,7 +2497,17 @@ function emitReturn(
     // 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)
+        ? mapSlotUnion(
+            rv.types,
+            rv.doc,
+            mapType,
+            false,
+            resolver,
+            constantTokens,
+            elementName,
+            "return",
+            rv.name,
+          )
         : "unknown",
     );
     return { type: `LuaMultiReturn<[${slots.join(", ")}]>`, trailing: "" };
@@ -2343,6 +2522,7 @@ function emitReturn(
           mapType,
           false,
           resolver,
+          constantTokens,
           elementName,
           "return",
           first.name,
@@ -2380,13 +2560,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 =
@@ -2457,9 +2650,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

package/src/optional-correction-provenance.ts

@@ -24,13 +24,19 @@ interface VersionedManifestEntry extends ManifestEntry {
   readonly editor?: boolean;
 }
 
+// The provenance target the committed extension goldens are recorded under. They
+// belong to no engine version: `resolve` applies the same correction table to them.
+export const EXTENSION_GOLDENS_TARGET = "extension-goldens";
+
 // Every runtime module regen emits through the global correction table: the
-// default target's manifest plus every older generated target's. Editor-VM
-// entries are outside the scope the corrections cover.
+// default target's manifest plus every older generated target's, plus the
+// extension goldens when given. Editor-VM entries are outside the scope the
+// corrections cover.
 export function retainedSurfaces(
   defaultTarget: string,
   defaultManifest: readonly ManifestEntry[],
   versionedManifest: readonly VersionedManifestEntry[],
+  extensionGoldenManifest: readonly ManifestEntry[] = [],
 ): ProvenanceSurface[] {
   return [
     ...defaultManifest.map((entry) => ({
@@ -41,6 +47,11 @@ export function retainedSurfaces(
     ...versionedManifest
       .filter((entry) => entry.editor !== true)
       .map((entry) => ({ target: entry.versionId, namespace: entry.namespace, doc: entry.doc })),
+    ...extensionGoldenManifest.map((entry) => ({
+      target: EXTENSION_GOLDENS_TARGET,
+      namespace: entry.namespace,
+      doc: entry.doc,
+    })),
   ];
 }
 

package/src/render-overloads.d.ts

@@ -0,0 +1,29 @@
+/** @noSelfInFile */
+
+import type { Opaque } from "./core-types";
+
+declare global {
+  namespace render {
+    /**
+     * Creates a new render target according to the supplied specification table.
+     * The parameter table is keyed by buffer type, with one parameter table per
+     * attachment; see the reference for the available keys and values.
+     *
+     * @param parameters - table of buffer parameters, see the description for available keys and values
+     * @returns new render target
+     */
+    function render_target(parameters: Record<string | number, unknown>): Opaque<"render_target">;
+    /**
+     * Creates a new named render target according to the supplied specification
+     * table. The name is used by the profiler and by render target lookups.
+     *
+     * @param name - render target name
+     * @param parameters - table of buffer parameters, see the description for available keys and values
+     * @returns new render target
+     */
+    function render_target(
+      name: string,
+      parameters: Record<string | number, unknown>,
+    ): Opaque<"render_target">;
+  }
+}