@defold-typescript/types 0.5.4 → 0.6.0

package/generated/webview.d.ts

@@ -1,5 +1,8 @@
 /** @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.

package/generated/window.d.ts

@@ -2,6 +2,10 @@
 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.
@@ -114,24 +118,26 @@ declare global {
      * - number `width`: The width of a resize event. nil otherwise.
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
-     * ```lua
-     * function window_callback(self, event, data)
-     *     if event == window.WINDOW_EVENT_FOCUS_LOST then
-     *         print("window.WINDOW_EVENT_FOCUS_LOST")
-     *     elseif event == window.WINDOW_EVENT_FOCUS_GAINED then
-     *         print("window.WINDOW_EVENT_FOCUS_GAINED")
-     *     elseif event == window.WINDOW_EVENT_ICONFIED then
-     *         print("window.WINDOW_EVENT_ICONFIED")
-     *     elseif event == window.WINDOW_EVENT_DEICONIFIED then
-     *         print("window.WINDOW_EVENT_DEICONIFIED")
-     *     elseif event == window.WINDOW_EVENT_RESIZED then
-     *         print("Window resized: ", data.width, data.height)
-     *     end
-     * end
+     * ```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);
+     *   }
+     * }
      *
-     * function init(self)
-     *     window.set_listener(window_callback)
-     * end
+     * export default defineScript({
+     *   init() {
+     *     window.set_listener(window_callback);
+     *   },
+     * });
      * ```
      */
     function set_listener(callback?: (self: unknown, event: unknown, data: unknown) => void): void;

package/generated/zlib.d.ts

@@ -1,5 +1,8 @@
 /** @noSelfInFile */
 declare global {
+  /**
+   * Functions for compression and decompression of string buffers.
+   */
   namespace zlib {
     /**
      * A lua error is raised is on error
@@ -7,14 +10,14 @@ declare global {
      * @param buf - buffer to deflate
      * @returns deflated buffer
      * @example
-     * ```lua
-     * local data = "This is a string with uncompressed data."
-     * local compressed_data = zlib.deflate(data)
-     * local s = ""
-     * for c in string.gmatch(compressed_data, ".") do
-     *     s = s .. '\\' .. string.byte(c)
-     * end
-     * print(s) --> \120\94\11\201\200\44\86\0\162\68\133\226\146\162 ...
+     * ```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;
@@ -24,10 +27,10 @@ declare global {
      * @param buf - buffer to inflate
      * @returns inflated buffer
      * @example
-     * ```lua
-     * local 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"
-     * local uncompressed_data = zlib.inflate(data)
-     * print(uncompressed_data) --> This is a string with uncompressed data.
+     * ```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;

package/index.d.ts

@@ -2,7 +2,6 @@ import "./generated/builtin-messages";
 import "./src/msg-overloads";
 import "./src/message-guard";
 import "./src/message-dispatch";
-import "./src/go-overloads";
 import "./src/engine-globals";
 import "./generated/b2d";
 import "./generated/buffer";
@@ -12,6 +11,7 @@ import "./generated/collectionproxy";
 import "./generated/crash";
 import "./generated/factory";
 import "./generated/go";
+import "./src/go-overloads";
 import "./generated/graphics";
 import "./generated/gui";
 import "./generated/http";
@@ -64,5 +64,7 @@ export {
   SCRIPT_HOOK_NAMES,
   type ScriptHookName,
   type ScriptHooks,
+  type ScriptProperties,
+  type ScriptProperty,
 } from "./src/lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./src/publish-dts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,9 @@
     "./render-script": {
       "types": "./generated/kinds/render-script.d.ts"
     },
+    "./core-types": {
+      "types": "./src/core-types.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -39,7 +42,8 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "regen": "bun scripts/regen.ts",
-    "sync-api-docs": "bun scripts/sync-api-docs.ts"
+    "sync-api-docs": "bun scripts/sync-api-docs.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"
   },
   "devDependencies": {
     "@typescript-to-lua/language-extensions": "1.19.0"

package/scripts/example-store-io.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { TranslationStore } from "../src/example-store";
+
+// Build-time only: lives under `scripts/` (never reachable from the shipped
+// `src/index.ts` graph) so its `node:fs` import cannot leak into a consumer's
+// typecheck. `src/example-store.ts` stays pure for exactly that reason.
+const TRANSLATIONS_PATH = resolve(import.meta.dir, "..", "examples", "translations.json");
+
+export function loadTranslations(path: string = TRANSLATIONS_PATH): TranslationStore {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return {};
+  }
+  return JSON.parse(raw) as TranslationStore;
+}

package/scripts/fidelity-audit.ts

@@ -5,8 +5,11 @@ import {
   buildTableDocResolver,
   HOMOGENEOUS_ARRAY_SLOTS,
   MAPPING_TABLE_SLOTS,
+  type NestedMapping,
   parseTableFields,
   recoverCallbackSignature,
+  TABLE_SLOT_CURATIONS,
+  type TableSlotCuration,
   TS_IDENTIFIER,
 } from "../src/emit-dts";
 import { parseMessagesDoc } from "../src/emit-messages";
@@ -113,6 +116,7 @@ function auditEntry(
     arbitraryTable = false,
     mappingSlot?: { key: string; value: string },
     homogeneousElement?: string | readonly string[],
+    tableSlotCuration?: TableSlotCuration,
   ) => {
     for (const token of types) {
       // A `table` slot whose doc carries a parseable `<dl>` field list is
@@ -127,6 +131,29 @@ function auditEntry(
         // the curated key/value tokens — not a `Record`, so don't count it.
         // Feed the curated tokens back through considerTypes so an unmapped one
         // still surfaces under unknownTokens (none today: hash/node/vector3 map).
+        if (tableSlotCuration?.kind === "mapping") {
+          // A single-token value feeds straight back; an object-valued mapping
+          // (`LuaMap<K, { … }>`) feeds the key plus each curated field type, the
+          // same way the object branch does; a nested-mapping value
+          // (`LuaMap<K, LuaMap<K, V>>`) feeds the outer key plus the inner
+          // key/value tokens — so an unmapped token in any arm still surfaces.
+          if (typeof tableSlotCuration.value === "string") {
+            considerTypes([tableSlotCuration.key, tableSlotCuration.value]);
+          } else if (Array.isArray(tableSlotCuration.value)) {
+            considerTypes([tableSlotCuration.key]);
+            for (const field of tableSlotCuration.value) {
+              if (field.fields !== undefined) {
+                for (const nested of field.fields) considerTypes(nested.types);
+              } else if (field.numberList !== true) {
+                considerTypes(field.types);
+              }
+            }
+          } else {
+            const nested = tableSlotCuration.value as NestedMapping;
+            considerTypes([tableSlotCuration.key, nested.key, nested.value]);
+          }
+          continue;
+        }
         if (mappingSlot !== undefined) {
           considerTypes([mappingSlot.key, mappingSlot.value]);
           continue;
@@ -136,6 +163,24 @@ function auditEntry(
         // `Record`, so don't count it. Feed the curated token(s) back through
         // considerTypes so an unmapped one still surfaces under unknownTokens
         // (none today: number/hash/string/url map).
+        if (tableSlotCuration?.kind === "array") {
+          considerTypes(
+            typeof tableSlotCuration.element === "string"
+              ? [tableSlotCuration.element]
+              : tableSlotCuration.element,
+          );
+          continue;
+        }
+        if (tableSlotCuration?.kind === "object" || tableSlotCuration?.kind === "array-object") {
+          for (const field of tableSlotCuration.fields) {
+            if (field.fields !== undefined) {
+              for (const nested of field.fields) considerTypes(nested.types);
+            } else if (field.numberList !== true) {
+              considerTypes(field.types);
+            }
+          }
+          continue;
+        }
         if (homogeneousElement !== undefined) {
           considerTypes(
             typeof homogeneousElement === "string" ? [homogeneousElement] : homogeneousElement,
@@ -236,26 +281,37 @@ function auditEntry(
     const homogeneousElement =
       typeof element.name === "string" ? HOMOGENEOUS_ARRAY_SLOTS.get(element.name) : undefined;
     params.forEach((param, index) => {
+      const tableSlotCuration =
+        typeof element.name === "string" && typeof param.name === "string"
+          ? TABLE_SLOT_CURATIONS.get(tableSlotKey(element.name, "param", param.name))
+          : undefined;
       considerTypes(
         stringArray(param.types),
         docString(param.doc),
         arbitraryTable,
         mappingSlot,
         homogeneousElement,
+        tableSlotCuration,
       );
       // Residual: a doc-optional param the emitter cannot mark `?` because a
       // required param follows it. The trailing-run cutoff must match
       // emit-dts so the gate and the emitted surface agree.
       if (isDocOptional(param) && index < cutoff) optionalAsRequired += 1;
     });
-    for (const ret of returns)
+    for (const ret of returns) {
+      const tableSlotCuration =
+        typeof element.name === "string" && typeof ret.name === "string"
+          ? TABLE_SLOT_CURATIONS.get(tableSlotKey(element.name, "return", ret.name))
+          : undefined;
       considerTypes(
         stringArray(ret.types),
         docString(ret.doc),
         arbitraryTable,
         mappingSlot,
         homogeneousElement,
+        tableSlotCuration,
       );
+    }
   }
 
   return {
@@ -274,6 +330,10 @@ function stripNamespace(name: string): string {
   return index === -1 ? name : name.slice(index + 1);
 }
 
+function tableSlotKey(elementName: string, slotKind: "param" | "return", slotName: string): string {
+  return `${elementName}:${slotKind}:${slotName}`;
+}
+
 export function buildFidelityReport(
   manifest: readonly ModuleManifestEntry[] = MODULE_MANIFEST,
 ): Record<string, FidelityEntry> {

package/scripts/fidelity-baseline.json

@@ -26,7 +26,7 @@
   "collectionfactory": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 1,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -60,7 +60,7 @@
     "unknownTokens": [],
     "recordTables": 2,
     "multiReturn": 0,
-    "droppedMembers": 2,
+    "droppedMembers": 3,
     "optionalAsRequired": 0
   },
   "graphics": {
@@ -90,7 +90,7 @@
   "iac": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -98,7 +98,7 @@
   "iap": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 3,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -130,7 +130,7 @@
   "liveupdate": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -138,7 +138,7 @@
   "model": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -162,7 +162,7 @@
   "physics": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 5,
+    "recordTables": 3,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -178,7 +178,7 @@
   "push": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 4,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -202,7 +202,7 @@
   "socket": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 8,
+    "recordTables": 4,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -234,7 +234,7 @@
   "tilemap": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0

package/scripts/ref-doc-delta.ts

@@ -0,0 +1,143 @@
+import { parseDefoldApiDoc } from "../src/api-doc";
+import {
+  type ApiTarget,
+  loadApiTargets,
+  type ResolveTargetOptions,
+  resolveTargetModules,
+} from "./regen";
+
+export interface RefDocDeltaArgs {
+  target: string;
+  namespace: string;
+  present: string[];
+  absent: string[];
+  json: boolean;
+}
+
+export interface RefDocDeltaReport {
+  ok: boolean;
+  targetId: string;
+  version: string;
+  namespace: string;
+  provenance: string | null;
+  missingPresent: string[];
+  unexpectedPresent: string[];
+}
+
+export interface VerifyRefDocDeltaInput {
+  target: ApiTarget;
+  namespace: string;
+  present: readonly string[];
+  absent: readonly string[];
+  resolveOpts?: ResolveTargetOptions;
+}
+
+export function collectElementNames(doc: unknown): Set<string> {
+  const module = parseDefoldApiDoc(doc);
+  const names = new Set<string>([module.namespace]);
+  for (const collection of [
+    module.functions,
+    module.constants,
+    module.variables,
+    module.properties,
+  ]) {
+    for (const item of collection) {
+      if (item.name.length > 0) names.add(item.name);
+    }
+  }
+  return names;
+}
+
+export function parseRefDocDeltaArgs(argv: readonly string[]): RefDocDeltaArgs {
+  const args: RefDocDeltaArgs = { target: "", namespace: "", present: [], absent: [], json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      args.json = true;
+      continue;
+    }
+    if (arg === "--target" || arg === "--namespace" || arg === "--present" || arg === "--absent") {
+      const value = argv[++i];
+      if (!value) throw new Error(`${arg} requires a value`);
+      if (arg === "--target") args.target = value;
+      else if (arg === "--namespace") args.namespace = value;
+      else if (arg === "--present") args.present.push(value);
+      else args.absent.push(value);
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!args.target) throw new Error("--target is required");
+  if (!args.namespace) throw new Error("--namespace is required");
+  if (args.present.length === 0 && args.absent.length === 0) {
+    throw new Error("at least one --present or --absent assertion is required");
+  }
+  return args;
+}
+
+export function selectRefDocDeltaTarget(
+  targets: readonly ApiTarget[],
+  targetId: string,
+): ApiTarget {
+  const target = targets.find((item) => item.id === targetId);
+  if (!target) throw new Error(`target "${targetId}" not found`);
+  if ((target.source ?? null)?.kind !== "ref-doc") {
+    throw new Error(`target "${targetId}" is not ref-doc sourced`);
+  }
+  return target;
+}
+
+export async function verifyRefDocDelta(input: VerifyRefDocDeltaInput): Promise<RefDocDeltaReport> {
+  const source = input.target.source ?? null;
+  if (source?.kind !== "ref-doc") {
+    throw new Error(`target "${input.target.id}" is not ref-doc sourced`);
+  }
+  const modules = await resolveTargetModules(input.target, input.resolveOpts);
+  const module = modules.find((entry) => entry.namespace === input.namespace);
+  if (!module) {
+    throw new Error(`target "${input.target.id}" has no namespace "${input.namespace}"`);
+  }
+  const names = collectElementNames(module.doc);
+  const missingPresent = input.present.filter((name) => !names.has(name));
+  const unexpectedPresent = input.absent.filter((name) => names.has(name));
+  return {
+    ok: missingPresent.length === 0 && unexpectedPresent.length === 0,
+    targetId: input.target.id,
+    version: source.version,
+    namespace: input.namespace,
+    provenance: module.sourceProvenance ?? null,
+    missingPresent,
+    unexpectedPresent,
+  };
+}
+
+function renderPlainReport(report: RefDocDeltaReport): string {
+  const lines = [
+    `${report.ok ? "ok" : "drift"}: ${report.targetId}/${report.namespace} (${report.version}, ${report.provenance ?? "unknown"})`,
+  ];
+  if (report.missingPresent.length > 0) {
+    lines.push(`missing expected present: ${report.missingPresent.join(", ")}`);
+  }
+  if (report.unexpectedPresent.length > 0) {
+    lines.push(`unexpected expected absent: ${report.unexpectedPresent.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseRefDocDeltaArgs(process.argv.slice(2));
+    const target = selectRefDocDeltaTarget(loadApiTargets(), args.target);
+    const report = await verifyRefDocDelta({
+      target,
+      namespace: args.namespace,
+      present: args.present,
+      absent: args.absent,
+    });
+    console.log(args.json ? JSON.stringify(report, null, 2) : renderPlainReport(report));
+    if (!report.ok) process.exitCode = 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/scripts/regen.ts

@@ -4,8 +4,15 @@ 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 { TranslationStore } from "../src/example-store";
 import { wrapAsAmbientGlobal } from "../src/publish-dts";
-import { type DownloadRefDoc, refDocCacheDir, resolveRefDoc } from "./doc-source";
+import {
+  type DocSourceProvenance,
+  type DownloadRefDoc,
+  refDocCacheDir,
+  resolveRefDoc,
+} from "./doc-source";
+import { loadTranslations } from "./example-store-io";
 import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
 
 export interface ApiTargetModule {
@@ -73,6 +80,7 @@ export interface ModuleManifestEntry {
   readonly outFile: string;
   readonly skipFunctions?: readonly string[];
   readonly importsFrom?: string;
+  readonly sourceProvenance?: DocSourceProvenance;
 }
 
 export interface ResolveTargetOptions {
@@ -95,7 +103,7 @@ export async function resolveTargetModules(
   if (source == null) {
     return loadTargetModules(target, opts.packageRoot);
   }
-  const { zip } = await resolveRefDoc({
+  const { zip, provenance } = await resolveRefDoc({
     version: source.version,
     cacheDir: opts.cacheDir ?? refDocCacheDir(),
     ...(opts.download ? { download: opts.download } : {}),
@@ -114,6 +122,7 @@ export async function resolveTargetModules(
       doc: JSON.parse(zip.read(sync.zipEntry)),
       outFile: module.outFile,
       importsFrom: target.coreTypesImport,
+      sourceProvenance: provenance,
     };
     return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
   });
@@ -159,6 +168,7 @@ export function collectConstantFqns(
 
 export interface GenerateOptions {
   knownConstantFqns?: ReadonlySet<string>;
+  translations?: TranslationStore;
 }
 
 export function generateModuleDeclaration(
@@ -178,7 +188,8 @@ export function generateModuleDeclaration(
     return true;
   });
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
-  const emitted = emitDeclarations(module, { knownConstantFqns });
+  const translations = options?.translations ?? loadTranslations();
+  const emitted = emitDeclarations(module, { knownConstantFqns, translations });
   const contents = wrapAsAmbientGlobal({
     namespace: module.namespace,
     emitted,
@@ -208,6 +219,7 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../builtin-messages",
+  "../../src/engine-globals",
   "../../src/msg-overloads",
   "../../src/message-guard",
   "../../src/go-overloads",
@@ -216,12 +228,13 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
 export interface KindManifestEntry {
   readonly kind: string;
   readonly restricted?: string;
+  readonly factory: string;
 }
 
 export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
-  { kind: "script" },
-  { kind: "gui-script", restricted: "gui" },
-  { kind: "render-script", restricted: "render" },
+  { kind: "script", factory: "defineScript" },
+  { kind: "gui-script", restricted: "gui", factory: "defineGuiScript" },
+  { kind: "render-script", restricted: "render", factory: "defineRenderScript" },
 ];
 
 export function generateKindIndex(kind: string): string {
@@ -230,11 +243,11 @@ export function generateKindIndex(kind: string): string {
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
   ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
-  const lines = [...UNIVERSAL_EXTRA_IMPORTS, ...universalNamespaces]
-    .sort()
-    .map((path) => `import "${path}";`);
+  const lines = [
+    ...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()]),
+  ].map((path) => `import "${path}";`);
   if (entry.restricted) lines.push(`import "../${entry.restricted}";`);
-  return `${lines.join("\n")}\n\nexport {};\n`;
+  return `${lines.join("\n")}\n\nexport { ${entry.factory} } from "../../src/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "../../src/lifecycle";\n`;
 }
 
 export function generateVersionIndex(

package/src/core-types.ts

@@ -78,6 +78,20 @@ export interface Hash {
 }
 
 declare const OpaqueBrand: unique symbol;
+/**
+ * A nominal handle to an engine value you may hold and pass back to the API but
+ * must never inspect or construct — a Defold `node`, `texture`, `render_target`,
+ * `userdata`, etc. The `Name` parameter mints a distinct, mutually-incompatible
+ * brand per kind, so TypeScript's structural typing can't silently swap a
+ * `render_target` for a `constant`, and a plain object can't stand in for either.
+ *
+ * @remarks
+ * The brand is a phantom `unique symbol` property: it exists only in the type
+ * system (erased at transpile, never present at runtime). Because the symbol is
+ * not exported, consumer code cannot fabricate an `Opaque` — the engine API is
+ * the only source. Contrast with a `LuaTable` alias, which says the opposite:
+ * "inspect freely, the shape just isn't modeled."
+ */
 export interface Opaque<Name extends string> {
   readonly [OpaqueBrand]: Name;
 }

package/src/doc-comment.ts

@@ -73,6 +73,7 @@ export interface DocCommentParts {
   params?: { name: string; doc: string }[];
   returns?: string;
   example?: string;
+  exampleLang?: "lua" | "ts";
 }
 
 /**
@@ -115,7 +116,7 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   }
   if (example !== "") {
     lines.push(" * @example");
-    lines.push(" * ```lua");
+    lines.push(` * \`\`\`${parts.exampleLang ?? "lua"}`);
     for (const line of example.split("\n")) {
       lines.push(line === "" ? " *" : ` * ${line}`);
     }