@defold-typescript/transpiler 0.52.0 → 0.54.0

package/dist/lua-require-scan.d.ts

@@ -5,6 +5,10 @@ export interface EmittedRequireSite {
     readonly start: number;
     /** Offset one past its closing delimiter. */
     readonly end: number;
+    /** Offset of the `require` keyword, when the whole call is recoverable. */
+    readonly callStart?: number;
+    /** Offset one past the closing paren, when the whole call is recoverable. */
+    readonly callEnd?: number;
 }
 /**
  * Every code-position `require` of a string literal in an emitted Lua chunk, in

package/dist/native-global-modules.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from "typescript-to-lua";
+export declare const GLOBAL_TABLE_REQUIRE_MARKER = "@defold-typescript:global-table:";
+export declare const nativeGlobalModulesPlugin: Plugin;
+/**
+ * Replace every marker require the scanner can span with the global name it
+ * encodes: `local p = require("<marker>pixels")` becomes `local p = _G.pixels`,
+ * rooted in `_G` so no local in scope — including one named `pixels` — can
+ * shadow the global. A marker site without a recoverable call span is left in
+ * place for `findGlobalAliasMarkerLeak` to fail the build on.
+ */
+export declare function rewriteGlobalAliasRequires(lua: string): string;
+/**
+ * The global name of the first marker require surviving in a chunk after the
+ * swap, or undefined when the chunk is clean. Only require paths the scanner
+ * yields count — marker text in an ordinary string or comment is user data,
+ * not a leak. A survivor means an emit shape the swap cannot reach; the output
+ * would fail to load in Defold, so the caller turns it into a build error
+ * rather than shipping it.
+ */
+export declare function findGlobalAliasMarkerLeak(lua: string): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,9 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.52.0",
+    "@defold-typescript/types": "0.54.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"
+  },
+  "devDependencies": {
+    "lua-wasm-bindings": "0.5.3"
   }
 }

package/src/companion-closure.ts

@@ -1,4 +1,5 @@
 import * as ts from "typescript";
+import { findManagedBootstrap } from "./debug-bootstrap";
 import { resolvesToFactoryExport } from "./lifecycle-erasure";
 
 /**
@@ -49,6 +50,13 @@ export interface CompanionClosure {
    * companion takes its own `require` of the same module instead.
    */
   readonly importBindings: readonly string[];
+  /**
+   * The unedited `setup-debug` managed block's statements, in source order, or
+   * empty. They are exempt from the order rule because the emit runs them ahead
+   * of the companion's `require`, so the debugger starts before anything the
+   * companion loads.
+   */
+  readonly bootstrap: readonly ts.Statement[];
   /** Shapes a split cannot preserve. Empty means the source is splittable. */
   readonly violations: readonly ClosureViolation[];
 }
@@ -717,11 +725,20 @@ export function computeCompanionClosure(
     });
   }
 
+  const managed = findManagedBootstrap(sourceFile);
+  const bootstrap = managed?.canonical === true ? managed.statements : [];
+  const editedBlock = new Set(managed?.canonical === false ? managed.statements : []);
+  const exempt = new Set(bootstrap);
+
   // The companion loads as a unit, so the constraint is pairwise: any effectful
   // script statement with any closure declaration below it is reordered by the
   // split, whatever the first member's position.
   for (const statement of sourceFile.statements) {
-    if (closureStatements.has(statement) || isEffectFreeStatement(statement, checker)) {
+    if (
+      closureStatements.has(statement) ||
+      exempt.has(statement) ||
+      isEffectFreeStatement(statement, checker)
+    ) {
       continue;
     }
     const start = statement.getStart(sourceFile);
@@ -735,14 +752,18 @@ export function computeCompanionClosure(
       siteOf(statement, "runs in the script"),
       siteOf(hoisted.declaration.node, "moves into the companion"),
     ];
+    const name = hoisted.declaration.name;
     violations.push({
       kind: "initialization-order",
-      member: hoisted.declaration.name,
+      member: name,
       sites,
-      message:
-        `top-level work precedes "${hoisted.declaration.name}", which the companion would run first, ` +
-        `reversing their order (${formatSites(sites)}). ` +
-        "Move that work below the companion's declarations, or into a lifecycle hook.",
+      message: editedBlock.has(statement)
+        ? `the setup-debug managed block was edited and now runs top-level work before "${name}", ` +
+          `which the companion would run first (${formatSites(sites)}). ` +
+          "Run `defold-typescript setup-debug` to restore the block."
+        : `top-level work precedes "${name}", which the companion would run first, ` +
+          `reversing their order (${formatSites(sites)}). ` +
+          "Move that work below the companion's declarations, or into a lifecycle hook.",
     });
   }
 
@@ -756,6 +777,7 @@ export function computeCompanionClosure(
     internals: ordered
       .filter(({ symbol }) => !exportSet.has(symbol) && scriptReferences.has(symbol))
       .map(({ declaration }) => declaration.name),
+    bootstrap,
     violations,
   };
 }

package/src/companion-emit.ts

@@ -66,6 +66,8 @@ function isRuntimeScriptSource(sourceFile: ts.SourceFile, checker: ts.TypeChecke
 interface CompanionPlan {
   /** Full start of each top-level statement the companion takes over. */
   readonly closureStarts: ReadonlySet<number>;
+  /** Full start of each unedited `setup-debug` block statement. */
+  readonly bootstrapStarts: ReadonlySet<number>;
   /** Members the script reaches by bare name, which the companion must expose. */
   readonly internals: readonly string[];
   /** Import bindings the companion needs its own `require` of. */
@@ -86,6 +88,7 @@ function planFor(sourceFile: ts.SourceFile, checker: ts.TypeChecker): CompanionP
   }
   return {
     closureStarts: new Set(closure.statements.map((statement) => statement.pos)),
+    bootstrapStarts: new Set(closure.bootstrap.map((statement) => statement.pos)),
     internals: closure.internals,
     importBindings: closure.importBindings,
     requirePath: requirePathForRel(sourceFile.fileName),
@@ -466,6 +469,10 @@ interface SplitHalves {
  * first. The run stops at the first statement that reads the companion, and at
  * the first non-declaration — a lifecycle hook closes over the internals it
  * reads, so its declaration must precede the hook's.
+ *
+ * The `setup-debug` block's gate is taken out of `script` before this runs and
+ * placed immediately ahead of the `require`, so the debugger starts before any
+ * companion code does while `lldebugger` itself is still required above it.
  */
 function requireInsertionPoint(script: readonly Statement[], reads: ReadonlySet<string>): number {
   let index = 0;
@@ -524,6 +531,7 @@ export interface CompanionEmitter {
 export function createCompanionEmitPlugin(): CompanionEmitter {
   const plans = new Map<string, CompanionPlan | undefined>();
   const owned = new Map<string, Set<Statement>>();
+  const bootstraps = new Map<string, Set<Statement>>();
   const companions = new Map<string, string>();
 
   function planOf(sourceFile: ts.SourceFile, checker: ts.TypeChecker): CompanionPlan | undefined {
@@ -552,6 +560,24 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
     return statements;
   }
 
+  function captureBootstrap(node: ts.IfStatement, context: TransformationContext): Statement[] {
+    const statements = context.superTransformStatements(node);
+    const sourceFile = context.sourceFile;
+    const plan = planOf(sourceFile, context.checker);
+    if (plan === undefined || !plan.bootstrapStarts.has(node.pos)) {
+      return statements;
+    }
+    let bucket = bootstraps.get(sourceFile.fileName);
+    if (bucket === undefined) {
+      bucket = new Set();
+      bootstraps.set(sourceFile.fileName, bucket);
+    }
+    for (const statement of statements) {
+      bucket.add(statement);
+    }
+    return statements;
+  }
+
   const visitors: Plugin["visitors"] = {
     [ts.SyntaxKind.VariableStatement]: capture,
     [ts.SyntaxKind.FunctionDeclaration]: capture,
@@ -561,6 +587,7 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
     // because TSTL emits its `require` bindings through its own hoisting. The
     // companion takes a copy of that prelude instead — see `copiedPrelude`.
     [ts.SyntaxKind.ExportDeclaration]: capture,
+    [ts.SyntaxKind.IfStatement]: captureBootstrap,
   };
 
   let configuredNoResolvePaths: readonly string[] = [];
@@ -582,7 +609,8 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
         if (plan === undefined || bucket === undefined || bucket.size === 0) {
           continue;
         }
-        emitCompanion(program, emitHost, file, sourceFile, plan, bucket, companions);
+        const bootstrap = bootstraps.get(sourceFile.fileName) ?? new Set();
+        emitCompanion(program, emitHost, file, sourceFile, plan, bucket, bootstrap, companions);
         emitted.push(plan.requirePath);
       }
       // The companion is written by the CLI, not by TSTL's emit plan, so TSTL's
@@ -606,6 +634,7 @@ function emitCompanion(
   sourceFile: ts.SourceFile,
   plan: CompanionPlan,
   owned: ReadonlySet<Statement>,
+  bootstrap: ReadonlySet<Statement>,
   companions: Map<string, string>,
 ): void {
   const luaAst = file.luaAst;
@@ -644,9 +673,11 @@ function emitCompanion(
   ];
 
   const reads = new Set([EXPORTS_NAME, ...plan.internals]);
-  const insertAt = requireInsertionPoint(halves.script, reads);
+  const rest = halves.script.filter((statement) => !bootstrap.has(statement));
+  const insertAt = requireInsertionPoint(rest, reads);
   const scriptStatements: Statement[] = [
-    ...halves.script.slice(0, insertAt),
+    ...rest.slice(0, insertAt),
+    ...halves.script.filter((statement) => bootstrap.has(statement)),
     createVariableDeclarationStatement(
       exportsIdentifier(),
       createCallExpression(createIdentifier("require"), [createStringLiteral(plan.requirePath)]),
@@ -654,7 +685,7 @@ function emitCompanion(
     ...plan.internals.map((name) =>
       createVariableDeclarationStatement(createIdentifier(name), internalsField(name)),
     ),
-    ...halves.script.slice(insertAt),
+    ...rest.slice(insertAt),
     createReturnStatement([exportsIdentifier()]),
   ];
 

package/src/debug-bootstrap.ts

@@ -0,0 +1,88 @@
+import * as ts from "typescript";
+
+// Managed-block sentinels. A re-run locates the single BEGIN…END pair and
+// refreshes the enclosed text if it drifted, so wording changes self-heal.
+// They are `//` line comments, stripped by TSTL, so they never reach the
+// emitted `.ts.script`.
+export const DEBUG_BLOCK_BEGIN =
+  "// defold-typescript:setup-debug BEGIN — managed block, do not edit";
+export const DEBUG_BLOCK_END = "// defold-typescript:setup-debug END";
+
+// The canonical managed block: import + gated start, marker-free, no
+// `declare module` (that lives in the ambient `.d.ts`). Mirrors the snippet in
+// `packages/docs/guide/debugging.md` exactly; a guide-comparison test locks the two.
+// The blank line before END keeps Biome's organizeImports assist from gluing
+// the END comment onto a following import as its leading comment (which would
+// then demand a blank line before the whole group). With blank lines on both
+// sides of END, an import injected above the user's own imports stays clean.
+export const DEBUG_MANAGED_BLOCK = `${DEBUG_BLOCK_BEGIN}
+import * as lldebugger from "lldebugger.debug";
+
+if (sys.get_engine_info().is_debug) {
+  lldebugger.start();
+}
+
+${DEBUG_BLOCK_END}`;
+
+export interface ManagedBootstrap {
+  /** The top-level statements wholly between the sentinels, in source order. */
+  readonly statements: readonly ts.Statement[];
+  /**
+   * Whether the text between the sentinels is the canonical body token for
+   * token, so line endings, quote style, comments and optional semicolons never
+   * decide it.
+   */
+  readonly canonical: boolean;
+}
+
+function occurrences(haystack: string, needle: string): number {
+  return haystack.split(needle).length - 1;
+}
+
+function bodyTokens(text: string): string[] {
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text);
+  const tokens: string[] = [];
+  for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+    if (kind === ts.SyntaxKind.SemicolonToken) {
+      continue;
+    }
+    const spelling =
+      kind === ts.SyntaxKind.StringLiteral ? scanner.getTokenValue() : scanner.getTokenText();
+    tokens.push(`${kind}:${spelling}`);
+  }
+  return tokens;
+}
+
+const CANONICAL_BODY_TOKENS = bodyTokens(
+  DEBUG_MANAGED_BLOCK.slice(
+    DEBUG_BLOCK_BEGIN.length,
+    DEBUG_MANAGED_BLOCK.length - DEBUG_BLOCK_END.length,
+  ),
+);
+
+/**
+ * The `setup-debug` managed block in a source, located the way
+ * `upsertManagedBlock` locates it: exactly one BEGIN and one END, BEGIN first.
+ * Any other sentinel shape is one `setup-debug` itself refuses to edit, so it
+ * is not a managed block at all.
+ */
+export function findManagedBootstrap(sourceFile: ts.SourceFile): ManagedBootstrap | undefined {
+  const text = sourceFile.text;
+  if (occurrences(text, DEBUG_BLOCK_BEGIN) !== 1 || occurrences(text, DEBUG_BLOCK_END) !== 1) {
+    return undefined;
+  }
+  const beginAt = text.indexOf(DEBUG_BLOCK_BEGIN);
+  const endAt = text.indexOf(DEBUG_BLOCK_END);
+  if (endAt < beginAt) {
+    return undefined;
+  }
+  const bodyStart = beginAt + DEBUG_BLOCK_BEGIN.length;
+  const statements = sourceFile.statements.filter(
+    (statement) => statement.getStart(sourceFile) >= bodyStart && statement.end <= endAt,
+  );
+  const tokens = bodyTokens(text.slice(bodyStart, endAt));
+  const canonical =
+    tokens.length === CANONICAL_BODY_TOKENS.length &&
+    tokens.every((token, index) => token === CANONICAL_BODY_TOKENS[index]);
+  return { statements, canonical };
+}

package/src/index.ts

@@ -11,6 +11,13 @@ export {
   componentIdOfSameObjectAddress,
 } from "./component-animation-index";
 export { buildConfigKeyIndex, readGameProjectSetting } from "./config-key-index";
+export type { ManagedBootstrap } from "./debug-bootstrap";
+export {
+  DEBUG_BLOCK_BEGIN,
+  DEBUG_BLOCK_END,
+  DEBUG_MANAGED_BLOCK,
+  findManagedBootstrap,
+} from "./debug-bootstrap";
 export { findEmittedRequires, LUALIB_REQUIRE_NAME } from "./emitted-requires";
 export type { GuiFlipbookIndex } from "./gui-flipbook-index";
 export { buildGuiFlipbookIndex } from "./gui-flipbook-index";

package/src/native-global-modules.ts

@@ -0,0 +1,183 @@
+import * as ts from "typescript";
+import type { Plugin } from "typescript-to-lua";
+import { scanEmittedRequires } from "./lua-require-scan";
+
+const GLOBAL_TABLE_TAG = "globalTable";
+
+// Survives into the emitted require path, so it must collide with no real
+// module path a build can own: `@` and `:` are impossible in one.
+export const GLOBAL_TABLE_REQUIRE_MARKER = "@defold-typescript:global-table:";
+
+// `@NoResolution:` tells TSTL's resolver to leave the path alone (the module
+// has no source file in the program); the resolver strips the prefix, leaving
+// the marker path for the post-pass swap.
+const NO_RESOLUTION_PREFIX = "@NoResolution:";
+
+const LUA_GLOBAL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+type TagResolution =
+  | { readonly kind: "untagged" }
+  | { readonly kind: "tagged"; readonly globalName: string }
+  | { readonly kind: "invalid"; readonly globalName: string; readonly moduleId: string };
+
+// The tag is consulted only when the specifier resolves to an ambient
+// `declare module "<id>"`; a real source file sharing the id resolves to the
+// file and stays on the ordinary require lane.
+function resolveGlobalTableTag(specifier: ts.Expression, checker: ts.TypeChecker): TagResolution {
+  if (!ts.isStringLiteral(specifier)) {
+    return { kind: "untagged" };
+  }
+  const symbol = checker.getSymbolAtLocation(specifier);
+  for (const declaration of symbol?.declarations ?? []) {
+    if (!ts.isModuleDeclaration(declaration) || !ts.isStringLiteral(declaration.name)) {
+      continue;
+    }
+    const tag = ts.getJSDocTags(declaration).find((t) => t.tagName.text === GLOBAL_TABLE_TAG);
+    if (tag === undefined) {
+      continue;
+    }
+    const comment = ts.getTextOfJSDocComment(tag.comment)?.trim();
+    const globalName =
+      comment === undefined || comment === ""
+        ? specifier.text
+        : (comment.split(/\s+/)[0] ?? specifier.text);
+    if (!LUA_GLOBAL_NAME_RE.test(globalName)) {
+      return { kind: "invalid", globalName, moduleId: specifier.text };
+    }
+    return { kind: "tagged", globalName };
+  }
+  return { kind: "untagged" };
+}
+
+function markerRequirePath(globalName: string): string {
+  return `${NO_RESOLUTION_PREFIX}${GLOBAL_TABLE_REQUIRE_MARKER}${globalName}`;
+}
+
+function invalidGlobalName(
+  node: ts.Node,
+  resolution: {
+    readonly globalName: string;
+    readonly moduleId: string;
+  },
+): ts.Diagnostic {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `@${GLOBAL_TABLE_TAG} on module "${resolution.moduleId}" names \`${resolution.globalName}\`, which is not a valid Lua global name; use dotted identifiers (\`pixels\`, \`b2d.body\`).`,
+  };
+}
+
+export const nativeGlobalModulesPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.ImportDeclaration]: (node, context) => {
+      const resolution = resolveGlobalTableTag(node.moduleSpecifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(node.moduleSpecifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      if (node.importClause === undefined) {
+        // A side-effect import of a runtime global loads nothing.
+        return [];
+      }
+      const rewritten = ts.factory.updateImportDeclaration(
+        node,
+        node.modifiers,
+        node.importClause,
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        node.attributes,
+      );
+      return context.superTransformStatements(rewritten);
+    },
+    [ts.SyntaxKind.ExportDeclaration]: (node, context) => {
+      const specifier = node.moduleSpecifier;
+      if (specifier === undefined) {
+        return context.superTransformStatements(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      const rewritten = ts.factory.updateExportDeclaration(
+        node,
+        node.modifiers,
+        node.isTypeOnly,
+        node.exportClause,
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        node.attributes,
+      );
+      return context.superTransformStatements(rewritten);
+    },
+    [ts.SyntaxKind.CallExpression]: (node, context) => {
+      const specifier = node.arguments[0];
+      if (node.expression.kind !== ts.SyntaxKind.ImportKeyword || specifier === undefined) {
+        return context.superTransformExpression(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformExpression(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformExpression(node);
+      }
+      const rewritten = ts.factory.updateCallExpression(node, node.expression, node.typeArguments, [
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        ...node.arguments.slice(1),
+      ]);
+      return context.superTransformExpression(rewritten);
+    },
+  },
+};
+
+/**
+ * Replace every marker require the scanner can span with the global name it
+ * encodes: `local p = require("<marker>pixels")` becomes `local p = _G.pixels`,
+ * rooted in `_G` so no local in scope — including one named `pixels` — can
+ * shadow the global. A marker site without a recoverable call span is left in
+ * place for `findGlobalAliasMarkerLeak` to fail the build on.
+ */
+export function rewriteGlobalAliasRequires(lua: string): string {
+  let out = "";
+  let cursor = 0;
+  for (const site of scanEmittedRequires(lua)) {
+    if (!site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      continue;
+    }
+    if (site.callStart === undefined || site.callEnd === undefined) {
+      continue;
+    }
+    out += lua.slice(cursor, site.callStart);
+    out += `_G.${site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length)}`;
+    cursor = site.callEnd;
+  }
+  return out + lua.slice(cursor);
+}
+
+/**
+ * The global name of the first marker require surviving in a chunk after the
+ * swap, or undefined when the chunk is clean. Only require paths the scanner
+ * yields count — marker text in an ordinary string or comment is user data,
+ * not a leak. A survivor means an emit shape the swap cannot reach; the output
+ * would fail to load in Defold, so the caller turns it into a build error
+ * rather than shipping it.
+ */
+export function findGlobalAliasMarkerLeak(lua: string): string | undefined {
+  for (const site of scanEmittedRequires(lua)) {
+    if (site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      return site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length);
+    }
+  }
+  return undefined;
+}

package/src/session.ts

@@ -9,6 +9,7 @@ import { hsmLoweringPlugin } from "./hsm-builtin";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { nativeGlobalModulesPlugin } from "./native-global-modules";
 import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
 import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
@@ -54,6 +55,7 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
       { plugin: physicsEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: nativeGlobalModulesPlugin },
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin },

package/src/transpile.ts

@@ -21,6 +21,11 @@ import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { scanEmittedRequires } from "./lua-require-scan";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import {
+  findGlobalAliasMarkerLeak,
+  nativeGlobalModulesPlugin,
+  rewriteGlobalAliasRequires,
+} from "./native-global-modules";
 import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
 import { TIMERS_RUNTIME } from "./timers-runtime";
@@ -258,6 +263,7 @@ export function collectOutputs(
   const lua: Record<string, string> = {};
   const sourceMaps: Record<string, string> = {};
   const companions: Record<string, string> = {};
+  const markerLeaks: { file: string; globalName: string }[] = [];
   let lualib: string | undefined;
   for (const file of transpiledFiles) {
     if (isLualibBundle(file) && typeof file.lua === "string") {
@@ -268,13 +274,25 @@ export function collectOutputs(
     if (!userSource || typeof file.lua !== "string") {
       continue;
     }
-    lua[userSource.fileName] = file.lua;
+    // Column offsets after a swap shift, as they already do under the CLI's
+    // require respelling — accepted.
+    const swapped = rewriteGlobalAliasRequires(file.lua);
+    lua[userSource.fileName] = swapped;
+    const leaked = findGlobalAliasMarkerLeak(swapped);
+    if (leaked !== undefined) {
+      markerLeaks.push({ file: userSource.fileName, globalName: leaked });
+    }
     if (typeof file.luaSourceMap === "string") {
       sourceMaps[userSource.fileName] = file.luaSourceMap;
     }
     const companion = emittedCompanions.get(userSource.fileName);
     if (companion !== undefined) {
-      companions[userSource.fileName] = companion;
+      const swappedCompanion = rewriteGlobalAliasRequires(companion);
+      companions[userSource.fileName] = swappedCompanion;
+      const companionLeak = findGlobalAliasMarkerLeak(swappedCompanion);
+      if (companionLeak !== undefined) {
+        markerLeaks.push({ file: userSource.fileName, globalName: companionLeak });
+      }
     }
   }
 
@@ -291,6 +309,15 @@ export function collectOutputs(
     return { file: fileName, message, line: line + 1, column: character + 1 };
   });
 
+  // A surviving marker is a build error, not a fallback: the alternative —
+  // leaving the original require — fails silently at load time in Defold.
+  for (const leak of markerLeaks) {
+    collectedDiagnostics.push({
+      file: leak.file,
+      message: `@globalTable lowering left an unrewritten require for \`${leak.globalName}\` in the emitted chunk; the output would fail to load in Defold.`,
+    });
+  }
+
   // Advisory scan of the user TypeScript AST for the deprecated direct
   // `go.property` call, plus detection of the timers polyfill import. Run here
   // (shared by transpileProject and the watch session) so both paths report it
@@ -378,6 +405,7 @@ function transpileVirtual(
         { plugin: physicsEventGuardLoweringPlugin },
         { plugin: messageDispatchLoweringPlugin },
         { plugin: timersLoweringPlugin },
+        { plugin: nativeGlobalModulesPlugin },
         { plugin: hsmLoweringPlugin },
         { plugin: typeApplicationErasurePlugin },
         { plugin: companionEmit.plugin },