@defold-typescript/types 0.39.0 → 0.40.0

package/src/emit-dts.ts

@@ -131,6 +131,8 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // names; bare `on_message`'s receive `message` is the pre-hashed, user-routed
   // payload (mitigated for authored code by isMessage/onMessage). No static shape
   // exists, so `Record<string | number, unknown>` is faithful, not a loss.
+  // collectionfactory.create curates the instance-id layer of `properties` as a
+  // mapping; each per-instance property table stays that faithful `Record`.
   "factory.create",
   "collectionfactory.create",
   "on_message",
@@ -254,6 +256,16 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
 // 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.
+//
+// The same table holds a `function` return whose prose documents the returned
+// function's contract, which the bare token cannot carry: `socket.protect`'s
+// safe function "returns nil followed by an error message", and
+// `socket.newtry`'s try function returns its first argument when it is truthy
+// and throws otherwise, the LuaSocket contract its example relies on to unwrap
+// `socket.connect`'s `client, err` pair. The try function takes that pair
+// destructured into separate arguments; a boxed `LuaMultiReturn` is rejected
+// because TSTL passes it as one table, which is always truthy. `reason` quotes
+// the slot prose the provenance test searches for, as for the `nil` entries.
 export interface ReturnTypeCorrection {
   readonly ts: string;
   readonly upstream: readonly string[];
@@ -270,8 +282,193 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       reason: "the body if successful. Otherwise nil.",
     },
   ],
+  [
+    "socket.protect",
+    {
+      ts: "(...args: unknown[]) => LuaMultiReturn<[unknown, string | undefined]>",
+      upstream: ["function(function())"],
+      reason: "returns nil followed by an error message.",
+    },
+  ],
+  [
+    "socket.newtry",
+    {
+      ts: "<T>(value: T | undefined, ...rest: T extends { readonly __tstlMultiReturn: unknown } ? [boxedMultiReturn: never] : unknown[]) => T",
+      upstream: ["function"],
+      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.
+export interface ParamTypeCorrection {
+  readonly adds: string;
+  readonly upstream: readonly string[];
+  readonly reason: string;
+}
+
+// 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([
+  [
+    "render.set_render_target:param:render_target",
+    {
+      adds: "string | Hash | typeof render.RENDER_TARGET_DEFAULT",
+      upstream: ["render_target"],
+      reason:
+        "\"render.RENDER_TARGET_DEFAULT to set the default render target\"; example `render.set_render_target('my_rt_resource')`",
+    },
+  ],
+  [
+    "render.get_render_target_width:param:render_target",
+    {
+      adds: "string | Hash",
+      upstream: ["render_target"],
+      reason:
+        "example `render.get_render_target_width('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)`",
+    },
+  ],
+  [
+    "render.get_render_target_height:param:render_target",
+    {
+      adds: "string | Hash",
+      upstream: ["render_target"],
+      reason:
+        "example `render.get_render_target_height('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)`",
+    },
+  ],
+  [
+    "render.set_render_target_size:param:render_target",
+    {
+      adds: "string | Hash",
+      upstream: ["render_target"],
+      reason:
+        "\"a render target created from either a render script, or from a render target resource\"; example `render.set_render_target_size('my_rt_resource', ...)`",
+    },
+  ],
+  [
+    "render.enable_texture:param:handle_or_name",
+    {
+      adds: 'Opaque<"render_target"> | number',
+      upstream: ["texture", "string", "hash"],
+      reason:
+        "\"render target or texture handle that should be bound, or a named resource\"; examples `render.enable_texture(0, self.my_render_target, ...)` and `render.enable_texture(0, 'my_rt_resource', ...)`; `resource.get_texture_info` returns the handle as a number",
+    },
+  ],
+  [
+    "render.disable_texture:param:binding",
+    {
+      adds: "number",
+      upstream: ["texture", "string", "hash"],
+      reason:
+        '"texture binding, either by texture unit, string or hash"; example `render.disable_texture(0)`',
+    },
+  ],
+  [
+    "render.set_camera:param:camera",
+    {
+      adds: "string",
+      upstream: ["url", "number", "nil"],
+      reason: 'example `render.set_camera("main:/my_go#camera")`',
+    },
+  ],
+  [
+    "go.delete:param:id",
+    {
+      adds: "boolean",
+      upstream: ["string", "hash", "url", "table"],
+      reason: "example `go.delete(true)` deletes the script game object and its children",
+    },
+  ],
+  [
+    "buffer.get_bytes:param:stream_name",
+    {
+      adds: "string",
+      upstream: ["hash"],
+      reason: 'sys.load_buffer example `buffer.get_bytes(my_buffer, "data")`',
+    },
+  ],
+  [
+    "gui.set:param:value",
+    {
+      adds: "Matrix4 | Hash",
+      upstream: ["number", "vector4", "vector3", "quaternion"],
+      reason:
+        'example `gui.set(node, "light_matrix", vmath.matrix4())` ("matrix4 is also supported"); example `gui.set(msg.url(), "textures", atlas_id, {key = "runtime_texture"})` passes the hash `resource.create_atlas` returns',
+    },
+  ],
+  [
+    "gui.set_rotation:param:rotation",
+    {
+      adds: "Vector3",
+      upstream: ["quaternion", "vector4"],
+      reason: "gui.set example `gui.set_rotation(node, vmath.vector3(0,0,45))`",
+    },
+  ],
+  [
+    "sys.save:param:table",
+    {
+      adds: "readonly unknown[]",
+      upstream: ["table"],
+      reason:
+        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.save`',
+    },
+  ],
+  [
+    "sys.serialize:param:table",
+    {
+      adds: "readonly unknown[]",
+      upstream: ["table"],
+      reason:
+        'example builds `my_table` with `table.insert(my_table, "my_value")` and passes it to `sys.serialize`',
+    },
+  ],
+]);
+
+// 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
@@ -320,6 +517,26 @@ export const PROPERTY_TYPE_CORRECTIONS: ReadonlyMap<string, PropertyTypeCorrecti
   ],
 ]);
 
+// A property upstream names with a placeholder standing for a numbered family of
+// keys, so its literal name is not a key the engine accepts. The emitted members
+// are one literal key per number in `first..last`, each typed like the
+// placeholder. `evidence` is the brief phrase that defines the range;
+// `property-correction-provenance.test.ts` reds when a vendored ref-doc stops
+// saying it, or when the phrase stops stating `first-last`. Curated rather than
+// matched on a trailing `N`, so each new upstream placeholder is a deliberate
+// addition.
+export interface PropertyKeyRange {
+  readonly prefix: string;
+  readonly first: number;
+  readonly last: number;
+  readonly evidence: string;
+}
+
+// Keyed `<namespace>.<property>`, mirroring PROPERTY_TYPE_CORRECTIONS.
+export const PROPERTY_KEY_RANGES: ReadonlyMap<string, PropertyKeyRange> = new Map([
+  ["model.textureN", { prefix: "texture", first: 0, last: 7, evidence: "textureN where N is 0-7" }],
+]);
+
 // A parameter the ref-doc metadata marks required while the same element's prose
 // or examples show it being omitted. `is_optional` is the only optionality
 // signal the emitter has, and upstream leaves it `False` on slots its own
@@ -357,11 +574,16 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     "b2d.fixture.set_shape:param:update_mass",
     '2 of 3 examples omit it; "The body mass is not updated unless update_mass is true"',
   ],
+  [
+    "b2d.shape.set_shape:param:update_mass",
+    '1 of 3 examples omits it; "The body mass is not updated unless update_mass is true"',
+  ],
   [
     "b2d.shape.ray_cast:param:max_fraction",
     '"optional maximum translation fraction, defaults to 1"',
   ],
   ["iap.buy:param:options", '"optional parameters as properties"'],
+  ["socket.newtry:param:finalizer", "socket.protect's example `local try = socket.newtry()`"],
   ...(
     [
       "create_distance",
@@ -383,6 +605,69 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
   ),
 ]);
 
+// 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
+// `parameters` in that slot's place. Keyed `<namespace>:param:<slot>`, so only a
+// curated entry adds an overload: a reworded doc cannot add or drop one, and the
+// same prose in another namespace adds nothing.
+//
+// `evidence` is the upstream slot-doc fragment that names the alternative. The
+// emitter throws once a curated slot stops carrying it, so upstream dropping the
+// alternative reds here rather than shipping an overload nothing documents.
+export interface FirstSlotAlternative {
+  readonly parameters: readonly ApiParameter[];
+  readonly evidence: string;
+}
+
+export const FIRST_SLOT_ALTERNATIVES: ReadonlyMap<string, FirstSlotAlternative> = new Map([
+  [
+    "b2d.shape:param:shape_id",
+    {
+      parameters: [
+        {
+          name: "body",
+          doc: "The body that owns the shape.",
+          types: ["b2Body"],
+          isOptional: false,
+        },
+        {
+          name: "shape_index",
+          doc: "The shape's 1-based index on that body, as <code>b2d.body.get_shapes</code> lists them.",
+          types: ["number"],
+          isOptional: false,
+        },
+      ],
+      evidence: "or pass <code>body, shape_index</code>",
+    },
+  ],
+]);
+
+// The alternative signature FIRST_SLOT_ALTERNATIVES gives `fn`, or null when
+// its first slot is not curated. Shared with the fidelity audit so the arity it
+// measures is the arity the emitter declares.
+export function firstSlotAlternativeOf(fn: ApiFunction, namespace: string): ApiFunction | null {
+  const [first, ...rest] = fn.parameters;
+  if (first === undefined) return null;
+  const key = `${namespace}:param:${first.name}`;
+  const alternative = FIRST_SLOT_ALTERNATIVES.get(key);
+  if (alternative === undefined) return null;
+  if (!first.doc.includes(alternative.evidence)) {
+    throw new Error(
+      `first-slot alternative ${key}: ${fn.name} no longer documents "${alternative.evidence}"`,
+    );
+  }
+  return { ...fn, parameters: [...alternative.parameters, ...rest] };
+}
+
+function firstSlotAlternative(
+  prepared: PreparedFunction,
+  namespace: string,
+): PreparedFunction | null {
+  const original = firstSlotAlternativeOf(prepared.original, namespace);
+  return original === null ? null : { ...prepared, original };
+}
+
 export type ConstantSlotResolution =
   | { readonly borrow: string }
   | { readonly family: string; readonly evidence: string }
@@ -1047,6 +1332,27 @@ const PHYSICS_SHAPE_TABLE_FIELDS: readonly TableField[] = [
 ];
 
 export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map([
+  // 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.
+  [
+    "buffer.create:param:declaration",
+    {
+      kind: "array-object",
+      fields: [
+        { name: "name", types: ["hash", "string"] },
+        { name: "type", types: ["constant"], tsType: "buffer.ValueType" },
+        { name: "count", types: ["number"] },
+      ],
+    },
+  ],
+  // collectionfactory.create's `properties` is keyed by "game object ids (hash)",
+  // which upstream's example builds with `hash("/go")`. The `string` key keeps
+  // the object-literal form this slot accepted as a bare `table`.
+  [
+    "collectionfactory.create:param:properties",
+    { kind: "mapping", key: "hash | string", value: "table" },
+  ],
   ["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
   // `fonts` field whose `<dd>` is itself a `<dl>` (`path: string`, `path_hash:
@@ -1752,11 +2058,33 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
 // 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.
+//
+// The other entries type what the slot's own prose lists and nothing more.
+// `http.request`'s response fields are the `<ul>` under "The response data.
+// Contains the fields:"; each is conditional ("if not saved on disc", "only if
+// option report_progress is true") except `status`, and `headers` is the same
+// string map the request sends. `sprite.play_flipbook`'s message is the
+// "Information about the completion" list. `collectionproxy.load` documents
+// only that the callback receives `proxy_loading`, `proxy_ready` or
+// `proxy_error` messages and lists no fields, so its message is the bare record
+// `window.set_listener`'s `data` is.
 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",
   ],
+  [
+    "http.request:param:callback",
+    "(self: unknown, id: Hash, response: { status: number; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void",
+  ],
+  [
+    "sprite.play_flipbook:param:complete_function",
+    "(self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void",
+  ],
+  [
+    "collectionproxy.load:param:callback",
+    "(self: unknown, message_id: Hash, message: Record<string | number, unknown>, sender: Url) => void",
+  ],
 ]);
 
 // resource.set_atlas's `table` param and resource.get_atlas's `data` return are
@@ -1789,7 +2117,19 @@ export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]>
 // parser recovers every other field faithfully but leaves that `table` token as
 // a bare `Record`; this pins only the `value` field's TS type to the documented
 // array union while every sibling field stays parser-authoritative. Keyed by
-// `<element>:<kind>:<slot>:<field>`, mirroring NESTED_FIELD_CURATIONS.
+// `<element>:<kind>:<slot>:<field>`, mirroring NESTED_FIELD_CURATIONS; a field
+// one level down is `<field>.<member>`, or `<field>[].<member>` inside a list.
+//
+// The atlas animation `playback` field is documented as `constant` with the
+// prose "the default value is go.PLAYBACK_ONCE_FORWARD", which names the enum
+// the bare token cannot.
+//
+// `gui.set`'s `options.key` is documented as `hash`, while upstream's own
+// example sets a named font with `{ key = "my_font_name" }`.
+//
+// `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.
 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([
@@ -1797,6 +2137,11 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["material.set_constants:param:constants:value", CONSTANT_VALUE_TS],
   ["material.set_vertex_attributes:param:attributes:value", ATTRIBUTE_VALUE_TS],
   ["material.get_vertex_attributes:return:table:value", ATTRIBUTE_VALUE_TS],
+  ["resource.set_atlas:param:table:animations[].playback", "go.Playback"],
+  ["resource.create_atlas:param:table:animations[].playback", "go.Playback"],
+  ["resource.get_atlas:return:data:animations[].playback", "go.Playback"],
+  ["gui.set:param:options:key", "string | Hash"],
+  ["render.set_render_target:param:options:transient", "graphics.BufferType[]"],
 ]);
 
 // A field the engine accepts on an option bag whose `<dl>` upstream otherwise
@@ -1949,11 +2294,17 @@ export function applyFieldTypeOverrides(
   fields: readonly TableField[],
 ): TableField[] {
   if (slotKind === undefined || slotName === undefined) return [...fields];
-  return fields.map((field) => {
-    const override = TABLE_FIELD_TYPE_OVERRIDES.get(
-      `${elementName}:${slotKind}:${slotName}:${field.name}`,
-    );
+  const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
+  const typed = (field: TableField, path: string): TableField => {
+    const override = TABLE_FIELD_TYPE_OVERRIDES.get(`${prefix}${path}`);
     return override === undefined ? field : { ...field, tsType: override };
+  };
+  return fields.map((field) => {
+    const own = typed(field, field.name);
+    if (own.fields === undefined) return own;
+    const parent = `${field.name}${field.isList === true ? "[]" : ""}`;
+    const nested = own.fields.map((child) => typed(child, `${parent}.${child.name}`));
+    return nested.every((child, i) => child === own.fields?.[i]) ? own : { ...own, fields: nested };
   });
 }
 
@@ -2285,6 +2636,15 @@ function groupFlattenedTableFields(fields: readonly TableField[]): TableField[]
   return grouped;
 }
 
+// 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};`;
+}
+
 export function emitDeclarations(module: ApiModule, options?: EmitOptions): string {
   const prefix = `${module.namespace}.`;
 
@@ -2367,7 +2727,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     // 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}type ${t.name} = Opaque<"${t.name}">;`);
+    lines.push(`${INDENT}${decl}${typedefAlias(t.name, baseMapType)}`);
   }
   for (const aliasDecl of constantUnionAliasDeclarations(module.namespace)) {
     lines.push(`${INDENT}${decl}${aliasDecl}`);
@@ -2413,6 +2773,18 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     for (const docLine of functionDocLines(fn.original, translations)) 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) {
+      const overload = emitFunction(
+        alternative,
+        emitName,
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+      );
+      lines.push(`${INDENT}${reserved ? "" : decl}${overload}`);
+    }
   }
 
   for (const alias of [...aliases].sort((a, b) => a.public.localeCompare(b.public))) {
@@ -2475,10 +2847,12 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     const members = [...module.properties].sort((a, b) => a.name.localeCompare(b.name));
     lines.push(`${INDENT}${decl}interface properties {`);
     for (const p of members) {
-      for (const docLine of summaryDocLines(p.brief, p.description, `${INDENT}${INDENT}`)) {
-        lines.push(docLine);
+      for (const member of emitPropertyMembers(p, mapType, module.namespace)) {
+        for (const docLine of summaryDocLines(p.brief, p.description, `${INDENT}${INDENT}`)) {
+          lines.push(docLine);
+        }
+        lines.push(`${INDENT}${INDENT}${member}`);
       }
-      lines.push(`${INDENT}${INDENT}${emitPropertyMember(p, mapType, module.namespace)}`);
     }
     lines.push(`${INDENT}}`);
   }
@@ -2518,7 +2892,10 @@ export interface SymbolSignature {
  * {@link collectNestedGroups} tree the declaration emitter walks, so neither
  * surface can decide on its own which members are nested or how deep they go.
  * The caller applies the same `skipFunctions` filter the `.d.ts` generation
- * does, so a dropped member never yields a signature.
+ * does, so a dropped member never yields a signature. A top-level function the
+ * declaration emits with a first-slot alternative overload carries one arm per
+ * 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[] {
   const prefix = `${module.namespace}.`;
@@ -2558,19 +2935,28 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     const prepared = prepareFunction(fn, prefix);
     if (prepared === null) continue;
     const slotTypes: Record<string, string> = {};
-    out.push({
-      identity: fnIdentity(fn),
-      tsSignature: emitFunction(
-        prepared,
-        emitName(prepared.name),
-        mapType,
-        resolver,
-        constantTokens,
-        urlParameters,
-        slotTypes,
-      ),
+    const primary = emitFunction(
+      prepared,
+      emitName(prepared.name),
+      mapType,
+      resolver,
+      constantTokens,
+      urlParameters,
       slotTypes,
-    });
+    );
+    const alternative = firstSlotAlternative(prepared, module.namespace);
+    const tsSignature =
+      alternative === null
+        ? primary
+        : `${primary}\n${emitFunction(
+            alternative,
+            emitName(prepared.name),
+            mapType,
+            resolver,
+            constantTokens,
+            urlParameters,
+          )}`;
+    out.push({ identity: fnIdentity(fn), tsSignature, slotTypes });
   }
 
   const nested = flattenNestedGroups(collectNestedGroups(module, prefix));
@@ -2642,10 +3028,14 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     });
   }
 
+  // A key-range property emits several members that share one type; its entry
+  // carries the first, which is verbatim in the `.d.ts` and is what the `/api`
+  // render layer reduces to `<placeholder>: <type>`.
   for (const p of module.properties) {
+    const [firstMember = ""] = emitPropertyMembers(p, mapType, module.namespace);
     out.push({
       identity: { namespace: module.namespace, kind: "PROPERTY", name: p.name, signature: "" },
-      tsSignature: emitPropertyMember(p, mapType, module.namespace),
+      tsSignature: firstMember,
       slotTypes: NO_SLOTS,
     });
   }
@@ -2654,7 +3044,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     if (!TS_IDENTIFIER.test(t.name) || handleGroups.has(t.name)) continue;
     out.push({
       identity: { namespace: module.namespace, kind: "TYPEDEF", name: t.name, signature: "" },
-      tsSignature: `type ${t.name} = Opaque<"${t.name}">;`,
+      tsSignature: typedefAlias(t.name, baseMapType),
       slotTypes: NO_SLOTS,
     });
   }
@@ -2971,7 +3361,7 @@ function functionDocLines(
 ): string[] {
   const params = fn.parameters.map((p, index) => ({
     name: emittedParamName(p, index),
-    doc: htmlToDocText(p.doc),
+    doc: rewriteParamDoc(fn.name, p.name, htmlToDocText(p.doc)),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
   const lua = htmlToCodeText(fn.examples ?? "");
@@ -3102,19 +3492,22 @@ function parameterType(
   // `safeParamName` fallback.
   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,
-        constantTokens,
-        elementName,
-        "param",
-        p.name,
-      )
-    : "unknown";
+  const mapped =
+    concrete.length > 0
+      ? mapSlotUnion(
+          concrete,
+          p.doc,
+          slotMapType,
+          true,
+          resolver,
+          constantTokens,
+          elementName,
+          "param",
+          p.name,
+        )
+      : "unknown";
+  const correction = PARAM_TYPE_CORRECTIONS.get(tableSlotKey(elementName, "param", p.name));
+  return correction === undefined ? mapped : `${mapped} | ${correction.adds}`;
 }
 
 const VARARG_PREFIX = "...";
@@ -3263,12 +3656,19 @@ function emitReturn(
   return { type: ts, trailing: "", slots: [{ position: 0, name: first.name, ts }] };
 }
 
-function emitPropertyMember(
+function emitPropertyMembers(
   p: ApiProperty,
   mapType: (t: string) => string,
   namespace: string,
-): string {
-  const key = TS_IDENTIFIER.test(p.name) ? p.name : JSON.stringify(p.name);
+): readonly string[] {
+  const keyRange = PROPERTY_KEY_RANGES.get(`${namespace}.${p.name}`);
+  const keys: string[] = [];
+  if (keyRange !== undefined) {
+    for (let unit = keyRange.first; unit <= keyRange.last; unit++)
+      keys.push(`${keyRange.prefix}${unit}`);
+  } else {
+    keys.push(TS_IDENTIFIER.test(p.name) ? p.name : JSON.stringify(p.name));
+  }
   const correction = PROPERTY_TYPE_CORRECTIONS.get(`${namespace}.${p.name}`);
   const ts =
     correction !== undefined
@@ -3276,7 +3676,7 @@ function emitPropertyMember(
       : p.types.length > 0
         ? unionFromTokens(p.types, mapType)
         : "unknown";
-  return `${key}: ${ts};`;
+  return keys.map((key) => `${key}: ${ts};`);
 }
 
 // Like `unionFromTokens`, but a `table` token whose slot doc carries a parseable
@@ -3341,11 +3741,21 @@ function mapSlotUnion(
         // 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}>`;
+        const keyTokens = mapping.key.split("|").map((token) => token.trim());
+        if (slotKind === "param" && keyTokens.includes("string")) {
+          // A caller builds a string-keyed parameter table as an object literal,
+          // which `LuaMap` rejects; the `Record` arm admits it and TSTL lowers
+          // both to the same Lua table. The `Record` arm carries the string keys,
+          // so `LuaMap` keeps only the other key tokens: `LuaMap`'s key is
+          // invariant, and a `LuaMap<Hash | string, V>` would reject the
+          // `LuaMap<Hash, V>` a caller builds. A string-only key keeps its
+          // `LuaMap` arm so an existing `LuaMap` caller stays valid.
+          const otherKeys = keyTokens.filter((token) => token !== "string");
+          const key = unionFromTokens(otherKeys.length > 0 ? otherKeys : keyTokens, mapType);
+          ts = `LuaMap<${key}, ${value}> | Record<string, ${value}>`;
+        } else {
+          ts = `LuaMap<${unionFromTokens(keyTokens, mapType)}, ${value}>`;
+        }
       } else if (element !== undefined) {
         ts = arrayTypeFromTokens(element, mapType);
       } else if (curation?.kind === "object" || curation?.kind === "array-object") {