@defold-typescript/types 0.25.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,84 +56,7 @@ import "./generated/webview";
 import "./generated/window";
 import "./generated/zlib";
 
-export {
-  type ApiAvailability,
-  type ApiSymbolIdentity,
-  type AvailabilityLabel,
-  type AvailabilityLabelKind,
-  availabilityLabel,
-  deriveAvailabilityMatrix,
-  groupByLogicalName,
-  isSignatureTransition,
-  type LogicalNameGroup,
-  normalizedFunctionSignature,
-  symbolIdentityKey,
-  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.25.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,9 +1,10 @@
-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";
 import {
   apiElementIdentity,
+  EDITOR_MANIFEST,
   IGNORED_UPSTREAM,
   mergeApiDocs,
   readZip,
@@ -15,6 +16,14 @@ const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
 const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 
+// Editor-scripting namespaces are mapped, but not by `api-targets.json`: they
+// emit through `EDITOR_MODULE_MANIFEST` rather than the runtime module set the
+// baseline is built from, so the baseline can never vouch for them. Only
+// `EDITOR_MANIFEST` is consulted — `EDITOR_VM_MANIFEST` entries are split out of
+// the editor document and never surface as an upstream `info.namespace`, so
+// excusing their bare names would suppress a real runtime namespace instead.
+const EDITOR_MAPPED_NAMESPACES = new Set(EDITOR_MANIFEST.map((source) => source.namespace));
+
 // The set of namespaces promoted into the generated surface at Defold 1.13.0.
 // Held here rather than derived from the root release model because the
 // per-package `rootDir` boundary forbids importing outside this package tree;
@@ -325,6 +334,7 @@ export function buildReleaseImportPlan(input: {
       (source) =>
         source.functionCount > 0 &&
         !baselineByNamespace.has(source.namespace) &&
+        !EDITOR_MAPPED_NAMESPACES.has(source.namespace) &&
         !IGNORED_UPSTREAM.has(source.namespace),
     )
     .map((source) => ({
@@ -377,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/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.0";
+export const DEFOLD_VERSION = "1.13.1";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -184,6 +184,7 @@ export const EDITOR_MANIFEST: readonly SyncManifestEntry[] = [
 // `http_doc.json` / `json_doc.json` / `zlib_doc.json`.
 export const EDITOR_VM_MANIFEST: readonly SyncManifestEntry[] = [
   editorVm("http"),
+  editorVm("image"),
   editorVm("json"),
   editorVm("localization"),
   editorVm("zip"),
@@ -204,7 +205,7 @@ function editorVm(namespace: string): SyncManifestEntry {
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/defold-1.13.0/${namespace.replace(/\./g, "_")}_doc.json`,
+  fixture: string = `fixtures/defold-1.13.1/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
@@ -235,7 +236,7 @@ function ext(namespace: string, repo: string, tag: string, path: string): Extens
     repo,
     tag,
     path,
-    fixture: `fixtures/defold-1.13.0/${namespace}_doc.json`,
+    fixture: `fixtures/defold-1.13.1/${namespace}_doc.json`,
   };
 }
 

package/src/emit-dts.ts

@@ -157,6 +157,12 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // is opaque to the field-list parser and the whole-slot `Record` is faithful.
   "render.render_target",
   "render.set_render_target",
+  // reserved-but-undocumented options bag: `collectionproxy.load`'s `options`
+  // slot is documented verbatim as "options table, currently unused" and accepts
+  // `nil`, so upstream defines no field list to emit. The whole-slot `Record` is
+  // faithful to what is documented today. If a later release fills the bag in,
+  // drop this entry so the missing fields resurface under `recordTables`.
+  "collectionproxy.load",
 ]);
 
 // Per-slot companion to ARBITRARY_TABLE_SLOTS (`element:kind:name`), for a

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/src/index.ts

@@ -5,6 +5,7 @@ export {
   type ApiSymbolIdentity,
   type AvailabilityLabel,
   type AvailabilityLabelKind,
+  type AvailabilityLabelOptions,
   applyMigrationOverlay,
   availabilityLabel,
   type Box2dBackend,
@@ -14,7 +15,9 @@ export {
   isSignatureTransition,
   type LogicalNameGroup,
   normalizedFunctionSignature,
+  signatureTransitionNames,
   symbolIdentityKey,
+  symbolNameKey,
   type VersionSurface,
   validateAvailability,
 } from "./api-availability";