@defold-typescript/transpiler 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
+export { getProgramDiagnostics } from "./program-diagnostics";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
 export type { TranspileDiagnostic, TranspileProjectInput, TranspileProjectResult, TranspileResult, } from "./transpile";

package/dist/index.js

@@ -1,9 +1,5 @@
-// src/session.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { createRequire as createRequire2 } from "node:module";
-import * as path2 from "node:path";
-import * as ts5 from "typescript";
-import * as tstl2 from "typescript-to-lua";
+// src/main-entry-factory-imports.ts
+import * as ts3 from "typescript";
 
 // src/lifecycle-erasure.ts
 import * as ts2 from "typescript";
@@ -234,9 +230,12 @@ function initBuilderBody(fn, context) {
   return [createReturnStatement([context.transformExpression(fn.body)])];
 }
 function emitInitMerge(fn, context, property) {
-  const builder = createFunctionExpression2(createBlock2(initBuilderBody(fn, context)), [], undefined, NodeFlags2.Declaration, fn);
+  const authorParam = fn.parameters.find((param) => !isThisParameter2(param) && ts2.isIdentifier(param.name));
+  const builderParams = authorParam === undefined ? [] : [context.transformExpression(authorParam.name)];
+  const builder = createFunctionExpression2(createBlock2(initBuilderBody(fn, context)), builderParams, undefined, NodeFlags2.Declaration, fn);
   const builderDecl = createVariableDeclarationStatement2(createIdentifier2("____init"), builder);
-  const stateDecl = createVariableDeclarationStatement2(createIdentifier2("____s"), createCallExpression2(createIdentifier2("____init"), []));
+  const builderArgs = authorParam === undefined ? [] : [createIdentifier2("self")];
+  const stateDecl = createVariableDeclarationStatement2(createIdentifier2("____s"), createCallExpression2(createIdentifier2("____init"), builderArgs));
   const mergeAssignment = createAssignmentStatement(createTableIndexExpression(createIdentifier2("self"), createIdentifier2("____k")), createIdentifier2("____v"));
   const forIn = createForInStatement(createBlock2([mergeAssignment]), [createIdentifier2("____k"), createIdentifier2("____v")], [createCallExpression2(createIdentifier2("pairs"), [createIdentifier2("____s")])]);
   const guard = createIfStatement2(createBinaryExpression2(createIdentifier2("____s"), createNilLiteral(), SyntaxKind4.InequalityOperator), createBlock2([forIn]));
@@ -330,8 +329,37 @@ var lifecycleErasurePlugin = {
   }
 };
 
+// src/main-entry-factory-imports.ts
+function findMainEntryFactoryImports(fileName, source) {
+  const sourceFile = ts3.createSourceFile(fileName, source, ts3.ScriptTarget.Latest, true);
+  const factories = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts3.isImportDeclaration(statement)) {
+      continue;
+    }
+    const specifier = statement.moduleSpecifier;
+    if (!ts3.isStringLiteral(specifier) || specifier.text !== FACTORY_MODULE) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings === undefined || !ts3.isNamedImports(bindings)) {
+      continue;
+    }
+    for (const element of bindings.elements) {
+      const imported = (element.propertyName ?? element.name).text;
+      if (FACTORY_NAMES.has(imported)) {
+        factories.push(imported);
+      }
+    }
+  }
+  return factories;
+}
+// src/program-diagnostics.ts
+import * as ts6 from "typescript";
+import * as tstl from "typescript-to-lua";
+
 // src/message-guard-lowering.ts
-import * as ts3 from "typescript";
+import * as ts4 from "typescript";
 import {
   createBinaryExpression as createBinaryExpression3,
   createCallExpression as createCallExpression3,
@@ -345,7 +373,7 @@ function resolvesToGuardExport(callee, checker) {
   if (symbol === undefined) {
     return false;
   }
-  if (symbol.flags & ts3.SymbolFlags.Alias) {
+  if (symbol.flags & ts4.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
   if (symbol.getName() !== GUARD_NAME) {
@@ -359,7 +387,7 @@ function resolvesToGuardExport(callee, checker) {
 }
 var messageGuardLoweringPlugin = {
   visitors: {
-    [ts3.SyntaxKind.CallExpression]: (node, context) => {
+    [ts4.SyntaxKind.CallExpression]: (node, context) => {
       const [messageIdArg, , expectedArg] = node.arguments;
       if (node.arguments.length === 3 && messageIdArg !== undefined && expectedArg !== undefined && resolvesToGuardExport(node.expression, context.checker)) {
         const messageId = context.transformExpression(messageIdArg);
@@ -371,24 +399,117 @@ var messageGuardLoweringPlugin = {
   }
 };
 
+// src/timers-lowering.ts
+import * as ts5 from "typescript";
+
+// src/timers-runtime.ts
+var TIMERS_MODULE_SPECIFIER = "@defold-typescript/types/timers";
+var TIMERS_REQUIRE_NAME = "defold_typescript_timers";
+var TIMERS_RUNTIME = `local ____lualib = require("lualib_bundle")
+local __TS__Promise = ____lualib.__TS__Promise
+local __TS__New = ____lualib.__TS__New
+
+local function setTimeout(callback, delayMs)
+    return timer.delay(delayMs / 1000, false, function()
+        callback()
+    end)
+end
+
+local function setInterval(callback, delayMs)
+    return timer.delay(delayMs / 1000, true, function()
+        callback()
+    end)
+end
+
+local function clearTimeout(handle)
+    timer.cancel(handle)
+end
+
+local function clearInterval(handle)
+    timer.cancel(handle)
+end
+
+local function wait(seconds)
+    return __TS__New(__TS__Promise, function(_, resolve)
+        timer.delay(seconds, false, function()
+            resolve()
+        end)
+    end)
+end
+
+return {
+    setTimeout = setTimeout,
+    setInterval = setInterval,
+    clearTimeout = clearTimeout,
+    clearInterval = clearInterval,
+    wait = wait,
+}
+`;
+
+// src/timers-lowering.ts
+function isTimersSpecifier(node) {
+  return ts5.isStringLiteral(node) && node.text === TIMERS_MODULE_SPECIFIER;
+}
+function importsTimersModule(sourceFile) {
+  return sourceFile.statements.some((statement) => ts5.isImportDeclaration(statement) && isTimersSpecifier(statement.moduleSpecifier));
+}
+var TIMERS_REQUIRE_PATH = `@NoResolution:${TIMERS_REQUIRE_NAME}`;
+var timersLoweringPlugin = {
+  visitors: {
+    [ts5.SyntaxKind.ImportDeclaration]: (node, context) => {
+      if (!isTimersSpecifier(node.moduleSpecifier)) {
+        return context.superTransformStatements(node);
+      }
+      const rewritten = ts5.factory.updateImportDeclaration(node, node.modifiers, node.importClause, ts5.factory.createStringLiteral(TIMERS_REQUIRE_PATH), node.attributes);
+      return context.superTransformStatements(rewritten);
+    }
+  }
+};
+
+// src/program-diagnostics.ts
+var LUA_PLUGINS = [
+  lifecycleErasurePlugin,
+  messageGuardLoweringPlugin,
+  messageDispatchLoweringPlugin,
+  timersLoweringPlugin
+];
+var noopWriteFile = () => {};
+function isAmbient(fileName) {
+  return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
+}
+function getProgramDiagnostics(program, sourceFile) {
+  const { diagnostics } = tstl.getProgramTranspileResult(ts6.sys, noopWriteFile, {
+    program,
+    plugins: LUA_PLUGINS,
+    ...sourceFile ? { sourceFiles: [sourceFile] } : {}
+  });
+  return diagnostics.filter((d) => d.file !== undefined && !isAmbient(d.file.fileName));
+}
+// src/session.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import * as path2 from "node:path";
+import * as ts8 from "typescript";
+import * as tstl3 from "typescript-to-lua";
+
 // src/transpile.ts
 import { readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import * as tstl from "typescript-to-lua";
+import * as tstl2 from "typescript-to-lua";
 
 // src/go-property-direct-call.ts
-import * as ts4 from "typescript";
+import * as ts7 from "typescript";
 var GO_PROPERTY_DIRECT_CALL_MESSAGE = "`go.property` called directly is deprecated; declare the property in `defineScript({ properties })` so it types onto `self` (the transpiler emits the registration for you).";
 function findDirectGoPropertyCalls(sourceFile) {
   const calls = [];
   const visit = (node) => {
-    if (ts4.isCallExpression(node) && ts4.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts4.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
+    if (ts7.isCallExpression(node) && ts7.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts7.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
       calls.push(node);
     }
-    ts4.forEachChild(node, visit);
+    ts7.forEachChild(node, visit);
   };
-  ts4.forEachChild(sourceFile, visit);
+  ts7.forEachChild(sourceFile, visit);
   return calls;
 }
 
@@ -405,6 +526,29 @@ var TSTL_LANG_EXT_ROOT = path.dirname(requireFromHere.resolve("@typescript-to-lu
 function readAmbient(rel) {
   return readFileSync(path.join(TYPES_PKG_ROOT, rel), "utf8");
 }
+var LUA_TYPES_ROOT = path.dirname(createRequire(path.join(TYPES_PKG_ROOT, "package.json")).resolve("lua-types/package.json"));
+var LUA_TYPES_ENTRY_FILES = ["5.1.d.ts", "special/jit-only.d.ts"];
+var REFERENCE_PATH_RE = /\/\/\/\s*<reference\s+path="([^"]+)"\s*\/>/g;
+function collectLuaTypesClosure() {
+  const files = {};
+  const visit = (rel) => {
+    const key = `node_modules/lua-types/${rel}`;
+    if (key in files)
+      return;
+    const source = readFileSync(path.join(LUA_TYPES_ROOT, rel), "utf8");
+    files[key] = source;
+    const dir = path.posix.dirname(rel);
+    for (const match of source.matchAll(REFERENCE_PATH_RE)) {
+      const ref = match[1];
+      if (!ref)
+        continue;
+      visit(path.posix.normalize(path.posix.join(dir, ref)));
+    }
+  };
+  for (const entry of LUA_TYPES_ENTRY_FILES)
+    visit(entry);
+  return files;
+}
 function buildAmbientFiles() {
   const files = {
     "node_modules/@typescript-to-lua/language-extensions/index.d.ts": readFileSync(path.join(TSTL_LANG_EXT_ROOT, "index.d.ts"), "utf8"),
@@ -415,6 +559,7 @@ function buildAmbientFiles() {
     "node_modules/@defold-typescript/types/src/message-guard.d.ts": readAmbient("src/message-guard.d.ts"),
     "node_modules/@defold-typescript/types/src/message-dispatch.d.ts": readAmbient("src/message-dispatch.d.ts"),
     "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
+    "node_modules/@defold-typescript/types/src/timers.d.ts": readAmbient("src/timers.d.ts"),
     "node_modules/@defold-typescript/types/index.ts": [
       'export { defineGuiScript, defineRenderScript, defineScript } from "./src/lifecycle";',
       'export type { GuiScriptHooks, InputAction, InputTouch, RenderScriptHooks, ScriptHooks, ScriptProperties, ScriptProperty } from "./src/lifecycle";',
@@ -432,6 +577,7 @@ export type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";
 export type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";
 `
   };
+  Object.assign(files, collectLuaTypesClosure());
   for (const entry of readdirSync(path.join(TYPES_PKG_ROOT, "generated"))) {
     if (entry.endsWith(".d.ts")) {
       files[`node_modules/@defold-typescript/types/generated/${entry}`] = readAmbient(`generated/${entry}`);
@@ -440,10 +586,19 @@ export type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";
   return files;
 }
 var AMBIENT_FILES = buildAmbientFiles();
+var LUALIB_BUNDLE_NAME = "lualib_bundle.lua";
+function isLualibBundle(file) {
+  return file.sourceFiles.length === 0 && file.outPath.endsWith(LUALIB_BUNDLE_NAME);
+}
 function collectOutputs(transpiledFiles, diagnostics, userKeys) {
   const lua = {};
   const sourceMaps = {};
+  let lualib;
   for (const file of transpiledFiles) {
+    if (isLualibBundle(file) && typeof file.lua === "string") {
+      lualib = file.lua;
+      continue;
+    }
     const userSource = file.sourceFiles.find((s) => userKeys.has(s.fileName));
     if (!userSource || typeof file.lua !== "string") {
       continue;
@@ -459,6 +614,7 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys) {
     return fileName !== undefined && userKeys.has(fileName) ? { file: fileName, message } : { message };
   });
   const scanned = new Set;
+  let timersImported = false;
   for (const file of transpiledFiles) {
     for (const sourceFile of file.sourceFiles) {
       if (!userKeys.has(sourceFile.fileName) || scanned.has(sourceFile.fileName)) {
@@ -472,22 +628,32 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys) {
           category: "warning"
         });
       }
+      if (importsTimersModule(sourceFile)) {
+        timersImported = true;
+      }
     }
   }
-  return { lua, sourceMaps, diagnostics: collectedDiagnostics };
+  return {
+    lua,
+    sourceMaps,
+    diagnostics: collectedDiagnostics,
+    ...lualib !== undefined ? { lualib } : {},
+    ...timersImported ? { timersRuntime: TIMERS_RUNTIME } : {}
+  };
 }
 function transpileProject(input) {
   const userKeys = new Set(Object.keys(input.files));
   const merged = { ...AMBIENT_FILES, ...input.files };
-  const result = tstl.transpileVirtualProject(merged, {
-    luaTarget: tstl.LuaTarget.Lua54,
+  const result = tstl2.transpileVirtualProject(merged, {
+    luaTarget: tstl2.LuaTarget.Lua51,
     sourceMap: true,
     skipLibCheck: true,
     noImplicitSelf: true,
     luaPlugins: [
       { plugin: lifecycleErasurePlugin },
       { plugin: messageGuardLoweringPlugin },
-      { plugin: messageDispatchLoweringPlugin }
+      { plugin: messageDispatchLoweringPlugin },
+      { plugin: timersLoweringPlugin }
     ]
   });
   return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);
@@ -504,14 +670,15 @@ function transpile(source) {
 // src/session.ts
 var requireFromHere2 = createRequire2(import.meta.url);
 var COMPILER_OPTIONS = {
-  luaTarget: tstl2.LuaTarget.Lua54,
+  luaTarget: tstl3.LuaTarget.Lua51,
   sourceMap: true,
   skipLibCheck: true,
   noImplicitSelf: true,
   luaPlugins: [
     { plugin: lifecycleErasurePlugin },
     { plugin: messageGuardLoweringPlugin },
-    { plugin: messageDispatchLoweringPlugin }
+    { plugin: messageDispatchLoweringPlugin },
+    { plugin: timersLoweringPlugin }
   ]
 };
 function normalizeSlashes(p) {
@@ -552,7 +719,7 @@ function createTranspileSession() {
       if (cached) {
         return cached;
       }
-      const created = ts5.createSourceFile(fileName, content, ts5.ScriptTarget.Latest, false);
+      const created = ts8.createSourceFile(fileName, content, ts8.ScriptTarget.Latest, false);
       sourceFileCache.set(normalized, created);
       return created;
     }
@@ -571,7 +738,7 @@ function createTranspileSession() {
         return cached;
       }
       const fileContent = readFileSync2(filePath, "utf8");
-      const created = ts5.createSourceFile(filePath, fileContent, ts5.ScriptTarget.Latest, false);
+      const created = ts8.createSourceFile(filePath, fileContent, ts8.ScriptTarget.Latest, false);
       libCache.set(fileName, created);
       return created;
     }
@@ -584,10 +751,10 @@ function createTranspileSession() {
     return AMBIENT_FILES[normalized];
   }
   const host = {
-    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts5.sys.fileExists(fileName),
+    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts8.sys.fileExists(fileName),
     getCanonicalFileName: (fileName) => fileName,
     getCurrentDirectory: () => "",
-    getDefaultLibFileName: ts5.getDefaultLibFileName,
+    getDefaultLibFileName: ts8.getDefaultLibFileName,
     readFile: () => "",
     getNewLine: () => `
 `,
@@ -608,15 +775,15 @@ function createTranspileSession() {
     }
     const userKeys = new Set(userFiles.keys());
     const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
-    program = ts5.createProgram(rootNames, COMPILER_OPTIONS, host, program);
-    const preEmitDiagnostics = ts5.getPreEmitDiagnostics(program);
+    program = ts8.createProgram(rootNames, COMPILER_OPTIONS, host, program);
+    const preEmitDiagnostics = ts8.getPreEmitDiagnostics(program);
     const collector = createOutputCollector();
-    const { diagnostics: transpileDiagnostics } = new tstl2.Transpiler().emit({
+    const { diagnostics: transpileDiagnostics } = new tstl3.Transpiler().emit({
       program,
       writeFile: collector.writeFile
     });
     const diagnostics = [
-      ...ts5.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
+      ...ts8.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
     ];
     return collectOutputs(collector.files, diagnostics, userKeys);
   }
@@ -628,5 +795,7 @@ function createTranspileSession() {
 export {
   transpileProject,
   transpile,
+  getProgramDiagnostics,
+  findMainEntryFactoryImports,
   createTranspileSession
 };

package/dist/lifecycle-erasure.d.ts

@@ -1,4 +1,6 @@
 import * as ts from "typescript";
 import { type Plugin } from "typescript-to-lua";
+export declare const FACTORY_MODULE = "@defold-typescript/types";
+export declare const FACTORY_NAMES: Set<string>;
 export declare function isFactoryOnlyImport(node: ts.ImportDeclaration): boolean;
 export declare const lifecycleErasurePlugin: Plugin;

package/dist/main-entry-factory-imports.d.ts

@@ -0,0 +1 @@
+export declare function findMainEntryFactoryImports(fileName: string, source: string): string[];

package/dist/program-diagnostics.d.ts

@@ -0,0 +1,2 @@
+import * as ts from "typescript";
+export declare function getProgramDiagnostics(program: ts.Program, sourceFile?: ts.SourceFile): ts.Diagnostic[];

package/dist/timers-lowering.d.ts

@@ -0,0 +1,4 @@
+import * as ts from "typescript";
+import type { Plugin } from "typescript-to-lua";
+export declare function importsTimersModule(sourceFile: ts.SourceFile): boolean;
+export declare const timersLoweringPlugin: Plugin;

package/dist/timers-runtime.d.ts

@@ -0,0 +1,3 @@
+export declare const TIMERS_MODULE_SPECIFIER = "@defold-typescript/types/timers";
+export declare const TIMERS_REQUIRE_NAME = "defold_typescript_timers";
+export declare const TIMERS_RUNTIME = "local ____lualib = require(\"lualib_bundle\")\nlocal __TS__Promise = ____lualib.__TS__Promise\nlocal __TS__New = ____lualib.__TS__New\n\nlocal function setTimeout(callback, delayMs)\n    return timer.delay(delayMs / 1000, false, function()\n        callback()\n    end)\nend\n\nlocal function setInterval(callback, delayMs)\n    return timer.delay(delayMs / 1000, true, function()\n        callback()\n    end)\nend\n\nlocal function clearTimeout(handle)\n    timer.cancel(handle)\nend\n\nlocal function clearInterval(handle)\n    timer.cancel(handle)\nend\n\nlocal function wait(seconds)\n    return __TS__New(__TS__Promise, function(_, resolve)\n        timer.delay(seconds, false, function()\n            resolve()\n        end)\n    end)\nend\n\nreturn {\n    setTimeout = setTimeout,\n    setInterval = setInterval,\n    clearTimeout = clearTimeout,\n    clearInterval = clearInterval,\n    wait = wait,\n}\n";

package/dist/transpile.d.ts

@@ -16,9 +16,12 @@ export interface TranspileProjectResult {
     readonly lua: Readonly<Record<string, string>>;
     readonly sourceMaps: Readonly<Record<string, string>>;
     readonly diagnostics: readonly TranspileDiagnostic[];
+    readonly lualib?: string;
+    readonly timersRuntime?: string;
 }
 export declare const AMBIENT_FILES: Readonly<Record<string, string>>;
 interface CollectableFile {
+    readonly outPath: string;
     readonly sourceFiles: readonly ts.SourceFile[];
     readonly lua?: string;
     readonly luaSourceMap?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.7.0",
+    "@defold-typescript/types": "0.8.1",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript-to-lua": "^1.36.0"
   }

package/src/index.ts

@@ -1,3 +1,5 @@
+export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
+export { getProgramDiagnostics } from "./program-diagnostics";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
 export type {

package/src/lifecycle-erasure.ts

@@ -23,8 +23,8 @@ import {
 } from "typescript-to-lua";
 import { resolvesToDispatchExport } from "./message-dispatch-lowering";
 
-const FACTORY_MODULE = "@defold-typescript/types";
-const FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
+export const FACTORY_MODULE = "@defold-typescript/types";
+export const FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
 // A walled source imports its factory from the matching kind subpath
 // (`@defold-typescript/types/gui-script`) to avoid pulling the cross-kind
 // `declare global` namespaces; those imports erase exactly like the bare one.
@@ -155,18 +155,31 @@ function emitInitMerge(
   context: TransformationContext,
   property: ts.ObjectLiteralElementLike,
 ): Statement[] {
+  // init-self: Defold has already populated `self` with the declared property
+  // values when `init` runs, so an `init(self)` body must resolve `self` to the
+  // engine table — not a nil global. Bind the builder's parameter to the
+  // author's first non-`this:` param (which may be named anything) and pass the
+  // engine `self` at the call. A param-less `init` keeps the zero-arg builder.
+  const authorParam = fn.parameters.find(
+    (param) => !isThisParameter(param) && ts.isIdentifier(param.name),
+  );
+  const builderParams: Identifier[] =
+    authorParam === undefined
+      ? []
+      : [context.transformExpression(authorParam.name as ts.Identifier) as Identifier];
   const builder = createFunctionExpression(
     createBlock(initBuilderBody(fn, context)),
-    [],
+    builderParams,
     undefined,
     NodeFlags.Declaration,
     fn,
   );
   const builderDecl = createVariableDeclarationStatement(createIdentifier("____init"), builder);
 
+  const builderArgs = authorParam === undefined ? [] : [createIdentifier("self")];
   const stateDecl = createVariableDeclarationStatement(
     createIdentifier("____s"),
-    createCallExpression(createIdentifier("____init"), []),
+    createCallExpression(createIdentifier("____init"), builderArgs),
   );
   const mergeAssignment = createAssignmentStatement(
     createTableIndexExpression(createIdentifier("self"), createIdentifier("____k")),

package/src/main-entry-factory-imports.ts

@@ -0,0 +1,31 @@
+import * as ts from "typescript";
+import { FACTORY_MODULE, FACTORY_NAMES } from "./lifecycle-erasure";
+
+// A walled source narrows only its ambient `types`; importing a factory from the
+// bare main entry (`@defold-typescript/types`) still pulls the cross-kind
+// `declare global` namespaces and silently re-defeats the wall. The sanctioned
+// `@defold-typescript/types/<kind>` subpath imports are never flagged.
+export function findMainEntryFactoryImports(fileName: string, source: string): string[] {
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
+  const factories: string[] = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) {
+      continue;
+    }
+    const specifier = statement.moduleSpecifier;
+    if (!ts.isStringLiteral(specifier) || specifier.text !== FACTORY_MODULE) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings === undefined || !ts.isNamedImports(bindings)) {
+      continue;
+    }
+    for (const element of bindings.elements) {
+      const imported = (element.propertyName ?? element.name).text;
+      if (FACTORY_NAMES.has(imported)) {
+        factories.push(imported);
+      }
+    }
+  }
+  return factories;
+}

package/src/program-diagnostics.ts

@@ -0,0 +1,37 @@
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import { lifecycleErasurePlugin } from "./lifecycle-erasure";
+import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
+import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { timersLoweringPlugin } from "./timers-lowering";
+
+// The same four lua plugins the build path lists (transpile.ts / session.ts),
+// so the editor and the build agree on what is unsupported.
+const LUA_PLUGINS: tstl.Plugin[] = [
+  lifecycleErasurePlugin,
+  messageGuardLoweringPlugin,
+  messageDispatchLoweringPlugin,
+  timersLoweringPlugin,
+];
+
+const noopWriteFile: ts.WriteFileCallback = () => {};
+
+function isAmbient(fileName: string): boolean {
+  return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
+}
+
+// Run the build path's TSTL diagnostic pass against an already-open `ts.Program`
+// (e.g. the editor's), returning the raw, span-bearing diagnostics so a squiggle
+// can land on the offending source. Restricts to `sourceFile` when given and
+// drops diagnostics on lib/`node_modules` ambients.
+export function getProgramDiagnostics(
+  program: ts.Program,
+  sourceFile?: ts.SourceFile,
+): ts.Diagnostic[] {
+  const { diagnostics } = tstl.getProgramTranspileResult(ts.sys, noopWriteFile, {
+    program,
+    plugins: LUA_PLUGINS,
+    ...(sourceFile ? { sourceFiles: [sourceFile] } : {}),
+  });
+  return diagnostics.filter((d) => d.file !== undefined && !isAmbient(d.file.fileName));
+}

package/src/session.ts

@@ -6,6 +6,7 @@ import * as tstl from "typescript-to-lua";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { timersLoweringPlugin } from "./timers-lowering";
 import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
 
 export interface TranspileSession {
@@ -16,7 +17,7 @@ export interface TranspileSession {
 const requireFromHere = createRequire(import.meta.url);
 
 const COMPILER_OPTIONS: tstl.CompilerOptions = {
-  luaTarget: tstl.LuaTarget.Lua54,
+  luaTarget: tstl.LuaTarget.Lua51,
   sourceMap: true,
   // Don't cross-check the seeded ambient .d.ts surface against itself; only user
   // files matter (mirrors transpileProject and the editor's skipLibCheck).
@@ -28,6 +29,7 @@ const COMPILER_OPTIONS: tstl.CompilerOptions = {
     { plugin: lifecycleErasurePlugin },
     { plugin: messageGuardLoweringPlugin },
     { plugin: messageDispatchLoweringPlugin },
+    { plugin: timersLoweringPlugin },
   ],
 };
 

package/src/timers-lowering.ts

@@ -0,0 +1,43 @@
+import * as ts from "typescript";
+import type { Plugin } from "typescript-to-lua";
+import { TIMERS_MODULE_SPECIFIER, TIMERS_REQUIRE_NAME } from "./timers-runtime";
+
+function isTimersSpecifier(node: ts.Expression): node is ts.StringLiteral {
+  return ts.isStringLiteral(node) && node.text === TIMERS_MODULE_SPECIFIER;
+}
+
+// True when a user source imports the polyfill module, so `collectOutputs` can
+// surface the runtime pay-for-use. The original specifier is read here (the
+// lowering rewrites a fresh node for emit, not the source AST).
+export function importsTimersModule(sourceFile: ts.SourceFile): boolean {
+  return sourceFile.statements.some(
+    (statement) =>
+      ts.isImportDeclaration(statement) && isTimersSpecifier(statement.moduleSpecifier),
+  );
+}
+
+// Rewrite the dotted package specifier to the flat `require` name so TSTL emits
+// `require("defold_typescript_timers")` instead of the unresolvable default.
+// The `@NoResolution:` marker tells TSTL's resolver to leave the path alone (the
+// runtime module has no source file in the program); the resolver strips the
+// marker, leaving the bare flat require. The import clause is the original node,
+// so the checker/resolver still bind the named imports.
+const TIMERS_REQUIRE_PATH = `@NoResolution:${TIMERS_REQUIRE_NAME}`;
+
+export const timersLoweringPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.ImportDeclaration]: (node, context) => {
+      if (!isTimersSpecifier(node.moduleSpecifier)) {
+        return context.superTransformStatements(node);
+      }
+      const rewritten = ts.factory.updateImportDeclaration(
+        node,
+        node.modifiers,
+        node.importClause,
+        ts.factory.createStringLiteral(TIMERS_REQUIRE_PATH),
+        node.attributes,
+      );
+      return context.superTransformStatements(rewritten);
+    },
+  },
+};

package/src/timers-runtime.ts

@@ -0,0 +1,52 @@
+// The importable polyfill specifier (matched by the type checker and the
+// lowering pass) and the flat Lua require name the import is rewritten to. The
+// CLI writes the runtime to `<require name>.lua` at the output root, mirroring
+// `lualib_bundle`, so `require("defold_typescript_timers")` resolves in Defold.
+export const TIMERS_MODULE_SPECIFIER = "@defold-typescript/types/timers";
+export const TIMERS_REQUIRE_NAME = "defold_typescript_timers";
+
+// Hand-authored runtime Lua. Unlike `defineScript` (which `lifecycle-erasure`
+// removes), these wrappers have real behavior, so the Lua must reach the Defold
+// project. `__TS__Promise`/`__TS__New` come from the lualib bundle the build
+// already writes alongside this file; `wait` resolves its promise from inside
+// the `timer.delay` callback, the only thing that advances it (no event loop).
+export const TIMERS_RUNTIME = `local ____lualib = require("lualib_bundle")
+local __TS__Promise = ____lualib.__TS__Promise
+local __TS__New = ____lualib.__TS__New
+
+local function setTimeout(callback, delayMs)
+    return timer.delay(delayMs / 1000, false, function()
+        callback()
+    end)
+end
+
+local function setInterval(callback, delayMs)
+    return timer.delay(delayMs / 1000, true, function()
+        callback()
+    end)
+end
+
+local function clearTimeout(handle)
+    timer.cancel(handle)
+end
+
+local function clearInterval(handle)
+    timer.cancel(handle)
+end
+
+local function wait(seconds)
+    return __TS__New(__TS__Promise, function(_, resolve)
+        timer.delay(seconds, false, function()
+            resolve()
+        end)
+    end)
+end
+
+return {
+    setTimeout = setTimeout,
+    setInterval = setInterval,
+    clearTimeout = clearTimeout,
+    clearInterval = clearInterval,
+    wait = wait,
+}
+`;

package/src/transpile.ts

@@ -10,6 +10,8 @@ import {
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
+import { TIMERS_RUNTIME } from "./timers-runtime";
 
 export interface TranspileResult {
   readonly lua: string;
@@ -34,6 +36,17 @@ export interface TranspileProjectResult {
   readonly lua: Readonly<Record<string, string>>;
   readonly sourceMaps: Readonly<Record<string, string>>;
   readonly diagnostics: readonly TranspileDiagnostic[];
+  // TSTL synthesizes this bundle (no user source) whenever a lualib feature
+  // (`Object.keys`, spread, `__TS__TypeOf`, ...) is used; the emitted
+  // `require("lualib_bundle")` only resolves in Defold if the CLI writes it to
+  // the output root. Absent when no feature pulls it in.
+  readonly lualib?: string;
+  // Hand-authored runtime Lua for the `@defold-typescript/types/timers`
+  // polyfills (`setTimeout`/`wait`/...). Unlike `defineScript`, the import is
+  // not erased — it lowers to `require("defold_typescript_timers")`, so the CLI
+  // must write this to the output root. Present only when a user file imports
+  // the module (pay-for-use).
+  readonly timersRuntime?: string;
 }
 
 function flattenDiagnosticMessage(
@@ -57,6 +70,36 @@ function readAmbient(rel: string): string {
   return readFileSync(path.join(TYPES_PKG_ROOT, rel), "utf8");
 }
 
+// lua-types is a dependency of @defold-typescript/types, not the transpiler, so
+// resolve it from the types package root where it is installed.
+const LUA_TYPES_ROOT = path.dirname(
+  createRequire(path.join(TYPES_PKG_ROOT, "package.json")).resolve("lua-types/package.json"),
+);
+
+// Follow the triple-slash `path` reference graph from the 5.1 + LuaJIT entry
+// files so the virtual program sees exactly the Lua 5.1 surface (single-arg
+// `randomseed`) and never the conflicting 5.2–5.5 global declarations.
+const LUA_TYPES_ENTRY_FILES = ["5.1.d.ts", "special/jit-only.d.ts"];
+const REFERENCE_PATH_RE = /\/\/\/\s*<reference\s+path="([^"]+)"\s*\/>/g;
+
+function collectLuaTypesClosure(): Record<string, string> {
+  const files: Record<string, string> = {};
+  const visit = (rel: string): void => {
+    const key = `node_modules/lua-types/${rel}`;
+    if (key in files) return;
+    const source = readFileSync(path.join(LUA_TYPES_ROOT, rel), "utf8");
+    files[key] = source;
+    const dir = path.posix.dirname(rel);
+    for (const match of source.matchAll(REFERENCE_PATH_RE)) {
+      const ref = match[1];
+      if (!ref) continue;
+      visit(path.posix.normalize(path.posix.join(dir, ref)));
+    }
+  };
+  for (const entry of LUA_TYPES_ENTRY_FILES) visit(entry);
+  return files;
+}
+
 function buildAmbientFiles(): Record<string, string> {
   const files: Record<string, string> = {
     "node_modules/@typescript-to-lua/language-extensions/index.d.ts": readFileSync(
@@ -76,6 +119,10 @@ function buildAmbientFiles(): Record<string, string> {
       "src/message-dispatch.d.ts",
     ),
     "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
+    // Ambient `declare module "@defold-typescript/types/timers"` so user code
+    // type-resolves the polyfill import in the virtual program; the lowering
+    // rewrites the specifier to a flat require at emit.
+    "node_modules/@defold-typescript/types/src/timers.d.ts": readAmbient("src/timers.d.ts"),
     // Mirror the consumer-facing re-exports of the real package index so a user
     // file can `import { defineScript }` and `import type { Hash, Vector3 }`.
     "node_modules/@defold-typescript/types/index.ts": [
@@ -97,6 +144,9 @@ function buildAmbientFiles(): Record<string, string> {
     "node_modules/@defold-typescript/types/render-script.d.ts":
       'export { defineRenderScript } from "./src/lifecycle.js";\nexport type { ScriptProperties, ScriptProperty } from "./src/lifecycle.js";\n',
   };
+  // Seed the Lua 5.1 standard library (math/os/string/table/coroutine + base
+  // globals) so user code can call e.g. `math.randomseed(os.time())`.
+  Object.assign(files, collectLuaTypesClosure());
   // Seed every generated namespace so real multi-namespace user code (sprite,
   // physics, label, ...) resolves — not just the historical vmath/msg/go subset.
   for (const entry of readdirSync(path.join(TYPES_PKG_ROOT, "generated"))) {
@@ -112,11 +162,18 @@ function buildAmbientFiles(): Record<string, string> {
 export const AMBIENT_FILES: Readonly<Record<string, string>> = buildAmbientFiles();
 
 interface CollectableFile {
+  readonly outPath: string;
   readonly sourceFiles: readonly ts.SourceFile[];
   readonly lua?: string;
   readonly luaSourceMap?: string;
 }
 
+const LUALIB_BUNDLE_NAME = "lualib_bundle.lua";
+
+function isLualibBundle(file: CollectableFile): boolean {
+  return file.sourceFiles.length === 0 && file.outPath.endsWith(LUALIB_BUNDLE_NAME);
+}
+
 export function collectOutputs(
   transpiledFiles: readonly CollectableFile[],
   diagnostics: readonly ts.Diagnostic[],
@@ -124,7 +181,12 @@ export function collectOutputs(
 ): TranspileProjectResult {
   const lua: Record<string, string> = {};
   const sourceMaps: Record<string, string> = {};
+  let lualib: string | undefined;
   for (const file of transpiledFiles) {
+    if (isLualibBundle(file) && typeof file.lua === "string") {
+      lualib = file.lua;
+      continue;
+    }
     const userSource = file.sourceFiles.find((s) => userKeys.has(s.fileName));
     if (!userSource || typeof file.lua !== "string") {
       continue;
@@ -144,9 +206,11 @@ export function collectOutputs(
   });
 
   // Advisory scan of the user TypeScript AST for the deprecated direct
-  // `go.property` call. Run here (shared by transpileProject and the watch
-  // session) so both paths report it identically.
+  // `go.property` call, plus detection of the timers polyfill import. Run here
+  // (shared by transpileProject and the watch session) so both paths report it
+  // identically.
   const scanned = new Set<string>();
+  let timersImported = false;
   for (const file of transpiledFiles) {
     for (const sourceFile of file.sourceFiles) {
       if (!userKeys.has(sourceFile.fileName) || scanned.has(sourceFile.fileName)) {
@@ -160,10 +224,19 @@ export function collectOutputs(
           category: "warning",
         });
       }
+      if (importsTimersModule(sourceFile)) {
+        timersImported = true;
+      }
     }
   }
 
-  return { lua, sourceMaps, diagnostics: collectedDiagnostics };
+  return {
+    lua,
+    sourceMaps,
+    diagnostics: collectedDiagnostics,
+    ...(lualib !== undefined ? { lualib } : {}),
+    ...(timersImported ? { timersRuntime: TIMERS_RUNTIME } : {}),
+  };
 }
 
 export function transpileProject(input: TranspileProjectInput): TranspileProjectResult {
@@ -171,7 +244,7 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
   const merged: Record<string, string> = { ...AMBIENT_FILES, ...input.files };
 
   const result = tstl.transpileVirtualProject(merged, {
-    luaTarget: tstl.LuaTarget.Lua54,
+    luaTarget: tstl.LuaTarget.Lua51,
     sourceMap: true,
     // Don't cross-check the seeded ambient .d.ts surface against itself; we only
     // care about diagnostics on user files (mirrors the editor's skipLibCheck).
@@ -183,6 +256,7 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
       { plugin: lifecycleErasurePlugin },
       { plugin: messageGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
+      { plugin: timersLoweringPlugin },
     ],
   });