@defold-typescript/types 0.53.0 → 0.54.0

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/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

@@ -68,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.
@@ -89,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. */
@@ -110,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;
   /**
@@ -363,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),
   };
 }
@@ -408,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/emit-dts.ts

@@ -74,6 +74,11 @@ export interface EmitOptions {
   // map; a library or extension declaration passes its page keys (`[]` for one
   // no page documents), so it never names Defold as the receiver.
   indexBaseSource?: IndexBaseSource;
+  // Whether the module declares the `CONSTANT_UNION_ALIASES` rows homed in its
+  // namespace. Defaults to `true`; an extension declaring an engine namespace
+  // passes `false`, so it never re-declares an alias the engine module already
+  // declares, while its signatures still spell `gui.Playback`.
+  ownsConstantUnionAliases?: boolean;
   // The TS path of each `ENUM`, `STRUCT` and `TYPEDEF` another module declares
   // (`declaredTypePaths`), so a token naming one resolves instead of widening to
   // `unknown`. The module's own declarations resolve without it. Read only by the
@@ -205,9 +210,10 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // crash.get_modules is "module table".
   "crash.get_backtrace",
   "crash.get_modules",
-  // platform-specific options: the doc is a dead backtick-prose cross-ref to a
-  // sibling whose function is absent from the fixture (webview.open is not
-  // documented), so no machine-readable shape exists.
+  // platform-specific options: the doc is a backtick-prose cross-ref to
+  // webview.open, whose options are documented as structured `.script_api`
+  // fields rather than a prose field list, so the cross-reference resolver (which
+  // reads a sibling's prose only) finds no machine-readable shape here.
   "webview.open_raw",
   // OS-resolver returns: the shape is set by the host resolver, not Defold's
   // API contract; each fixture doc reads "a table with all information
@@ -1907,10 +1913,6 @@ export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResoluti
   ],
   ["gui.new_texture:param:type", { residual: "the doc lists texture type strings only" }],
   ["gui.set_texture_data:param:type", { residual: "the doc lists texture type strings only" }],
-  [
-    "iap.get_provider_id:return:provider_id",
-    { residual: "the doc names iap.PROVIDER_ID_*, which no ref-doc defines as a constant" },
-  ],
 ]);
 
 export interface ConstantUnionNamedRow {
@@ -2373,7 +2375,9 @@ export function constantUnionSpelling(row: ConstantUnionAlias): string {
 // declared in its home whether or not that module references it, so a
 // cross-namespace row is reachable from the module whose signatures spell it.
 // A row whose name the module's own `ENUM` already declares is left to that
-// `ENUM`, which carries the reference's member order and nilable arms.
+// `ENUM`, which carries the reference's member order and nilable arms. An
+// extension module is never a row's home, even when it declares the engine
+// namespace (`gui`), so its emit skips this (`ownsConstantUnionAliases`).
 function ownedConstantUnionAliases(
   namespace: string,
   enumDeclared: ReadonlySet<string>,
@@ -2588,9 +2592,9 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
   ["iap.list", "string"],
   // push.register's `notifications` is a prose-only array of push.NOTIFICATION_*
   // bitmask constants (the ref example sums NOTIFICATION_BADGE/SOUND/ALERT). The
-  // vendored push_doc.json fixture declares no NOTIFICATION_* constant elements, so
-  // no brand exists to reference; `number` is the faithful element token for these
-  // numeric constants, mirroring the vmath.vector/buffer.* number entries.
+  // slot's prose names no constant the expansion could read, and a summed bitmask
+  // is a plain number rather than any one brand, so `number` is the faithful
+  // element token, mirroring the vmath.vector/buffer.* number entries.
   ["push.register", "number"],
   // camera.get_cameras returns "a table with all camera URLs" (the ref example
   // iterates it with `pairs`) — a homogeneous list of `url`, emitted `Url[]`.
@@ -5116,11 +5120,13 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   lines.push(`declare namespace ${module.namespace} {`);
 
   for (const declaration of typeDeclarations) lines.push(...declaration.lines(INDENT, decl));
-  for (const aliasDecl of constantUnionAliasDeclarations(
-    module.namespace,
-    new Set(enumAliases.all.map((alias) => alias.path)),
-  )) {
-    lines.push(`${INDENT}${decl}${aliasDecl}`);
+  if (options?.ownsConstantUnionAliases !== false) {
+    for (const aliasDecl of constantUnionAliasDeclarations(
+      module.namespace,
+      new Set(enumAliases.all.map((alias) => alias.path)),
+    )) {
+      lines.push(`${INDENT}${decl}${aliasDecl}`);
+    }
   }
   for (const { declaration } of overloadSlotAliasDeclarations(
     [...module.functions, ...(options?.withheldFunctions ?? [])],
@@ -5668,10 +5674,14 @@ export function emitSymbolSignatures(
   // names one carries no member list of its own, so the docs read the members
   // from here rather than from the emitter's table.
   const enumAliases = collectEnumAliases(module, constants, nestedRoot);
-  for (const row of ownedConstantUnionAliases(
-    module.namespace,
-    new Set(enumAliases.all.map((alias) => alias.path)),
-  )) {
+  const ownedAliases =
+    options?.ownsConstantUnionAliases === false
+      ? []
+      : ownedConstantUnionAliases(
+          module.namespace,
+          new Set(enumAliases.all.map((alias) => alias.path)),
+        );
+  for (const row of ownedAliases) {
     const name = engineTypeName(row.name);
     out.push({
       identity: { namespace: module.namespace, kind: "TYPEDEF", name, signature: "" },
@@ -6471,6 +6481,7 @@ function parameterType(
           "param",
           p.name,
           bindingEvidence,
+          p.fields,
         )
       : "unknown";
   const key = tableSlotKey(elementName, "param", p.name);
@@ -6694,6 +6705,7 @@ function emitReturn(
                 "return",
                 rv.name,
                 bindingEvidence,
+                rv.fields,
               )
             : "unknown"),
       };
@@ -6733,6 +6745,7 @@ function emitReturn(
           "return",
           first.name,
           bindingEvidence,
+          first.fields,
         )
       : "unknown";
   // A LuaLS vararg return (`...`) is every value the call returns, however many.
@@ -6846,6 +6859,73 @@ function wrappedInParens(text: string): boolean {
   return false;
 }
 
+// A ref-doc slot's structured `fields` (a `.script_api` callback's `parameters:`
+// or a table's `fields:`) as the field list `inlineTableType` renders. A field
+// flagged `is_optional` keeps that flag so a return-side or callback-argument
+// table marks only it `?`; a nested table's own fields nest the same way.
+function refDocTableFields(fields: readonly ApiParameter[]): TableField[] {
+  return fields.map((field) => {
+    const out: TableField = { name: field.name, types: field.types };
+    if (field.fields !== undefined) out.fields = refDocTableFields(field.fields);
+    if (field.isOptional) out.optional = true;
+    return out;
+  });
+}
+
+// The TS type of one documented callback argument. The engine supplies these
+// values, so a table argument's fields are required unless flagged optional; a
+// `self` argument is the calling script instance, typed `unknown` like the
+// engine callback corrections type it.
+// A `constant` argument expands to the brands its own doc names, through the
+// slot's constant resolver; one whose doc names none keeps the generic brand.
+function callbackArgumentType(
+  field: ApiParameter,
+  mapType: DefoldTypeMapper,
+  constantsNamed: (doc: string) => readonly string[],
+): string {
+  if (field.name === "self") return "unknown";
+  if (field.fields !== undefined && field.fields.length > 0) {
+    if (field.types.includes("function")) {
+      return callbackTypeFromFields(field.fields, mapType, constantsNamed);
+    }
+    if (field.types.includes("table")) {
+      return inlineTableType(refDocTableFields(field.fields), mapType, false);
+    }
+  }
+  if (field.types.includes("constant")) {
+    const fqns = constantsNamed(field.doc);
+    if (fqns.length > 0) {
+      const others = field.types.filter((token) => token !== "constant");
+      return unionFromTokens([...fqns, ...others], mapType);
+    }
+  }
+  return field.types.length > 0 ? unionFromTokens(field.types, mapType) : "unknown";
+}
+
+// Renders a `function` slot's documented arguments as `(name: T, ...) => void`.
+// Optionality follows `emitParameter`: a trailing optional run takes `?`, an
+// interior optional argument takes `| undefined` because TS forbids a required
+// parameter after an optional one.
+function callbackTypeFromFields(
+  fields: readonly ApiParameter[],
+  mapType: DefoldTypeMapper,
+  constantsNamed: (doc: string) => readonly string[],
+): string {
+  let trailingOptionalFrom = fields.length;
+  while (trailingOptionalFrom > 0 && fields[trailingOptionalFrom - 1]?.isOptional === true) {
+    trailingOptionalFrom--;
+  }
+  const args = fields.map((field, index) => {
+    const name = safeParamName(field.name, index);
+    const ts = callbackArgumentType(field, mapType, constantsNamed);
+    if (index >= trailingOptionalFrom) return `${name}?: ${ts}`;
+    if (!field.isOptional) return `${name}: ${ts}`;
+    const operand = isFunctionTypeText(ts) ? `(${ts})` : ts;
+    return `${name}: ${operand} | undefined`;
+  });
+  return `(${args.join(", ")}) => void`;
+}
+
 // Like `unionFromTokens`, but a `table` token whose slot doc carries a parseable
 // `<dl>` field list emits an inline object type instead of the opaque `Record`
 // fallback. Other tokens in the union map unchanged. `optionalFields` marks the
@@ -6853,6 +6933,10 @@ function wrappedInParens(text: string): boolean {
 // optionality and an input option-bag's fields are individually omittable (the
 // old `Record` accepted partial/empty objects), so a parameter's fields are
 // optional while a return's fields (engine-populated, all present) stay required.
+// A slot carrying structured ref-doc `fields` (a `.script_api` conversion) types
+// a `table` token from them ahead of the prose parser and the curations, the
+// precedence `slotFieldNames` applies, and a `function` token from them as a
+// typed callback signature.
 function mapSlotUnion(
   types: readonly string[],
   doc: string,
@@ -6864,6 +6948,7 @@ function mapSlotUnion(
   slotKind: "param" | "return" | undefined,
   slotName: string | undefined,
   bindingEvidence: ReadonlySet<string>,
+  fields?: readonly ApiParameter[],
 ): string {
   const mapped: string[] = [];
   const seen = new Set<string>();
@@ -6872,6 +6957,7 @@ function mapSlotUnion(
     seen.add(ts);
     mapped.push(ts);
   };
+  const structured = fields !== undefined && fields.length > 0 ? fields : undefined;
   for (const token of types) {
     if (token === "constant" && slotKind !== undefined && slotName !== undefined) {
       const expanded = constantTokens(elementName, slotKind, slotName, doc);
@@ -6885,7 +6971,15 @@ function mapSlotUnion(
       slotKind !== undefined && slotName !== undefined
         ? TABLE_SLOT_CURATIONS.get(tableSlotKey(elementName, slotKind, slotName))
         : undefined;
-    if (token === "table" || slotCuration?.retypedUpstream?.includes(token) === true) {
+    if (token === "table" && structured !== undefined) {
+      ts = inlineTableType(refDocTableFields(structured), mapType, optionalFields);
+    } else if (token === "function" && structured !== undefined) {
+      ts = callbackTypeFromFields(structured, mapType, (fieldDoc) =>
+        slotKind !== undefined && slotName !== undefined
+          ? constantTokens(elementName, slotKind, slotName, fieldDoc)
+          : [],
+      );
+    } else if (token === "table" || slotCuration?.retypedUpstream?.includes(token) === true) {
       const curation = slotCuration;
       const mapping =
         curation?.kind === "mapping" ? curation : MAPPING_TABLE_SLOTS.get(elementName);