@defold-typescript/transpiler 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { TranspileSession } from "./session";
+export { createTranspileSession } from "./session";
+export type { TranspileDiagnostic, TranspileProjectInput, TranspileProjectResult, TranspileResult, } from "./transpile";
+export { transpile, transpileProject } from "./transpile";

package/dist/index.js

@@ -0,0 +1,312 @@
+// 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 ts2 from "typescript";
+import * as tstl2 from "typescript-to-lua";
+
+// src/lifecycle-erasure.ts
+import * as ts from "typescript";
+import {
+  createAssignmentStatement,
+  createBlock,
+  createExpressionStatement,
+  createFunctionExpression,
+  createIdentifier,
+  NodeFlags
+} from "typescript-to-lua";
+var FACTORY_MODULE = "@defold-typescript/types";
+var FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
+function resolvesToFactoryExport(callee, checker) {
+  let symbol = checker.getSymbolAtLocation(callee);
+  if (symbol === undefined) {
+    return false;
+  }
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    symbol = checker.getAliasedSymbol(symbol);
+  }
+  if (!FACTORY_NAMES.has(symbol.getName())) {
+    return false;
+  }
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+  if (declaration === undefined) {
+    return false;
+  }
+  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
+}
+function isThisParameter(param) {
+  return ts.isIdentifier(param.name) && ts.identifierToKeywordKind(param.name) === ts.SyntaxKind.ThisKeyword;
+}
+function hookName(property) {
+  const name = property.name;
+  if (name === undefined) {
+    return;
+  }
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+    return name.text;
+  }
+  return;
+}
+function hookFunction(property) {
+  if (ts.isMethodDeclaration(property) && property.body !== undefined) {
+    return property;
+  }
+  if (ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer;
+    if (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer)) {
+      return initializer;
+    }
+  }
+  return;
+}
+function transformHookBody(fn, context) {
+  if (ts.isBlock(fn.body)) {
+    return context.transformStatements(fn.body.statements);
+  }
+  return [createExpressionStatement(context.transformExpression(fn.body))];
+}
+function eraseFactoryCall(expression, context) {
+  if (!ts.isCallExpression(expression)) {
+    return;
+  }
+  if (!resolvesToFactoryExport(expression.expression, context.checker)) {
+    return;
+  }
+  const hooks = expression.arguments[0];
+  if (hooks === undefined || !ts.isObjectLiteralExpression(hooks)) {
+    return;
+  }
+  const statements = [];
+  for (const property of hooks.properties) {
+    const name = hookName(property);
+    const fn = hookFunction(property);
+    if (name === undefined || fn === undefined) {
+      continue;
+    }
+    const params = fn.parameters.filter((param) => !isThisParameter(param) && ts.isIdentifier(param.name)).map((param) => createIdentifier(param.name.text, param));
+    const fnExpression = createFunctionExpression(createBlock(transformHookBody(fn, context)), params, undefined, NodeFlags.Declaration, fn);
+    statements.push(createAssignmentStatement(createIdentifier(name), fnExpression, property));
+  }
+  return statements;
+}
+function isFactoryOnlyImport(node) {
+  if (!ts.isStringLiteral(node.moduleSpecifier) || node.moduleSpecifier.text !== FACTORY_MODULE) {
+    return false;
+  }
+  const clause = node.importClause;
+  if (clause === undefined || clause.name !== undefined) {
+    return false;
+  }
+  const bindings = clause.namedBindings;
+  if (bindings === undefined || !ts.isNamedImports(bindings)) {
+    return false;
+  }
+  return bindings.elements.every((element) => FACTORY_NAMES.has((element.propertyName ?? element.name).text));
+}
+var lifecycleErasurePlugin = {
+  visitors: {
+    [ts.SyntaxKind.ExpressionStatement]: (node, context) => eraseFactoryCall(node.expression, context) ?? context.superTransformStatements(node),
+    [ts.SyntaxKind.ExportAssignment]: (node, context) => {
+      if (!node.isExportEquals) {
+        const erased = eraseFactoryCall(node.expression, context);
+        if (erased !== undefined) {
+          return erased;
+        }
+      }
+      return context.superTransformStatements(node);
+    },
+    [ts.SyntaxKind.ImportDeclaration]: (node, context) => isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
+  }
+};
+
+// src/transpile.ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import * as tstl from "typescript-to-lua";
+function flattenDiagnosticMessage(text) {
+  if (typeof text === "string") {
+    return text;
+  }
+  return flattenDiagnosticMessage(text.messageText);
+}
+var requireFromHere = createRequire(import.meta.url);
+var TYPES_PKG_ROOT = path.dirname(requireFromHere.resolve("@defold-typescript/types/package.json"));
+var TSTL_LANG_EXT_ROOT = path.dirname(requireFromHere.resolve("@typescript-to-lua/language-extensions/package.json"));
+function readAmbient(rel) {
+  return readFileSync(path.join(TYPES_PKG_ROOT, rel), "utf8");
+}
+var AMBIENT_FILES = {
+  "node_modules/@typescript-to-lua/language-extensions/index.d.ts": readFileSync(path.join(TSTL_LANG_EXT_ROOT, "index.d.ts"), "utf8"),
+  "node_modules/@defold-typescript/types/generated/vmath.d.ts": readAmbient("generated/vmath.d.ts"),
+  "node_modules/@defold-typescript/types/generated/msg.d.ts": readAmbient("generated/msg.d.ts"),
+  "node_modules/@defold-typescript/types/generated/go.d.ts": readAmbient("generated/go.d.ts"),
+  "node_modules/@defold-typescript/types/generated/builtin-messages.d.ts": readAmbient("generated/builtin-messages.d.ts"),
+  "node_modules/@defold-typescript/types/src/core-types.ts": readAmbient("src/core-types.ts"),
+  "node_modules/@defold-typescript/types/src/msg-overloads.d.ts": readAmbient("src/msg-overloads.d.ts"),
+  "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
+  "node_modules/@defold-typescript/types/index.ts": `export { defineGuiScript, defineRenderScript, defineScript } from "./src/lifecycle";
+`
+};
+function collectOutputs(transpiledFiles, diagnostics, userKeys) {
+  const lua = {};
+  const sourceMaps = {};
+  for (const file of transpiledFiles) {
+    const userSource = file.sourceFiles.find((s) => userKeys.has(s.fileName));
+    if (!userSource || typeof file.lua !== "string") {
+      continue;
+    }
+    lua[userSource.fileName] = file.lua;
+    if (typeof file.luaSourceMap === "string") {
+      sourceMaps[userSource.fileName] = file.luaSourceMap;
+    }
+  }
+  const collectedDiagnostics = diagnostics.map((d) => {
+    const fileName = d.file?.fileName;
+    const message = flattenDiagnosticMessage(d.messageText);
+    return fileName !== undefined && userKeys.has(fileName) ? { file: fileName, message } : { message };
+  });
+  return { lua, sourceMaps, diagnostics: collectedDiagnostics };
+}
+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,
+    sourceMap: true,
+    luaPlugins: [{ plugin: lifecycleErasurePlugin }]
+  });
+  return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);
+}
+function transpile(source) {
+  const project = transpileProject({ files: { "main.ts": source } });
+  return {
+    lua: project.lua["main.ts"] ?? "",
+    sourceMap: project.sourceMaps["main.ts"] ?? "",
+    diagnostics: project.diagnostics.map((d) => d.message)
+  };
+}
+
+// src/session.ts
+var requireFromHere2 = createRequire2(import.meta.url);
+var COMPILER_OPTIONS = {
+  luaTarget: tstl2.LuaTarget.Lua54,
+  sourceMap: true,
+  luaPlugins: [{ plugin: lifecycleErasurePlugin }]
+};
+function normalizeSlashes(p) {
+  return p.replace(/\\/g, "/");
+}
+function createOutputCollector() {
+  const files = [];
+  const writeFile = (fileName, data, _bom, _onError, sourceFiles = []) => {
+    let file = files.find((f) => f.sourceFiles.some((s) => sourceFiles.includes(s)));
+    if (!file) {
+      file = { outPath: fileName, sourceFiles: [...sourceFiles] };
+      files.push(file);
+    } else {
+      for (const s of sourceFiles) {
+        if (!file.sourceFiles.includes(s)) {
+          file.sourceFiles.push(s);
+        }
+      }
+    }
+    if (fileName.endsWith(".lua")) {
+      file.lua = data;
+    } else if (fileName.endsWith(".lua.map")) {
+      file.luaSourceMap = data;
+    }
+  };
+  return { writeFile, files };
+}
+function createTranspileSession() {
+  const userFiles = new Map;
+  const sourceFileCache = new Map;
+  const libCache = new Map;
+  let program;
+  const getSourceFile = (fileName) => {
+    const normalized = normalizeSlashes(fileName);
+    const content = mergedContent(normalized);
+    if (content !== undefined) {
+      const cached = sourceFileCache.get(normalized);
+      if (cached) {
+        return cached;
+      }
+      const created = ts2.createSourceFile(fileName, content, ts2.ScriptTarget.Latest, false);
+      sourceFileCache.set(normalized, created);
+      return created;
+    }
+    let filePath;
+    if (fileName.startsWith("lib.")) {
+      const typeScriptDir = path2.dirname(requireFromHere2.resolve("typescript"));
+      filePath = path2.join(typeScriptDir, fileName);
+    }
+    if (fileName.includes("language-extensions")) {
+      const dtsName = fileName.replace(/(\.d)?(\.ts)$/, ".d.ts");
+      filePath = path2.resolve(dtsName);
+    }
+    if (filePath !== undefined) {
+      const cached = libCache.get(fileName);
+      if (cached) {
+        return cached;
+      }
+      const fileContent = readFileSync2(filePath, "utf8");
+      const created = ts2.createSourceFile(filePath, fileContent, ts2.ScriptTarget.Latest, false);
+      libCache.set(fileName, created);
+      return created;
+    }
+    return;
+  };
+  function mergedContent(normalized) {
+    if (userFiles.has(normalized)) {
+      return userFiles.get(normalized);
+    }
+    return AMBIENT_FILES[normalized];
+  }
+  const host = {
+    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts2.sys.fileExists(fileName),
+    getCanonicalFileName: (fileName) => fileName,
+    getCurrentDirectory: () => "",
+    getDefaultLibFileName: ts2.getDefaultLibFileName,
+    readFile: () => "",
+    getNewLine: () => `
+`,
+    useCaseSensitiveFileNames: () => false,
+    writeFile() {},
+    getSourceFile
+  };
+  function update(changes) {
+    for (const [name, value] of Object.entries(changes)) {
+      const normalized = normalizeSlashes(name);
+      if (value === null) {
+        userFiles.delete(normalized);
+        sourceFileCache.delete(normalized);
+      } else {
+        userFiles.set(normalized, value);
+        sourceFileCache.delete(normalized);
+      }
+    }
+    const userKeys = new Set(userFiles.keys());
+    const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
+    program = ts2.createProgram(rootNames, COMPILER_OPTIONS, host, program);
+    const preEmitDiagnostics = ts2.getPreEmitDiagnostics(program);
+    const collector = createOutputCollector();
+    const { diagnostics: transpileDiagnostics } = new tstl2.Transpiler().emit({
+      program,
+      writeFile: collector.writeFile
+    });
+    const diagnostics = [
+      ...ts2.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
+    ];
+    return collectOutputs(collector.files, diagnostics, userKeys);
+  }
+  return {
+    update,
+    getProgram: () => program
+  };
+}
+export {
+  transpileProject,
+  transpile,
+  createTranspileSession
+};

package/dist/lifecycle-erasure.d.ts

@@ -0,0 +1,2 @@
+import { type Plugin } from "typescript-to-lua";
+export declare const lifecycleErasurePlugin: Plugin;

package/dist/session.d.ts

@@ -0,0 +1,7 @@
+import * as ts from "typescript";
+import { type TranspileProjectResult } from "./transpile";
+export interface TranspileSession {
+    update(changes: Readonly<Record<string, string | null>>): TranspileProjectResult;
+    getProgram(): ts.Program | undefined;
+}
+export declare function createTranspileSession(): TranspileSession;

package/dist/transpile.d.ts

@@ -0,0 +1,28 @@
+import type * as ts from "typescript";
+export interface TranspileResult {
+    readonly lua: string;
+    readonly sourceMap: string;
+    readonly diagnostics: readonly string[];
+}
+export interface TranspileDiagnostic {
+    readonly file?: string;
+    readonly message: string;
+}
+export interface TranspileProjectInput {
+    readonly files: Readonly<Record<string, string>>;
+}
+export interface TranspileProjectResult {
+    readonly lua: Readonly<Record<string, string>>;
+    readonly sourceMaps: Readonly<Record<string, string>>;
+    readonly diagnostics: readonly TranspileDiagnostic[];
+}
+export declare const AMBIENT_FILES: Readonly<Record<string, string>>;
+interface CollectableFile {
+    readonly sourceFiles: readonly ts.SourceFile[];
+    readonly lua?: string;
+    readonly luaSourceMap?: string;
+}
+export declare function collectOutputs(transpiledFiles: readonly CollectableFile[], diagnostics: readonly ts.Diagnostic[], userKeys: ReadonlySet<string>): TranspileProjectResult;
+export declare function transpileProject(input: TranspileProjectInput): TranspileProjectResult;
+export declare function transpile(source: string): TranspileResult;
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@defold-typescript/transpiler",
+  "version": "0.1.0",
+  "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --packages=external --outdir=dist && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@defold-typescript/types": "0.1.0",
+    "@typescript-to-lua/language-extensions": "1.19.0",
+    "typescript-to-lua": "^1.36.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export type { TranspileSession } from "./session";
+export { createTranspileSession } from "./session";
+export type {
+  TranspileDiagnostic,
+  TranspileProjectInput,
+  TranspileProjectResult,
+  TranspileResult,
+} from "./transpile";
+export { transpile, transpileProject } from "./transpile";

package/src/lifecycle-erasure.ts

@@ -0,0 +1,147 @@
+import * as ts from "typescript";
+import {
+  createAssignmentStatement,
+  createBlock,
+  createExpressionStatement,
+  createFunctionExpression,
+  createIdentifier,
+  type Identifier,
+  NodeFlags,
+  type Plugin,
+  type Statement,
+  type TransformationContext,
+} from "typescript-to-lua";
+
+const FACTORY_MODULE = "@defold-typescript/types";
+const FACTORY_NAMES = new Set(["defineScript", "defineGuiScript", "defineRenderScript"]);
+
+function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+  let symbol = checker.getSymbolAtLocation(callee);
+  if (symbol === undefined) {
+    return false;
+  }
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    symbol = checker.getAliasedSymbol(symbol);
+  }
+  if (!FACTORY_NAMES.has(symbol.getName())) {
+    return false;
+  }
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+  if (declaration === undefined) {
+    return false;
+  }
+  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
+}
+
+function isThisParameter(param: ts.ParameterDeclaration): boolean {
+  return (
+    ts.isIdentifier(param.name) &&
+    ts.identifierToKeywordKind(param.name) === ts.SyntaxKind.ThisKeyword
+  );
+}
+
+function hookName(property: ts.ObjectLiteralElementLike): string | undefined {
+  const name = property.name;
+  if (name === undefined) {
+    return undefined;
+  }
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+    return name.text;
+  }
+  return undefined;
+}
+
+type HookFunction = (ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction) & {
+  body: ts.ConciseBody;
+};
+
+function hookFunction(property: ts.ObjectLiteralElementLike): HookFunction | undefined {
+  if (ts.isMethodDeclaration(property) && property.body !== undefined) {
+    return property as HookFunction;
+  }
+  if (ts.isPropertyAssignment(property)) {
+    const initializer = property.initializer;
+    if (ts.isFunctionExpression(initializer) || ts.isArrowFunction(initializer)) {
+      return initializer as HookFunction;
+    }
+  }
+  return undefined;
+}
+
+function transformHookBody(fn: HookFunction, context: TransformationContext): Statement[] {
+  if (ts.isBlock(fn.body)) {
+    return context.transformStatements(fn.body.statements);
+  }
+  return [createExpressionStatement(context.transformExpression(fn.body))];
+}
+
+function eraseFactoryCall(
+  expression: ts.Expression,
+  context: TransformationContext,
+): Statement[] | undefined {
+  if (!ts.isCallExpression(expression)) {
+    return undefined;
+  }
+  if (!resolvesToFactoryExport(expression.expression, context.checker)) {
+    return undefined;
+  }
+  const hooks = expression.arguments[0];
+  if (hooks === undefined || !ts.isObjectLiteralExpression(hooks)) {
+    return undefined;
+  }
+  const statements: Statement[] = [];
+  for (const property of hooks.properties) {
+    const name = hookName(property);
+    const fn = hookFunction(property);
+    if (name === undefined || fn === undefined) {
+      continue;
+    }
+    const params: Identifier[] = fn.parameters
+      .filter((param) => !isThisParameter(param) && ts.isIdentifier(param.name))
+      .map((param) => createIdentifier((param.name as ts.Identifier).text, param));
+    const fnExpression = createFunctionExpression(
+      createBlock(transformHookBody(fn, context)),
+      params,
+      undefined,
+      NodeFlags.Declaration,
+      fn,
+    );
+    statements.push(createAssignmentStatement(createIdentifier(name), fnExpression, property));
+  }
+  return statements;
+}
+
+function isFactoryOnlyImport(node: ts.ImportDeclaration): boolean {
+  if (!ts.isStringLiteral(node.moduleSpecifier) || node.moduleSpecifier.text !== FACTORY_MODULE) {
+    return false;
+  }
+  const clause = node.importClause;
+  if (clause === undefined || clause.name !== undefined) {
+    return false;
+  }
+  const bindings = clause.namedBindings;
+  if (bindings === undefined || !ts.isNamedImports(bindings)) {
+    return false;
+  }
+  return bindings.elements.every((element) =>
+    FACTORY_NAMES.has((element.propertyName ?? element.name).text),
+  );
+}
+
+export const lifecycleErasurePlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.ExpressionStatement]: (node, context) =>
+      eraseFactoryCall(node.expression, context) ?? context.superTransformStatements(node),
+    [ts.SyntaxKind.ExportAssignment]: (node, context) => {
+      if (!node.isExportEquals) {
+        const erased = eraseFactoryCall(node.expression, context);
+        if (erased !== undefined) {
+          return erased;
+        }
+      }
+      return context.superTransformStatements(node);
+    },
+    [ts.SyntaxKind.ImportDeclaration]: (node, context) =>
+      isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node),
+  },
+};

package/src/session.ts

@@ -0,0 +1,151 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import { lifecycleErasurePlugin } from "./lifecycle-erasure";
+import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
+
+export interface TranspileSession {
+  update(changes: Readonly<Record<string, string | null>>): TranspileProjectResult;
+  getProgram(): ts.Program | undefined;
+}
+
+const requireFromHere = createRequire(import.meta.url);
+
+const COMPILER_OPTIONS: tstl.CompilerOptions = {
+  luaTarget: tstl.LuaTarget.Lua54,
+  sourceMap: true,
+  luaPlugins: [{ plugin: lifecycleErasurePlugin }],
+};
+
+function normalizeSlashes(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+interface CollectorFile {
+  outPath: string;
+  sourceFiles: ts.SourceFile[];
+  lua?: string;
+  luaSourceMap?: string;
+}
+
+function createOutputCollector(): { writeFile: ts.WriteFileCallback; files: CollectorFile[] } {
+  const files: CollectorFile[] = [];
+  const writeFile: ts.WriteFileCallback = (fileName, data, _bom, _onError, sourceFiles = []) => {
+    let file = files.find((f) => f.sourceFiles.some((s) => sourceFiles.includes(s)));
+    if (!file) {
+      file = { outPath: fileName, sourceFiles: [...sourceFiles] };
+      files.push(file);
+    } else {
+      for (const s of sourceFiles) {
+        if (!file.sourceFiles.includes(s)) {
+          file.sourceFiles.push(s);
+        }
+      }
+    }
+    if (fileName.endsWith(".lua")) {
+      file.lua = data;
+    } else if (fileName.endsWith(".lua.map")) {
+      file.luaSourceMap = data;
+    }
+  };
+  return { writeFile, files };
+}
+
+export function createTranspileSession(): TranspileSession {
+  const userFiles = new Map<string, string>();
+  const sourceFileCache = new Map<string, ts.SourceFile>();
+  const libCache = new Map<string, ts.SourceFile>();
+  let program: ts.Program | undefined;
+
+  const getSourceFile: ts.CompilerHost["getSourceFile"] = (fileName) => {
+    const normalized = normalizeSlashes(fileName);
+    const content = mergedContent(normalized);
+    if (content !== undefined) {
+      const cached = sourceFileCache.get(normalized);
+      if (cached) {
+        return cached;
+      }
+      const created = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, false);
+      sourceFileCache.set(normalized, created);
+      return created;
+    }
+
+    let filePath: string | undefined;
+    if (fileName.startsWith("lib.")) {
+      const typeScriptDir = path.dirname(requireFromHere.resolve("typescript"));
+      filePath = path.join(typeScriptDir, fileName);
+    }
+    if (fileName.includes("language-extensions")) {
+      const dtsName = fileName.replace(/(\.d)?(\.ts)$/, ".d.ts");
+      filePath = path.resolve(dtsName);
+    }
+    if (filePath !== undefined) {
+      const cached = libCache.get(fileName);
+      if (cached) {
+        return cached;
+      }
+      const fileContent = readFileSync(filePath, "utf8");
+      const created = ts.createSourceFile(filePath, fileContent, ts.ScriptTarget.Latest, false);
+      libCache.set(fileName, created);
+      return created;
+    }
+    return undefined;
+  };
+
+  function mergedContent(normalized: string): string | undefined {
+    if (userFiles.has(normalized)) {
+      return userFiles.get(normalized);
+    }
+    return AMBIENT_FILES[normalized];
+  }
+
+  const host: ts.CompilerHost = {
+    fileExists: (fileName) =>
+      mergedContent(normalizeSlashes(fileName)) !== undefined || ts.sys.fileExists(fileName),
+    getCanonicalFileName: (fileName) => fileName,
+    getCurrentDirectory: () => "",
+    getDefaultLibFileName: ts.getDefaultLibFileName,
+    readFile: () => "",
+    getNewLine: () => "\n",
+    useCaseSensitiveFileNames: () => false,
+    writeFile() {},
+    getSourceFile,
+  };
+
+  function update(changes: Readonly<Record<string, string | null>>): TranspileProjectResult {
+    for (const [name, value] of Object.entries(changes)) {
+      const normalized = normalizeSlashes(name);
+      if (value === null) {
+        userFiles.delete(normalized);
+        sourceFileCache.delete(normalized);
+      } else {
+        userFiles.set(normalized, value);
+        sourceFileCache.delete(normalized);
+      }
+    }
+
+    const userKeys = new Set(userFiles.keys());
+    const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
+
+    program = ts.createProgram(rootNames, COMPILER_OPTIONS, host, program);
+
+    const preEmitDiagnostics = ts.getPreEmitDiagnostics(program);
+    const collector = createOutputCollector();
+    const { diagnostics: transpileDiagnostics } = new tstl.Transpiler().emit({
+      program,
+      writeFile: collector.writeFile,
+    });
+    const diagnostics = [
+      ...ts.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics]),
+    ];
+
+    return collectOutputs(collector.files, diagnostics, userKeys);
+  }
+
+  return {
+    update,
+    getProgram: () => program,
+  };
+}

package/src/transpile.ts

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import type * as ts from "typescript";
+import * as tstl from "typescript-to-lua";
+import { lifecycleErasurePlugin } from "./lifecycle-erasure";
+
+export interface TranspileResult {
+  readonly lua: string;
+  readonly sourceMap: string;
+  readonly diagnostics: readonly string[];
+}
+
+export interface TranspileDiagnostic {
+  readonly file?: string;
+  readonly message: string;
+}
+
+export interface TranspileProjectInput {
+  readonly files: Readonly<Record<string, string>>;
+}
+
+export interface TranspileProjectResult {
+  readonly lua: Readonly<Record<string, string>>;
+  readonly sourceMaps: Readonly<Record<string, string>>;
+  readonly diagnostics: readonly TranspileDiagnostic[];
+}
+
+function flattenDiagnosticMessage(
+  text: string | { messageText: string | { messageText: string } },
+): string {
+  if (typeof text === "string") {
+    return text;
+  }
+  return flattenDiagnosticMessage(text.messageText);
+}
+
+const requireFromHere = createRequire(import.meta.url);
+const TYPES_PKG_ROOT = path.dirname(
+  requireFromHere.resolve("@defold-typescript/types/package.json"),
+);
+const TSTL_LANG_EXT_ROOT = path.dirname(
+  requireFromHere.resolve("@typescript-to-lua/language-extensions/package.json"),
+);
+
+function readAmbient(rel: string): string {
+  return readFileSync(path.join(TYPES_PKG_ROOT, rel), "utf8");
+}
+
+export const AMBIENT_FILES: Readonly<Record<string, string>> = {
+  "node_modules/@typescript-to-lua/language-extensions/index.d.ts": readFileSync(
+    path.join(TSTL_LANG_EXT_ROOT, "index.d.ts"),
+    "utf8",
+  ),
+  "node_modules/@defold-typescript/types/generated/vmath.d.ts": readAmbient("generated/vmath.d.ts"),
+  "node_modules/@defold-typescript/types/generated/msg.d.ts": readAmbient("generated/msg.d.ts"),
+  "node_modules/@defold-typescript/types/generated/go.d.ts": readAmbient("generated/go.d.ts"),
+  "node_modules/@defold-typescript/types/generated/builtin-messages.d.ts": readAmbient(
+    "generated/builtin-messages.d.ts",
+  ),
+  "node_modules/@defold-typescript/types/src/core-types.ts": readAmbient("src/core-types.ts"),
+  "node_modules/@defold-typescript/types/src/msg-overloads.d.ts":
+    readAmbient("src/msg-overloads.d.ts"),
+  "node_modules/@defold-typescript/types/src/lifecycle.ts": readAmbient("src/lifecycle.ts"),
+  "node_modules/@defold-typescript/types/index.ts":
+    'export { defineGuiScript, defineRenderScript, defineScript } from "./src/lifecycle";\n',
+};
+
+interface CollectableFile {
+  readonly sourceFiles: readonly ts.SourceFile[];
+  readonly lua?: string;
+  readonly luaSourceMap?: string;
+}
+
+export function collectOutputs(
+  transpiledFiles: readonly CollectableFile[],
+  diagnostics: readonly ts.Diagnostic[],
+  userKeys: ReadonlySet<string>,
+): TranspileProjectResult {
+  const lua: Record<string, string> = {};
+  const sourceMaps: Record<string, string> = {};
+  for (const file of transpiledFiles) {
+    const userSource = file.sourceFiles.find((s) => userKeys.has(s.fileName));
+    if (!userSource || typeof file.lua !== "string") {
+      continue;
+    }
+    lua[userSource.fileName] = file.lua;
+    if (typeof file.luaSourceMap === "string") {
+      sourceMaps[userSource.fileName] = file.luaSourceMap;
+    }
+  }
+
+  const collectedDiagnostics: TranspileDiagnostic[] = diagnostics.map((d) => {
+    const fileName = d.file?.fileName;
+    const message = flattenDiagnosticMessage(d.messageText);
+    return fileName !== undefined && userKeys.has(fileName)
+      ? { file: fileName, message }
+      : { message };
+  });
+
+  return { lua, sourceMaps, diagnostics: collectedDiagnostics };
+}
+
+export function transpileProject(input: TranspileProjectInput): TranspileProjectResult {
+  const userKeys = new Set(Object.keys(input.files));
+  const merged: Record<string, string> = { ...AMBIENT_FILES, ...input.files };
+
+  const result = tstl.transpileVirtualProject(merged, {
+    luaTarget: tstl.LuaTarget.Lua54,
+    sourceMap: true,
+    luaPlugins: [{ plugin: lifecycleErasurePlugin }],
+  });
+
+  return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);
+}
+
+export function transpile(source: string): TranspileResult {
+  const project = transpileProject({ files: { "main.ts": source } });
+  return {
+    lua: project.lua["main.ts"] ?? "",
+    sourceMap: project.sourceMaps["main.ts"] ?? "",
+    diagnostics: project.diagnostics.map((d) => d.message),
+  };
+}