@defold-typescript/types 0.52.0 → 0.54.0

package/scripts/extension-goldens.ts

@@ -10,15 +10,19 @@ import type { ModuleManifestEntry } from "./regen";
 // break every installed `resolve`.
 export const EXTENSION_GOLDENS_DIR = "extension-goldens";
 
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 const EXTENSION_GOLDEN_NAMESPACES = ["iac", "iap", "push", "webview"] as const;
 
+// Each golden's doc is the conversion of the extension's `.script_api` at its
+// `packages/library-types/defold-extensions.json` pin, the same JSON the
+// Libraries pages render, so a golden carries the namespace's constants, optional
+// slots and callback arguments exactly as `resolve` would emit them for a project.
+const EXTENSION_DOCS_DIR = resolve(PACKAGE_ROOT, "../library-types/defold-extensions/api-doc");
+
 export const EXTENSION_GOLDEN_MANIFEST: readonly ModuleManifestEntry[] =
   EXTENSION_GOLDEN_NAMESPACES.map((namespace) => ({
     namespace,
-    doc: JSON.parse(
-      readFileSync(resolve(PACKAGE_ROOT, "fixtures", `${namespace}_doc.json`), "utf8"),
-    ),
+    doc: JSON.parse(readFileSync(resolve(EXTENSION_DOCS_DIR, `${namespace}.json`), "utf8")),
     outFile: `${namespace}.d.ts`,
-    indexBaseSource: { pages: [] },
+    indexBaseSource: { pages: [], classifications: new Map() },
   }));

package/scripts/generate-api-availability.ts

@@ -30,7 +30,7 @@ import { splitTopLevel } from "../src/luals-type-expr";
 import { type ApiTarget, loadApiTargets, loadTargetModules } from "./regen";
 import { compareVersions, versionOf } from "./target-version";
 
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 const MIGRATIONS_PATH = resolve(PACKAGE_ROOT, "api-migrations.json");
 const AVAILABILITY_PATH = resolve(PACKAGE_ROOT, "api-availability.json");
 
@@ -78,8 +78,12 @@ export function identityCorrections(): IdentityCorrections {
         key,
         {
           pins: correctionPins(correction),
-          ...(correction.adds === undefined ? {} : { adds: union(correction.adds) }),
-          ...(correction.removes === undefined ? {} : { removes: [...correction.removes] }),
+          ...(correction.ts !== undefined
+            ? { replaces: union(correction.ts) }
+            : {
+                ...(correction.adds === undefined ? {} : { adds: union(correction.adds) }),
+                ...(correction.removes === undefined ? {} : { removes: [...correction.removes] }),
+              }),
         },
       ]),
     ),
@@ -98,7 +102,9 @@ export function identityCorrections(): IdentityCorrections {
       ]),
     ),
     constantFamilies: Object.fromEntries(
-      CONSTANT_UNION_ALIASES.map((alias) => [`${alias.home}.${alias.name}`, alias.members]),
+      CONSTANT_UNION_ALIASES.flatMap((alias) =>
+        "name" in alias ? [[`${alias.home}.${alias.name}`, alias.members] as const] : [],
+      ),
     ),
   };
 }

package/scripts/generate-api-signatures.ts

@@ -14,7 +14,7 @@ import {
 import { loadSignatureFile } from "./signature-store-fs";
 import { versionOf } from "./target-version";
 
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
 
 export interface SignaturesArtifact {

package/scripts/import-defold-release.ts

@@ -17,7 +17,7 @@ import {
 
 const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
 const DECLARED_NAME_KINDS = new Set(["CONSTANT", "ENUM", "STRUCT", "TYPEDEF", "CLASS"]);
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 
 // Editor-scripting namespaces are mapped, but not by `api-targets.json`: they
 // emit through `EDITOR_MODULE_MANIFEST` rather than the runtime module set the

package/scripts/regen.ts

@@ -30,7 +30,7 @@ import {
   formatFieldCorrectionGaps,
 } from "../src/field-correction-coverage";
 import type { IndexBaseSource } from "../src/index-slot-classifications";
-import { wrapAsAmbientGlobal, wrapAsModule } from "../src/publish-dts";
+import { wrapAsAmbientGlobal, wrapAsGlobalTableModule, wrapAsModule } from "../src/publish-dts";
 import type { UrlParameterTable } from "../src/url-parameters";
 import {
   type DocSourceProvenance,
@@ -87,8 +87,8 @@ export interface ApiTarget {
   readonly luaStdlib?: readonly { readonly namespace: string; readonly fixture: string }[];
 }
 
-const REGISTRY_PATH = resolve(import.meta.dir, "..", "api-targets.json");
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const REGISTRY_PATH = resolve(import.meta.dirname, "..", "api-targets.json");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 
 export function loadApiTargets(
   registryPath: string = REGISTRY_PATH,
@@ -176,6 +176,9 @@ export interface ModuleManifestEntry {
   // The classification map this entry's index notes read; absent means the
   // engine map. A library or extension declaration names its page keys.
   readonly indexBaseSource?: IndexBaseSource;
+  // `false` for an extension declaration, which leaves the constant-union
+  // aliases of the namespace it shares to the engine module; absent means `true`.
+  readonly ownsConstantUnionAliases?: boolean;
 }
 
 export interface ResolveTargetOptions {
@@ -752,10 +755,10 @@ export function assertCommittedFieldCorrectionCoverage(
   return targets.length;
 }
 
-export function generateModuleDeclaration(
+function emitModuleBody(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
-): GenerateResult {
+): { namespace: string; emitted: string; importsFrom: string; dropped: string[] } {
   const {
     module,
     knownConstantFqns,
@@ -780,14 +783,34 @@ export function generateModuleDeclaration(
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
     ...(entry.indexBaseSource ? { indexBaseSource: entry.indexBaseSource } : {}),
+    ...(entry.ownsConstantUnionAliases !== undefined
+      ? { ownsConstantUnionAliases: entry.ownsConstantUnionAliases }
+      : {}),
   });
   const importsFrom = entry.importsFrom ?? "../src/core-types";
+  return { namespace: module.namespace, emitted, importsFrom, dropped };
+}
+
+export function generateModuleDeclaration(
+  entry: ModuleManifestEntry,
+  options?: GenerateOptions,
+): GenerateResult {
+  const { namespace, emitted, importsFrom, dropped } = emitModuleBody(entry, options);
   const contents = entry.moduleId
-    ? wrapAsModule({ namespace: module.namespace, emitted, importsFrom, moduleId: entry.moduleId })
-    : wrapAsAmbientGlobal({ namespace: module.namespace, emitted, importsFrom });
+    ? wrapAsModule({ namespace, emitted, importsFrom, moduleId: entry.moduleId })
+    : wrapAsAmbientGlobal({ namespace, emitted, importsFrom });
   return { contents, dropped };
 }
 
+// A `.script_api` namespace as `resolve` writes it: a `@globalTable` module.
+export function generateGlobalTableDeclaration(
+  entry: ModuleManifestEntry,
+  options?: GenerateOptions,
+): GenerateResult {
+  const { namespace, emitted, importsFrom, dropped } = emitModuleBody(entry, options);
+  return { contents: wrapAsGlobalTableModule({ namespace, emitted, importsFrom }), dropped };
+}
+
 // The authoritative per-symbol signatures for a manifest entry, rendered through
 // the same prepared module (skip filter + constant branding) as
 // `generateModuleDeclaration`, so every signature corresponds to the committed
@@ -816,6 +839,9 @@ export function generateModuleSignatures(
     ...(nilRaisingSlots ? { nilRaisingSlots } : {}),
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
+    ...(entry.ownsConstantUnionAliases !== undefined
+      ? { ownsConstantUnionAliases: entry.ownsConstantUnionAliases }
+      : {}),
   });
 }
 
@@ -1325,7 +1351,7 @@ export async function regenerate(
   // Imported here rather than at module scope: the vendored engine bindings are
   // not published, and `resolve` loads this module from an installed package.
   const { targetBindingOptions } = await import("./binding-pin");
-  const generated = resolve(import.meta.dir, "..", "generated");
+  const generated = resolve(import.meta.dirname, "..", "generated");
   io.mkdir(resolve(generated, "editor-vm"));
   const defaultBinding = targetBindingOptions(DEFAULT_TARGET);
   for (const entry of MODULE_MANIFEST) {
@@ -1356,7 +1382,7 @@ export async function regenerate(
   const goldens = resolve(PACKAGE_ROOT, EXTENSION_GOLDENS_DIR);
   io.mkdir(goldens);
   for (const entry of EXTENSION_GOLDEN_MANIFEST) {
-    const { contents, dropped } = generateModuleDeclaration(entry);
+    const { contents, dropped } = generateGlobalTableDeclaration(entry);
     if (dropped.length > 0) {
       io.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
     }

package/scripts/shared-handle-methods.ts

@@ -1,3 +1,4 @@
+import type { SocketHandleReceiver } from "../src/core-types";
 import type { ModuleManifestEntry } from "./regen";
 
 // A method the engine shares across several handle classes where a release's
@@ -20,8 +21,8 @@ export const SHARED_HANDLE_METHODS: readonly SharedHandleMethod[] = (
 ).map((method) => ({
   namespace: "socket",
   method,
-  source: "client",
-  handles: ["master", "server"],
+  source: "client" satisfies SocketHandleReceiver,
+  handles: ["master", "server"] satisfies SocketHandleReceiver[],
   evidence: TCP_ANY,
 }));
 

package/scripts/signature-store-fs.ts

@@ -5,28 +5,48 @@ import type { SignatureStore } from "../src/signature-store";
 // Build-time only: lives under `scripts/` (never reachable from the shipped
 // `src/index.ts` graph) so its `node:fs` import cannot leak into a consumer's
 // typecheck. `src/signature-store.ts` stays pure for exactly that reason.
-export const IO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "io.json");
-export const STRING_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "string.json");
-export const TABLE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "table.json");
-export const OS_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "os.json");
+export const IO_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "io.json");
+export const STRING_SIGNATURES_PATH = resolve(
+  import.meta.dirname,
+  "..",
+  "signatures",
+  "string.json",
+);
+export const TABLE_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "table.json");
+export const OS_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "os.json");
 export const COROUTINE_SIGNATURES_PATH = resolve(
-  import.meta.dir,
+  import.meta.dirname,
   "..",
   "signatures",
   "coroutine.json",
 );
-export const MATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "math.json");
-export const BIT_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "bit.json");
-export const DEBUG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "debug.json");
-export const PACKAGE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "package.json");
-export const BASE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "base.json");
-export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "socket.json");
-export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
-export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
-export const GUI_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "gui.json");
-export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
-export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
-export const SYS_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "sys.json");
+export const MATH_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "math.json");
+export const BIT_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "bit.json");
+export const DEBUG_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "debug.json");
+export const PACKAGE_SIGNATURES_PATH = resolve(
+  import.meta.dirname,
+  "..",
+  "signatures",
+  "package.json",
+);
+export const BASE_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "base.json");
+export const SOCKET_SIGNATURES_PATH = resolve(
+  import.meta.dirname,
+  "..",
+  "signatures",
+  "socket.json",
+);
+export const VMATH_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "vmath.json");
+export const GO_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "go.json");
+export const GUI_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "gui.json");
+export const MSG_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "msg.json");
+export const RENDER_SIGNATURES_PATH = resolve(
+  import.meta.dirname,
+  "..",
+  "signatures",
+  "render.json",
+);
+export const SYS_SIGNATURES_PATH = resolve(import.meta.dirname, "..", "signatures", "sys.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/scripts/sync-api-docs.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { inflateRawSync } from "node:zlib";
 import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
 import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import { parseScriptApi } from "../src/script-api";
@@ -234,19 +235,13 @@ export const UPSTREAM_MAPPED_NAMESPACES: ReadonlySet<string> = new Set(
   [...SYNC_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map((e) => e.namespace),
 );
 
-// Convert a raw `.script_api` YAML doc to the core ref-doc JSON string written
-// to fixtures/<ns>_doc.json. The result is byte-compared by the same drift
-// semantics core fixtures use.
+// Convert a raw `.script_api` YAML doc to the core ref-doc JSON string the
+// Libraries pages, the `script-api` lane and `resolve` all read. The result is
+// byte-compared by the same drift semantics core fixtures use.
 export function scriptApiToFixtureJson(text: string): string {
   return JSON.stringify(parseScriptApi(text));
 }
 
-// The docs-only variant: the same ref-doc JSON with constants kept, for pages
-// that render a module's full surface rather than feed the emitter.
-export function scriptApiToDocsJson(text: string): string {
-  return JSON.stringify(parseScriptApi(text, { complete: true }));
-}
-
 // The types-api-coverage `What` checklist in vision.md lists every namespace as
 // a backtick-quoted token on the "Concrete breadth checklist" line. Reading it
 // here keeps SYNC_MANIFEST + UNMAPPED honest against the source of truth: the
@@ -278,21 +273,133 @@ export interface ZipAccessor {
   entries(): string[];
 }
 
-export function readZip(path: string): ZipAccessor {
-  const list = Bun.spawnSync(["unzip", "-Z1", path]);
-  if (list.exitCode !== 0) {
-    throw new Error(`unzip -Z1 failed for ${path}: ${list.stderr.toString()}`);
+const ZIP_LOCAL_HEADER_SIGNATURE = 0x04034b50;
+const ZIP_CENTRAL_HEADER_SIGNATURE = 0x02014b50;
+const ZIP_END_RECORD_SIGNATURE = 0x06054b50;
+const ZIP_END_RECORD_SIZE = 22;
+const ZIP_MAX_COMMENT_SIZE = 0xffff;
+const ZIP_METHOD_STORED = 0;
+const ZIP_METHOD_DEFLATE = 8;
+const ZIP64_MARKER = 0xffffffff;
+
+interface ZipDirectoryEntry {
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly localHeaderOffset: number;
+}
+
+// The directory an end record names must run exactly up to that record.
+function readCentralDirectory(
+  bytes: Buffer,
+  endRecord: number,
+  path: string,
+): Map<string, ZipDirectoryEntry> | Error {
+  const count = bytes.readUInt16LE(endRecord + 10);
+  const directorySize = bytes.readUInt32LE(endRecord + 12);
+  const directoryOffset = bytes.readUInt32LE(endRecord + 16);
+  if (count === 0xffff || directoryOffset === ZIP64_MARKER) {
+    return new Error(`${path}: zip64 archives are not supported`);
+  }
+  const disagrees = new Error(
+    `${path}: central directory disagrees with its end-of-central-directory record`,
+  );
+  if (directoryOffset + directorySize !== endRecord) {
+    return disagrees;
+  }
+  const entries = new Map<string, ZipDirectoryEntry>();
+  let cursor = directoryOffset;
+  for (let index = 0; index < count; index++) {
+    if (cursor + 46 > endRecord) {
+      return disagrees;
+    }
+    if (bytes.readUInt32LE(cursor) !== ZIP_CENTRAL_HEADER_SIGNATURE) {
+      return new Error(`${path}: central directory entry ${index} has no header signature`);
+    }
+    const method = bytes.readUInt16LE(cursor + 10);
+    const compressedSize = bytes.readUInt32LE(cursor + 20);
+    const uncompressedSize = bytes.readUInt32LE(cursor + 24);
+    const nameLength = bytes.readUInt16LE(cursor + 28);
+    const extraLength = bytes.readUInt16LE(cursor + 30);
+    const commentLength = bytes.readUInt16LE(cursor + 32);
+    const localHeaderOffset = bytes.readUInt32LE(cursor + 42);
+    if (
+      compressedSize === ZIP64_MARKER ||
+      uncompressedSize === ZIP64_MARKER ||
+      localHeaderOffset === ZIP64_MARKER
+    ) {
+      return new Error(`${path}: zip64 archives are not supported`);
+    }
+    const next = cursor + 46 + nameLength + extraLength + commentLength;
+    if (next > endRecord) {
+      return disagrees;
+    }
+    const name = bytes.toString("utf8", cursor + 46, cursor + 46 + nameLength);
+    entries.set(name, { method, compressedSize, localHeaderOffset });
+    cursor = next;
+  }
+  if (cursor !== endRecord) {
+    return disagrees;
   }
-  const entries = new Set(list.stdout.toString().split("\n").filter(Boolean));
+  return entries;
+}
+
+// Walks the central directory, which is the archive's own index: every entry
+// an archiver listed, directory entries included, in archive order. Found from
+// the end record, which sits in the last 22 bytes unless a comment follows it.
+// A comment may itself contain an end record, so a candidate counts only when
+// its own comment length reaches exactly to the end of the archive and it
+// describes a central directory ending at it. When no candidate does, the
+// nearest one's own defect is reported.
+function readZipDirectory(bytes: Buffer, path: string): Map<string, ZipDirectoryEntry> {
+  const earliest = Math.max(0, bytes.length - ZIP_END_RECORD_SIZE - ZIP_MAX_COMMENT_SIZE);
+  let nearestDefect: Error | undefined;
+  for (let at = bytes.length - ZIP_END_RECORD_SIZE; at >= earliest; at--) {
+    if (
+      bytes.readUInt32LE(at) === ZIP_END_RECORD_SIGNATURE &&
+      at + ZIP_END_RECORD_SIZE + bytes.readUInt16LE(at + 20) === bytes.length
+    ) {
+      const directory = readCentralDirectory(bytes, at, path);
+      if (!(directory instanceof Error)) {
+        return directory;
+      }
+      nearestDefect ??= directory;
+    }
+  }
+  if (nearestDefect !== undefined) {
+    throw nearestDefect;
+  }
+  throw new Error(`${path}: no end-of-central-directory record, not a zip archive`);
+}
+
+// Parses the archive itself rather than shelling out to `unzip`, which a stock
+// Windows machine does not have: the CLI opens extension archives through this
+// under Node and Bun on every OS.
+export function readZip(path: string): ZipAccessor {
+  const bytes = readFileSync(path);
+  const entries = readZipDirectory(bytes, path);
   return {
     has: (name) => entries.has(name),
-    entries: () => [...entries],
+    entries: () => [...entries.keys()],
     read: (name) => {
-      const out = Bun.spawnSync(["unzip", "-p", path, name]);
-      if (out.exitCode !== 0) {
-        throw new Error(`unzip -p failed for ${name} in ${path}: ${out.stderr.toString()}`);
+      const entry = entries.get(name);
+      if (entry === undefined) {
+        throw new Error(`no entry ${name} in ${path}`);
+      }
+      const { localHeaderOffset, compressedSize, method } = entry;
+      if (bytes.readUInt32LE(localHeaderOffset) !== ZIP_LOCAL_HEADER_SIGNATURE) {
+        throw new Error(`${path}: local header of ${name} has no signature`);
+      }
+      const nameLength = bytes.readUInt16LE(localHeaderOffset + 26);
+      const extraLength = bytes.readUInt16LE(localHeaderOffset + 28);
+      const start = localHeaderOffset + 30 + nameLength + extraLength;
+      const data = bytes.subarray(start, start + compressedSize);
+      if (method === ZIP_METHOD_STORED) {
+        return data.toString("utf8");
+      }
+      if (method === ZIP_METHOD_DEFLATE) {
+        return inflateRawSync(data).toString("utf8");
       }
-      return out.stdout.toString();
+      throw new Error(`${path}: entry ${name} uses unsupported compression method ${method}`);
     },
   };
 }
@@ -434,7 +541,7 @@ export interface SyncOptions {
   format?: (raw: string) => string;
 }
 
-const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 
 function canonicalJson(raw: string): string {
   return JSON.stringify(JSON.parse(raw));

package/src/api-doc.ts

@@ -31,6 +31,8 @@ export interface ApiStruct {
   brief: string;
   description: string;
   members: ApiStructMember[];
+  /** See {@link ApiTypedef.declaredIn}. */
+  declaredIn?: string;
 }
 
 /** One `STRUCT` member; upstream marks an optional one with a `name?` suffix. */
@@ -66,6 +68,8 @@ export interface ApiTypedef {
   types?: string[];
   /** The type text of each parent an interface-backed typedef extends. */
   extends?: string[];
+  /** See {@link ApiFunction.generics}. */
+  generics?: string;
   /**
    * The type an engine ref-doc `TYPEDEF` aliases (`parameters[0].types`): a
    * handle's `userdata`/`number`, or the arms of a union, literal or record alias.
@@ -73,6 +77,12 @@ export interface ApiTypedef {
   aliasOf?: string[];
   /** See {@link ApiFunction.global}. */
   global?: true;
+  /**
+   * The namespace of the ref-doc module that declared this type, set when
+   * `routeTypeDeclarations` moves it to another module; the reference lists it
+   * on the declaring module's page. Absent on a type its own module declares.
+   */
+  declaredIn?: string;
 }
 
 export interface ApiConstant {
@@ -81,8 +91,9 @@ export interface ApiConstant {
   description: string;
   /**
    * Present when the constant is a member of an `ENUM` whose value type is
-   * `string` (`parameters[0].types`); absence means a number, as every
-   * pre-`ENUM` constant is.
+   * `string` (`parameters[0].types`), or a `.script_api` scalar declared
+   * `type: string` (the converted `CONSTANT` element's `types`); absence means
+   * a number, as every pre-`ENUM` engine constant is.
    */
   valueType?: "string";
   /** Present when an `ENUM` member is typed `<ENUM>|nil`: some platforms leave it unset. */
@@ -102,8 +113,9 @@ export interface ApiFunction {
   examples?: string;
   /**
    * A pre-rendered generic-parameter clause (`<T extends druid_widget>`) inserted
-   * between the name and the `(` at render time. Present only on LuaLS-lowered
-   * library functions; engine ref-docs carry no `generics`, so it stays absent.
+   * right after the name at render time, before a function's `(` or an alias's
+   * `=`. Present only on library functions, type aliases and interfaces; engine
+   * ref-docs carry no `generics`, so it stays absent.
    */
   generics?: string;
   /**
@@ -355,6 +367,7 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
     ...(types.length > 0 ? { types } : {}),
     ...(parents.length > 0 ? { extends: parents } : {}),
     ...(aliasOf.length > 0 ? { aliasOf } : {}),
+    ...(typeof element.generics === "string" ? { generics: element.generics } : {}),
     ...globalKey(element),
   };
 }
@@ -400,10 +413,12 @@ function parseProperty(element: Record<string, unknown>): ApiProperty {
 }
 
 function parseConstant(element: Record<string, unknown>): ApiConstant {
+  const types = parseStringArray(element.types);
   return {
     name: stringOr(element.name, ""),
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
+    ...(types.length === 1 && types[0] === "string" ? { valueType: "string" as const } : {}),
     ...globalKey(element),
   };
 }

package/src/api-identity.ts

@@ -1,6 +1,7 @@
 import type { ApiFunction, ApiModule, ApiParameter } from "./api-doc";
 import { DEFOLD_TYPE_MAP } from "./core-types";
 import { pinMatches } from "./correction-pins";
+import { engineTypeName } from "./engine-type-name";
 import { splitTopLevel } from "./luals-type-expr";
 
 /**
@@ -32,7 +33,7 @@ export interface IdentityCorrections {
   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. */
+  /** Constant-family aliases a correction may name (`graphics.BLEND_FACTOR`), with members. */
   readonly constantFamilies: Readonly<Record<string, readonly string[]>>;
 }
 
@@ -117,6 +118,32 @@ const NUMERIC_LITERAL = /^-?\d+(\.\d+)?$/;
 const STRING_LITERAL = /^(".*"|'.*')$/;
 // The TypeScript table types a correction writes.
 const TS_TABLE = /^(Record|LuaMap|ReadonlyLuaMap|LuaTable)\b/;
+// A subset of a constant union a correction writes, which is still that union's value.
+const EXCLUDE = /^Exclude<([\w.]+),.*>$/;
+
+const REFERENCE_TYPE_PATHS = new WeakMap<IdentityVocabulary, ReadonlyMap<string, string>>();
+
+// The reference name a correction's TypeScript type path was derived from
+// (`gui.Anchor` -> `gui.ANCHOR`), so renaming a type re-keys no identity.
+function referenceTypePath(path: string, vocabulary: IdentityVocabulary): string {
+  let paths = REFERENCE_TYPE_PATHS.get(vocabulary);
+  if (paths === undefined) {
+    const built = new Map<string, string>();
+    for (const name of [
+      ...Object.keys(vocabulary.enums),
+      ...vocabulary.tables,
+      ...Object.keys(vocabulary.aliases),
+    ]) {
+      const dot = name.lastIndexOf(".");
+      if (dot < 0) continue;
+      const renamed = `${name.slice(0, dot + 1)}${engineTypeName(name.slice(dot + 1))}`;
+      if (renamed !== name) built.set(renamed, name);
+    }
+    paths = built;
+    REFERENCE_TYPE_PATHS.set(vocabulary, paths);
+  }
+  return paths.get(path) ?? path;
+}
 
 function canonicalLeaves(
   token: string,
@@ -136,6 +163,10 @@ function canonicalLeaves(
   if (trimmed.startsWith("typeof ")) {
     return canonicalLeaves(trimmed.slice("typeof ".length), vocabulary, expanding);
   }
+  const excluded = EXCLUDE.exec(trimmed);
+  if (excluded !== null) return canonicalLeaves(excluded[1] as string, vocabulary, expanding);
+  const reference = referenceTypePath(trimmed, vocabulary);
+  if (reference !== trimmed) return canonicalLeaves(reference, 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

package/src/component-properties.d.ts

@@ -8,7 +8,7 @@ import type { Hash, Vector3 } from "./core-types";
 // evidence. A key the engine reads but never writes is `readonly`.
 declare global {
   namespace go {
-    interface properties {
+    interface Properties {
       /** The position's x component. `gameobject.cpp:GetProperty` reads one float. */
       "position.x": number;
       /** The position's y component. `gameobject.cpp:GetProperty` reads one float. */
@@ -45,7 +45,7 @@ declare global {
   }
 
   namespace label {
-    interface properties {
+    interface Properties {
       /** The scale's x component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
       "scale.x": number;
       /** The scale's y component. `comp_label.cpp` and `comp_private.cpp` read and write one float. */
@@ -100,7 +100,7 @@ declare global {
   }
 
   namespace sprite {
-    interface properties {
+    interface Properties {
       /** The scale's x component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
       "scale.x": number;
       /** The scale's y component. `comp_sprite.cpp` and `comp_private.cpp` read and write one float. */
@@ -146,7 +146,7 @@ declare global {
   }
 
   namespace model {
-    interface properties {
+    interface Properties {
       /**
        * The material resource the model renders with.
        * `comp_model.cpp:CompModelGetProperty` and `CompModelSetProperty` read
@@ -162,7 +162,7 @@ declare global {
   }
 
   namespace physics {
-    interface properties {
+    interface Properties {
       /**
        * Whether the body runs continuous collision detection as a fast-moving
        * bullet. Box2D only: `comp_collision_object_box2d.cpp` reads and writes
@@ -176,7 +176,7 @@ declare global {
     /**
      * Factory component properties. Upstream's factory reference declares none.
      */
-    interface properties {
+    interface Properties {
       /**
        * The path hash of the prototype the factory spawns. Read-only:
        * `comp_factory.cpp:CompFactoryGetProperty` reads it and the component
@@ -191,7 +191,7 @@ declare global {
      * Collection factory component properties. Upstream's collectionfactory
      * reference declares none.
      */
-    interface properties {
+    interface Properties {
       /**
        * The path hash of the collection prototype the factory spawns.
        * Read-only: `comp_collection_factory.cpp:CompCollectionFactoryGetProperty`
@@ -207,7 +207,7 @@ declare global {
    * `CompMeshSetProperty` handle.
    */
   namespace mesh {
-    interface properties {
+    interface Properties {
       /**
        * The buffer resource holding the mesh's vertex data.
        * `resource.get_buffer` and `resource.set_buffer` read it with