@defold-typescript/types 0.49.0 → 0.50.0

package/generated/versions/defold-1.13.2/window.d.ts

@@ -0,0 +1,196 @@
+/** @noSelfInFile */
+declare global {
+  /**
+   * Functions and constants to access the window, window event listeners
+   * and screen dimming.
+   */
+  namespace window {
+    /**
+     * Width and height are present for window.WINDOW_EVENT_RESIZED and
+     * absent for other window events.
+     */
+    interface event_data {
+      /**
+       * Window width after a resize.
+       */
+      width?: number;
+      /**
+       * Window height after a resize.
+       */
+      height?: number;
+    }
+    /**
+     * Window safe-area data
+     */
+    interface safe_area {
+      /**
+       * Safe-area x-coordinate.
+       */
+      x: number;
+      /**
+       * Safe-area y-coordinate.
+       */
+      y: number;
+      /**
+       * Safe-area width.
+       */
+      width: number;
+      /**
+       * Safe-area height.
+       */
+      height: number;
+      /**
+       * Inset from the left window edge.
+       */
+      inset_left: number;
+      /**
+       * Inset from the top window edge.
+       */
+      inset_top: number;
+      /**
+       * Inset from the right window edge.
+       */
+      inset_right: number;
+      /**
+       * Inset from the bottom window edge.
+       */
+      inset_bottom: number;
+    }
+    type DimModeState = typeof window.DIMMING_UNKNOWN | typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
+    type DimModeStateSettable = typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
+    type DIMMING = typeof window.DIMMING_OFF | typeof window.DIMMING_ON | typeof window.DIMMING_UNKNOWN;
+    type WINDOW_EVENT = typeof window.WINDOW_EVENT_DEICONIFIED | typeof window.WINDOW_EVENT_FOCUS_GAINED | typeof window.WINDOW_EVENT_FOCUS_LOST | typeof window.WINDOW_EVENT_ICONIFIED | typeof window.WINDOW_EVENT_RESIZED;
+    /**
+     * dimming mode off Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
+     */
+    const DIMMING_OFF: number & { readonly __brand: "window.DIMMING_OFF" };
+    /**
+     * dimming mode on Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
+     */
+    const DIMMING_ON: number & { readonly __brand: "window.DIMMING_ON" };
+    /**
+     * dimming mode unknown Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction. This mode indicates that the dim mode can't be determined, or that the platform doesn't support dimming.
+     */
+    const DIMMING_UNKNOWN: number & { readonly __brand: "window.DIMMING_UNKNOWN" };
+    /**
+     * deiconified window event This event is sent to a window event listener when the game window or app screen is restored after being iconified.
+     */
+    const WINDOW_EVENT_DEICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_DEICONIFIED" };
+    /**
+     * focus gained window event This event is sent to a window event listener when the game window or app screen has gained focus. This event is also sent at game startup and the engine gives focus to the game.
+     */
+    const WINDOW_EVENT_FOCUS_GAINED: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_GAINED" };
+    /**
+     * focus lost window event This event is sent to a window event listener when the game window or app screen has lost focus.
+     */
+    const WINDOW_EVENT_FOCUS_LOST: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_LOST" };
+    /**
+     * Deprecated misspelling of `window.WINDOW_EVENT_ICONIFIED`, with the same value. The engine still registers it.
+     */
+    const WINDOW_EVENT_ICONFIED: typeof window.WINDOW_EVENT_ICONIFIED;
+    /**
+     * iconify window event This event is sent to a window event listener when the game window or app screen is iconified (reduced to an application icon in a toolbar, application tray or similar).
+     */
+    const WINDOW_EVENT_ICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_ICONIFIED" };
+    /**
+     * resized window event This event is sent to a window event listener when the game window or app screen is resized. The new size is passed along in the data field to the event listener.
+     */
+    const WINDOW_EVENT_RESIZED: number & { readonly __brand: "window.WINDOW_EVENT_RESIZED" };
+    /**
+     * Returns the current dimming mode set on a mobile device.
+     * The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction.
+     * On platforms that does not support dimming, `window.DIMMING_UNKNOWN` is always returned.
+     *
+     * @returns The mode for screen dimming
+     */
+    function get_dim_mode(): window.DIMMING;
+    /**
+     * This returns the content scale of the current display.
+     *
+     * @returns The display scale
+     */
+    function get_display_scale(): number;
+    /**
+     * This returns the current lock state of the mouse cursor
+     *
+     * @returns The lock state
+     */
+    function get_mouse_lock(): boolean;
+    /**
+     * This returns the safe area rectangle (x, y, width, height) and the inset
+     * values relative to the window edges. On platforms without a safe area,
+     * this returns the full window size and zero insets.
+     *
+     * @returns safe area data
+     */
+    function get_safe_area(): window.safe_area;
+    /**
+     * This returns the current window size (width and height).
+     */
+    function get_size(): LuaMultiReturn<[number, number]>;
+    /**
+     * Sets the dimming mode on a mobile device.
+     * The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction. The dimming mode will only affect the mobile device while the game is in focus on the device, but not when the game is running in the background.
+     * This function has no effect on platforms that does not support dimming.
+     *
+     * @param mode - The mode for screen dimming
+     */
+    function set_dim_mode(mode: window.DimModeStateSettable): void;
+    /**
+     * Sets a window event listener. Only one window event listener can be set at a time.
+     *
+     * @param callback - A callback which receives info about window events. Pass an empty function or `nil` if you no longer wish to receive callbacks.
+     * @example
+     * ```ts
+     * export default defineScript({
+     *   init() {
+     *     window.set_listener((self, event, data) => {
+     *       if (event === window.WINDOW_EVENT_FOCUS_LOST) {
+     *         print("window.WINDOW_EVENT_FOCUS_LOST");
+     *       } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
+     *         print("window.WINDOW_EVENT_FOCUS_GAINED");
+     *       } else if (event === window.WINDOW_EVENT_ICONIFIED) {
+     *         print("window.WINDOW_EVENT_ICONIFIED");
+     *       } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
+     *         print("window.WINDOW_EVENT_DEICONIFIED");
+     *       } else if (event === window.WINDOW_EVENT_RESIZED) {
+     *         print("Window resized: ", data.width, data.height);
+     *       }
+     *     });
+     *   },
+     * });
+     * ```
+     */
+    function set_listener(callback: ((self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: Record<string | number, unknown>) => void) | undefined): void;
+    /**
+     * Set the locking state for current mouse cursor on a PC platform.
+     * This function locks or unlocks the mouse cursor to the center point of the window. While the cursor is locked,
+     * mouse position updates will still be sent to the scripts as usual.
+     *
+     * @param flag - The lock state for the mouse cursor
+     */
+    function set_mouse_lock(flag: boolean): void;
+    /**
+     * Sets the window position.
+     *
+     * @param x - Horizontal position of window
+     * @param y - Vertical position of window
+     */
+    function set_position(x: number, y: number): void;
+    /**
+     * Sets the window size. Works on desktop platforms only.
+     *
+     * @param width - Width of window
+     * @param height - Height of window
+     */
+    function set_size(width: number, height: number): void;
+    /**
+     * Sets the window title. Works on desktop platforms.
+     *
+     * @param title - The title, encoded as UTF-8
+     */
+    function set_title(title: string): void;
+  }
+}
+
+export {};

package/generated/versions/defold-1.13.2/zlib.d.ts

@@ -0,0 +1,41 @@
+/** @noSelfInFile */
+declare global {
+  /**
+   * Functions for compression and decompression of string buffers.
+   */
+  namespace zlib {
+    /**
+     * A lua error is raised is on error
+     *
+     * @param buf - buffer to deflate
+     * @returns deflated buffer
+     * @example
+     * ```ts
+     * const data = "This is a string with uncompressed data.";
+     * const compressed_data = zlib.deflate(data);
+     * let s = "";
+     * for (const c of compressed_data) {
+     *   s = s + "\\" + c.charCodeAt(0);
+     * }
+     * print(s); //> \120\94\11\201\200\44\86\0\162\68\133\226\146\162 ...
+     * ```
+     */
+    function deflate(buf: string): string;
+    /**
+     * A lua error is raised is on error
+     *
+     * @param buf - buffer to inflate
+     * @returns inflated buffer
+     * @example
+     * ```ts
+     * const data =
+     *   "\x78\x5e\x0b\xc9\xc8\x2c\x56\x00\xa2\x44\x85\xe2\x92\xa2\xcc\xbc\x74\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xe4\xfc\xdc\x82\xa2\xd4\xe2\xe2\xd4\x14\x85\x94\xc4\x92\x44\x3d\x00\x2c\x43\x0e\xc9";
+     * const uncompressed_data = zlib.inflate(data);
+     * print(uncompressed_data); //> This is a string with uncompressed data.
+     * ```
+     */
+    function inflate(buf: string): string;
+  }
+}
+
+export {};

package/identity-vocabulary.json

@@ -158,6 +158,7 @@
     "graphics.COMPRESSION_TYPE": "number",
     "graphics.CONTEXT_FEATURE": "number",
     "graphics.COORDINATE_SPACE": "number",
+    "graphics.CUBEMAP_FACE": "number",
     "graphics.DATA_TYPE": "number",
     "graphics.FACE_TYPE": "number",
     "graphics.SEMANTIC_TYPE": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -116,7 +116,7 @@
     "import-defold-release": "bun scripts/import-defold-release.ts",
     "sync-api-docs": "bun scripts/sync-api-docs.ts",
     "sync-engine-bindings": "bun scripts/sync-engine-bindings.ts",
-    "ref-doc-delta": "bun scripts/ref-doc-delta.ts --target defold-1.9.8 --namespace label --present label.get_text --absent label.set_text"
+    "ref-doc-delta": "bun scripts/ref-doc-delta.ts --target defold-1.9.8 --namespace label --present label.get_text --present label.set_text --absent label.get_layout_objects"
   },
   "dependencies": {
     "lua-types": "^2.13.1",

package/scripts/import-defold-release.ts

@@ -7,6 +7,7 @@ import {
   EDITOR_MANIFEST,
   type ExtractedFixture,
   extractAnnotationFixtures,
+  groupDocsByNamespace,
   IGNORED_UPSTREAM,
   mergeApiDocs,
   readZip,
@@ -15,7 +16,6 @@ import {
 } from "./sync-api-docs";
 
 const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
-const LUA_NAMESPACE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 const DECLARED_NAME_KINDS = new Set(["CONSTANT", "ENUM", "STRUCT", "TYPEDEF", "CLASS"]);
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 
@@ -75,11 +75,6 @@ interface RawElement extends Record<string, unknown> {
   name?: string;
 }
 
-interface RawApiDoc extends Record<string, unknown> {
-  info?: { namespace?: string };
-  elements?: RawElement[];
-}
-
 export interface ReleaseBaselineModule {
   readonly namespace: string;
   readonly fixture: string;
@@ -177,20 +172,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function parsedDoc(raw: string): RawApiDoc | null {
-  try {
-    const value: unknown = JSON.parse(raw);
-    return isRecord(value) ? (value as RawApiDoc) : null;
-  } catch {
-    return null;
-  }
-}
-
-function namespaceOf(doc: RawApiDoc): string | null {
-  const namespace = isRecord(doc.info) ? doc.info.namespace : undefined;
-  return typeof namespace === "string" && LUA_NAMESPACE.test(namespace) ? namespace : null;
-}
-
 function elementsOf(doc: unknown): RawElement[] {
   if (!isRecord(doc) || !Array.isArray(doc.elements)) return [];
   return doc.elements.filter(isRecord) as RawElement[];
@@ -297,16 +278,7 @@ export function buildReleaseImportPlan(input: {
     throw new Error(`expected an exact Defold release version, received '${input.version}'`);
   }
 
-  const grouped = new Map<string, Array<{ entry: string; doc: RawApiDoc }>>();
-  for (const zipEntry of [...input.zip.entries()].sort()) {
-    const doc = parsedDoc(input.zip.read(zipEntry));
-    if (!doc) continue;
-    const namespace = namespaceOf(doc);
-    if (!namespace) continue;
-    const group = grouped.get(namespace) ?? [];
-    group.push({ entry: zipEntry, doc });
-    grouped.set(namespace, group);
-  }
+  const grouped = groupDocsByNamespace(input.zip);
 
   const baselineModules = [...input.baseline.modules, ...input.baseline.luaStdlib];
   const generatedNamespaces = new Set(input.baseline.modules.map((module) => module.namespace));
@@ -319,7 +291,7 @@ export function buildReleaseImportPlan(input: {
   };
 
   const sources: ReleaseSource[] = incomingNamespaces.map((namespace) => {
-    const group = grouped.get(namespace) as Array<{ entry: string; doc: RawApiDoc }>;
+    const group = grouped.get(namespace) ?? [];
     return {
       namespace,
       entries: group.map(({ entry }) => entry).sort(),

package/scripts/materialize-version.ts

@@ -11,6 +11,7 @@ import {
   loadSrcAugmentations,
   loadTargetEditorModules,
   MESSAGES_MANIFEST,
+  type ModuleManifestEntry,
   type ResolveTargetOptions,
   resolveTargetModules,
 } from "./regen";
@@ -138,13 +139,18 @@ export async function buildVersionedSurfaceFiles(
     opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined)
   ).filter((file) => kept(file.path));
 
-  const files: VersionedSurfaceFile[] = [...modules, ...editorModules].map((entry) => ({
-    path: entry.outFile,
-    contents: generateModuleDeclaration({
-      ...entry,
-      importsFrom: surfaceCoreTypesImport(entry.outFile),
-    }).contents,
-  }));
+  // Re-rooting an entry makes it a new object no committed manifest holds, so
+  // each lane is handed to the emit as the surface it routes: a type one module
+  // declares for another, or names from another, resolves only across the set.
+  const rerooted = (entries: readonly ModuleManifestEntry[]): ModuleManifestEntry[] =>
+    entries.map((entry) => ({ ...entry, importsFrom: surfaceCoreTypesImport(entry.outFile) }));
+  const files: VersionedSurfaceFile[] = [rerooted(modules), rerooted(editorModules)].flatMap(
+    (surface) =>
+      surface.map((entry) => ({
+        path: entry.outFile,
+        contents: generateModuleDeclaration(entry, { surface }).contents,
+      })),
+  );
 
   files.push(...augmentations);
   files.push({ path: "core-types.d.ts", contents: CORE_TYPES_REEXPORT });

package/scripts/regen.ts

@@ -42,7 +42,7 @@ import {
 import { loadTranslations } from "./example-store-io";
 import { synthesizeProseConstants } from "./prose-constants";
 import { restoreSharedHandleMethods } from "./shared-handle-methods";
-import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
+import { groupDocsByNamespace, mergeApiDocs, type readZip } from "./sync-api-docs";
 
 export interface ApiTargetModule {
   readonly namespace: string;
@@ -120,6 +120,12 @@ function withSkipRules(entry: ModuleManifestEntry, module: ApiTargetModule): Mod
   };
 }
 
+// Shared by both module sources: a step applied in one branch alone gives a
+// ref-doc surface different members from a committed one.
+function restoreOmittedMembers(modules: readonly ModuleManifestEntry[]): ModuleManifestEntry[] {
+  return restoreSharedHandleMethods(synthesizeProseConstants(modules));
+}
+
 export function loadTargetModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
@@ -142,7 +148,7 @@ export function loadTargetModules(
     };
     return withSkipRules(entry, module);
   });
-  return restoreSharedHandleMethods(synthesizeProseConstants(modules));
+  return restoreOmittedMembers(modules);
 }
 
 export interface ModuleManifestEntry {
@@ -174,7 +180,6 @@ export interface ResolveTargetOptions {
   readonly cacheDir?: string;
   readonly download?: DownloadRefDoc;
   readonly readZip?: typeof readZip;
-  readonly syncManifest?: readonly SyncManifestEntry[];
   readonly packageRoot?: string;
   readonly channel?: RefDocChannel;
   readonly fetchChannelInfo?: FetchChannelInfo;
@@ -182,8 +187,8 @@ export interface ResolveTargetOptions {
 
 // Source-aware module resolution: a `null`-source target reads committed
 // fixtures from disk (delegates to loadTargetModules); a `ref-doc` target
-// resolves its docs on demand from the version's ref-doc zip, keyed by the
-// SYNC_MANIFEST namespace -> zip-entry map.
+// resolves its docs on demand from the version's ref-doc zip, reading every
+// doc the zip declares for the namespace, merged.
 export async function resolveTargetModules(
   target: ApiTarget,
   opts: ResolveTargetOptions = {},
@@ -200,24 +205,24 @@ export async function resolveTargetModules(
     ...(opts.readZip ? { readZip: opts.readZip } : {}),
     ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
-  const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
+  const grouped = groupDocsByNamespace(zip);
   const modules = target.modules.map((module) => {
-    const sync = syncManifest.find((s) => s.namespace === module.namespace);
-    if (!sync) {
+    const group = grouped.get(module.namespace);
+    if (!group) {
       throw new Error(
-        `api-targets.json: target "${target.id}" module "${module.namespace}": no SYNC_MANIFEST zip entry`,
+        `api-targets.json: target "${target.id}" module "${module.namespace}": no doc in the ref-doc zip declares this namespace`,
       );
     }
     const entry: ModuleManifestEntry = {
       namespace: module.namespace,
-      doc: JSON.parse(zip.read(sync.zipEntry)),
+      doc: mergeApiDocs(group.map((item) => item.doc)),
       outFile: module.outFile,
       importsFrom: target.coreTypesImport,
       sourceProvenance: provenance,
     };
     return withSkipRules(entry, module);
   });
-  return synthesizeProseConstants(modules);
+  return restoreOmittedMembers(modules);
 }
 
 const API_TARGETS = loadApiTargets();
@@ -451,6 +456,10 @@ export interface GenerateOptions {
   translations?: TranslationStore;
   urlParameters?: UrlParameterTable;
   registeredConstants?: ReadonlySet<string>;
+  // 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[];
 }
 
 interface PreparedGeneratedModule {
@@ -472,7 +481,7 @@ function prepareGeneratedModule(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): PreparedGeneratedModule {
-  const routed = routedModuleOf(entry);
+  const routed = routedModuleOf(entry, options?.surface);
   const { module, dropped } = routed?.prepared ?? withheldApiModule(entry);
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
   const translations = options?.translations ?? loadTranslations();
@@ -495,36 +504,61 @@ interface RoutedSurface {
 }
 
 const routedSurfaces = new Map<string, RoutedSurface>();
+const routedCallerSurfaces = new WeakMap<readonly ModuleManifestEntry[], RoutedSurface>();
+
+function routeSurface(entries: readonly ModuleManifestEntry[]): RoutedSurface {
+  const withheld = entries.map(withheldApiModule);
+  const routed = routeTypeDeclarations(withheld.map(({ module }) => module));
+  return {
+    modules: new Map(
+      entries.map((member, index) => [
+        member,
+        {
+          module: routed[index] as ApiModule,
+          dropped: (withheld[index] as { dropped: string[] }).dropped,
+        },
+      ]),
+    ),
+    declaredTypes: declaredTypePaths(routed),
+  };
+}
 
 // A doc may declare a type another module owns (`b2d.joint.revolute_definition`
 // in the `b2d` doc) or name one another doc declares (`material.constant_info`
 // in `compute`), so each committed surface is routed as a whole: the runtime
-// modules and the editor modules of one target, never across targets. An entry
-// outside every committed manifest routes alone, as a single-module surface.
-function routedModuleOf(entry: ModuleManifestEntry):
+// modules and the editor modules of one target, never across targets. A caller
+// that names its own surface routes that set instead. An entry with neither, and
+// outside every committed manifest, routes alone, as a single-module surface.
+function routedModuleOf(
+  entry: ModuleManifestEntry,
+  callerSurface?: readonly ModuleManifestEntry[],
+):
   | {
       prepared: { module: ApiModule; dropped: string[] };
       declaredTypes: ReadonlyMap<string, string>;
     }
   | undefined {
+  if (callerSurface !== undefined) {
+    let surface = routedCallerSurfaces.get(callerSurface);
+    if (surface === undefined) {
+      surface = routeSurface(callerSurface);
+      routedCallerSurfaces.set(callerSurface, surface);
+    }
+    const prepared = surface.modules.get(entry);
+    // Falling back to a lone module here would emit `unknown` for every type a
+    // sibling declares, which type-checks and so goes unnoticed.
+    if (prepared === undefined) {
+      throw new Error(
+        `module "${entry.namespace}" is not a member of the surface it is emitted in`,
+      );
+    }
+    return { prepared, declaredTypes: surface.declaredTypes };
+  }
   const located = committedSurfaceOf(entry);
   if (located === undefined) return undefined;
   let surface = routedSurfaces.get(located.key);
   if (surface === undefined) {
-    const withheld = located.entries.map(withheldApiModule);
-    const routed = routeTypeDeclarations(withheld.map(({ module }) => module));
-    surface = {
-      modules: new Map(
-        located.entries.map((member, index) => [
-          member,
-          {
-            module: routed[index] as ApiModule,
-            dropped: (withheld[index] as { dropped: string[] }).dropped,
-          },
-        ]),
-      ),
-      declaredTypes: declaredTypePaths(routed),
-    };
+    surface = routeSurface(located.entries);
     routedSurfaces.set(located.key, surface);
   }
   const prepared = surface.modules.get(located.member);

package/scripts/sync-api-docs.ts

@@ -11,7 +11,7 @@ import { MODULE_MANIFEST } from "./regen";
 // model because the per-package `rootDir` boundary forbids a types-package
 // module importing outside its own tree; `scripts/release-model.test.ts`
 // correspondence-guards these against the model so drift fails CI.
-export const DEFOLD_VERSION = "1.13.2";
+export const DEFOLD_VERSION = "1.14.0";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -216,7 +216,7 @@ function editorVm(namespace: string): SyncManifestEntry {
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/defold-1.13.2/${namespace.replace(/\./g, "_")}_doc.json`,
+  fixture: string = `fixtures/defold-1.14.0/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
@@ -538,6 +538,35 @@ export interface CoverageInput {
   ignoredUpstream?: ReadonlyMap<string, string>;
 }
 
+// The Lua docs of a zip, grouped by the namespace each one declares. Entry names
+// belong to one release (`label` is one entry in 1.9.8 and two in 1.14.0), so
+// the declared namespace picks the docs. Entries are read in sorted order
+// because `mergeApiDocs` keeps the first doc's `info` and the docs' element
+// order; only `.json` entries are read because each read of a real zip is one
+// `unzip -p` process.
+export function groupDocsByNamespace(
+  zip: ZipAccessor,
+): Map<string, { entry: string; doc: Record<string, unknown> }[]> {
+  const grouped = new Map<string, { entry: string; doc: Record<string, unknown> }[]>();
+  for (const entry of [...zip.entries()].sort()) {
+    if (!entry.endsWith(".json")) continue;
+    const raw = zip.read(entry);
+    let doc: unknown;
+    try {
+      doc = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!isRecord(doc)) continue;
+    const namespace = isRecord(doc.info) ? doc.info.namespace : undefined;
+    if (typeof namespace !== "string" || !LUA_NAMESPACE.test(namespace)) continue;
+    const group = grouped.get(namespace) ?? [];
+    group.push({ entry, doc });
+    grouped.set(namespace, group);
+  }
+  return grouped;
+}
+
 // Enumerate every `doc/*.json` zip entry, reading its `info.namespace` and the
 // count of FUNCTION elements. Only function-bearing docs are returned, so
 // message-only / struct-only docs never reach the coverage guard.

package/src/emit-dts.ts

@@ -5639,6 +5639,27 @@ function unionFromTokens(tokens: readonly string[], mapType: DefoldTypeMapper):
 }
 
 const BRAND_ARM = /^(?:number|string) & \{ readonly __brand: "([^"]+)" \}$/;
+const OPAQUE_ARM = /^Opaque<("[^"]+"(?: \| "[^"]+")*)>$/;
+
+// Drops each `Opaque` arm whose brands are a proper subset of another `Opaque`
+// arm's. `Opaque<Name>` holds `Name` in one readonly property, so a narrower
+// brand set is assignable to a wider one and the narrower arm adds nothing.
+// An arm of any other shape (`Opaque<"x">[]`, an intersection) is never dropped
+// and never causes a drop.
+function withoutSubsumedOpaqueArms(mapped: readonly string[]): string[] {
+  const brandSets = mapped.map((arm) => {
+    const match = OPAQUE_ARM.exec(arm);
+    return match === null ? undefined : new Set((match[1] as string).split(" | "));
+  });
+  return mapped.filter((_, index) => {
+    const own = brandSets[index];
+    if (own === undefined) return true;
+    return !brandSets.some(
+      (other) =>
+        other !== undefined && other.size > own.size && [...own].every((b) => other.has(b)),
+    );
+  });
+}
 
 // Joins already-mapped arms, collapsing the branded ones to their alias when
 // they are exactly a `CONSTANT_UNION_ALIASES` member set. The alias takes the
@@ -5646,16 +5667,17 @@ const BRAND_ARM = /^(?:number|string) & \{ readonly __brand: "([^"]+)" \}$/;
 // (`gui.Easing | Vector`). Arms that are not constants are untouched, and a set
 // with no row keeps every arm inline.
 function joinUnionArms(mapped: readonly string[]): string {
+  const arms = withoutSubsumedOpaqueArms(mapped);
   const branded: string[] = [];
-  for (const arm of mapped) {
+  for (const arm of arms) {
     const match = BRAND_ARM.exec(arm);
     if (match !== null) branded.push(match[1] as string);
   }
   const alias = constantUnionAlias(branded);
-  if (alias === undefined) return mapped.join(" | ");
+  if (alias === undefined) return arms.join(" | ");
   const out: string[] = [];
   let placed = false;
-  for (const arm of mapped) {
+  for (const arm of arms) {
     if (BRAND_ARM.test(arm)) {
       if (placed) continue;
       out.push(`${alias.home}.${alias.name}`);