@defold-typescript/types 0.51.0 → 0.53.0

package/scripts/regen.ts

@@ -44,6 +44,7 @@ import { loadTranslations } from "./example-store-io";
 import { synthesizeProseConstants } from "./prose-constants";
 import { restoreSharedHandleMethods } from "./shared-handle-methods";
 import { groupDocsByNamespace, mergeApiDocs, type readZip } from "./sync-api-docs";
+import { compareVersions, versionOf } from "./target-version";
 
 export interface ApiTargetModule {
   readonly namespace: string;
@@ -461,12 +462,19 @@ export interface GenerateOptions {
   urlParameters?: UrlParameterTable;
   registeredConstants?: ReadonlySet<string>;
   bindingEvidence?: ReadonlySet<string>;
+  nilRaisingSlots?: ReadonlyMap<string, readonly number[]>;
   // The modules the entry is emitted beside, the entry among them. Routing
   // reads this set instead of looking the entry up in a committed manifest, so
   // a surface built with its own import root still routes as a whole.
   surface?: readonly ModuleManifestEntry[];
 }
 
+// What a target's own engine source decides for its emit (`targetBindingOptions`).
+export type TargetBindingOptions = Pick<
+  GenerateOptions,
+  "registeredConstants" | "bindingEvidence" | "nilRaisingSlots"
+>;
+
 interface PreparedGeneratedModule {
   module: ApiModule;
   knownConstantFqns: ReadonlySet<string>;
@@ -474,6 +482,7 @@ interface PreparedGeneratedModule {
   urlParameters: UrlParameterTable;
   registeredConstants: ReadonlySet<string> | undefined;
   bindingEvidence: ReadonlySet<string> | undefined;
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]> | undefined;
   typeLeaves: Readonly<Record<string, string>> | undefined;
   declaredTypes: ReadonlyMap<string, string> | undefined;
   dropped: string[];
@@ -500,6 +509,7 @@ function prepareGeneratedModule(
     urlParameters,
     registeredConstants: options?.registeredConstants,
     bindingEvidence: options?.bindingEvidence,
+    nilRaisingSlots: options?.nilRaisingSlots,
     typeLeaves: entry.typeLeaves,
     declaredTypes: routed?.declaredTypes,
     dropped,
@@ -753,6 +763,7 @@ export function generateModuleDeclaration(
     urlParameters,
     registeredConstants,
     bindingEvidence,
+    nilRaisingSlots,
     typeLeaves,
     declaredTypes,
     dropped,
@@ -765,6 +776,7 @@ export function generateModuleDeclaration(
     withheldFunctions,
     ...(registeredConstants ? { registeredConstants } : {}),
     ...(bindingEvidence ? { bindingEvidence } : {}),
+    ...(nilRaisingSlots ? { nilRaisingSlots } : {}),
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
     ...(entry.indexBaseSource ? { indexBaseSource: entry.indexBaseSource } : {}),
@@ -790,14 +802,18 @@ export function generateModuleSignatures(
     urlParameters,
     registeredConstants,
     bindingEvidence,
+    nilRaisingSlots,
     typeLeaves,
     declaredTypes,
+    withheldFunctions,
   } = prepareGeneratedModule(entry, options);
   return emitSymbolSignatures(module, {
     knownConstantFqns,
     urlParameters,
+    withheldFunctions,
     ...(registeredConstants ? { registeredConstants } : {}),
     ...(bindingEvidence ? { bindingEvidence } : {}),
+    ...(nilRaisingSlots ? { nilRaisingSlots } : {}),
     ...(typeLeaves ? { typeLeaves } : {}),
     ...(declaredTypes ? { declaredTypes } : {}),
   });
@@ -864,9 +880,17 @@ export function kindStdlibReferences(entry: KindManifestEntry): string {
 // `generateKindIndex` stays pure; `srcAugmentationScopingViolations` in
 // `./augmentation-namespaces` is what catches a future restricted augmentation
 // added without one, by reading the namespaces each file really re-opens.
+// `since` is the first Defold release, a bare semver, whose engine has what the
+// augmentation declares; a surface generated for an older target omits it.
+// `requiresGoInstance` lists the exact functions an augmentation declares that
+// need a game object, so it rides no index of a kind without one; the same
+// guard checks this list against the functions the file declares, in both
+// directions.
 interface UniversalExtraImport {
   readonly specifier: string;
   readonly restrictedTo?: string;
+  readonly since?: string;
+  readonly requiresGoInstance?: readonly string[];
 }
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
@@ -878,9 +902,17 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
   { specifier: "../../src/window-event-guard" },
   { specifier: "../../src/physics-event-guard" },
   { specifier: "../../src/scene-addresses" },
-  { specifier: "../../src/go-overloads" },
+  // `go.property` is listed by hand: `GetScript` finds no `.script` instance in
+  // a render script and returns null rather than raising, and `Script_Property`
+  // raises on that null itself, a check the bindings manifest does not record.
+  {
+    specifier: "../../src/go-overloads",
+    requiresGoInstance: ["go.get", "go.set", "go.property"],
+  },
   { specifier: "../../src/component-properties" },
   { specifier: "../../src/render-overloads", restrictedTo: "render" },
+  { specifier: "../../src/gui-overloads", restrictedTo: "gui" },
+  { specifier: "../../src/gui-texture-removal", restrictedTo: "gui", since: "1.13.1" },
   { specifier: "../../src/vmath-overloads" },
   { specifier: "../../src/sys-overloads" },
 ];
@@ -903,14 +935,57 @@ export const RESTRICTED_SRC_AUGMENTATIONS: Readonly<Record<string, string>> = Ob
   ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.restrictedTo as string]),
 );
 
-// Read those augmentations as surface-root files. Mirrors
-// `loadTargetEditorModules`: a missing file throws with its path rather than
-// filtering silently, so a renamed augmentation fails loud instead of vanishing
-// from every materialized surface.
+// The `src/*` augmentations that declare a function needing a game object, as
+// `<module name> -> <the functions it declares that need one>`. Exported so the
+// scoping guard and the wall probe read the same list.
+export const GO_INSTANCE_SRC_FUNCTIONS: Readonly<Record<string, readonly string[]>> =
+  Object.fromEntries(
+    UNIVERSAL_EXTRA_IMPORTS.filter(
+      (entry) =>
+        entry.requiresGoInstance !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+    ).map((entry) => [
+      entry.specifier.slice(SRC_IMPORT_PREFIX.length),
+      entry.requiresGoInstance as readonly string[],
+    ]),
+  );
+
+// The same augmentations as module names. Exported so the materialized kind
+// indexes drop them the same way the in-repo ones do.
+export const GO_INSTANCE_SRC_AUGMENTATIONS: readonly string[] =
+  Object.keys(GO_INSTANCE_SRC_FUNCTIONS);
+
+// The `src/*` augmentations gated to a release, as `<module name> -> <since>`.
+export const SRC_AUGMENTATION_GATES: Readonly<Record<string, string>> = Object.fromEntries(
+  UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.since !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+  ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.since as string]),
+);
+
+function admitsTarget(entry: UniversalExtraImport, target: ApiTarget): boolean {
+  return entry.since === undefined || compareVersions(versionOf(target), entry.since) >= 0;
+}
+
+// The `src/*` augmentations a surface generated for `target` carries: those
+// whose gate the target's version meets. Every surface writer reads this one
+// filter, so the committed indexes, the kind indexes and both materializers
+// agree on which arms a target declares.
+export function srcAugmentationModulesFor(target: ApiTarget): readonly string[] {
+  return UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.specifier.startsWith(SRC_IMPORT_PREFIX) && admitsTarget(entry, target),
+  ).map((entry) => entry.specifier.slice(SRC_IMPORT_PREFIX.length));
+}
+
+// Read those augmentations as surface-root files, narrowed to `target`'s set
+// when one is given. Mirrors `loadTargetEditorModules`: a missing file throws
+// with its path rather than filtering silently, so a renamed augmentation fails
+// loud instead of vanishing from every materialized surface.
 export function loadSrcAugmentations(
   packageRoot: string = PACKAGE_ROOT,
+  target?: ApiTarget,
 ): { path: string; contents: string }[] {
-  return SRC_AUGMENTATION_MODULES.map((name) => {
+  const modules =
+    target === undefined ? SRC_AUGMENTATION_MODULES : srcAugmentationModulesFor(target);
+  return modules.map((name) => {
     const from = resolve(packageRoot, "src", `${name}.d.ts`);
     let contents: string;
     try {
@@ -922,6 +997,76 @@ export function loadSrcAugmentations(
   });
 }
 
+export const GO_INSTANCE_FUNCTIONS_FILE = "go-instance-functions.json";
+
+export type GoInstanceFunctions = Readonly<Record<string, readonly string[]>>;
+
+// The functions that need a game-object instance on `target`, keyed by fqn,
+// read from the manifest `go-instance-functions.ts` commits beside the target's
+// fixtures. `null` for a target with no vendored engine source to derive it
+// from, whose surfaces keep every function.
+export function loadGoInstanceFunctions(
+  target: ApiTarget,
+  packageRoot: string = PACKAGE_ROOT,
+): GoInstanceFunctions | null {
+  const path = resolve(packageRoot, target.fixturesDir, GO_INSTANCE_FUNCTIONS_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")) as GoInstanceFunctions;
+}
+
+// The functions a kind with no game object omits, by the bare name of the
+// module declaring them: `<module> -> <local names>`. A module declaring none,
+// or declaring only names its skip rules already withhold, has no entry.
+export function goInstanceWalls(
+  modules: readonly ModuleManifestEntry[],
+  needsGoInstance: GoInstanceFunctions | null,
+): Map<string, string[]> {
+  const walls = new Map<string, string[]>();
+  if (needsGoInstance === null) return walls;
+  const fqns = Object.keys(needsGoInstance);
+  for (const entry of modules) {
+    const prefix = `${entry.namespace}.`;
+    const localOf = (name: string): string =>
+      name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    const declared = new Set(parseDefoldApiDoc(entry.doc).functions.map((fn) => localOf(fn.name)));
+    const rules = entry.skipFunctions ?? [];
+    const skipped = (local: string): boolean =>
+      rules.some((rule) => (rule.endsWith(".") ? local.startsWith(rule) : local === rule));
+    const walled = fqns
+      .filter((fqn) => fqn.startsWith(prefix))
+      .map(localOf)
+      .filter((local) => !local.includes(".") && declared.has(local) && !skipped(local))
+      .sort();
+    if (walled.length > 0) walls.set(entry.outFile.replace(/\.d\.ts$/, ""), walled);
+  }
+  return walls;
+}
+
+// The modules a kind with no game object is emitted from: each walled module is
+// replaced by a copy that withholds the functions needing one and lands in
+// `dir`, one level below the surface root. The surface is returned whole
+// because a copy routes its types across its siblings, never alone.
+export function goInstanceFreeSurface(
+  modules: readonly ModuleManifestEntry[],
+  walls: ReadonlyMap<string, readonly string[]>,
+  dir: string,
+): { surface: ModuleManifestEntry[]; copies: ModuleManifestEntry[] } {
+  const copies: ModuleManifestEntry[] = [];
+  const surface = modules.map((entry) => {
+    const walled = walls.get(entry.outFile.replace(/\.d\.ts$/, ""));
+    if (walled === undefined) return entry;
+    const copy: ModuleManifestEntry = {
+      ...entry,
+      outFile: `${dir}/${entry.outFile}`,
+      importsFrom: oneLevelDeeper(entry.importsFrom ?? "../src/core-types"),
+      skipFunctions: [...(entry.skipFunctions ?? []), ...walled],
+    };
+    copies.push(copy);
+    return copy;
+  });
+  return { surface, copies };
+}
+
 const DEFAULT_FACTORY_MODULE = "../../src/lifecycle";
 
 export interface KindManifestEntry {
@@ -947,12 +1092,23 @@ export interface KindManifestEntry {
   readonly propertyTypes?: boolean;
   // Whether the kind's VM is LuaJIT. The editor runs plain Lua 5.1.
   readonly jit?: boolean;
+  // Set for a kind whose script has no game object: the directory, beside the
+  // surface root, holding copies of the modules that declare a function needing
+  // one, with those functions withheld. Its index imports the copies instead.
+  readonly goInstanceFreeDir?: string;
 }
 
 export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
   { kind: "script", factory: "defineScript" },
   { kind: "gui-script", restricted: "gui", factory: "defineGuiScript" },
-  { kind: "render-script", restricted: "render", factory: "defineRenderScript" },
+  {
+    kind: "render-script",
+    restricted: "render",
+    factory: "defineRenderScript",
+    // Only the GUI component registers a game-object resolver
+    // (`comp_gui.cpp`), so every `CheckGOInstance` raises in a render script.
+    goInstanceFreeDir: "render-script-modules",
+  },
   {
     kind: "editor-script",
     // Empty on purpose: the emitted namespaces come from the declaring target's
@@ -999,17 +1155,30 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === kind);
   if (!entry) throw new Error(`unknown script kind: ${kind}`);
   const srcPrefix = targetSrcPrefix(target);
+  // A kind with no game object loses what needs one, on a target whose engine
+  // source records what that is; a module declaring such a function is
+  // imported from its filtered copy.
+  const freeDir = entry.goInstanceFreeDir;
+  const needsGoInstance = freeDir === undefined ? null : loadGoInstanceFunctions(target);
+  const walls = goInstanceWalls(MODULE_MANIFEST, needsGoInstance);
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
-  ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+  )
+    .map((m) => m.outFile.replace(/\.d\.ts$/, ""))
+    .sort()
+    .map((base) => (walls.has(base) ? `../${freeDir}/${base}` : `../${base}`));
   // An augmentation bound to a restricted namespace rides only that namespace's
-  // kind index; every unmarked entry stays universal.
+  // kind index; every unmarked entry stays universal. A gated entry rides only a
+  // target its gate admits, and a marked one only a kind with a game object.
   const extraImports = UNIVERSAL_EXTRA_IMPORTS.filter(
-    (extra) => extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted,
+    (extra) =>
+      (extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted) &&
+      (needsGoInstance === null || extra.requiresGoInstance === undefined) &&
+      admitsTarget(extra, target),
   ).map((extra) => extra.specifier);
   const modules = (
     entry.only === undefined
-      ? [...new Set([...universalNamespaces.sort(), ...extraImports.sort()])]
+      ? [...new Set([...universalNamespaces, ...extraImports.sort()])]
       : [...editorKindModules(target), ...(entry.extraModules ?? [])]
   ).map((path) => retargetSrcPath(path, srcPrefix));
   const lines = modules.map((path) => `import "${path}";`);
@@ -1054,11 +1223,11 @@ export function generateVersionIndex(
 // The authored augmentations a committed per-version index imports, addressed
 // back into the package's `src/`. The in-repo surface has no copies beside its
 // modules, so a skipped symbol would otherwise be declared on no versioned
-// surface at all. Derived from `SRC_AUGMENTATION_MODULES`, so a new augmentation
+// surface at all. Derived from `srcAugmentationModulesFor`, so a new augmentation
 // reaches the pinned surfaces on the same edit that reaches the materialized ones.
 export function versionSrcAugmentationImports(target: ApiTarget): string[] {
   const srcPrefix = target.coreTypesImport.slice(0, -"core-types".length);
-  return SRC_AUGMENTATION_MODULES.map((name) => `${srcPrefix}${name}`);
+  return srcAugmentationModulesFor(target).map((name) => `${srcPrefix}${name}`);
 }
 
 // The `src/`-relative prefix a kind index living in `<generatedDir>/kinds/` needs
@@ -1089,6 +1258,9 @@ export function targetKindManifest(target: ApiTarget): readonly KindManifestEntr
 
 // Every `src/*` augmentation bound to a kind-restricted namespace carries its
 // `restrictedTo` marker, and every marker names a namespace its file re-opens.
+// Likewise `requiresGoInstance` sits on exactly the files declaring a function
+// the default target's manifest lists, read from this package whatever root the
+// files come from, and lists exactly the functions its file declares.
 // Exported so a test can reach the guard the entry point runs; never called on
 // import, so the dynamic import below stays unreached from an installed package.
 export async function assertSrcAugmentationScoping(
@@ -1096,13 +1268,18 @@ export async function assertSrcAugmentationScoping(
 ): Promise<number> {
   // Imported here rather than at module scope: it imports the devDependency
   // `typescript`, and `resolve` loads this module from an installed package.
-  const { srcAugmentationScopingViolations } = await import("./augmentation-namespaces");
-  const files = loadSrcAugmentations(packageRoot);
-  const violations = srcAugmentationScopingViolations(
-    files,
-    RESTRICTED_SRC_AUGMENTATIONS,
-    RESTRICTED_NAMESPACES,
+  const { goInstanceMarkerViolations, srcAugmentationScopingViolations } = await import(
+    "./augmentation-namespaces"
   );
+  const files = loadSrcAugmentations(packageRoot);
+  const violations = [
+    ...srcAugmentationScopingViolations(files, RESTRICTED_SRC_AUGMENTATIONS, RESTRICTED_NAMESPACES),
+    ...goInstanceMarkerViolations(
+      files,
+      GO_INSTANCE_SRC_FUNCTIONS,
+      new Set(Object.keys(loadGoInstanceFunctions(DEFAULT_TARGET) ?? {})),
+    ),
+  ];
   if (violations.length > 0) {
     throw new Error(`src augmentation scoping violations:\n${violations.join("\n")}`);
   }
@@ -1239,6 +1416,24 @@ export async function regenerate(
     }
   }
 
+  // The copies a kind with no game object imports instead of the modules that
+  // declare a function needing one; `generateKindIndex` routes to this same set.
+  const defaultWalls = goInstanceWalls(MODULE_MANIFEST, loadGoInstanceFunctions(DEFAULT_TARGET));
+  for (const entry of KIND_MODULE_MANIFEST) {
+    if (entry.goInstanceFreeDir === undefined) continue;
+    const { surface, copies } = goInstanceFreeSurface(
+      MODULE_MANIFEST,
+      defaultWalls,
+      entry.goInstanceFreeDir,
+    );
+    io.mkdir(resolve(generated, entry.goInstanceFreeDir));
+    for (const copy of copies) {
+      const out = resolve(generated, copy.outFile);
+      io.write(out, generateModuleDeclaration(copy, { ...defaultBinding, surface }).contents);
+      io.log(`wrote ${out}`);
+    }
+  }
+
   const kindsDir = resolve(generated, "kinds");
   io.mkdir(kindsDir);
   for (const entry of KIND_MODULE_MANIFEST) {

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

@@ -23,6 +23,7 @@ export const BASE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures",
 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");

package/scripts/target-version.ts

@@ -0,0 +1,26 @@
+const VERSION_FROM_ID = /^defold-(\d+\.\d+\.\d+)$/;
+
+// A ref-doc target names its release outright; a committed one carries it in
+// its id.
+export function versionOf(target: {
+  readonly id: string;
+  readonly source?: { readonly version: string } | null;
+}): string {
+  if (target.source) return target.source.version;
+  const match = VERSION_FROM_ID.exec(target.id);
+  if (!match?.[1]) throw new Error(`cannot derive a release version from target id "${target.id}"`);
+  return match[1];
+}
+
+function versionTuple(version: string): number[] {
+  return version.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+export function compareVersions(a: string, b: string): number {
+  const [ta, tb] = [versionTuple(a), versionTuple(b)];
+  for (let index = 0; index < Math.max(ta.length, tb.length); index += 1) {
+    const diff = (ta[index] ?? 0) - (tb[index] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}

package/src/api-doc.ts

@@ -1,4 +1,5 @@
 import { correctedDoc, docCorrectionKey } from "./doc-corrections";
+import { SCRIPT_HOOK_NAMES } from "./lifecycle";
 
 export interface ApiModule {
   namespace: string;
@@ -16,6 +17,12 @@ export interface ApiModule {
   enums?: ApiEnum[];
   /** Each ref-doc `STRUCT`. Absent on a hand-built module, read as an empty list. */
   structs?: ApiStruct[];
+  /**
+   * Each lifecycle hook the reference documents as a bare-named `FUNCTION` under
+   * `go` or `gui`. The engine calls it as a script global and binds nothing under
+   * the name. Absent on a hand-built module.
+   */
+  scriptHooks?: ApiFunction[];
 }
 
 /** A ref-doc `STRUCT`: a named table shape. */
@@ -24,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 +75,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 {
@@ -193,6 +208,17 @@ export const FUNCTION_NAME_CORRECTIONS: ReadonlyMap<string, FunctionNameCorrecti
   ],
 ]);
 
+// The engine reads each hook a script defines with `lua_getglobal` over
+// `SCRIPT_FUNCTION_NAMES` (`gameobject_script.cpp`, and `gui.cpp` for GUI
+// scripts) and registers no module function under the name, yet the reference
+// documents the hooks as bare-named `go` and `gui` functions.
+export const SCRIPT_HOOK_NAMESPACES: ReadonlySet<string> = new Set(["go", "gui"]);
+const SCRIPT_HOOK_NAME_SET: ReadonlySet<string> = new Set(SCRIPT_HOOK_NAMES);
+
+function isScriptHook(namespace: string, name: string): boolean {
+  return SCRIPT_HOOK_NAMESPACES.has(namespace) && SCRIPT_HOOK_NAME_SET.has(name);
+}
+
 export function parseDefoldApiDoc(input: unknown): ApiModule {
   if (!isRecord(input)) {
     throw new Error(`parseDefoldApiDoc: expected object, got ${describeKind(input)}`);
@@ -218,12 +244,17 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
   const typedefs: ApiTypedef[] = [];
   const enums: ApiEnum[] = [];
   const structs: ApiStruct[] = [];
+  const scriptHooks: ApiFunction[] = [];
 
   for (const element of elements) {
     if (!isRecord(element)) continue;
     const type = element.type;
     if (type === "FUNCTION") {
       const fn = withDocCorrections(parseFunction(element));
+      if (isScriptHook(namespace, fn.name)) {
+        scriptHooks.push(fn);
+        continue;
+      }
       const corrected = FUNCTION_NAME_CORRECTIONS.get(fn.name);
       functions.push(corrected === undefined ? fn : { ...fn, name: corrected.name });
     } else if (type === "VARIABLE") {
@@ -264,6 +295,7 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
     typedefs,
     enums,
     structs,
+    scriptHooks,
   };
 }
 
@@ -310,6 +342,8 @@ function withDocCorrections(fn: ApiFunction): ApiFunction {
   };
   return {
     ...fn,
+    brief: correctedDoc(docCorrectionKey(fn.name, "brief"), fn.brief),
+    description: correctedDoc(docCorrectionKey(fn.name, "description"), fn.description),
     parameters: fn.parameters.map(correct("param")),
     returnValues: fn.returnValues.map(correct("return")),
   };

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