@defold-typescript/types 0.19.4 → 0.20.1

package/scripts/materialize-version.ts

@@ -31,8 +31,7 @@ export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOpt
   return `${LUA_STDLIB_REFERENCES}${lines.join("\n")}\n\nexport { ${entry.factory} } from "@defold-typescript/types/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "@defold-typescript/types/lifecycle";\n`;
 }
 
-export interface MaterializeVersionedSurfaceOptions {
-  readonly destDir: string;
+export interface BuildVersionedSurfaceOptions {
   readonly resolveOpts?: ResolveTargetOptions;
   // Bare module names (no `.d.ts`) to omit from the surface — both the emitted
   // file and its aggregate-index import. Lets a caller narrow the surface to a
@@ -40,35 +39,61 @@ export interface MaterializeVersionedSurfaceOptions {
   readonly excludeModules?: readonly string[];
 }
 
-// Generate a versioned surface on the fly into a project-local faux `@types`
-// package: resolve the target's module docs (ref-doc or committed fixture),
-// emit each module declaration, then write the aggregate side-effect entrypoint
-// and a minimal package.json. ref-doc targets are never pre-baked, so this is
-// the only path that turns a resolved version into a consumable type surface.
-export async function materializeVersionedSurface(
+export interface MaterializeVersionedSurfaceOptions extends BuildVersionedSurfaceOptions {
+  readonly destDir: string;
+}
+
+export interface VersionedSurfaceFile {
+  // Relative to the surface root, so a sink can write it to disk or key it in
+  // object storage without rewriting the path.
+  readonly path: string;
+  readonly contents: string;
+}
+
+// Generate a versioned surface as an in-memory file map: resolve the target's
+// module docs (ref-doc or committed fixture), emit each module declaration, then
+// the aggregate side-effect entrypoint and a minimal package.json. Pure — no
+// `node:fs` — so a Worker with no filesystem can serve a version generated at
+// request time; `materializeVersionedSurface` is the disk sink over the same map.
+export async function buildVersionedSurfaceFiles(
   target: ApiTarget,
-  opts: MaterializeVersionedSurfaceOptions,
-): Promise<void> {
+  opts: BuildVersionedSurfaceOptions = {},
+): Promise<VersionedSurfaceFile[]> {
   const exclude = new Set(opts.excludeModules ?? []);
   const modules = (await resolveTargetModules(target, opts.resolveOpts ?? {})).filter(
     (entry) => !exclude.has(entry.outFile.replace(/\.d\.ts$/, "")),
   );
-  mkdirSync(opts.destDir, { recursive: true });
 
-  for (const entry of modules) {
-    const { contents } = generateModuleDeclaration(entry);
-    writeFileSync(resolve(opts.destDir, entry.outFile), contents);
-  }
+  const files: VersionedSurfaceFile[] = modules.map((entry) => ({
+    path: entry.outFile,
+    contents: generateModuleDeclaration(entry).contents,
+  }));
 
   const versioned = modules.map((entry) => ({ ...entry, versionId: target.id }));
-  writeFileSync(resolve(opts.destDir, "index.d.ts"), generateVersionIndex(target.id, versioned));
+  files.push({ path: "index.d.ts", contents: generateVersionIndex(target.id, versioned) });
 
-  writeFileSync(
-    resolve(opts.destDir, "package.json"),
-    `${JSON.stringify(
+  files.push({
+    path: "package.json",
+    contents: `${JSON.stringify(
       { name: `@defold-typescript/materialized-${target.id}`, types: "index.d.ts" },
       null,
       2,
     )}\n`,
-  );
+  });
+
+  return files;
+}
+
+// Write the generated surface into a project-local faux `@types` package.
+// ref-doc targets are never pre-baked, so this is the only path that turns a
+// resolved version into a consumable on-disk type surface.
+export async function materializeVersionedSurface(
+  target: ApiTarget,
+  opts: MaterializeVersionedSurfaceOptions,
+): Promise<void> {
+  const files = await buildVersionedSurfaceFiles(target, opts);
+  mkdirSync(opts.destDir, { recursive: true });
+  for (const file of files) {
+    writeFileSync(resolve(opts.destDir, file.path), file.contents);
+  }
 }

package/scripts/regen.ts

@@ -1,9 +1,13 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
-import { parseDefoldApiDoc } from "../src/api-doc";
-import { emitDeclarations } from "../src/emit-dts";
-import { emitBuiltinMessages, parseMessagesDoc } from "../src/emit-messages";
+import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
+import { emitDeclarations, emitSymbolSignatures, type SymbolSignature } from "../src/emit-dts";
+import {
+  applyMessageDeprecations,
+  emitBuiltinMessages,
+  parseMessagesDoc,
+} from "../src/emit-messages";
 import type { TranslationStore } from "../src/example-store";
 import { wrapAsAmbientGlobal } from "../src/publish-dts";
 import {
@@ -143,6 +147,15 @@ const DEFAULT_TARGET = API_TARGETS.find((t) => t.default === true) as ApiTarget;
 
 export const MODULE_MANIFEST: readonly ModuleManifestEntry[] = loadTargetModules(DEFAULT_TARGET);
 
+// The fidelity audit runs over the promoted default surface (the `default: true`
+// target) so the 1.13-only modules (b2d.*, compute, material) and the 1.13 model
+// additions are audited too — auditing the older 1.12.4 target left them unseen,
+// which is how the promoted surface shipped opaque `Record` fallbacks while the
+// gate read `recordTables: 0`.
+const FIDELITY_BASELINE_TARGET = DEFAULT_TARGET;
+export const FIDELITY_BASELINE_MANIFEST: readonly ModuleManifestEntry[] =
+  loadTargetModules(FIDELITY_BASELINE_TARGET);
+
 export interface MessagesManifestEntry {
   readonly doc: unknown;
   readonly outFile: string;
@@ -158,7 +171,7 @@ export const MESSAGES_MANIFEST: MessagesManifestEntry = {
 };
 
 export function generateBuiltinMessagesDeclaration(entry: MessagesManifestEntry): string {
-  return emitBuiltinMessages(parseMessagesDoc(entry.doc));
+  return emitBuiltinMessages(applyMessageDeprecations(parseMessagesDoc(entry.doc)));
 }
 
 export interface GenerateResult {
@@ -185,10 +198,21 @@ export interface GenerateOptions {
   translations?: TranslationStore;
 }
 
-export function generateModuleDeclaration(
+interface PreparedGeneratedModule {
+  module: ApiModule;
+  knownConstantFqns: ReadonlySet<string>;
+  translations: TranslationStore;
+  dropped: string[];
+}
+
+// Parse a manifest entry, apply its `skipFunctions` filter, and resolve the
+// shared constant-brand universe and translations. Both the `.d.ts` emit and
+// the authoritative-signature emit run off this identical prepared module, so a
+// dropped member never appears in either surface.
+function prepareGeneratedModule(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
-): GenerateResult {
+): PreparedGeneratedModule {
   const module = parseDefoldApiDoc(entry.doc);
   const prefix = `${module.namespace}.`;
   const dropped: string[] = [];
@@ -203,6 +227,17 @@ export function generateModuleDeclaration(
   });
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
   const translations = options?.translations ?? loadTranslations();
+  return { module, knownConstantFqns, translations, dropped };
+}
+
+export function generateModuleDeclaration(
+  entry: ModuleManifestEntry,
+  options?: GenerateOptions,
+): GenerateResult {
+  const { module, knownConstantFqns, translations, dropped } = prepareGeneratedModule(
+    entry,
+    options,
+  );
   const emitted = emitDeclarations(module, { knownConstantFqns, translations });
   const contents = wrapAsAmbientGlobal({
     namespace: module.namespace,
@@ -212,6 +247,18 @@ export function generateModuleDeclaration(
   return { contents, 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
+// `.d.ts` byte-for-byte.
+export function generateModuleSignatures(
+  entry: ModuleManifestEntry,
+  options?: GenerateOptions,
+): SymbolSignature[] {
+  const { module, knownConstantFqns } = prepareGeneratedModule(entry, options);
+  return emitSymbolSignatures(module, { knownConstantFqns });
+}
+
 export interface VersionedModuleManifestEntry extends ModuleManifestEntry {
   readonly versionId: string;
 }

package/scripts/sync-api-docs.ts

@@ -6,7 +6,7 @@ import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import { parseScriptApi } from "../src/script-api";
 import { MODULE_MANIFEST } from "./regen";
 
-export const DEFOLD_VERSION = "1.12.4";
+export const DEFOLD_VERSION = "1.13.0";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -26,52 +26,71 @@ export interface SyncManifestEntry {
 // so each path is confirmed against the pinned release artifact, not derived.
 export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("b2d", "doc/scripts-box2d-script_box2d.cpp_doc.json"),
-  // On-disk name uses underscores to avoid a double-dotted filename; the namespace
-  // string stays `b2d.body` so /api/b2d.body routes correctly and the emitter
-  // produces `declare global { namespace b2d.body { ... } }`. Use the non-`_defold`
-  // variant — the `_defold` variant has duplicate `get_world_center` elements.
-  entry(
-    "b2d.body",
-    "doc/scripts-box2d-script_box2d_body.cpp_doc.json",
-    "fixtures/b2d_body_doc.json",
-  ),
+  // Box2D 1.13.0 documents the v2 and v3 backends separately. On-disk dotted
+  // namespaces use underscores while the namespace itself stays dotted.
+  entry("b2d.body", "doc/scripts-box2d-v2-script_box2d_body_v2.cpp_doc.json", undefined, [
+    "doc/scripts-box2d-v3-script_box2d_body_v3.cpp_doc.json",
+  ]),
+  entry("b2d.chain", "doc/scripts-box2d-v3-script_box2d_chain_v3.cpp_doc.json"),
+  entry("b2d.fixture", "doc/scripts-box2d-v2-script_box2d_fixture_v2.cpp_doc.json"),
+  entry("b2d.joint", "doc/scripts-box2d-v2-script_box2d_joint_v2.cpp_doc.json", undefined, [
+    "doc/scripts-box2d-v3-script_box2d_joint_v3.cpp_doc.json",
+  ]),
+  entry("b2d.shape", "doc/scripts-box2d-v2-script_box2d_shape_v2.cpp_doc.json", undefined, [
+    "doc/scripts-box2d-v3-script_box2d_shape_v3.cpp_doc.json",
+  ]),
+  entry("b2d.world", "doc/scripts-box2d-v2-script_box2d_world_v2.cpp_doc.json", undefined, [
+    "doc/scripts-box2d-v3-script_box2d_world_v3.cpp_doc.json",
+  ]),
   entry("buffer", "doc/scripts-script_buffer.cpp_doc.json"),
-  // camera's Lua surface lives in the render-script doc, not the scripts-script
-  // one (`doc/scripts-script_camera.cpp_doc.json` is empty upstream in 1.12.4).
-  entry("camera", "doc/render-render_script_camera.cpp_doc.json"),
+  // Camera and component namespaces merge their DDF messages/properties into
+  // the callable script API so release snapshots retain every declared symbol.
+  entry("camera", "doc/gamesys-camera_ddf.proto_doc.json", undefined, [
+    "doc/render-render_script_camera.cpp_doc.json",
+  ]),
   entry("collectionfactory", "doc/scripts-script_collection_factory.cpp_doc.json"),
   entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json"),
+  entry("compute", "doc/scripts-script_compute.cpp_doc.json"),
   entry("crash", "doc/script_crash.cpp_doc.json"),
   entry("factory", "doc/scripts-script_factory.cpp_doc.json"),
   entry("font", "doc/scripts-script_font.cpp_doc.json"),
-  entry("go", "doc/gameobject_script.cpp_doc.json"),
+  entry("go", "doc/gameobject-gameobject_ddf.proto_doc.json", undefined, [
+    "doc/gameobject_script.cpp_doc.json",
+  ]),
   entry("graphics", "doc/src-script_graphics.cpp_doc.json"),
-  entry("gui", "doc/gui_script.cpp_doc.json"),
+  entry("gui", "doc/gamesys-gui_ddf.proto_doc.json", undefined, ["doc/gui_script.cpp_doc.json"]),
   entry("html5", "doc/src-script_html5_js.cpp_doc.json"),
   entry("http", "doc/scripts-script_http.cpp_doc.json"),
   entry("image", "doc/scripts-script_image.cpp_doc.json"),
   entry("json", "doc/src-script_json.cpp_doc.json"),
-  entry("label", "doc/scripts-script_label.cpp_doc.json"),
+  entry("label", "doc/gamesys-label_ddf.proto_doc.json", undefined, [
+    "doc/scripts-script_label.cpp_doc.json",
+  ]),
   entry("liveupdate", "doc/src-script_liveupdate.h_doc.json"),
-  entry("model", "doc/scripts-script_model.cpp_doc.json"),
+  entry("material", "doc/scripts-script_material.cpp_doc.json"),
+  entry("model", "doc/gamesys-model_ddf.proto_doc.json", undefined, [
+    "doc/scripts-script_model.cpp_doc.json",
+  ]),
   entry("msg", "doc/src-script_msg.cpp_doc.json"),
   entry("particlefx", "doc/scripts-script_particlefx.cpp_doc.json"),
-  entry("physics", "doc/scripts-script_physics.cpp_doc.json"),
+  entry("physics", "doc/gamesys-physics_ddf.proto_doc.json", undefined, [
+    "doc/scripts-script_physics.cpp_doc.json",
+  ]),
   entry("profiler", "doc/profiler.cpp_doc.json"),
-  entry("render", "doc/render-render_script.cpp_doc.json"),
+  entry("render", "doc/render-render_ddf.proto_doc.json", undefined, [
+    "doc/render-render_script.cpp_doc.json",
+  ]),
   entry("resource", "doc/scripts-script_resource.cpp_doc.json"),
   entry("socket", "doc/luasocket-luasocket.doc_h_doc.json"),
   entry("sound", "doc/scripts-script_sound.cpp_doc.json"),
-  entry("sprite", "doc/scripts-script_sprite.cpp_doc.json"),
-  // The `sys` Lua surface is split across three docs in ref-doc.zip: the core
-  // (src-script_sys), the gamesys subset (`load_buffer`/`load_buffer_async` plus
-  // the `REQUEST_STATUS_*` constants), and the engine doc (`set_engine_throttle`/
-  // `set_render_enable`). `mergeEntries` folds all three into one fixture at sync
-  // time. The `*_ddf.proto` doc is deliberately excluded — it is message-shaped
-  // and owned by the builtin-messages catalog.
-  entry("sys", "doc/src-script_sys.cpp_doc.json", "fixtures/sys_doc.json", [
+  entry("sprite", "doc/gamesys-sprite_ddf.proto_doc.json", undefined, [
+    "doc/scripts-script_sprite.cpp_doc.json",
+  ]),
+  // The sys surface spans core, gamesys, engine, and DDF documents in 1.13.0.
+  entry("sys", "doc/script-script_engine.cpp_doc.json", undefined, [
+    "doc/script-sys_ddf.proto_doc.json",
     "doc/scripts-script_sys_gamesys.cpp_doc.json",
-    "doc/script-script_engine.cpp_doc.json",
+    "doc/src-script_sys.cpp_doc.json",
   ]),
   entry("tilemap", "doc/scripts-script_tilemap.cpp_doc.json"),
   entry("timer", "doc/src-script_timer.cpp_doc.json"),
@@ -118,7 +137,7 @@ export const IGNORED_UPSTREAM: ReadonlyMap<string, string> = new Map([
 export const LUA_STDLIB_MANIFEST: readonly SyncManifestEntry[] = [
   entry("base", "doc/lua_base.doc_h_doc.json"),
   entry("bit", "doc/src-script_bitop.cpp_doc.json"),
-  // Core Lua stdlib docs. The 1.12.4 release names these `doc/lua_<ns>.doc_h_doc.json`
+  // Core Lua stdlib docs. The 1.13.0 release names these `doc/lua_<ns>.doc_h_doc.json`
   // (confirmed against the pinned ref-doc.zip, not derived — the naming drifted from
   // the 1.9.8 `doc/<ns>_doc.json` form). Typed by the lua-types dependency, so docs-only.
   entry("math", "doc/lua_math.doc_h_doc.json"),
@@ -127,7 +146,7 @@ export const LUA_STDLIB_MANIFEST: readonly SyncManifestEntry[] = [
   entry("table", "doc/lua_table.doc_h_doc.json"),
   entry("coroutine", "doc/lua_coroutine.doc_h_doc.json"),
   // Sandboxed-runtime stdlib surfaces. Defold sandboxes the Lua VM, but the pinned
-  // 1.12.4 ref-doc.zip documents all three with real function elements; types stay
+  // 1.13.0 ref-doc.zip documents all three with real function elements; types stay
   // owned by lua-types (core/{debug,io}.d.ts + core/modules.d.ts for `package`).
   entry("debug", "doc/lua_debug.doc_h_doc.json"),
   entry("io", "doc/lua_io.doc_h_doc.json"),
@@ -137,7 +156,7 @@ export const LUA_STDLIB_MANIFEST: readonly SyncManifestEntry[] = [
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/${namespace}_doc.json`,
+  fixture: string = `fixtures/defold-1.13.0/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
@@ -163,7 +182,13 @@ export const EXTENSION_MANIFEST: readonly ExtensionManifestEntry[] = [
 ];
 
 function ext(namespace: string, repo: string, tag: string, path: string): ExtensionManifestEntry {
-  return { namespace, repo, tag, path, fixture: `fixtures/${namespace}_doc.json` };
+  return {
+    namespace,
+    repo,
+    tag,
+    path,
+    fixture: `fixtures/defold-1.13.0/${namespace}_doc.json`,
+  };
 }
 
 export const extensionRawUrl = (e: ExtensionManifestEntry): string =>
@@ -249,22 +274,20 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// Concatenate the `elements` of every doc into the first doc, deduping by
-// (name, type) with first occurrence winning, and keep the first doc's `info`.
-// First-wins guards the `b2d.body` `_defold` duplicate-`get_world_center`
-// hazard. Operates on the raw ref-doc JSON shape (`{ info, elements }`), so the
-// result is still parseable by `parseDefoldApiDoc`.
+// Concatenate the `elements` of every doc into the first doc, deduping exact
+// API signatures with first occurrence winning, and keep the first doc's
+// `info`. Function signatures include parameters and returns because the same
+// namespace can expose backend-specific overloads under one function name.
 export function mergeApiDocs(docs: readonly unknown[]): unknown {
   const first = docs[0];
   const seen = new Set<string>();
   const elements: unknown[] = [];
   for (const doc of docs) {
     if (!isRecord(doc) || !Array.isArray(doc.elements)) continue;
+    const info = isRecord(doc.info) ? doc.info : null;
+    const namespace = info && typeof info.namespace === "string" ? info.namespace : "";
     for (const element of doc.elements) {
-      const key =
-        isRecord(element) && typeof element.name === "string" && typeof element.type === "string"
-          ? `${element.type}${element.name}`
-          : null;
+      const key = apiElementIdentity(namespace, element);
       if (key !== null) {
         if (seen.has(key)) continue;
         seen.add(key);
@@ -275,6 +298,31 @@ export function mergeApiDocs(docs: readonly unknown[]): unknown {
   return isRecord(first) ? { ...first, elements } : { elements };
 }
 
+export function apiElementIdentity(namespace: string, element: unknown): string | null {
+  if (!isRecord(element) || typeof element.name !== "string" || typeof element.type !== "string") {
+    return null;
+  }
+  const base = `${namespace}\0${element.type}\0${element.name}`;
+  if (element.type !== "FUNCTION") return base;
+  return `${base}\0${normalizedArguments(element.parameters)}\0${normalizedArguments(element.returnvalues)}`;
+}
+
+function normalizedArguments(value: unknown): string {
+  if (!Array.isArray(value)) return "[]";
+  return JSON.stringify(
+    value.map((argument) => {
+      if (!isRecord(argument)) return argument;
+      const types = Array.isArray(argument.types)
+        ? argument.types.filter((type): type is string => typeof type === "string").sort()
+        : [];
+      return {
+        types,
+        ...(argument.is_optional === undefined ? {} : { is_optional: argument.is_optional }),
+      };
+    }),
+  );
+}
+
 export function extractFixtures(
   zip: ZipAccessor,
   manifest: readonly SyncManifestEntry[] = SYNC_MANIFEST,

package/src/core-types.ts

@@ -188,6 +188,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   vector4: "Vector4",
   quaternion: "Quaternion",
   matrix4: "Matrix4",
+  "vmath.vector3": "Vector3",
+  "vmath.vector4": "Vector4",
+  "vmath.matrix4": "Matrix4",
   hash: "Hash",
   url: "Url",
   node: 'Opaque<"node">',
@@ -201,6 +204,12 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   resource: 'Opaque<"resource">',
   b2World: 'Opaque<"b2World">',
   b2Body: 'Opaque<"b2Body">',
+  b2Chain: 'Opaque<"b2Chain">',
+  b2Shape: 'Opaque<"b2Shape">',
+  b2Joint: 'Opaque<"b2Joint">',
+  b2ContactEdge: 'Opaque<"b2ContactEdge">',
+  b2MassData: 'Opaque<"b2MassData">',
+  b2Transform: 'Opaque<"b2Transform">',
   b2BodyType:
     '(number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })',
   // socket handle types resolve to the method-bearing `interface <receiver>`