@defold-typescript/types 0.26.0 → 0.27.0

package/generated/versions/defold-1.13.0/webview.d.ts

@@ -0,0 +1,68 @@
+/** @noSelfInFile */
+declare global {
+  /**
+   * Functions and constants for interacting with webview APIs
+   */
+  namespace webview {
+    /**
+     * Creates a webview instance. It can show HTML pages as well as evaluate Javascript. The view remains hidden until the first call. There can exist a maximum of 4 webviews at the same time.
+     * On iOS, the callback will never get a `webview.CALLBACK_RESULT_EVAL_ERROR`, due to the iOS SDK implementation."
+     *
+     * @param callback - A callback which receives info about finished requests taking the following parameters:
+     */
+    function create(callback: (...args: unknown[]) => unknown): void;
+    /**
+     * Destroys an instance of a webview.
+     *
+     * @param webview_id - The webview id (returned by the `webview.create()` call)
+     */
+    function destroy(webview_id: number): void;
+    /**
+     * Evaluates JavaScript within the context of the currently loaded page (if any). Once the request is done, the callback (registered in `webview.create()`) is invoked. The callback will get the result in the `data["result"]` field.
+     *
+     * @param webview_id - The webview id
+     * @param code - The JavaScript code to evaluate
+     */
+    function eval(webview_id: number, code: string): void;
+    /**
+     * Returns the visibility state of the webview.
+     *
+     * @param webview_id - The webview id
+     */
+    function is_visible(webview_id: number): void;
+    /**
+     * Opens a web page in the webview, using HTML data. Once the request is done, the callback (registered in `webview.create()`) is invoked.
+     *
+     * @param webview_id - The webview id
+     * @param html - The HTML data to display
+     * @param options - A table of options for the request. See `webview.open()`
+     */
+    function open_raw(webview_id: number, html: string, options: Record<string | number, unknown>): void;
+    /**
+     * Sets the position and size of the webview
+     *
+     * @param webview_id - The webview id
+     * @param x - The x position of the webview
+     * @param y - The y position of the webview
+     * @param width - The width of the webview (-1 to match screen width)
+     * @param height - The height of the webview (-1 to match screen height)
+     */
+    function set_position(webview_id: number, x: number, y: number, width: number, height: number): void;
+    /**
+     * Set transparency of webview background
+     *
+     * @param webview_id - The webview id
+     * @param transparent - If `true`, the webview background becomes transparent, otherwise opaque.
+     */
+    function set_transparent(webview_id: number, transparent: boolean): void;
+    /**
+     * Shows or hides a webview
+     *
+     * @param webview_id - The webview id
+     * @param visible - If `0`, hides the webview. If non zero, shows the view
+     */
+    function set_visible(webview_id: number, visible: number): void;
+  }
+}
+
+export {};

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

@@ -0,0 +1,198 @@
+/** @noSelfInFile */
+import type { Opaque } from "../../../src/core-types";
+
+declare global {
+  /**
+   * Functions and constants to access the window, window event listeners
+   * and screen dimming.
+   */
+  namespace window {
+    /**
+     * 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 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 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" };
+    /**
+     * 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" };
+    /**
+     * 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" };
+    /**
+     * 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" };
+    /**
+     * 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_ICONFIED: number & { readonly __brand: "window.WINDOW_EVENT_ICONFIED" };
+    /**
+     * 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
+     *
+     * - `window.DIMMING_UNKNOWN`
+     *
+     * - `window.DIMMING_ON`
+     *
+     * - `window.DIMMING_OFF`
+     */
+    function get_dim_mode(): Opaque<"constant">;
+    /**
+     * 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
+     *
+     * `safe_area`
+     * table table containing these keys:
+     *
+     * - number `x`
+     *
+     * - number `y`
+     *
+     * - number `width`
+     *
+     * - number `height`
+     *
+     * - number `inset_left`
+     *
+     * - number `inset_top`
+     *
+     * - number `inset_right`
+     *
+     * - number `inset_bottom`
+     */
+    function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
+    /**
+     * 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
+     *
+     * - `window.DIMMING_ON`
+     *
+     * - `window.DIMMING_OFF`
+     */
+    function set_dim_mode(mode: Opaque<"constant">): 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.
+     *
+     * `self`
+     * object The calling script
+     * `event`
+     * constant The type of event. Can be one of these:
+     *
+     * - `window.WINDOW_EVENT_FOCUS_LOST`
+     *
+     * - `window.WINDOW_EVENT_FOCUS_GAINED`
+     *
+     * - `window.WINDOW_EVENT_RESIZED`
+     *
+     * - `window.WINDOW_EVENT_ICONIFIED`
+     *
+     * - `window.WINDOW_EVENT_DEICONIFIED`
+     *
+     * `data`
+     * table The callback value `data` is a table which currently holds these values
+     *
+     * - number `width`: The width of a resize event. nil otherwise.
+     *
+     * - number `height`: The height of a resize event. nil otherwise.
+     * @example
+     * ```ts
+     * function window_callback(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_ICONFIED) {
+     *     print("window.WINDOW_EVENT_ICONFIED");
+     *   } 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);
+     *   }
+     * }
+     *
+     * export default defineScript({
+     *   init() {
+     *     window.set_listener(window_callback);
+     *   },
+     * });
+     * ```
+     */
+    function set_listener(callback?: (self: unknown, event: typeof WINDOW_EVENT_FOCUS_LOST | typeof WINDOW_EVENT_FOCUS_GAINED | typeof WINDOW_EVENT_RESIZED | typeof WINDOW_EVENT_ICONFIED | typeof WINDOW_EVENT_DEICONIFIED, data: Record<string | number, unknown>) => void): 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.0/zlib.d.ts

@@ -0,0 +1,40 @@
+/** @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 = "\120\94\11\201\200\44\86\0\162\68\133\226\146\162\204\188\116\133\242\204\146\12\133\210\188\228\252\220\130\162\212\226\226\212\20\133\148\196\146\68\61\0\44\67\14\201";
+     * const uncompressed_data = zlib.inflate(data);
+     * print(uncompressed_data); //> This is a string with uncompressed data.
+     * ```
+     */
+    function inflate(buf: string): string;
+  }
+}
+
+export {};

package/index.d.ts

@@ -56,87 +56,7 @@ import "./generated/webview";
 import "./generated/window";
 import "./generated/zlib";
 
-export {
-  type ApiAvailability,
-  type ApiSymbolIdentity,
-  type AvailabilityLabel,
-  type AvailabilityLabelKind,
-  type AvailabilityLabelOptions,
-  availabilityLabel,
-  deriveAvailabilityMatrix,
-  groupByLogicalName,
-  isSignatureTransition,
-  type LogicalNameGroup,
-  normalizedFunctionSignature,
-  signatureTransitionNames,
-  symbolIdentityKey,
-  symbolNameKey,
-  type VersionSurface,
-} from "./src/api-availability";
-export type { ApiFunction, ApiModule, ApiParameter, ApiVariable } from "./src/api-doc";
-export { parseDefoldApiDoc } from "./src/api-doc";
-export {
-  DEFOLD_TYPE_MAP,
-  type Hash,
-  type Matrix4,
-  type Quaternion,
-  type Url,
-  type Vector,
-  type Vector3,
-  type Vector4,
-} from "./src/core-types";
-export {
-  examplesHtmlToMarkdown,
-  htmlToCodeText,
-  htmlToDocText,
-  renderDocComment,
-} from "./src/doc-comment";
-export {
-  defineEditorScript,
-  type EditorCommand,
-  type EditorScriptModule,
-} from "./src/editor";
-export {
-  type EmitOptions,
-  emitDeclarations,
-  TS_IDENTIFIER,
-  TS_RESERVED_NAMES,
-} from "./src/emit-dts";
-export {
-  hashExampleSource,
-  lookupTranslation,
-  type Translation,
-  type TranslationStore,
-} from "./src/example-store";
-export {
-  hasTopLevelUnion,
-  luaMultiReturn,
-  needsArrayParens,
-  varargElementType,
-} from "./src/library-signature";
-export {
-  defineGuiScript,
-  defineRenderScript,
-  defineScript,
-  type GuiScriptHooks,
-  type InputAction,
-  type InputTouch,
-  type RenderScriptHooks,
-  SCRIPT_HOOK_NAMES,
-  type ScriptHookName,
-  type ScriptHooks,
-  type ScriptProperties,
-  type ScriptPropertiesOf,
-  type ScriptProperty,
-} from "./src/lifecycle";
-export { type WrapOptions, wrapAsAmbientGlobal } from "./src/publish-dts";
-export {
-  lookupSignature,
-  type SignatureOverride,
-  type SignatureStore,
-} from "./src/signature-store";
-export type {
-  UrlParameterClass,
-  UrlParameterEntry,
-  UrlParameterTable,
-} from "./src/url-parameters";
+// The root export set lives in `src/index.ts`, the runtime `default` condition.
+// Re-exporting it keeps the `types` condition from drifting into a subset, and
+// is what `@defold-typescript/types/api` publishes for a pinned entrypoint.
+export * from "./src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,9 @@
     "./editor-script": {
       "types": "./generated/kinds/editor-script.d.ts"
     },
+    "./api": {
+      "types": "./src/index.ts"
+    },
     "./core-types": {
       "types": "./src/core-types.ts"
     },
@@ -57,9 +60,13 @@
     "api-signatures.json",
     "url-parameters.json",
     "index.d.ts",
+    "fixtures/messages_doc.json",
+    "fixtures/defold-*",
+    "examples/translations.json",
     "!src/**/*.test.ts",
     "!scripts/**/*.test.ts",
-    "!src/**/__snapshots__"
+    "!src/**/__snapshots__",
+    "!scripts/lua-types-signature-index.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -75,7 +82,8 @@
     "ref-doc-delta": "bun scripts/ref-doc-delta.ts --target defold-1.9.8 --namespace label --present label.get_text --absent label.set_text"
   },
   "dependencies": {
-    "lua-types": "^2.13.1"
+    "lua-types": "^2.13.1",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@typescript-to-lua/language-extensions": "1.19.0",

package/scripts/import-defold-release.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { isKnownDefoldTypeToken } from "../src/emit-dts";
 import { refDocCacheDir, resolveRefDoc } from "./doc-source";
@@ -387,6 +387,23 @@ export function applyReleaseImport(plan: ReleaseImportPlan, packageRoot = PACKAG
     writeFileSync(path, `${JSON.stringify(snapshot.doc, null, 2)}\n`);
     written.push(relative);
   }
+  // The prefixless builtins (`hash`, `pprint`, ...) are hand-vendored rather than
+  // generated, so no upstream snapshot carries them. Seeding the canonical copy
+  // here is what keeps a newly imported target from being born without a globals
+  // document — which the availability projection would read as a removal. The
+  // source is always the real package's canonical file, never `packageRoot`,
+  // which for a writer test is an empty temp tree.
+  const canonicalGlobals = resolve(PACKAGE_ROOT, "fixtures/globals_doc.json");
+  if (!existsSync(canonicalGlobals))
+    throw new Error(`missing canonical globals document at ${canonicalGlobals}`);
+  const globals = JSON.parse(readFileSync(canonicalGlobals, "utf8")) as {
+    info: Record<string, unknown>;
+  };
+  globals.info = { ...globals.info, version: plan.version };
+  const globalsPath = `${relativeRoot}/globals_doc.json`;
+  writeFileSync(resolve(packageRoot, globalsPath), `${JSON.stringify(globals, null, 2)}\n`);
+  written.push(globalsPath);
+
   const manifestPath = `${relativeRoot}/import-manifest.json`;
   writeFileSync(resolve(packageRoot, manifestPath), releaseImportReportJson(plan));
   written.push(manifestPath);

package/src/example-store.ts

@@ -10,6 +10,11 @@ export interface Translation {
 // An FQN maps to one translation per distinct example body it carries: an
 // overloaded element (same name, differing `@example` source) contributes one
 // array entry per body, each pinned by its own `sourceHash`.
+//
+// add-don't-swap: a ref-doc re-pin that rewrites an element's example must
+// *append* the translation for the new source hash, never overwrite the entry
+// for the old one. Older API targets keep shipping the previous body, so
+// replacing the entry silently regresses every demoted surface to raw Lua.
 export type TranslationStore = Record<string, Translation[]>;
 
 const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;

package/scripts/lua-types-signature-index.ts

@@ -1,151 +0,0 @@
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import * as ts from "typescript";
-
-// Build-time only: lives under `scripts/` (never reachable from the shipped
-// `src/index.ts` graph) so its `typescript`/`node:fs` imports cannot leak into a
-// consumer's typecheck, exactly like `signature-store-fs.ts`.
-
-// One indexed declaration: how many overloads the source carries for the FQN
-// and, per overload, the parameter names (so a future check can compare optional
-// params). A `const`/`var`/property value is recorded as a single entry with an
-// empty parameter list.
-export interface SignatureIndexEntry {
-  overloadCount: number;
-  params: string[][];
-}
-
-// FQN (`string.byte`, `file:read`, `socket.dns.toip`, bare `pcall`) -> entry.
-export type SignatureIndex = Map<string, SignatureIndexEntry>;
-
-export const LUA_TYPES_DIR = resolve(import.meta.dir, "..", "node_modules", "lua-types");
-
-export function luaTypesFile(...segments: string[]): string {
-  return resolve(LUA_TYPES_DIR, ...segments);
-}
-
-function recordEntry(index: SignatureIndex, key: string, params: string[]): void {
-  const existing = index.get(key);
-  if (existing) {
-    existing.overloadCount += 1;
-    existing.params.push(params);
-    return;
-  }
-  index.set(key, { overloadCount: 1, params: [params] });
-}
-
-function parameterNames(parameters: ts.NodeArray<ts.ParameterDeclaration>): string[] {
-  return parameters.map((parameter) =>
-    ts.isIdentifier(parameter.name) ? parameter.name.text : parameter.name.getText(),
-  );
-}
-
-// `declare global { ... }` is a transparent wrapper (the repo's `generated/*.d.ts`
-// nest their namespace under it); its members keep the surrounding prefix.
-function isGlobalAugmentation(node: ts.ModuleDeclaration): boolean {
-  if ((node.flags & ts.NodeFlags.GlobalAugmentation) !== 0) return true;
-  return ts.isIdentifier(node.name) && node.name.text === "global";
-}
-
-function qualify(prefix: string, name: string): string {
-  return prefix ? `${prefix}.${name}` : name;
-}
-
-function visit(
-  node: ts.Node,
-  prefix: string,
-  handleByInterface: Map<string, string>,
-  index: SignatureIndex,
-): void {
-  if (ts.isFunctionDeclaration(node) && node.name) {
-    recordEntry(index, qualify(prefix, node.name.text), parameterNames(node.parameters));
-    return;
-  }
-
-  if (ts.isModuleDeclaration(node)) {
-    const childPrefix = isGlobalAugmentation(node)
-      ? prefix
-      : ts.isIdentifier(node.name)
-        ? qualify(prefix, node.name.text)
-        : prefix;
-    if (node.body) {
-      if (ts.isModuleBlock(node.body)) {
-        for (const statement of node.body.statements) {
-          visit(statement, childPrefix, handleByInterface, index);
-        }
-      } else if (ts.isModuleDeclaration(node.body)) {
-        visit(node.body, childPrefix, handleByInterface, index);
-      }
-    }
-    return;
-  }
-
-  // Handle interfaces are re-keyed by their handle name (`LuaFile` -> `file:read`,
-  // socket's `client` -> `client:close`); non-handle interfaces are ignored. This
-  // fires for both top-level interfaces (io's `LuaFile`) and interfaces nested in
-  // a namespace (socket's handle interfaces), so the surrounding prefix is dropped.
-  if (ts.isInterfaceDeclaration(node)) {
-    const handle = handleByInterface.get(node.name.text);
-    if (!handle) return;
-    for (const member of node.members) {
-      if (!member.name || !ts.isIdentifier(member.name)) continue;
-      if (ts.isMethodSignature(member)) {
-        recordEntry(index, `${handle}:${member.name.text}`, parameterNames(member.parameters));
-      } else if (ts.isPropertySignature(member)) {
-        recordEntry(index, `${handle}:${member.name.text}`, []);
-      }
-    }
-    return;
-  }
-
-  if (ts.isVariableStatement(node)) {
-    for (const declaration of node.declarationList.declarations) {
-      if (ts.isIdentifier(declaration.name)) {
-        recordEntry(index, qualify(prefix, declaration.name.text), []);
-      }
-    }
-  }
-}
-
-function reverseHandles(handleInterfaces: Record<string, string>): Map<string, string> {
-  return new Map(Object.entries(handleInterfaces).map(([handle, iface]) => [iface, handle]));
-}
-
-function indexSourceFile(
-  index: SignatureIndex,
-  fileName: string,
-  source: string,
-  handleByInterface: Map<string, string>,
-): void {
-  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
-  for (const statement of sourceFile.statements) {
-    visit(statement, "", handleByInterface, index);
-  }
-}
-
-// Parse one in-memory `.d.ts` source into an index (or fold into `into`). Used by
-// the drift guard's synthetic-source cases; the file-reading path delegates here.
-export function indexDeclarationSource(
-  fileName: string,
-  source: string,
-  handleInterfaces: Record<string, string> = {},
-  into?: SignatureIndex,
-): SignatureIndex {
-  const index = into ?? new Map<string, SignatureIndexEntry>();
-  indexSourceFile(index, fileName, source, reverseHandles(handleInterfaces));
-  return index;
-}
-
-// Parse each `.d.ts` file and fold every declaration into one FQN -> entry index.
-// When an FQN appears in more than one file its overloads accumulate.
-export function buildSignatureIndex(
-  filePaths: string[],
-  handleInterfaces: Record<string, string> = {},
-): SignatureIndex {
-  const index = new Map<string, SignatureIndexEntry>();
-  const handleByInterface = reverseHandles(handleInterfaces);
-  for (const filePath of filePaths) {
-    indexSourceFile(index, filePath, readFileSync(filePath, "utf8"), handleByInterface);
-  }
-  return index;
-}