@defold-typescript/types 0.24.0 → 0.26.0

package/index.d.ts

@@ -5,6 +5,7 @@ import "./src/msg-overloads";
 import "./src/message-guard";
 import "./src/window-event-guard";
 import "./src/message-dispatch";
+import "./src/scene-addresses";
 import "./src/engine-globals";
 import "./generated/b2d";
 import "./generated/b2d_body";
@@ -60,13 +61,16 @@ export {
   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";
@@ -131,3 +135,8 @@ export {
   type SignatureOverride,
   type SignatureStore,
 } from "./src/signature-store";
+export type {
+  UrlParameterClass,
+  UrlParameterEntry,
+  UrlParameterTable,
+} from "./src/url-parameters";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -27,17 +27,24 @@
     "./render-script": {
       "types": "./generated/kinds/render-script.d.ts"
     },
+    "./editor-script": {
+      "types": "./generated/kinds/editor-script.d.ts"
+    },
     "./core-types": {
       "types": "./src/core-types.ts"
     },
     "./lifecycle": {
       "types": "./src/lifecycle.ts"
     },
+    "./editor": {
+      "types": "./src/editor.ts"
+    },
     "./timers": {
       "types": "./src/timers.d.ts"
     },
     "./api-availability.json": "./api-availability.json",
     "./api-signatures.json": "./api-signatures.json",
+    "./url-parameters.json": "./url-parameters.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -48,6 +55,7 @@
     "api-migrations.json",
     "api-availability.json",
     "api-signatures.json",
+    "url-parameters.json",
     "index.d.ts",
     "!src/**/*.test.ts",
     "!scripts/**/*.test.ts",

package/scripts/import-defold-release.ts

@@ -4,6 +4,7 @@ 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) => ({

package/scripts/materialize-version.ts

@@ -1,34 +1,61 @@
 import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import {
   type ApiTarget,
   generateModuleDeclaration,
   generateVersionIndex,
   KIND_MODULE_MANIFEST,
-  LUA_STDLIB_REFERENCES,
+  type KindManifestEntry,
+  kindStdlibReferences,
+  loadTargetEditorModules,
   type ResolveTargetOptions,
   resolveTargetModules,
 } from "./regen";
 
-export { KIND_MODULE_MANIFEST } from "./regen";
+export { RUNTIME_KIND_MANIFEST, targetKindManifest } from "./regen";
 
 export interface RenderMaterializedKindIndexOptions {
   readonly kind: string;
   readonly universalModules: readonly string[];
   readonly restrictedModule: string | null;
+  // Set for a kind built from the target's own editor documents. It replaces
+  // the universal set outright — an editor kind is disjoint from the runtime
+  // surface, not a narrowing of it.
+  readonly editorModules?: readonly string[];
+}
+
+// The installed subpath a materialized kind re-exports its factory from: the
+// surface has no relative `src/<module>` to reach, but the package publishes
+// each factory module under its own name.
+function installedFactoryModule(entry: KindManifestEntry): string {
+  const module = (entry.factoryFrom ?? "../../src/lifecycle").split("/").pop();
+  return `@defold-typescript/types/${module}`;
 }
 
 // Render one per-kind subpath for the materialized surface, mirroring
 // `generateKindIndex` but re-exporting the factory from the installed
-// `@defold-typescript/types/lifecycle` subpath (the materialized surface has no
-// relative `src/lifecycle` to reach). Pure: returns a string, no FS.
+// `@defold-typescript/types/<module>` subpath. Pure: returns a string, no FS.
 export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOptions): string {
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === opts.kind);
   if (!entry) throw new Error(`unknown script kind: ${opts.kind}`);
-  const universal = [...new Set(["engine-globals", ...opts.universalModules])].sort();
-  const lines = universal.map((mod) => `import "../${mod}";`);
-  if (opts.restrictedModule) lines.push(`import "../${opts.restrictedModule}";`);
-  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`;
+  const modules =
+    entry.only === undefined
+      ? [...new Set(["engine-globals", ...opts.universalModules])].sort()
+      : [...(opts.editorModules ?? [])];
+  const lines = modules.map((mod) => `import "../${mod}";`);
+  if (entry.only === undefined && opts.restrictedModule) {
+    lines.push(`import "../${opts.restrictedModule}";`);
+  }
+  const from = installedFactoryModule(entry);
+  const values = [entry.factory, ...(entry.extraExports ?? [])].join(", ");
+  const typeExports = entry.extraTypeExports?.length
+    ? `\nexport type { ${entry.extraTypeExports.join(", ")} } from "${from}";`
+    : "";
+  const properties =
+    entry.propertyTypes === false
+      ? ""
+      : `\nexport type { ScriptProperties, ScriptProperty } from "${from}";`;
+  return `${kindStdlibReferences(entry)}${lines.join("\n")}\n\nexport { ${values} } from "${from}";${typeExports}${properties}\n`;
 }
 
 export interface BuildVersionedSurfaceOptions {
@@ -60,15 +87,25 @@ export async function buildVersionedSurfaceFiles(
   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$/, "")),
+  const kept = (outFile: string): boolean => !exclude.has(outFile.replace(/\.d\.ts$/, ""));
+  const modules = (await resolveTargetModules(target, opts.resolveOpts ?? {})).filter((entry) =>
+    kept(entry.outFile),
   );
+  // The editor documents a target declares are always committed fixtures — the
+  // ref-doc zip carries no editor surface — so they resolve from disk whatever
+  // the target's `source` says.
+  const editorModules = loadTargetEditorModules(
+    target,
+    opts.resolveOpts?.packageRoot ?? undefined,
+  ).filter((entry) => kept(entry.outFile));
 
-  const files: VersionedSurfaceFile[] = modules.map((entry) => ({
+  const files: VersionedSurfaceFile[] = [...modules, ...editorModules].map((entry) => ({
     path: entry.outFile,
     contents: generateModuleDeclaration(entry).contents,
   }));
 
+  // The aggregate entrypoint stays the runtime surface: importing the editor VM
+  // there would drag it into every program that pins this version.
   const versioned = modules.map((entry) => ({ ...entry, versionId: target.id }));
   files.push({ path: "index.d.ts", contents: generateVersionIndex(target.id, versioned) });
 
@@ -94,6 +131,10 @@ export async function materializeVersionedSurface(
   const files = await buildVersionedSurfaceFiles(target, opts);
   mkdirSync(opts.destDir, { recursive: true });
   for (const file of files) {
-    writeFileSync(resolve(opts.destDir, file.path), file.contents);
+    const out = resolve(opts.destDir, file.path);
+    // An editor VM module lands in its own subdirectory, so the sink cannot
+    // assume every file is a direct child of the surface root.
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, file.contents);
   }
 }