@defold-typescript/types 0.39.0 → 0.41.0

package/src/luals-type-expr.ts

@@ -0,0 +1,354 @@
+/**
+ * The structural half of the LuaLS type-expression grammar (unions, `?`, `T[]`,
+ * grouping parentheses, `fun(...)`, `table<K, V>`, inline records, string, numeric
+ * and boolean literals), shared by the engine lane (`emit-dts.ts`
+ * `defaultMapType`) and the library lane
+ * (`packages/library-types/scripts/map-luals-types.ts`). Pure and deterministic.
+ *
+ * Every name that is not structure — `integer`, `table`, `function`, `...`,
+ * `vmath.vector3`, `druid.component` — is a leaf handed to the caller's
+ * `resolveLeaf`, so each lane keeps its own vocabulary and precedence. A leaf the
+ * resolver answers `undefined` for lowers to `unknown` and is reported in
+ * `unknowns`.
+ */
+
+import { luaMultiReturn } from "./library-signature";
+
+export type LualsLeafResolver = (leaf: string) => string | undefined;
+
+/**
+ * Who supplies the value a type describes: `"input"` for a slot the caller fills
+ * (a parameter, a field of a table passed as one, a callback's return), `"output"`
+ * for one the engine or library hands back (a return, a property read back, a
+ * callback's parameters). Only `"input"` widens a string-keyed `table<K, V>` to also
+ * accept an object literal, so `"output"` renders exactly what an unpositioned
+ * mapping does.
+ */
+export type LualsPosition = "input" | "output";
+
+export interface LualsMapResult {
+  ts: string;
+  unknowns: string[];
+}
+
+/**
+ * LuaLS's throwaway param name `_` declares no type at all, so lowering it to
+ * `unknown` loses nothing an author wrote. An untyped `self` or `ctx` *is* an
+ * upstream omission and stays recorded.
+ */
+const LUALS_THROWAWAY_PARAM = "_";
+export const LUALS_VARARG_TOKEN = "...";
+
+const NUMERIC_LITERAL = /^-?\d+(\.\d+)?$/;
+const TUPLE_KEY = /^\[(\d+)\](\??)$/;
+const INDEX_KEY = /^\[(.+)\]\??$/;
+
+/**
+ * Split `s` on every top-level occurrence of the single-character `sep`, honoring
+ * bracket depth and double-quoted string literals so a separator nested inside
+ * `<...>`, `(...)`, `[...]`, `{...}`, or a `"..."` literal does not split.
+ */
+export function splitTopLevel(s: string, sep: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let inQuote = false;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) {
+      if (c === '"') inQuote = false;
+      continue;
+    }
+    if (c === '"') inQuote = true;
+    else if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c === sep) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts;
+}
+
+/** Index of the matching close bracket for the opener at `open`, or -1 if unbalanced. */
+export function matchBracket(s: string, open: number): number {
+  const closers: Record<string, string> = { "<": ">", "(": ")", "[": "]", "{": "}" };
+  const want = closers[s[open] as string];
+  let depth = 0;
+  let inQuote = false;
+  for (let i = open; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) {
+      if (c === '"') inQuote = false;
+      continue;
+    }
+    if (c === '"') inQuote = true;
+    else if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") {
+      depth--;
+      if (depth === 0) return c === want ? i : -1;
+    }
+  }
+  return -1;
+}
+
+function isWrappedInParens(s: string): boolean {
+  return s.startsWith("(") && matchBracket(s, 0) === s.length - 1;
+}
+
+/** True when a top-level `=>` (an arrow function type) appears in a mapped result. */
+function hasTopLevelArrow(tsExpr: string): boolean {
+  let depth = 0;
+  for (let i = 0; i + 1 < tsExpr.length; i++) {
+    const c = tsExpr[i];
+    if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c === "=" && tsExpr[i + 1] === ">") return true;
+  }
+  return false;
+}
+
+/** A union member needs parentheses when it is itself a function type. */
+function wrapForUnion(tsExpr: string): string {
+  return hasTopLevelArrow(tsExpr) ? `(${tsExpr})` : tsExpr;
+}
+
+/** An array element needs parentheses when it is a union, a function, or an object. */
+export function needsArrayParens(tsExpr: string): boolean {
+  return (
+    splitTopLevel(tsExpr, "|").length > 1 || hasTopLevelArrow(tsExpr) || tsExpr.startsWith("{")
+  );
+}
+
+/**
+ * `LuaTable<K, V>` constrains `K` to `AnyNotNil`, so a mapped key that admits nil is
+ * not a compilable key however faithfully it renders the annotation. LuaLS `any` maps
+ * to `unknown` everywhere else, and `nil` to `undefined`; in key position both fail the
+ * constraint and `tsc` rejects the emitted declaration. `AnyNotNil` is the faithful
+ * target — "any non-nil Lua value" is exactly what a table key may be — so drop a nil
+ * arm from a key union and fall back to `AnyNotNil` when nothing survives.
+ */
+function luaTableKey(mapped: string): string {
+  const arms = splitTopLevel(mapped, "|")
+    .map((arm) => arm.trim())
+    .filter((arm) => arm !== "undefined" && arm !== "unknown");
+  return arms.length === 0 ? "AnyNotNil" : arms.join(" | ");
+}
+
+/**
+ * TSTL's `LuaTable` is built with `new LuaTable()`, so an object literal is not
+ * assignable to it although both compile to the same Lua table. A caller-supplied
+ * table whose key admits `string` (`AnyNotNil` does) also takes
+ * `Record<string, V>`; a `Hash` or numeric key cannot be spelled as an object
+ * literal's key, so it takes only a Lua table.
+ */
+function acceptsObjectLiteral(key: string): boolean {
+  return splitTopLevel(key, "|").some((arm) => ["string", "AnyNotNil"].includes(arm.trim()));
+}
+
+interface Walk {
+  resolveLeaf: LualsLeafResolver;
+  unknowns: string[];
+  position: LualsPosition;
+}
+
+/**
+ * The mapped `(params)` list and `ret` type of a `fun(...)` token, shared by the
+ * arrow form and the colon-return call signature. A return list wrapped in one pair
+ * of parentheses (`fun(): (a, b)`) is the same multi-return as the bare `fun(): a, b`.
+ */
+function functionParts(token: string, walk: Walk): { paramList: string; ret: string } {
+  const open = token.indexOf("(");
+  const close = matchBracket(token, open);
+  const paramsStr = token.slice(open + 1, close).trim();
+  const afterClose = token.slice(close + 1).trim();
+
+  const params = paramsStr === "" ? [] : splitTopLevel(paramsStr, ",");
+  // A callback's params are values the engine hands over. A returned or stored
+  // function's params keep `"output"` too: widening them would reject a callback
+  // with the narrower `LuaTable` param a caller assigns to a writable field.
+  const paramWalk: Walk = { ...walk, position: "output" };
+  const paramList = params
+    .map((raw) => raw.trim())
+    .map((part) => {
+      if (part.startsWith(LUALS_VARARG_TOKEN)) {
+        const after = part.slice(3).trim();
+        const element = after.startsWith(":")
+          ? mapToken(after.slice(1).trim(), paramWalk)
+          : "unknown";
+        return `...args: ${needsArrayParens(element) ? `(${element})[]` : `${element}[]`}`;
+      }
+      const colon = splitTopLevel(part, ":");
+      if (colon.length < 2) {
+        if (part !== LUALS_THROWAWAY_PARAM) walk.unknowns.push(part);
+        return `${part}: unknown`;
+      }
+      const name = colon[0]?.trim() ?? "";
+      const typeExpr = colon.slice(1).join(":").trim();
+      return `${name}: ${mapToken(typeExpr, paramWalk)}`;
+    })
+    .join(", ");
+
+  let ret = "void";
+  if (afterClose.startsWith(":")) {
+    const retStr = afterClose.slice(1).trim();
+    let retTokens = retStr === "" ? [] : splitTopLevel(retStr, ",").map((r) => r.trim());
+    if (retTokens.length === 1 && isWrappedInParens(retStr)) {
+      const grouped = splitTopLevel(retStr.slice(1, -1), ",").map((r) => r.trim());
+      if (grouped.length > 1) retTokens = grouped;
+    }
+    if (retTokens.length === 1) {
+      ret = mapToken(retTokens[0] as string, walk);
+    } else if (retTokens.length > 1) {
+      const restTail = retTokens.at(-1) === LUALS_VARARG_TOKEN;
+      ret = luaMultiReturn(
+        retTokens.map((r) => mapToken(r, walk)),
+        restTail,
+      );
+    }
+  }
+  return { paramList, ret };
+}
+
+/**
+ * An inline record. A numeric `[N]` key is a tuple slot and renders as the property
+ * key `N`. Any other `[K]` key is an index signature; TypeScript accepts only
+ * `string`/`number` there, so it renders as a `string` index when `K` maps to
+ * `string` and a `number` index otherwise (the upstream instance keys a numeric
+ * enum), intersected with the named entries. The key's own leaves never reach the
+ * output, so they are not reported.
+ */
+function mapObject(token: string, walk: Walk): string {
+  const inner = token.slice(1, -1).trim();
+  if (inner === "") return "{}";
+  const entries: string[] = [];
+  const indexes: string[] = [];
+  for (const part of splitTopLevel(inner, ",")) {
+    const trimmed = part.trim();
+    if (trimmed.length === 0) continue;
+    const colon = splitTopLevel(trimmed, ":");
+    const key = colon[0]?.trim() ?? "";
+    const value = mapToken(colon.slice(1).join(":").trim(), walk);
+    const tuple = TUPLE_KEY.exec(key);
+    if (tuple !== null) {
+      entries.push(`${tuple[1]}${tuple[2]}: ${value}`);
+      continue;
+    }
+    const index = INDEX_KEY.exec(key);
+    if (index !== null) {
+      const keyType = mapToken(index[1] as string, { ...walk, unknowns: [] });
+      indexes.push(`{ [key: ${keyType === "string" ? "string" : "number"}]: ${value} }`);
+      continue;
+    }
+    entries.push(`${key}: ${value}`);
+  }
+  const parts = entries.length > 0 || indexes.length === 0 ? [`{ ${entries.join("; ")} }`] : [];
+  return [...parts, ...indexes].join(" & ");
+}
+
+function mapToken(raw: string, walk: Walk): string {
+  let token = raw.trim();
+
+  // Strip a redundant pair of outer parentheses (LuaLS grouping) so `(a | b)[]`
+  // reaches the union handler rather than falling through to a leaf lookup.
+  while (isWrappedInParens(token)) {
+    token = token.slice(1, -1).trim();
+  }
+
+  if (token === "") return "unknown";
+
+  // A `fun(...)` whose return follows the `)` keeps its return-type `|` and `?` inside
+  // the function; splitting the union first would cut `fun(): a|b` into `(fun) | b`, and
+  // peeling the optional suffix first would turn `fun(): number?` — a function with an
+  // optional *return* — into an optional function. The whole-function optional is spelled
+  // with explicit parentheses, `(fun(): number)?`, which does not match here.
+  // `fun()|nil` (a `|` right after the `)`) falls through to the union split.
+  if (/^fun\s*\(/.test(token)) {
+    const close = matchBracket(token, token.indexOf("("));
+    const afterClose = close === -1 ? "" : token.slice(close + 1).trim();
+    if (close !== -1 && afterClose.startsWith(":")) {
+      return mapFunction(token, walk);
+    }
+  }
+
+  // Optional suffix.
+  if (token.length > 1 && token.endsWith("?")) {
+    const base = mapToken(token.slice(0, -1), walk);
+    const members = splitTopLevel(base, "|").map((m) => m.trim());
+    return members.includes("undefined") ? base : `${wrapForUnion(base)} | undefined`;
+  }
+
+  // Top-level union.
+  const unionParts = splitTopLevel(token, "|");
+  if (unionParts.length > 1) {
+    return unionParts.map((p) => wrapForUnion(mapToken(p.trim(), walk))).join(" | ");
+  }
+
+  // Trailing array.
+  if (token.endsWith("[]")) {
+    const element = mapToken(token.slice(0, -2), walk);
+    return needsArrayParens(element) ? `(${element})[]` : `${element}[]`;
+  }
+
+  if (/^fun\s*\(/.test(token)) return mapFunction(token, walk);
+
+  if (token.startsWith("table<") && token.endsWith(">")) {
+    const args = splitTopLevel(token.slice(6, -1), ",").map((a) => mapToken(a.trim(), walk));
+    if (args.length > 0) args[0] = luaTableKey(args[0] as string);
+    // A caller may build the table with either TSTL constructor. `LuaMap` takes
+    // both, since a `LuaTable` is assignable to it; the engine hands back a
+    // `LuaTable`, which a caller may still store as a `LuaMap`.
+    if (walk.position !== "input") return `LuaTable<${args.join(", ")}>`;
+    const table = `LuaMap<${args.join(", ")}>`;
+    const [key, value] = args;
+    if (args.length === 2 && acceptsObjectLiteral(key as string)) {
+      return `${table} | Record<string, ${value}>`;
+    }
+    return table;
+  }
+
+  if (token.startsWith("{") && token.endsWith("}")) return mapObject(token, walk);
+
+  if (token.startsWith('"') && token.endsWith('"')) return token;
+  if (NUMERIC_LITERAL.test(token) || token === "true" || token === "false") return token;
+
+  const leaf = walk.resolveLeaf(token);
+  if (leaf !== undefined) return leaf;
+  walk.unknowns.push(token);
+  return "unknown";
+}
+
+function mapFunction(token: string, walk: Walk): string {
+  const { paramList, ret } = functionParts(token, walk);
+  return `(${paramList}) => ${ret}`;
+}
+
+/** Map one raw LuaLS type expression to a TypeScript type string. */
+export function mapLualsExpression(
+  token: string,
+  resolveLeaf: LualsLeafResolver,
+  position: LualsPosition = "output",
+): LualsMapResult {
+  const walk: Walk = { resolveLeaf, unknowns: [], position };
+  return { ts: mapToken(token, walk), unknowns: walk.unknowns };
+}
+
+/**
+ * Map a `fun(...)` expression to a TypeScript **call signature** — the colon-return
+ * form `(params): ret` an interface uses to become callable, not the `=>` arrow a
+ * field or param function type takes. Throws on a non-`fun` token.
+ */
+export function mapLualsCallSignatureExpression(
+  token: string,
+  resolveLeaf: LualsLeafResolver,
+  position: LualsPosition = "output",
+): LualsMapResult {
+  const trimmed = token.trim();
+  if (!/^fun\s*\(/.test(trimmed)) {
+    throw new Error(`mapLualsCallSignature: expected a "fun(...)" token, got "${token}".`);
+  }
+  const walk: Walk = { resolveLeaf, unknowns: [], position };
+  const { paramList, ret } = functionParts(trimmed, walk);
+  return { ts: `(${paramList}): ${ret}`, unknowns: walk.unknowns };
+}

package/src/msg-overloads.d.ts

@@ -48,7 +48,6 @@ declare global {
      * The following receiver shorthands are available:
      *
      * - `"."` the current game object
-     *
      * - `"#"` the current component
      *
      * There is a 2 kilobyte limit to the message parameter table size.

package/src/param-correction-provenance.ts

@@ -0,0 +1,64 @@
+import { type ApiModule, parseDefoldApiDoc } from "./api-doc";
+import { correctionPins, pinMatches } from "./correction-pins";
+import type { ParamTypeCorrection } from "./emit-dts";
+import type { ProvenanceSurface } from "./optional-correction-provenance";
+
+export interface ParamTypeProvenance {
+  readonly key: string;
+  readonly sightedIn: readonly string[];
+  readonly neededBy: readonly string[];
+  readonly resolvedIn: readonly string[];
+}
+
+const PARAM_SEPARATOR = ":param:";
+
+// A target needs a correction while any declaration of the slot there still
+// states one of its pins, so an overload that shows the defect keeps it alive.
+// `nil` is optionality, which `isDocOptional` owns, so `pinMatches` compares
+// only the concrete tokens. Any other declared token set — fixed, or retyped
+// without a `retypedUpstream` pin — no longer carries the contradiction the
+// entry records, and the entry goes once no target needs it.
+export function paramCorrectionProvenance(
+  entries: readonly [string, ParamTypeCorrection][],
+  surfaces: readonly ProvenanceSurface[],
+): ParamTypeProvenance[] {
+  const parsed = new Map<ProvenanceSurface, ApiModule>();
+  const parse = (surface: ProvenanceSurface): ApiModule => {
+    let module = parsed.get(surface);
+    if (!module) {
+      module = parseDefoldApiDoc(surface.doc);
+      parsed.set(surface, module);
+    }
+    return module;
+  };
+
+  return entries.map(([key, correction]) => {
+    const separator = key.lastIndexOf(PARAM_SEPARATOR);
+    if (separator < 0) throw new Error(`paramCorrectionProvenance: malformed key ${key}`);
+    const element = key.slice(0, separator);
+    const slot = key.slice(separator + PARAM_SEPARATOR.length);
+    const namespace = element.slice(0, element.lastIndexOf("."));
+    const pins = correctionPins(correction);
+
+    const neededByTarget = new Map<string, boolean>();
+    for (const surface of surfaces) {
+      if (surface.namespace !== namespace) continue;
+      for (const fn of parse(surface).functions) {
+        if (fn.name !== element) continue;
+        for (const parameter of fn.parameters) {
+          if (parameter.name !== slot) continue;
+          const needed = neededByTarget.get(surface.target) ?? false;
+          neededByTarget.set(surface.target, needed || pinMatches(parameter.types, pins));
+        }
+      }
+    }
+
+    const sightedIn = [...neededByTarget.keys()].sort();
+    return {
+      key,
+      sightedIn,
+      neededBy: sightedIn.filter((target) => neededByTarget.get(target) === true),
+      resolvedIn: sightedIn.filter((target) => neededByTarget.get(target) === false),
+    };
+  });
+}

package/src/return-correction-provenance.ts

@@ -3,6 +3,7 @@
 // evidence a return-side correction rests on lives in the slot's HTML prose and
 // the parser discards it.
 
+import { correctionPins, pinMatches } from "./correction-pins";
 import type { ReturnFieldOptionalityCorrection, ReturnTypeCorrection } from "./emit-dts";
 import type { ProvenanceSurface } from "./optional-correction-provenance";
 
@@ -87,6 +88,28 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// A slot that names a STRUCT (`sys.interface_info[]`) carries its fields as that
+// struct's members rather than a `<dl>`; a member name ending in `?` is the
+// struct's own optionality mark. True when the named struct marks `field`
+// optional.
+function structMarksOptional(doc: unknown, slot: RawSlot, field: string): boolean {
+  if (!isRecord(doc) || !Array.isArray(doc.elements)) return false;
+  const names = new Set(
+    (slot.types ?? [])
+      .filter((token) => token !== "nil")
+      .map((token) => token.replace(/\[\]$/, "")),
+  );
+  return doc.elements.some(
+    (candidate) =>
+      isRecord(candidate) &&
+      candidate.type === "STRUCT" &&
+      typeof candidate.name === "string" &&
+      names.has(candidate.name) &&
+      Array.isArray(candidate.members) &&
+      candidate.members.some((member) => isRecord(member) && member.name === `${field}?`),
+  );
+}
+
 // Every `returnvalues` entry of every FUNCTION in the surface named `element`,
 // unfiltered by slot: one target can declare the element more than once.
 function returnSlots(doc: unknown, element: string): RawSlot[] {
@@ -101,9 +124,10 @@ function returnSlots(doc: unknown, element: string): RawSlot[] {
   );
 }
 
-// The first `returnvalues` entry of each declaration of `element`, one per
-// declaration so a target that declares the element twice is folded, not sliced.
-function firstReturnSlots(doc: unknown, element: string): RawSlot[] {
+// The `returnvalues` entry a correction rewrites in each declaration of
+// `element`: the one named `slot`, or the first. One per declaration, so a
+// target that declares the element twice is folded, not sliced.
+function correctedReturnSlots(doc: unknown, element: string, slot?: string): RawSlot[] {
   if (!isRecord(doc) || !Array.isArray(doc.elements)) return [];
   return doc.elements.flatMap((candidate) => {
     if (
@@ -114,8 +138,9 @@ function firstReturnSlots(doc: unknown, element: string): RawSlot[] {
     ) {
       return [];
     }
-    const first = candidate.returnvalues[0];
-    return isRecord(first) ? [first] : [];
+    const values = candidate.returnvalues.filter(isRecord);
+    const corrected = slot === undefined ? values[0] : values.find((value) => value.name === slot);
+    return corrected === undefined ? [] : [corrected];
   });
 }
 
@@ -151,6 +176,9 @@ export interface ReturnFieldProvenance {
 // therefore prose- and token-shaped: the evidence sentence is gone from the
 // field's `<dd>`, or its type span now declares `nil` itself.
 //
+// A slot that names a STRUCT resolves the field when the struct marks that
+// member optional, since the struct is where that target now declares it.
+//
 // `missingFieldIn` is deliberately not a resolution. A field upstream dropped
 // from a slot the target still declares makes the correction stale, and
 // `applyFieldOptionalityCorrections` throws rather than no-op for it, so that
@@ -179,7 +207,7 @@ export function fieldCorrectionProvenance(
 
         let verdict: FieldVerdict;
         if (prose === undefined) {
-          verdict = "missing";
+          verdict = structMarksOptional(surface.doc, slot, field) ? "resolved" : "missing";
         } else if (!prose.includes(correction.evidence) || (tokens ?? []).includes("nil")) {
           verdict = "resolved";
         } else {
@@ -235,10 +263,6 @@ const RETURN_VERDICT_RANK: Record<ReturnVerdict, number> = {
   resolved: 0,
 };
 
-function baseTokens(tokens: readonly string[]): string {
-  return tokens.filter((token) => token !== "nil").join("|");
-}
-
 // The return-type class has the same two-sided evidence: the declared tokens
 // still say what the correction contradicts, and the slot prose still states the
 // contradiction. A target that fixes either half no longer needs the entry.
@@ -255,24 +279,24 @@ export function returnCorrectionProvenance(
 ): ReturnTypeProvenance[] {
   return entries.map(([key, correction]) => {
     const namespace = namespaceOf(key);
-    const pinned = baseTokens(correction.upstream);
+    const pins = correctionPins(correction);
 
     const verdicts = new Map<string, ReturnVerdict>();
     const drift = new Map<string, Set<string>>();
     for (const surface of surfaces) {
       if (surface.namespace !== namespace) continue;
-      // The correction rewrites the first return only, so only that slot is
-      // evidence; a declaration with no returns at all sights nothing.
-      for (const slot of firstReturnSlots(surface.doc, key)) {
+      // The correction rewrites one return only, so only that slot is evidence;
+      // a declaration without it sights nothing.
+      for (const slot of correctedReturnSlots(surface.doc, key, correction.slot)) {
         const tokens = slot.types ?? [];
 
         let verdict: ReturnVerdict;
-        if (baseTokens(tokens) !== pinned) {
+        if (!pinMatches(tokens, pins)) {
           verdict = "drift";
           const messages = drift.get(surface.target) ?? new Set<string>();
           drift.set(surface.target, messages);
           messages.add(
-            `${surface.target}: pinned ${correction.upstream.join("|")}, found ${tokens.join("|")}`,
+            `${surface.target}: pinned ${pins.map((pin) => pin.join("|")).join(" or ")}, found ${tokens.join("|")}`,
           );
         } else if (
           tokens.includes("nil") ||
@@ -304,3 +328,21 @@ export function returnCorrectionProvenance(
     };
   });
 }
+
+// The `MISFILED_DECLARATIONS` keys no retained target still files: upstream
+// moved or dropped the misfiled declaration, so the entry is due for deletion.
+export function unfiledDeclarations(
+  keys: readonly string[],
+  surfaces: readonly ProvenanceSurface[],
+): string[] {
+  return keys.filter((key) => {
+    const split = key.lastIndexOf(":");
+    const element = key.slice(0, split);
+    const returnName = key.slice(split + 1);
+    return !surfaces.some(
+      (surface) =>
+        surface.namespace === namespaceOf(element) &&
+        correctedReturnSlots(surface.doc, element).some((slot) => slot.name === returnName),
+    );
+  });
+}

package/src/script-api.ts

@@ -49,8 +49,10 @@ function stringOr(value: unknown, fallback: string): string {
 
 // A `.script_api` `type:` may spell a union inline (`string | nil`), where the
 // core ref-doc format carries one token per alternative. Splitting here keeps the
-// downstream emitter and fidelity resolver working in single tokens.
+// downstream emitter and fidelity resolver working in single tokens. A `type:`
+// may also be a YAML list (`[table, string]`), one alternative per entry.
 function splitTypeTokens(type: unknown): string[] {
+  if (Array.isArray(type)) return type.flatMap(splitTypeTokens);
   if (typeof type !== "string") return [];
   return type
     .split("|")

package/src/sys-overloads.d.ts

@@ -0,0 +1,48 @@
+/** @noSelfInFile */
+
+declare global {
+  namespace sys {
+    /**
+     * Disables engine throttling.
+     *
+     * @param enable - false to disable throttling
+     */
+    function set_engine_throttle(enable: false): void;
+    /**
+     * Enables engine throttling. The engine reads `cooldown` whenever `enable` is
+     * true.
+     *
+     * @param enable - true if throttling should be enabled
+     * @param cooldown - the time period to do update + render for (seconds)
+     */
+    function set_engine_throttle(enable: boolean, cooldown: number): void;
+    /**
+     * Get string config value from the game.project configuration file, or nil
+     * when the key does not exist.
+     *
+     * @param key - key to get value for. The syntax is SECTION.KEY
+     * @returns config value as a string, or nil if the config key does not exist.
+     * @example
+     * ```ts
+     * const text = sys.get_config_string("my_game.text");
+     * if (text !== undefined) print(text);
+     * ```
+     */
+    function get_config_string(key: string): string | undefined;
+    /**
+     * Get string config value from the game.project configuration file with
+     * a default value.
+     *
+     * @param key - key to get value for. The syntax is SECTION.KEY
+     * @param default_value - default value to return if the value does not exist
+     * @returns config value as a string. default_value if the config key does not exist.
+     * @example
+     * ```ts
+     * const text = sys.get_config_string("my_game.text", "default text");
+     * ```
+     */
+    function get_config_string(key: string, default_value: string): string;
+  }
+}
+
+export {};

package/src/vmath-overloads.d.ts

@@ -1,6 +1,6 @@
 /** @noSelfInFile */
 
-import type { Quaternion, Vector3, Vector4 } from "./core-types";
+import type { Quaternion, Vector, Vector3, Vector4 } from "./core-types";
 
 declare global {
   namespace vmath {
@@ -124,5 +124,31 @@ declare global {
      * @returns the slerped quaternion
      */
     function slerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion;
+    /**
+     * Creates an empty vector. The engine raises on an explicit nil, so this
+     * form takes no argument at all.
+     *
+     * @returns new vector
+     */
+    function vector(): Vector;
+    /**
+     * Creates a vector of arbitrary size. The vector is initialized
+     * with numeric values from a table.
+     * The table values are converted to floating point
+     * values. If a value cannot be converted, a 0 is stored in that
+     * value position in the vector.
+     *
+     * @param t - table of numbers
+     * @returns new vector
+     * @example
+     * ```ts
+     * // How to create a vector with custom data to be used for animation easing:
+     * const values = [0, 0.5, 0];
+     * const vec = vmath.vector(values);
+     * print(vec); // => vmath.vector (size: 3)
+     * print(vec[2]); // => 0.5
+     * ```
+     */
+    function vector(t: number[]): Vector;
   }
 }