@defold-typescript/types 0.40.0 → 0.42.0

package/src/api-identity.ts

@@ -0,0 +1,252 @@
+import type { ApiFunction, ApiModule, ApiParameter } from "./api-doc";
+import { DEFOLD_TYPE_MAP } from "./core-types";
+import { pinMatches } from "./correction-pins";
+import { splitTopLevel } from "./luals-type-expr";
+
+/**
+ * A type correction as identity applies it: where the slot still declares one of
+ * `pins`, its values are the declared ones less `removes` plus `adds`, or
+ * `replaces` outright. Every list is written in ref-doc or TypeScript spelling;
+ * both canonicalize to the same values.
+ */
+export interface IdentityCorrection {
+  readonly pins: readonly (readonly string[])[];
+  readonly adds?: readonly string[];
+  readonly removes?: readonly string[];
+  readonly replaces?: readonly string[];
+  /** A return correction's slot name, when it rewrites one of several returns. */
+  readonly slot?: string;
+}
+
+/**
+ * The corrections this repo records from verified engine behavior. Identity
+ * follows them rather than each release's markup, so a release whose ref-doc
+ * starts stating what a correction already did is not a change.
+ */
+export interface IdentityCorrections {
+  /** `<element>:param:<slot>` keys a correction makes optional. */
+  readonly optionalSlots: readonly string[];
+  /** `<element>:param:<slot>` keys a correction keeps required. */
+  readonly requiredSlots: readonly string[];
+  /** Keyed `<element>:param:<slot>`. */
+  readonly parameterCorrections: Readonly<Record<string, IdentityCorrection>>;
+  /** Keyed by element. */
+  readonly returnCorrections: Readonly<Record<string, IdentityCorrection>>;
+  /** Constant-family aliases a correction may name (`window.DimModeStateSettable`), with members. */
+  readonly constantFamilies: Readonly<Record<string, readonly string[]>>;
+}
+
+/**
+ * The names a ref-doc type token may refer to, gathered across every committed
+ * target so each release's spelling resolves the same way, plus the corrections.
+ * A name keeps its kind across releases: a 1.13.2 `STRUCT` is a table wherever
+ * it appears.
+ */
+export interface IdentityVocabulary extends Omit<IdentityCorrections, "constantFamilies"> {
+  /** `STRUCT` names: a table at runtime. */
+  readonly tables: readonly string[];
+  /** `ENUM` names and constant families, with the runtime type of their members. */
+  readonly enums: Readonly<Record<string, "number" | "string">>;
+  /** Constants whose value is a string; every other constant is a number. */
+  readonly stringConstants: readonly string[];
+  /** Non-handle `TYPEDEF` names and the tokens they alias. */
+  readonly aliases: Readonly<Record<string, readonly string[]>>;
+}
+
+export const NO_IDENTITY_CORRECTIONS: IdentityCorrections = {
+  optionalSlots: [],
+  requiredSlots: [],
+  parameterCorrections: {},
+  returnCorrections: {},
+  constantFamilies: {},
+};
+
+const sortedRecord = <T>(entries: Iterable<[string, T]>): Record<string, T> =>
+  Object.fromEntries([...entries].sort(([a], [b]) => a.localeCompare(b)));
+
+export function buildIdentityVocabulary(
+  modules: readonly ApiModule[],
+  corrections: IdentityCorrections = NO_IDENTITY_CORRECTIONS,
+): IdentityVocabulary {
+  const tables = new Set<string>();
+  const stringConstants = new Set<string>();
+  const aliases = new Map<string, readonly string[]>();
+  const enumMembers = new Map<string, readonly string[]>(
+    Object.entries(corrections.constantFamilies),
+  );
+  for (const module of modules) {
+    for (const struct of module.structs ?? []) tables.add(struct.name);
+    for (const constant of module.constants) {
+      if (constant.valueType === "string") stringConstants.add(constant.name);
+    }
+    for (const enumeration of module.enums ?? []) {
+      enumMembers.set(enumeration.name, enumeration.members);
+    }
+    for (const typedef of module.typedefs) {
+      const aliasOf = typedef.aliasOf;
+      if (aliasOf === undefined || (aliasOf.length === 1 && aliasOf[0] === "userdata")) continue;
+      aliases.set(typedef.name, aliasOf);
+    }
+  }
+  const enums = [...enumMembers].map(([name, members]): [string, "number" | "string"] => [
+    name,
+    members.length > 0 && members.every((member) => stringConstants.has(member))
+      ? "string"
+      : "number",
+  ]);
+  return {
+    tables: [...tables].sort(),
+    enums: sortedRecord(enums),
+    stringConstants: [...stringConstants].sort(),
+    aliases: sortedRecord(aliases),
+    optionalSlots: [...corrections.optionalSlots].sort(),
+    requiredSlots: [...corrections.requiredSlots].sort(),
+    parameterCorrections: sortedRecord(Object.entries(corrections.parameterCorrections)),
+    returnCorrections: sortedRecord(Object.entries(corrections.returnCorrections)),
+  };
+}
+
+// Tokens a later release renamed without changing what they denote.
+const RENAMED_TOKENS: Readonly<Record<string, string>> = {
+  // 1.13.2 names the lifecycle callbacks' `self` after what it is.
+  script_instance: "userdata",
+};
+
+const CONSTANT_FQN = /^[a-z_][\w.]*\.[A-Z][A-Z0-9_]*$/;
+const NUMERIC_LITERAL = /^-?\d+(\.\d+)?$/;
+const STRING_LITERAL = /^(".*"|'.*')$/;
+// The TypeScript table types a correction writes.
+const TS_TABLE = /^(Record|LuaMap|ReadonlyLuaMap|LuaTable)\b/;
+
+function canonicalLeaves(
+  token: string,
+  vocabulary: IdentityVocabulary,
+  expanding: ReadonlySet<string>,
+): string[] {
+  const trimmed = token.trim();
+  const arms = splitTopLevel(trimmed, "|");
+  if (arms.length > 1) return arms.flatMap((arm) => canonicalLeaves(arm, vocabulary, expanding));
+  if (trimmed.endsWith("?")) {
+    return [...canonicalLeaves(trimmed.slice(0, -1), vocabulary, expanding), "nil"];
+  }
+  if (/^(fun|function)\b/.test(trimmed) || trimmed.includes("=>")) return ["function"];
+  if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
+    return canonicalLeaves(trimmed.slice(1, -1), vocabulary, expanding);
+  }
+  if (trimmed.startsWith("typeof ")) {
+    return canonicalLeaves(trimmed.slice("typeof ".length), vocabulary, expanding);
+  }
+  if (trimmed === "nil" || trimmed === "undefined") return ["nil"];
+  // Every table shape — a bare or typed `table`, a list, an inline record, a
+  // struct, a built-in message payload — is one Lua table at runtime; its
+  // documented fields are not part of what identifies the call.
+  if (
+    trimmed === "table" ||
+    trimmed.startsWith("table<") ||
+    trimmed.startsWith("{") ||
+    trimmed.endsWith("[]") ||
+    trimmed.startsWith("message.") ||
+    TS_TABLE.test(trimmed) ||
+    vocabulary.tables.includes(trimmed)
+  ) {
+    return ["table"];
+  }
+  if (STRING_LITERAL.test(trimmed)) return ["string"];
+  if (NUMERIC_LITERAL.test(trimmed)) return ["number"];
+  if (trimmed === "true" || trimmed === "false") return ["boolean"];
+  // An enum, one of its constants, or the untyped `constant` older releases
+  // wrote are all the value the engine registered: a number unless declared a
+  // string.
+  const enumType = vocabulary.enums[trimmed];
+  if (enumType !== undefined) return [enumType];
+  if (vocabulary.stringConstants.includes(trimmed)) return ["string"];
+  if (trimmed === "constant" || CONSTANT_FQN.test(trimmed)) return ["number"];
+  const aliasOf = vocabulary.aliases[trimmed];
+  if (aliasOf !== undefined && !expanding.has(trimmed)) {
+    const next = new Set(expanding).add(trimmed);
+    return aliasOf.flatMap((aliased) => canonicalLeaves(aliased, vocabulary, next));
+  }
+  const renamed = RENAMED_TOKENS[trimmed] ?? trimmed;
+  // Primitive synonyms (`integer` and `number`, `buffer_data` and `buffer`) are
+  // the tokens the engine vocabulary maps to one TypeScript type.
+  return [
+    Object.hasOwn(DEFOLD_TYPE_MAP, renamed)
+      ? ((DEFOLD_TYPE_MAP as Readonly<Record<string, string>>)[renamed] as string)
+      : renamed,
+  ];
+}
+
+/**
+ * A slot's ref-doc tokens in a vocabulary-neutral form: the runtime values the
+ * slot takes, sorted and without duplicates, so a release that only respells a
+ * slot keeps its identity while one that changes what it takes does not.
+ */
+export function canonicalIdentityTypes(
+  types: readonly string[],
+  vocabulary: IdentityVocabulary,
+): string[] {
+  return [
+    ...new Set(types.flatMap((token) => canonicalLeaves(token, vocabulary, new Set()))),
+  ].sort();
+}
+
+function correctedTypes(
+  types: readonly string[],
+  correction: IdentityCorrection | undefined,
+  vocabulary: IdentityVocabulary,
+): string[] {
+  if (correction === undefined || !pinMatches(types, correction.pins)) {
+    return canonicalIdentityTypes(types, vocabulary);
+  }
+  if (correction.replaces !== undefined) {
+    return canonicalIdentityTypes(correction.replaces, vocabulary);
+  }
+  const removed = new Set(canonicalIdentityTypes(correction.removes ?? [], vocabulary));
+  return [
+    ...new Set([
+      ...canonicalIdentityTypes(types, vocabulary).filter((value) => !removed.has(value)),
+      ...canonicalIdentityTypes(correction.adds ?? [], vocabulary),
+    ]),
+  ].sort();
+}
+
+export interface IdentitySlot {
+  readonly types: readonly string[];
+  readonly isOptional: boolean;
+}
+
+/** A parameter as identity reads it: its corrected values and effective optionality. */
+export function identityParameter(
+  fn: ApiFunction,
+  parameter: ApiParameter,
+  vocabulary: IdentityVocabulary,
+): IdentitySlot {
+  const key = `${fn.name}:param:${parameter.name}`;
+  const types = correctedTypes(parameter.types, vocabulary.parameterCorrections[key], vocabulary);
+  // A slot a correction keeps required may still take an explicit nil, which
+  // stays part of what it takes; anywhere else, taking nil is being omissible.
+  if (vocabulary.requiredSlots.includes(key)) return { types, isOptional: false };
+  return {
+    types: types.filter((value) => value !== "nil"),
+    isOptional:
+      parameter.isOptional || types.includes("nil") || vocabulary.optionalSlots.includes(key),
+  };
+}
+
+/** A return value as identity reads it, with a return correction applied where it holds. */
+export function identityReturn(
+  fn: ApiFunction,
+  returned: ApiParameter,
+  vocabulary: IdentityVocabulary,
+): IdentitySlot {
+  const correction = vocabulary.returnCorrections[fn.name];
+  const applies =
+    correction !== undefined &&
+    (correction.slot === undefined
+      ? fn.returnValues.length === 1
+      : correction.slot === returned.name);
+  return {
+    types: correctedTypes(returned.types, applies ? correction : undefined, vocabulary),
+    isOptional: returned.isOptional,
+  };
+}

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",
@@ -216,9 +220,8 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   constant: 'Opaque<"constant">',
   constant_buffer:
     'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }',
-  buffer: 'Opaque<"buffer">',
-  bufferstream:
-    'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }',
+  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
@@ -232,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>`
@@ -243,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/doc-comment.ts

@@ -39,6 +39,12 @@ 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,
@@ -57,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;
     }
@@ -66,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);
@@ -109,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.
@@ -161,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",
@@ -171,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,
@@ -223,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
@@ -303,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;
+}