@defold-typescript/types 0.38.0 → 0.40.0

package/src/emit-dts.ts

@@ -13,9 +13,10 @@ import {
   htmlToCodeText,
   htmlToDocText,
   renderDocComment,
+  splitExampleSources,
 } from "./doc-comment";
 import type { TranslationStore } from "./example-store";
-import { hashExampleSource, lookupTranslation } from "./example-store";
+import { hashExampleSource, lookupExampleTranslations, lookupTranslation } from "./example-store";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
 export interface EmitOptions {
@@ -130,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",
@@ -253,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[];
@@ -269,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
@@ -319,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
@@ -356,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",
@@ -382,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 }
@@ -415,6 +701,377 @@ export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResoluti
   ],
 ]);
 
+export interface ConstantUnionAlias {
+  // The namespace the alias is declared in. It is the namespace the union
+  // *means*, which is not always the one its constants live in: the three
+  // buffer keys `render.clear` accepts are `graphics.BUFFER_TYPE_*` constants,
+  // but the name that reads right at the call site is `render.ClearBufferKey`.
+  readonly home: string;
+  readonly name: string;
+  // In documentation order, which is the order the arms are emitted in today.
+  readonly members: readonly string[];
+}
+
+// A documented constant union gets a public name so a caller can spell the type
+// their own wrapper takes. Identity is the *member set*, never a name prefix:
+// `gui.ANCHOR_*` splits into two rows because the x and y slots accept
+// different thirds of it, and `graphics.BUFFER_TYPE_*` splits because
+// `render.clear` accepts three of the six.
+//
+// The table is the only thing the emitter reads, and every name in it has been
+// reviewed: a longest-common-prefix rule proposes, a human disposes. A union
+// with no row keeps its inline spelling, which the coverage gate in
+// `packages/types/test/constant-union-alias-coverage.test.ts` turns into a
+// failure naming the row to review.
+export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
+  {
+    home: "buffer",
+    name: "ValueType",
+    members: [
+      "buffer.VALUE_TYPE_FLOAT32",
+      "buffer.VALUE_TYPE_INT16",
+      "buffer.VALUE_TYPE_INT32",
+      "buffer.VALUE_TYPE_INT64",
+      "buffer.VALUE_TYPE_INT8",
+      "buffer.VALUE_TYPE_UINT16",
+      "buffer.VALUE_TYPE_UINT32",
+      "buffer.VALUE_TYPE_UINT64",
+      "buffer.VALUE_TYPE_UINT8",
+    ],
+  },
+  {
+    home: "collectionfactory",
+    name: "Status",
+    members: [
+      "collectionfactory.STATUS_UNLOADED",
+      "collectionfactory.STATUS_LOADING",
+      "collectionfactory.STATUS_LOADED",
+    ],
+  },
+  {
+    home: "factory",
+    name: "Status",
+    members: ["factory.STATUS_UNLOADED", "factory.STATUS_LOADING", "factory.STATUS_LOADED"],
+  },
+  {
+    home: "go",
+    name: "Easing",
+    members: [
+      "go.EASING_INBACK",
+      "go.EASING_INBOUNCE",
+      "go.EASING_INCIRC",
+      "go.EASING_INCUBIC",
+      "go.EASING_INELASTIC",
+      "go.EASING_INEXPO",
+      "go.EASING_INOUTBACK",
+      "go.EASING_INOUTBOUNCE",
+      "go.EASING_INOUTCIRC",
+      "go.EASING_INOUTCUBIC",
+      "go.EASING_INOUTELASTIC",
+      "go.EASING_INOUTEXPO",
+      "go.EASING_INOUTQUAD",
+      "go.EASING_INOUTQUART",
+      "go.EASING_INOUTQUINT",
+      "go.EASING_INOUTSINE",
+      "go.EASING_INQUAD",
+      "go.EASING_INQUART",
+      "go.EASING_INQUINT",
+      "go.EASING_INSINE",
+      "go.EASING_LINEAR",
+      "go.EASING_OUTBACK",
+      "go.EASING_OUTBOUNCE",
+      "go.EASING_OUTCIRC",
+      "go.EASING_OUTCUBIC",
+      "go.EASING_OUTELASTIC",
+      "go.EASING_OUTEXPO",
+      "go.EASING_OUTINBACK",
+      "go.EASING_OUTINBOUNCE",
+      "go.EASING_OUTINCIRC",
+      "go.EASING_OUTINCUBIC",
+      "go.EASING_OUTINELASTIC",
+      "go.EASING_OUTINEXPO",
+      "go.EASING_OUTINQUAD",
+      "go.EASING_OUTINQUART",
+      "go.EASING_OUTINQUINT",
+      "go.EASING_OUTINSINE",
+      "go.EASING_OUTQUAD",
+      "go.EASING_OUTQUART",
+      "go.EASING_OUTQUINT",
+      "go.EASING_OUTSINE",
+    ],
+  },
+  {
+    home: "go",
+    name: "Playback",
+    members: [
+      "go.PLAYBACK_ONCE_FORWARD",
+      "go.PLAYBACK_ONCE_BACKWARD",
+      "go.PLAYBACK_ONCE_PINGPONG",
+      "go.PLAYBACK_LOOP_FORWARD",
+      "go.PLAYBACK_LOOP_BACKWARD",
+      "go.PLAYBACK_LOOP_PINGPONG",
+    ],
+  },
+  {
+    home: "graphics",
+    name: "BufferType",
+    members: [
+      "graphics.BUFFER_TYPE_COLOR0_BIT",
+      "graphics.BUFFER_TYPE_COLOR1_BIT",
+      "graphics.BUFFER_TYPE_COLOR2_BIT",
+      "graphics.BUFFER_TYPE_COLOR3_BIT",
+      "graphics.BUFFER_TYPE_DEPTH_BIT",
+      "graphics.BUFFER_TYPE_STENCIL_BIT",
+    ],
+  },
+  {
+    home: "graphics",
+    name: "State",
+    members: [
+      "graphics.STATE_DEPTH_TEST",
+      "graphics.STATE_STENCIL_TEST",
+      "graphics.STATE_BLEND",
+      "graphics.STATE_ALPHA_TEST",
+      "graphics.STATE_CULL_FACE",
+      "graphics.STATE_POLYGON_OFFSET_FILL",
+    ],
+  },
+  {
+    home: "gui",
+    name: "AdjustMode",
+    members: ["gui.ADJUST_FIT", "gui.ADJUST_ZOOM", "gui.ADJUST_STRETCH"],
+  },
+  {
+    home: "gui",
+    name: "BlendMode",
+    members: [
+      "gui.BLEND_ALPHA",
+      "gui.BLEND_ADD",
+      "gui.BLEND_ADD_ALPHA",
+      "gui.BLEND_MULT",
+      "gui.BLEND_SCREEN",
+    ],
+  },
+  {
+    home: "gui",
+    name: "ClippingMode",
+    members: ["gui.CLIPPING_MODE_NONE", "gui.CLIPPING_MODE_STENCIL"],
+  },
+  {
+    home: "gui",
+    name: "Easing",
+    members: [
+      "gui.EASING_INBACK",
+      "gui.EASING_INBOUNCE",
+      "gui.EASING_INCIRC",
+      "gui.EASING_INCUBIC",
+      "gui.EASING_INELASTIC",
+      "gui.EASING_INEXPO",
+      "gui.EASING_INOUTBACK",
+      "gui.EASING_INOUTBOUNCE",
+      "gui.EASING_INOUTCIRC",
+      "gui.EASING_INOUTCUBIC",
+      "gui.EASING_INOUTELASTIC",
+      "gui.EASING_INOUTEXPO",
+      "gui.EASING_INOUTQUAD",
+      "gui.EASING_INOUTQUART",
+      "gui.EASING_INOUTQUINT",
+      "gui.EASING_INOUTSINE",
+      "gui.EASING_INQUAD",
+      "gui.EASING_INQUART",
+      "gui.EASING_INQUINT",
+      "gui.EASING_INSINE",
+      "gui.EASING_LINEAR",
+      "gui.EASING_OUTBACK",
+      "gui.EASING_OUTBOUNCE",
+      "gui.EASING_OUTCIRC",
+      "gui.EASING_OUTCUBIC",
+      "gui.EASING_OUTELASTIC",
+      "gui.EASING_OUTEXPO",
+      "gui.EASING_OUTINBACK",
+      "gui.EASING_OUTINBOUNCE",
+      "gui.EASING_OUTINCIRC",
+      "gui.EASING_OUTINCUBIC",
+      "gui.EASING_OUTINELASTIC",
+      "gui.EASING_OUTINEXPO",
+      "gui.EASING_OUTINQUAD",
+      "gui.EASING_OUTINQUART",
+      "gui.EASING_OUTINQUINT",
+      "gui.EASING_OUTINSINE",
+      "gui.EASING_OUTQUAD",
+      "gui.EASING_OUTQUART",
+      "gui.EASING_OUTQUINT",
+      "gui.EASING_OUTSINE",
+    ],
+  },
+  {
+    home: "gui",
+    name: "KeyboardType",
+    members: [
+      "gui.KEYBOARD_TYPE_DEFAULT",
+      "gui.KEYBOARD_TYPE_EMAIL",
+      "gui.KEYBOARD_TYPE_NUMBER_PAD",
+      "gui.KEYBOARD_TYPE_PASSWORD",
+    ],
+  },
+  {
+    home: "gui",
+    name: "NodeType",
+    members: [
+      "gui.TYPE_BOX",
+      "gui.TYPE_TEXT",
+      "gui.TYPE_PIE",
+      "gui.TYPE_PARTICLEFX",
+      "gui.TYPE_CUSTOM",
+    ],
+  },
+  {
+    home: "gui",
+    name: "PieBounds",
+    members: ["gui.PIEBOUNDS_RECTANGLE", "gui.PIEBOUNDS_ELLIPSE"],
+  },
+  {
+    home: "gui",
+    name: "Pivot",
+    members: [
+      "gui.PIVOT_CENTER",
+      "gui.PIVOT_N",
+      "gui.PIVOT_NE",
+      "gui.PIVOT_E",
+      "gui.PIVOT_SE",
+      "gui.PIVOT_S",
+      "gui.PIVOT_SW",
+      "gui.PIVOT_W",
+      "gui.PIVOT_NW",
+    ],
+  },
+  {
+    home: "gui",
+    name: "Playback",
+    members: [
+      "gui.PLAYBACK_ONCE_FORWARD",
+      "gui.PLAYBACK_ONCE_BACKWARD",
+      "gui.PLAYBACK_ONCE_PINGPONG",
+      "gui.PLAYBACK_LOOP_FORWARD",
+      "gui.PLAYBACK_LOOP_BACKWARD",
+      "gui.PLAYBACK_LOOP_PINGPONG",
+    ],
+  },
+  {
+    home: "gui",
+    name: "Property",
+    members: [
+      "gui.PROP_POSITION",
+      "gui.PROP_ROTATION",
+      "gui.PROP_EULER",
+      "gui.PROP_SCALE",
+      "gui.PROP_COLOR",
+      "gui.PROP_OUTLINE",
+      "gui.PROP_SHADOW",
+      "gui.PROP_SIZE",
+      "gui.PROP_FILL_ANGLE",
+      "gui.PROP_INNER_RADIUS",
+      "gui.PROP_LEADING",
+      "gui.PROP_TRACKING",
+      "gui.PROP_SLICE9",
+    ],
+  },
+  {
+    home: "gui",
+    name: "SafeAreaMode",
+    members: [
+      "gui.SAFE_AREA_NONE",
+      "gui.SAFE_AREA_LONG",
+      "gui.SAFE_AREA_SHORT",
+      "gui.SAFE_AREA_BOTH",
+    ],
+  },
+  {
+    home: "gui",
+    name: "SizeMode",
+    members: ["gui.SIZE_MODE_MANUAL", "gui.SIZE_MODE_AUTO"],
+  },
+  {
+    home: "gui",
+    name: "XAnchor",
+    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_LEFT", "gui.ANCHOR_RIGHT"],
+  },
+  {
+    home: "gui",
+    name: "YAnchor",
+    members: ["gui.ANCHOR_NONE", "gui.ANCHOR_TOP", "gui.ANCHOR_BOTTOM"],
+  },
+  {
+    home: "profiler",
+    name: "Mode",
+    members: [
+      "profiler.MODE_RUN",
+      "profiler.MODE_PAUSE",
+      "profiler.MODE_SHOW_PEAK_FRAME",
+      "profiler.MODE_RECORD",
+    ],
+  },
+  {
+    home: "profiler",
+    name: "ViewMode",
+    members: ["profiler.VIEW_MODE_FULL", "profiler.VIEW_MODE_MINIMIZED"],
+  },
+  {
+    home: "render",
+    name: "ClearBufferKey",
+    members: [
+      "graphics.BUFFER_TYPE_COLOR0_BIT",
+      "graphics.BUFFER_TYPE_DEPTH_BIT",
+      "graphics.BUFFER_TYPE_STENCIL_BIT",
+    ],
+  },
+  {
+    home: "sys",
+    name: "NetworkConnectivity",
+    members: [
+      "sys.NETWORK_DISCONNECTED",
+      "sys.NETWORK_CONNECTED_CELLULAR",
+      "sys.NETWORK_CONNECTED",
+    ],
+  },
+  {
+    home: "window",
+    name: "DimModeState",
+    members: ["window.DIMMING_UNKNOWN", "window.DIMMING_ON", "window.DIMMING_OFF"],
+  },
+  {
+    home: "window",
+    name: "DimModeStateSettable",
+    members: ["window.DIMMING_ON", "window.DIMMING_OFF"],
+  },
+];
+
+const CONSTANT_UNION_ALIAS_BY_MEMBERS: ReadonlyMap<string, ConstantUnionAlias> = new Map(
+  CONSTANT_UNION_ALIASES.map((row) => [constantUnionAliasKey(row.members), row] as const),
+);
+
+function constantUnionAliasKey(members: readonly string[]): string {
+  return [...new Set(members)].sort().join("\u0000");
+}
+
+// The alias naming exactly these constants, or undefined when no row does. A
+// single constant is never aliased: it already has a name.
+export function constantUnionAlias(fqns: readonly string[]): ConstantUnionAlias | undefined {
+  if (fqns.length < 2) return undefined;
+  return CONSTANT_UNION_ALIAS_BY_MEMBERS.get(constantUnionAliasKey(fqns));
+}
+
+// The alias declarations a module owns, in name order. A row is declared in its
+// home whether or not that module references it, so a cross-namespace row is
+// reachable from the module whose signatures spell it.
+export function constantUnionAliasDeclarations(namespace: string): string[] {
+  return CONSTANT_UNION_ALIASES.filter((row) => row.home === namespace)
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (row) => `type ${row.name} = ${row.members.map((member) => `typeof ${member}`).join(" | ")};`,
+    );
+}
+
 const DOC_CONSTANT_TOKEN =
   /(?<![A-Za-z0-9_.])([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*\.[A-Z][A-Z0-9_]*)(\*)?/g;
 
@@ -675,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:
@@ -906,8 +1584,8 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // 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.
+  // The key set is a CONSTANT_UNION_ALIASES row, so the signature carries the
+  // `render.ClearBufferKey` alias rather than the three branded arms.
   [
     "render.clear:param:buffers",
     {
@@ -1380,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
@@ -1417,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([
@@ -1425,6 +2137,40 @@ 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
+// documents in full. Every other authored table here retypes, marks optional or
+// suppresses a slot the parser already recovered; this one supplies a member
+// upstream omits, leaving the documented fields parser-authoritative so an
+// upstream edit to any of them lands without a hand-maintained restatement.
+//
+// `evidence` pins where upstream itself shows the field. applyFieldAdditions
+// throws once the parse recovers it, so upstream documenting the field reds
+// here and the entry is deleted rather than re-pinned.
+//
+// Keyed `<element>:<kind>:<slot>`, the TABLE_SLOT_CURATIONS shape.
+export interface TableFieldAddition {
+  readonly field: TableField;
+  readonly evidence: readonly string[];
+}
+
+export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition> = new Map([
+  [
+    "resource.create_texture:param:table",
+    {
+      field: { name: "page_count", types: ["number"], optional: true },
+      evidence: [
+        "the array-texture example on this element creates with `page_count = 5`",
+        "resource.get_texture_info documents `page_count` as the texture array's page count",
+      ],
+    },
+  ],
 ]);
 
 // A return-slot field upstream documents as platform-gated or nil-valued while
@@ -1516,6 +2262,26 @@ export function applyFieldOptionalityCorrections(
   return corrected;
 }
 
+// Append the member TABLE_SLOT_FIELD_ADDITIONS supplies for this slot, after
+// every field the parser recovered. Throws on an addition whose field the parse
+// already produced: upstream has documented it, and the entry is stale.
+// Returns a new array; never mutates the parser's result.
+export function applyFieldAdditions(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind === undefined || slotName === undefined) return [...fields];
+  const key = tableSlotKey(elementName, slotKind, slotName);
+  const addition = TABLE_SLOT_FIELD_ADDITIONS.get(key);
+  if (addition === undefined) return [...fields];
+  if (fields.some((field) => field.name === addition.field.name)) {
+    throw new Error(`field addition names a recovered field: ${key}:${addition.field.name}`);
+  }
+  return [...fields, addition.field];
+}
+
 // 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
@@ -1528,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 };
   });
 }
 
@@ -1864,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}.`;
 
@@ -1946,7 +2727,10 @@ 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}`);
   }
   const handleIndent = `${INDENT}${INDENT}`;
   for (const receiver of handleReceivers) {
@@ -1989,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))) {
@@ -2051,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}}`);
   }
@@ -2094,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}.`;
@@ -2134,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));
@@ -2218,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,
     });
   }
@@ -2230,7 +3044,20 @@ 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,
+    });
+  }
+
+  // The module's constant-union aliases travel as typedefs too: a signature that
+  // names one carries no member list of its own, so the docs read the members
+  // from here rather than from the emitter's table.
+  for (const row of CONSTANT_UNION_ALIASES.filter((r) => r.home === module.namespace)) {
+    out.push({
+      identity: { namespace: module.namespace, kind: "TYPEDEF", name: row.name, signature: "" },
+      tsSignature: `type ${row.name} = ${row.members
+        .map((member) => `typeof ${member}`)
+        .join(" | ")};`,
       slotTypes: NO_SLOTS,
     });
   }
@@ -2534,15 +3361,39 @@ 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 ?? "");
-  // A hand-authored TS translation pinned to this exact Lua flips the fence to
-  // ```ts; any hash mismatch (or absent translation) keeps the Lua fallback.
+  // A blob carrying several examples documents them as several, but only when
+  // every segment has an authored body: a partial resolve would drop the rest.
+  // Otherwise the whole-blob ladder stands — a hand-authored TS translation
+  // pinned to this exact Lua flips the fence to ```ts; any hash mismatch (or
+  // absent translation) keeps the Lua fallback.
+  const segments = splitExampleSources(fn.examples ?? "");
+  const perSegment =
+    segments.length > 1
+      ? lookupExampleTranslations(
+          translations,
+          fn.name,
+          segments.map((segment) => hashExampleSource(segment.code)),
+        )
+      : null;
   const ts = lua === "" ? null : lookupTranslation(translations, fn.name, hashExampleSource(lua));
-  const exampleParts: Pick<DocCommentParts, "example" | "exampleLang"> =
-    ts !== null ? { example: ts, exampleLang: "ts" } : lua !== "" ? { example: lua } : {};
+  const exampleParts: Pick<DocCommentParts, "examples"> =
+    perSegment !== null
+      ? {
+          examples: perSegment.map((text, index) => ({
+            text,
+            lang: "ts" as const,
+            ...(segments[index]?.prose ? { prose: segments[index]?.prose } : {}),
+          })),
+        }
+      : ts !== null
+        ? { examples: [{ text: ts, lang: "ts" }] }
+        : lua !== ""
+          ? { examples: [{ text: lua, lang: "lua" }] }
+          : {};
   const parts: DocCommentParts = {
     summary: htmlToDocText(summaryFor(fn.brief, fn.description)),
     params,
@@ -2641,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 = "...";
@@ -2802,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
@@ -2815,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
@@ -2880,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") {
@@ -2911,7 +3782,8 @@ function mapSlotUnion(
       } else {
         const parsed = parseTableFields(doc, resolver, slotName);
         if (parsed !== null) {
-          const nested = applyNestedFieldCurations(elementName, slotKind, slotName, parsed);
+          const added = applyFieldAdditions(elementName, slotKind, slotName, parsed);
+          const nested = applyNestedFieldCurations(elementName, slotKind, slotName, added);
           const typed = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
           const fields = applyFieldOptionalityCorrections(elementName, slotKind, slotName, typed);
           const object = inlineTableType(fields, mapType, optionalFields);
@@ -2940,7 +3812,7 @@ function mapSlotUnion(
   // every other union member, so collapse to exactly `unknown` rather than emit
   // a redundant `T | unknown` or `unknown | undefined`.
   if (mapped.includes("unknown")) return "unknown";
-  return mapped.join(" | ");
+  return joinUnionArms(mapped);
 }
 
 function tableSlotKey(elementName: string, slotKind: "param" | "return", slotName: string): string {
@@ -3030,7 +3902,36 @@ function unionFromTokens(tokens: readonly string[], mapType: (t: string) => stri
     seen.add(ts);
     mapped.push(ts);
   }
-  return mapped.join(" | ");
+  return joinUnionArms(mapped);
+}
+
+const BRAND_ARM = /^number & \{ readonly __brand: "([^"]+)" \}$/;
+
+// Joins already-mapped arms, collapsing the branded ones to their alias when
+// they are exactly a `CONSTANT_UNION_ALIASES` member set. The alias takes the
+// position of the first branded arm, so a mixed union keeps its reading order
+// (`gui.Easing | Vector`). Arms that are not constants are untouched, and a set
+// with no row keeps every arm inline.
+function joinUnionArms(mapped: readonly string[]): string {
+  const branded: string[] = [];
+  for (const arm of mapped) {
+    const match = BRAND_ARM.exec(arm);
+    if (match !== null) branded.push(match[1] as string);
+  }
+  const alias = constantUnionAlias(branded);
+  if (alias === undefined) return mapped.join(" | ");
+  const out: string[] = [];
+  let placed = false;
+  for (const arm of mapped) {
+    if (BRAND_ARM.test(arm)) {
+      if (placed) continue;
+      out.push(`${alias.home}.${alias.name}`);
+      placed = true;
+      continue;
+    }
+    out.push(arm);
+  }
+  return out.join(" | ");
 }
 
 export function isKnownDefoldTypeToken(token: string): boolean {