@defold-typescript/types 0.39.0 → 0.41.0

package/src/core-types.ts

@@ -188,6 +188,10 @@ export interface Url {
   readonly fragment: Hash | undefined;
 }
 
+const BUFFER_TYPE = 'Opaque<"buffer">';
+const BUFFERSTREAM_TYPE =
+  'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }';
+
 export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   number: "number",
   int: "number",
@@ -214,9 +218,10 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   texture: 'Opaque<"texture">',
   render_target: 'Opaque<"render_target">',
   constant: 'Opaque<"constant">',
-  constant_buffer: 'Opaque<"constant_buffer">',
-  buffer: 'Opaque<"buffer">',
-  bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
+  constant_buffer:
+    'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }',
+  buffer: BUFFER_TYPE,
+  bufferstream: BUFFERSTREAM_TYPE,
   userdata: 'Opaque<"userdata">',
   // Vocabulary, not a shipped brand: no current ref-doc fixture types a slot
   // `resource`, so nothing hand-written may name `Opaque<"resource">`. Kept so a
@@ -230,6 +235,10 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   b2ContactEdge: 'Opaque<"b2ContactEdge">',
   b2MassData: 'Opaque<"b2MassData">',
   b2Transform: 'Opaque<"b2Transform">',
+  // bullet3d's collision-object functions also take a rigid body (its docs say
+  // so), so that handle's brand admits both; a rigid-body slot keeps its own.
+  btCollisionObject: 'Opaque<"btCollisionObject" | "btRigidBody">',
+  btRigidBody: 'Opaque<"btRigidBody">',
   b2BodyType:
     '(number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })',
   // socket handle types resolve to the method-bearing `interface <receiver>`
@@ -241,4 +250,20 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   server: "server",
   unconnected: "unconnected",
   any: "unknown",
+  // 1.13.2 renames of the leaves above, same slots. Upstream declares each only as
+  // a `userdata`/`number` handle TYPEDEF, so each keeps its 1.13.1 mapping, with
+  // two exceptions: `script_instance` is the untyped `self` a callback recovery
+  // emits, and `resource_data` (1.13.1 `resource`, only in the hand-authored
+  // `go.get`/`go.set`/`go.property` slots) is a path hash.
+  buffer_data: BUFFER_TYPE,
+  buffer_stream: BUFFERSTREAM_TYPE,
+  script_instance: "unknown",
+  resource_data: "Hash",
+  timer_handle: "number",
+  render_predicate: "number",
+  socket_client: "client",
+  socket_connected: "connected",
+  socket_master: "master",
+  socket_server: "server",
+  socket_unconnected: "unconnected",
 } as const;

package/src/correction-pins.ts

@@ -0,0 +1,49 @@
+// A slot-level type correction records the upstream spelling it contradicts
+// (`upstream`) and any later spelling of the same defect a newer release
+// declares (`retypedUpstream`). The emitter applies the correction only while
+// the slot being emitted still declares one of them, and the provenance tests
+// ask the same question of every retained target, so one table serves every
+// release and neither side can drift from the other.
+export interface PinnedCorrection {
+  readonly upstream: readonly string[];
+  readonly retypedUpstream?: readonly (readonly string[])[];
+}
+
+// `nil` is optionality, which `isDocOptional` owns (and, for a return, the
+// return lane's own `nil` verdict); a correction rewrites only the concrete
+// tokens, so only those are evidence.
+export function baseTokens(tokens: readonly string[]): string {
+  return tokens.filter((token) => token !== "nil").join("|");
+}
+
+export function correctionPins(correction: PinnedCorrection): readonly (readonly string[])[] {
+  return [correction.upstream, ...(correction.retypedUpstream ?? [])];
+}
+
+export function pinMatches(
+  declared: readonly string[],
+  pins: readonly (readonly string[])[],
+): boolean {
+  const base = baseTokens(declared);
+  return pins.some((pin) => baseTokens(pin) === base);
+}
+
+// A property pins the text of its `<span class="type">`, split the way
+// `parseProperty` splits it.
+export function spanTokens(span: string): string[] {
+  return span
+    .split("|")
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+}
+
+export interface PinnedPropertyCorrection {
+  readonly upstream: string;
+  readonly retypedUpstream?: readonly string[];
+}
+
+export function propertyCorrectionPins(
+  correction: PinnedPropertyCorrection,
+): readonly (readonly string[])[] {
+  return [correction.upstream, ...(correction.retypedUpstream ?? [])].map(spanTokens);
+}

package/src/custom-messages.d.ts

@@ -41,14 +41,15 @@ declare global {
   // diagnostic at the call site rather than the declaration.
   /**
    * The payload declared for a message id: its `BuiltinMessages` entry, else
-   * its `CustomMessages` entry, else the open record an undeclared id keeps.
-   * An id declared in both resolves to the built-in payload.
+   * its `CustomMessages` entry, else the open table an undeclared id keeps: a
+   * record or a Lua sequence. An id declared in both resolves to the built-in
+   * payload.
    */
   type MessagePayload<K> = K extends BuiltinMessageId
     ? BuiltinMessages[K]
     : K extends keyof CustomMessages
       ? CustomMessages[K]
-      : Record<string | number, unknown>;
+      : Record<string | number, unknown> | readonly unknown[];
 }
 
 export {};

package/src/doc-comment.ts

@@ -1,21 +1,50 @@
 const NAMED_ENTITIES: Record<string, string> = {
-  "&lt;": "<",
-  "&gt;": ">",
-  "&quot;": '"',
-  "&#39;": "'",
-  "&apos;": "'",
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  // A non-breaking space in JSDoc is invisible noise; a plain space reads the same.
+  nbsp: " ",
+  times: "×",
+  copy: "©",
+  mdash: "—",
+  ndash: "–",
+  hellip: "…",
+  middot: "·",
+  deg: "°",
+  plusmn: "±",
+  le: "≤",
+  ge: "≥",
+  ne: "≠",
+  rarr: "→",
+  larr: "←",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
 };
 
+// One pass over the text, so a character an entity decodes to (`&amp;` -> `&`)
+// is never read as the start of another entity.
 function decodeEntities(text: string): string {
-  let out = text;
-  for (const [entity, char] of Object.entries(NAMED_ENTITIES)) {
-    out = out.split(entity).join(char);
-  }
-  out = out.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
-  // `&amp;` last so an already-decoded `&` is never re-interpreted.
-  return out.split("&amp;").join("&");
+  return text.replace(/&(?:#[xX]([0-9a-fA-F]+)|#(\d+)|([a-zA-Z]+));/g, (entity, hex, dec, name) => {
+    if (hex !== undefined) return codePointOr(Number.parseInt(hex, 16), entity);
+    if (dec !== undefined) return codePointOr(Number(dec), entity);
+    return Object.hasOwn(NAMED_ENTITIES, name) ? (NAMED_ENTITIES[name] ?? entity) : entity;
+  });
+}
+
+function codePointOr(code: number, fallback: string): string {
+  return code <= 0x10ffff ? String.fromCodePoint(code) : fallback;
 }
 
+// One level of list nesting while `htmlToDocText` runs its whitespace pass,
+// which would otherwise strip leading spaces.
+const LIST_INDENT = "";
+const STRANDED_MARKER = /^(*)-$/;
+const LIST_ITEM = /^*- /;
+
 /**
  * Join a list marker left alone on its line back onto the item's first content
  * line. Upstream prose puts a newline between `<li>` and the item's first word,
@@ -34,7 +63,8 @@ function weldStrandedListMarkers(text: string): string {
       out.push(line);
       continue;
     }
-    if (inFence || line !== "-") {
+    const stranded = STRANDED_MARKER.exec(line);
+    if (inFence || !stranded) {
       out.push(line);
       continue;
     }
@@ -43,35 +73,90 @@ function weldStrandedListMarkers(text: string): string {
     const content = lines[ahead];
     if (
       content === undefined ||
-      content === "-" ||
-      content.startsWith("- ") ||
+      STRANDED_MARKER.test(content) ||
+      LIST_ITEM.test(content) ||
       content.startsWith("```")
     ) {
       // No value to weld onto — drop the marker and the blank run behind it.
       index = ahead - 1;
       continue;
     }
-    out.push(`- ${content}`);
+    out.push(`${stranded[1]}- ${content}`);
     index = ahead;
   }
   return out.join("\n").trim();
 }
 
+// Upstream Markdown indented one level too deep is highlighted as code while
+// still reading as Markdown: every line opens on a backtick-quoted name, as in
+// the field table `graphics.get_adapter_info` documents under `limits`. That
+// doc is replaced whole by a `DOC_CORRECTIONS` entry, so no vendored ref-doc
+// reaches this rule today. It is the fallback for when upstream rewords such a
+// doc without fixing it — the correction's hash stops matching and this still
+// yields a readable list, not a mislabelled `lua` fence — and for any other doc
+// that repeats the mistake.
+const MISREAD_MARKDOWN_LINE = /^\s*`[^`]+`/;
+
+// A `<pre>` body as Markdown. Misread Markdown becomes a bullet per line, its
+// `[type:X]` marker reduced to the bare type the way a `<span class="type">` is.
+// Otherwise it is a fence: a `<code>` inside marks highlighted source, Lua
+// unless its class names another language, and a bare `<pre>` is a
+// preformatted diagram. Upstream indents some samples by a uniform margin,
+// which is dropped.
+function preToMarkdown(inner: string): string {
+  const lines = htmlToCodeText(inner).split("\n");
+  const filled = lines.filter((line) => line.trim() !== "");
+  if (filled.every((line) => MISREAD_MARKDOWN_LINE.test(line))) {
+    return filled
+      .map(
+        (line) =>
+          `- ${line
+            .trim()
+            .replace(/\[type:([^\]]+)\]/g, "$1")
+            .replace(/\s+/g, " ")}`,
+      )
+      .join("\n");
+  }
+  const lang =
+    inner.match(/class="language-([A-Za-z0-9_+-]+)"/)?.[1] ??
+    (/<code\b/i.test(inner) ? "lua" : "text");
+  const margin = Math.min(
+    ...lines.filter((line) => line.trim() !== "").map((line) => line.match(/^ */)?.[0].length ?? 0),
+  );
+  const body = lines.map((line) => line.slice(Number.isFinite(margin) ? margin : 0)).join("\n");
+  return `\`\`\`${lang}\n${body}\n\`\`\``;
+}
+
 /**
  * Convert a ref-doc HTML fragment to clean Markdown/plain text suitable for a
  * JSDoc comment body. Pure and free of any `ApiModule` dependency so the emit
  * slices and any future surface can reuse it.
  */
 export function htmlToDocText(html: string): string {
+  // Lift each `<pre>` out before the whitespace pass, which would flatten an
+  // ASCII diagram or a code sample into one line, and put it back as Markdown.
+  const fences: string[] = [];
+  // A list item's marker carries one `LIST_INDENT` per enclosing list beyond
+  // the first, which the whitespace pass leaves alone; each becomes two spaces,
+  // the content column of the parent `- ` marker, once that pass is done.
+  let listDepth = 0;
   let text = html
+    .replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, (_, inner: string) => {
+      fences.push(preToMarkdown(inner));
+      return `\n\n\uE000${fences.length - 1}\uE000\n\n`;
+    })
     .replace(/<code>([\s\S]*?)<\/code>/gi, "`$1`")
     .replace(/<(?:em|i)>([\s\S]*?)<\/(?:em|i)>/gi, "*$1*")
     .replace(/<a\b[^>]*>([\s\S]*?)<\/a>/gi, "$1")
-    .replace(/<li>/gi, "\n- ")
-    .replace(/<\/li>/gi, "")
+    .replace(/<(\/?)(ul|ol|li)\b[^>]*>/gi, (_, close: string, tag: string) => {
+      if (tag.toLowerCase() !== "li") {
+        listDepth = Math.max(0, listDepth + (close ? -1 : 1));
+        return "";
+      }
+      return close ? "" : `\n${LIST_INDENT.repeat(Math.max(0, listDepth - 1))}- `;
+    })
     .replace(/<br\s*\/?>/gi, "\n")
     .replace(/<\/p>/gi, "\n\n")
-    .replace(/<\/?pre>/gi, "\n")
     .replace(/<[^>]+>/g, "");
 
   text = decodeEntities(text);
@@ -86,7 +171,12 @@ export function htmlToDocText(html: string): string {
     .replace(/\n{3,}/g, "\n\n")
     .trim();
 
-  text = weldStrandedListMarkers(text);
+  // A blank line between two items would make the list loose, spacing every
+  // item apart like a paragraph.
+  text = weldStrandedListMarkers(text)
+    .replace(/(?<=^*- .*)\n\n(?=*- )/gm, "\n")
+    .replaceAll(LIST_INDENT, "  ")
+    .replace(/\uE000(\d+)\uE000/g, (_, i: string) => fences[Number(i)] ?? "");
 
   // Upstream prose can open a fence and end mid-body; left open it swallows the
   // rest of the JSDoc block and everything after it on the rendered page.
@@ -138,7 +228,7 @@ function scanExampleRegions(html: string): { matched: boolean; regions: ExampleR
   let matched = false;
   for (let match = blocks.exec(html); match !== null; match = blocks.exec(html)) {
     matched = true;
-    regions.push({ kind: "prose", html: html.slice(lastIndex, match.index), lang: "lua" });
+    regions.push(...proseRegions(html.slice(lastIndex, match.index)));
     const inner = match[1] ?? "";
     regions.push({
       kind: "code",
@@ -148,10 +238,28 @@ function scanExampleRegions(html: string): { matched: boolean; regions: ExampleR
     lastIndex = match.index + match[0].length;
   }
   if (!matched) return { matched: false, regions: [{ kind: "code", html, lang: "lua" }] };
-  regions.push({ kind: "prose", html: html.slice(lastIndex), lang: "lua" });
+  regions.push(...proseRegions(html.slice(lastIndex)));
   return { matched: true, regions };
 }
 
+// Upstream Markdown ```` ```lua ```` fences sometimes reach the ref-doc as
+// `<code>lua\n...</code>`: a language token, a newline, then source. Read as
+// prose it welds the code into the surrounding sentences, so each one is lifted
+// into a code region of its own. Inline `<code>` spans carry no such newline.
+const MANGLED_FENCE = /<code>([A-Za-z0-9_+-]+)\n([\s\S]*?)<\/code>/g;
+
+function proseRegions(html: string): ExampleRegion[] {
+  const regions: ExampleRegion[] = [];
+  let lastIndex = 0;
+  for (const match of html.matchAll(MANGLED_FENCE)) {
+    regions.push({ kind: "prose", html: html.slice(lastIndex, match.index), lang: "lua" });
+    regions.push({ kind: "code", html: match[2] ?? "", lang: match[1] ?? "lua" });
+    lastIndex = match.index + match[0].length;
+  }
+  regions.push({ kind: "prose", html: html.slice(lastIndex), lang: "lua" });
+  return regions;
+}
+
 /**
  * Convert a ref-doc `examples` HTML fragment — prose interleaved with one or
  * more `<div class="codehilite">…</div>` syntax-highlight blocks — into Markdown,
@@ -200,7 +308,8 @@ export interface ExampleSegmentation {
  * Carve an `examples` HTML fragment into one segment per example it carries.
  *
  * A `<div class="codehilite">` block is a code region and the markup between
- * two of them is a prose region; inside either, a ` ``` ` line switches between
+ * two of them is a prose region, less any mangled `<code>lang\n...</code>`
+ * fence lifted out of it as a code region; inside either, a ` ``` ` line switches between
  * code and prose, and an opener reached while already in code ends the running
  * example and starts the next. Upstream writes several examples both ways — as
  * several blocks, and as its own Markdown fences inside one block — so both
@@ -280,6 +389,13 @@ function trimBlankEdges(lines: readonly string[]): string[] {
   return out;
 }
 
+// Prefer the full `description`; fall back to the one-line `brief` when prose is
+// absent. Shared by every documented member kind so the summary source is
+// consistent across functions, constants, variables, and properties.
+export function summaryFor(brief: string, description: string): string {
+  return description.trim() !== "" ? description : brief;
+}
+
 export interface DocCommentParts {
   summary: string;
   // Present exactly when the source carried a deprecation tag; `""` is the bare

package/src/doc-corrections.ts

@@ -0,0 +1,108 @@
+import { fnv1a64 } from "./fnv1a";
+
+// A function slot whose upstream doc HTML is malformed badly enough to misread,
+// replaced wholesale with authored HTML that keeps upstream's wording, or a
+// property description that contradicts what the engine does. Each
+// entry is pinned by the FNV-1a hash of the exact upstream HTML it replaces: the
+// parse applies it only while the vendored doc still hashes to that value, so a
+// fixed or reworded upstream doc wins by itself, and
+// `doc-correction-provenance.test.ts` reds until the stale entry is deleted.
+//
+// Keyed `<function>#param:<name>`, `<function>#return:<name>`, or
+// `<namespace>#property:<name>` (the ref-doc `PROPERTY` element's bare name).
+export interface DocCorrection {
+  readonly upstreamHash: string;
+  readonly html: string;
+  readonly reason: string;
+}
+
+const li = (name: string, type: string, doc: string) =>
+  `<li><code>${name}</code> <span class="type">${type}</span> ${doc}</li>`;
+
+export const DOC_CORRECTIONS: ReadonlyMap<string, DocCorrection> = new Map([
+  [
+    "graphics.get_adapter_info#return:info",
+    {
+      upstreamHash: "77028e82ec2d15bd",
+      reason:
+        "script_graphics.cpp indents the field table as preformatted text: the top-level fields run together as one paragraph, and the `limits` and `features` sub-tables are highlighted as code",
+      html: [
+        "table with the following fields:",
+        "<ul>",
+        li("family", "string", 'adapter family name (e.g. "opengl", "vulkan")'),
+        li("version_major", "number", "adapter API major version (e.g. 1 for Vulkan 1.4)"),
+        li("version_minor", "number", "adapter API minor version (e.g. 4 for Vulkan 1.4)"),
+        `<li><code>limits</code> <span class="type">table</span> hardware/driver limits:<ul>`,
+        li("max_texture_size_2d", "number", "max 2D texture dimension in texels"),
+        li("max_texture_size_3d", "number", "max 3D (volume) texture dimension in texels"),
+        li("max_texture_size_cube", "number", "max cube map face dimension in texels"),
+        li("max_texture_array_layers", "number", "max layers in an array texture"),
+        li("max_framebuffer_width", "number", "max framebuffer width in pixels"),
+        li("max_framebuffer_height", "number", "max framebuffer height in pixels"),
+        li("max_color_attachments", "number", "max simultaneous color attachments"),
+        li("max_samplers_per_stage", "number", "max texture samplers per shader stage"),
+        li("max_textures_per_stage", "number", "max sampled textures per shader stage"),
+        li("max_vertex_attributes", "number", "max vertex attributes"),
+        li("max_vertex_buffers", "number", "max vertex buffer bindings"),
+        li("max_compute_workgroup_size_x", "number", "max compute workgroup size (X)"),
+        li("max_compute_workgroup_size_y", "number", "max compute workgroup size (Y)"),
+        li("max_compute_workgroup_size_z", "number", "max compute workgroup size (Z)"),
+        li("max_compute_workgroup_invocations", "number", "max invocations per compute workgroup"),
+        li(
+          "max_compute_shared_memory_size",
+          "number",
+          "max shared memory per compute workgroup (bytes)",
+        ),
+        li("max_uniform_buffer_range", "number", "max bindable uniform buffer range (bytes)"),
+        li("max_storage_buffer_range", "number", "max bindable storage buffer range (bytes)"),
+        "</ul></li>",
+        li("extensions", "table", "array of driver-reported extension name strings"),
+        `<li><code>features</code> <span class="type">table</span> array of supported context feature ids:<ul>`,
+        "<li><code>graphics.CONTEXT_FEATURE_MULTI_TARGET_RENDERING</code> multi-target rendering</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_TEXTURE_ARRAY</code> texture arrays</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_COMPUTE_SHADER</code> compute shaders</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_STORAGE_BUFFER</code> storage buffers</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_VSYNC</code> vertical sync</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_INSTANCING</code> hardware instancing</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_3D_TEXTURES</code> 3D (volume) textures</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_ASTC_ARRAY_TEXTURES</code> ASTC compressed 2D array textures</li>",
+        "<li><code>graphics.CONTEXT_FEATURE_BLEND_EQUATION_MIN_MAX</code> min/max blend equations</li>",
+        "</ul></li>",
+        "</ul>",
+      ].join("\n"),
+    },
+  ],
+  [
+    "go#property:scale",
+    {
+      upstreamHash: "a7f5ba1b125d1fae",
+      reason:
+        "upstream calls it a uniform number, but the engine reads a vector3 back from `go.get` and applies a written number as a uniform scale",
+      html: "The scale of the game object. <code>go.get</code> returns a vector3; <code>go.set</code> and <code>go.animate</code> also take a number, which sets a uniform scale.",
+    },
+  ],
+  [
+    "label#property:scale",
+    {
+      upstreamHash: "5a15760073a8629d",
+      reason:
+        'upstream says a number is accepted, but `go.set` raises "must be a vmath.vector3" on one; only `go.animate` takes a number',
+      html: "The scale of the label. <code>go.get</code> returns and <code>go.set</code> takes a vector3; <code>go.animate</code> also takes a number, which sets a uniform scale.",
+    },
+  ],
+]);
+
+export function docCorrectionKey(
+  owner: string,
+  slot: "param" | "return" | "property",
+  name: string,
+): string {
+  return `${owner}#${slot}:${name}`;
+}
+
+// The slot's doc with its correction applied, or `doc` itself when the slot has
+// no entry or upstream no longer matches the pinned hash.
+export function correctedDoc(key: string, doc: string): string {
+  const correction = DOC_CORRECTIONS.get(key);
+  return correction && fnv1a64(doc) === correction.upstreamHash ? correction.html : doc;
+}

package/src/editor-vm-globals.d.ts

@@ -19,6 +19,9 @@ import type {
 // sitting before a required one, or an empty `returnvalues` on a function
 // upstream's own prose says returns a value — are written out here as overload
 // sets. All three are withheld from the emit by `EDITOR_VM_SKIP_FUNCTIONS`. The
+// constant tables are VARIABLEs in 1.13.1; in 1.13.2 `zip.METHOD.*` and
+// `zip.ON_CONFLICT.*` are ENUM members and `http.server.*` are CONSTANTs, and the
+// entry's skip rules withhold them in every one of those shapes. The
 // contract is unchanged and still derived: this file declares exactly what the
 // emit leaves behind. The namespaces below merge with the emitted
 // `generated/editor-vm/` bodies rather than replacing them. Upstream records no
@@ -26,9 +29,9 @@ import type {
 
 declare global {
   /**
-   * Pretty-print a Lua value
+   * Pretty-print Lua values
    */
-  function pprint(value: unknown): void;
+  function pprint(...values: unknown[]): void;
 
   namespace http {
     namespace server {