@defold-typescript/cli 0.5.0 → 0.5.2

package/dist/bin.js

@@ -348,6 +348,107 @@ var VSCODE_EXTENSIONS_CONTENT = {
 var VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"]
 };
+function inlineSnippetBody(factory, includeOnInput) {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    `export const script = ${factory}({`,
+    "  // Initialize the component and return its state.",
+    "  init() {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$1},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$2},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$3},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$4},"
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$5},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$6},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$7},");
+  lines.push("});");
+  return lines;
+}
+function typedSnippetBody(factory, includeOnInput) {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    "type Self = {",
+    "  // Your script's state goes here.",
+    "  $1",
+    "};",
+    "",
+    `export const script = ${factory}<Self>({`,
+    "  // Initialize the component and return its state.",
+    "  init(): Self {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$2},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$3},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$4},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$5},"
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$6},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$7},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$8},");
+  lines.push("});");
+  return lines;
+}
+var VSCODE_SNIPPETS_CONTENT = {
+  "Defold script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-script",
+    body: inlineSnippetBody("defineScript", true),
+    description: "Empty Defold script; state inferred from init's return."
+  },
+  "Defold script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-script-typed",
+    body: typedSnippetBody("defineScript", true),
+    description: "Empty Defold script with an explicit Self type."
+  },
+  "Defold GUI script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-gui",
+    body: inlineSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script; state inferred from init's return."
+  },
+  "Defold GUI script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-gui-typed",
+    body: typedSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script with an explicit Self type."
+  },
+  "Defold render script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-render",
+    body: inlineSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script; state inferred from init's return."
+  },
+  "Defold render script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-render-typed",
+    body: typedSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script with an explicit Self type."
+  }
+};
 var MAIN_TS_CONTENT = `export function init(): void {
   const start = vmath.vector3(0, 0, 0);
   msg.post("main:/hero", "spawn", { start });
@@ -522,6 +623,26 @@ function writeVscodeSettings(cwd, written) {
   writeJson(filePath, VSCODE_SETTINGS_CONTENT);
   written.push(".vscode/settings.json");
 }
+function writeVscodeSnippets(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "defold-typescript.code-snippets");
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    for (const [key, snippet] of Object.entries(VSCODE_SNIPPETS_CONTENT)) {
+      if (!(key in existing)) {
+        existing[key] = snippet;
+      }
+    }
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
+  written.push(".vscode/defold-typescript.code-snippets");
+}
 function writeTsSurface(cwd, written, force = false) {
   mkdirSync2(path6.join(cwd, "src"), { recursive: true });
   writeFileSync2(path6.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -565,6 +686,7 @@ function writeTsSurface(cwd, written, force = false) {
   writeBiome(cwd, written);
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
+  writeVscodeSnippets(cwd, written);
   return selectScriptKind(kinds);
 }
 function runNewProjectInit(cwd, force = false) {
@@ -650,6 +772,8 @@ function materializeApiSurface(opts) {
   const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path7.join(srcDir, file)));
   const coreTypesSrc = path7.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync3(coreTypesSrc);
+  const engineGlobalsSrc = path7.join(srcDir, "engine-globals.d.ts");
+  const includeEngineGlobals = includeCoreTypes && existsSync3(engineGlobalsSrc);
   const wanted = new Set(sources);
   for (const file of overloads) {
     wanted.add(file);
@@ -657,6 +781,9 @@ function materializeApiSurface(opts) {
   if (includeCoreTypes) {
     wanted.add("core-types.d.ts");
   }
+  if (includeEngineGlobals) {
+    wanted.add("engine-globals.d.ts");
+  }
   for (const existing of readdirSync2(absDir)) {
     if (existing.endsWith(".d.ts") && existing !== "index.d.ts" && !wanted.has(existing)) {
       rmSync(path7.join(absDir, existing));
@@ -668,10 +795,16 @@ function materializeApiSurface(opts) {
   if (includeCoreTypes) {
     writeFileSync3(path7.join(absDir, "core-types.d.ts"), readFileSync6(coreTypesSrc, "utf8"));
   }
+  if (includeEngineGlobals) {
+    writeFileSync3(path7.join(absDir, "engine-globals.d.ts"), readFileSync6(engineGlobalsSrc, "utf8"));
+  }
   for (const file of overloads) {
     writeFileSync3(path7.join(absDir, file), readFileSync6(path7.join(srcDir, file), "utf8"));
   }
   const modules = [...sources, ...overloads].map((file) => file.replace(/\.d\.ts$/, ""));
+  if (includeEngineGlobals) {
+    modules.push("engine-globals");
+  }
   const imports = modules.map((mod) => `import "./${mod}";`).join(`
 `);
   writeFileSync3(path7.join(absDir, "index.d.ts"), `${imports}
@@ -747,6 +880,10 @@ async function materializeRefDocSurface(opts) {
       ...excludeModules.length > 0 ? { excludeModules } : {}
     });
     copyFileSync(path7.join(root, "src", "core-types.ts"), path7.join(absDir, "core-types.d.ts"));
+    copyFileSync(path7.join(root, "src", "engine-globals.d.ts"), path7.join(absDir, "engine-globals.d.ts"));
+    const indexPath = path7.join(absDir, "index.d.ts");
+    writeFileSync3(indexPath, `import "./engine-globals";
+${readFileSync6(indexPath, "utf8")}`);
   } catch {
     rmSync(absDir, { recursive: true, force: true });
     return { materializedDir: null, active: null };

package/dist/index.js

@@ -412,6 +412,107 @@ var VSCODE_EXTENSIONS_CONTENT = {
 var VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"]
 };
+function inlineSnippetBody(factory, includeOnInput) {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    `export const script = ${factory}({`,
+    "  // Initialize the component and return its state.",
+    "  init() {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$1},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$2},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$3},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$4},"
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$5},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$6},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$7},");
+  lines.push("});");
+  return lines;
+}
+function typedSnippetBody(factory, includeOnInput) {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    "type Self = {",
+    "  // Your script's state goes here.",
+    "  $1",
+    "};",
+    "",
+    `export const script = ${factory}<Self>({`,
+    "  // Initialize the component and return its state.",
+    "  init(): Self {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$2},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$3},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$4},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$5},"
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$6},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$7},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$8},");
+  lines.push("});");
+  return lines;
+}
+var VSCODE_SNIPPETS_CONTENT = {
+  "Defold script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-script",
+    body: inlineSnippetBody("defineScript", true),
+    description: "Empty Defold script; state inferred from init's return."
+  },
+  "Defold script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-script-typed",
+    body: typedSnippetBody("defineScript", true),
+    description: "Empty Defold script with an explicit Self type."
+  },
+  "Defold GUI script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-gui",
+    body: inlineSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script; state inferred from init's return."
+  },
+  "Defold GUI script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-gui-typed",
+    body: typedSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script with an explicit Self type."
+  },
+  "Defold render script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-render",
+    body: inlineSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script; state inferred from init's return."
+  },
+  "Defold render script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-render-typed",
+    body: typedSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script with an explicit Self type."
+  }
+};
 var MAIN_TS_CONTENT = `export function init(): void {
   const start = vmath.vector3(0, 0, 0);
   msg.post("main:/hero", "spawn", { start });
@@ -586,6 +687,26 @@ function writeVscodeSettings(cwd, written) {
   writeJson(filePath, VSCODE_SETTINGS_CONTENT);
   written.push(".vscode/settings.json");
 }
+function writeVscodeSnippets(cwd, written) {
+  const dir = path7.join(cwd, ".vscode");
+  const filePath = path7.join(dir, "defold-typescript.code-snippets");
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    for (const [key, snippet] of Object.entries(VSCODE_SNIPPETS_CONTENT)) {
+      if (!(key in existing)) {
+        existing[key] = snippet;
+      }
+    }
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
+  written.push(".vscode/defold-typescript.code-snippets");
+}
 function writeTsSurface(cwd, written, force = false) {
   mkdirSync2(path7.join(cwd, "src"), { recursive: true });
   writeFileSync2(path7.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -629,6 +750,7 @@ function writeTsSurface(cwd, written, force = false) {
   writeBiome(cwd, written);
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
+  writeVscodeSnippets(cwd, written);
   return selectScriptKind(kinds);
 }
 function runNewProjectInit(cwd, force = false) {
@@ -714,6 +836,8 @@ function materializeApiSurface(opts) {
   const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path8.join(srcDir, file)));
   const coreTypesSrc = path8.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync3(coreTypesSrc);
+  const engineGlobalsSrc = path8.join(srcDir, "engine-globals.d.ts");
+  const includeEngineGlobals = includeCoreTypes && existsSync3(engineGlobalsSrc);
   const wanted = new Set(sources);
   for (const file of overloads) {
     wanted.add(file);
@@ -721,6 +845,9 @@ function materializeApiSurface(opts) {
   if (includeCoreTypes) {
     wanted.add("core-types.d.ts");
   }
+  if (includeEngineGlobals) {
+    wanted.add("engine-globals.d.ts");
+  }
   for (const existing of readdirSync2(absDir)) {
     if (existing.endsWith(".d.ts") && existing !== "index.d.ts" && !wanted.has(existing)) {
       rmSync2(path8.join(absDir, existing));
@@ -732,10 +859,16 @@ function materializeApiSurface(opts) {
   if (includeCoreTypes) {
     writeFileSync3(path8.join(absDir, "core-types.d.ts"), readFileSync7(coreTypesSrc, "utf8"));
   }
+  if (includeEngineGlobals) {
+    writeFileSync3(path8.join(absDir, "engine-globals.d.ts"), readFileSync7(engineGlobalsSrc, "utf8"));
+  }
   for (const file of overloads) {
     writeFileSync3(path8.join(absDir, file), readFileSync7(path8.join(srcDir, file), "utf8"));
   }
   const modules = [...sources, ...overloads].map((file) => file.replace(/\.d\.ts$/, ""));
+  if (includeEngineGlobals) {
+    modules.push("engine-globals");
+  }
   const imports = modules.map((mod) => `import "./${mod}";`).join(`
 `);
   writeFileSync3(path8.join(absDir, "index.d.ts"), `${imports}
@@ -811,6 +944,10 @@ async function materializeRefDocSurface(opts) {
       ...excludeModules.length > 0 ? { excludeModules } : {}
     });
     copyFileSync(path8.join(root, "src", "core-types.ts"), path8.join(absDir, "core-types.d.ts"));
+    copyFileSync(path8.join(root, "src", "engine-globals.d.ts"), path8.join(absDir, "engine-globals.d.ts"));
+    const indexPath = path8.join(absDir, "index.d.ts");
+    writeFileSync3(indexPath, `import "./engine-globals";
+${readFileSync7(indexPath, "utf8")}`);
   } catch {
     rmSync2(absDir, { recursive: true, force: true });
     return { materializedDir: null, active: null };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "End-user CLI for scaffolding and building Defold projects written in TypeScript.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/transpiler": "0.5.0",
-    "@defold-typescript/types": "0.5.0"
+    "@defold-typescript/transpiler": "0.5.2",
+    "@defold-typescript/types": "0.5.2"
   }
 }

package/src/init.ts

@@ -81,6 +81,122 @@ const VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"],
 };
 
+interface VscodeSnippet {
+  scope: string;
+  prefix: string;
+  body: string[];
+  description: string;
+}
+
+// Whole-file TS scaffolds mirroring the Defold editor's empty script/gui/render
+// templates over the lifecycle factories. Two self-typing variants per kind:
+// inline-self (TSelf inferred from `init`'s return) and typed-self (an explicit
+// dummy `Self` placeholder). Hook order mirrors the Lua templates; render omits
+// `on_input` because `RenderScriptHooks` does. The final `$0` lands inside `init`.
+function inlineSnippetBody(factory: string, includeOnInput: boolean): string[] {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    `export const script = ${factory}({`,
+    "  // Initialize the component and return its state.",
+    "  init() {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$1},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$2},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$3},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$4},",
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$5},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$6},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$7},");
+  lines.push("});");
+  return lines;
+}
+
+function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
+  const lines = [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    "type Self = {",
+    "  // Your script's state goes here.",
+    "  $1",
+    "};",
+    "",
+    `export const script = ${factory}<Self>({`,
+    "  // Initialize the component and return its state.",
+    "  init(): Self {",
+    "    return { $0 };",
+    "  },",
+    "  // Update the component every frame; `dt` is the time step.",
+    "  update(self, dt) {$2},",
+    "  // Update at the fixed physics time step.",
+    "  fixed_update(self, dt) {$3},",
+    "  // Update every frame after `update`.",
+    "  late_update(self, dt) {$4},",
+    "  // Handle an incoming message.",
+    "  on_message(self, message_id, message, sender) {$5},",
+  ];
+  if (includeOnInput) {
+    lines.push("  // Handle input once input focus is acquired.");
+    lines.push("  on_input(self, action_id, action) {$6},");
+  }
+  lines.push("  // Clean up when the component is deleted.");
+  lines.push("  final(self) {$7},");
+  lines.push("  // React to a hot reload of this script.");
+  lines.push("  on_reload(self) {$8},");
+  lines.push("});");
+  return lines;
+}
+
+const VSCODE_SNIPPETS_CONTENT: Record<string, VscodeSnippet> = {
+  "Defold script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-script",
+    body: inlineSnippetBody("defineScript", true),
+    description: "Empty Defold script; state inferred from init's return.",
+  },
+  "Defold script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-script-typed",
+    body: typedSnippetBody("defineScript", true),
+    description: "Empty Defold script with an explicit Self type.",
+  },
+  "Defold GUI script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-gui",
+    body: inlineSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script; state inferred from init's return.",
+  },
+  "Defold GUI script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-gui-typed",
+    body: typedSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script with an explicit Self type.",
+  },
+  "Defold render script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-render",
+    body: inlineSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script; state inferred from init's return.",
+  },
+  "Defold render script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-render-typed",
+    body: typedSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script with an explicit Self type.",
+  },
+};
+
 const MAIN_TS_CONTENT = `export function init(): void {
   const start = vmath.vector3(0, 0, 0);
   msg.post("main:/hero", "spawn", { start });
@@ -301,6 +417,27 @@ function writeVscodeSettings(cwd: string, written: string[]): void {
   written.push(".vscode/settings.json");
 }
 
+function writeVscodeSnippets(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "defold-typescript.code-snippets");
+  if (existsSync(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    for (const [key, snippet] of Object.entries(VSCODE_SNIPPETS_CONTENT)) {
+      if (!(key in existing)) {
+        existing[key] = snippet;
+      }
+    }
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
+  written.push(".vscode/defold-typescript.code-snippets");
+}
+
 function writeTsSurface(cwd: string, written: string[], force = false): ScriptKind | null {
   mkdirSync(path.join(cwd, "src"), { recursive: true });
   writeFileSync(path.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -349,6 +486,7 @@ function writeTsSurface(cwd: string, written: string[], force = false): ScriptKi
 
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
+  writeVscodeSnippets(cwd, written);
 
   return selectScriptKind(kinds);
 }

package/src/materialize.ts

@@ -70,6 +70,8 @@ export function materializeApiSurface(
   );
   const coreTypesSrc = path.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync(coreTypesSrc);
+  const engineGlobalsSrc = path.join(srcDir, "engine-globals.d.ts");
+  const includeEngineGlobals = includeCoreTypes && existsSync(engineGlobalsSrc);
 
   const wanted = new Set(sources);
   for (const file of overloads) {
@@ -78,6 +80,9 @@ export function materializeApiSurface(
   if (includeCoreTypes) {
     wanted.add("core-types.d.ts");
   }
+  if (includeEngineGlobals) {
+    wanted.add("engine-globals.d.ts");
+  }
 
   for (const existing of readdirSync(absDir)) {
     if (existing.endsWith(".d.ts") && existing !== "index.d.ts" && !wanted.has(existing)) {
@@ -94,11 +99,17 @@ export function materializeApiSurface(
   if (includeCoreTypes) {
     writeFileSync(path.join(absDir, "core-types.d.ts"), readFileSync(coreTypesSrc, "utf8"));
   }
+  if (includeEngineGlobals) {
+    writeFileSync(path.join(absDir, "engine-globals.d.ts"), readFileSync(engineGlobalsSrc, "utf8"));
+  }
   for (const file of overloads) {
     writeFileSync(path.join(absDir, file), readFileSync(path.join(srcDir, file), "utf8"));
   }
 
   const modules = [...sources, ...overloads].map((file) => file.replace(/\.d\.ts$/, ""));
+  if (includeEngineGlobals) {
+    modules.push("engine-globals");
+  }
   const imports = modules.map((mod) => `import "./${mod}";`).join("\n");
   writeFileSync(path.join(absDir, "index.d.ts"), `${imports}\n\nexport {};\n`);
 
@@ -216,6 +227,12 @@ export async function materializeRefDocSurface(
       ...(excludeModules.length > 0 ? { excludeModules } : {}),
     });
     copyFileSync(path.join(root, "src", "core-types.ts"), path.join(absDir, "core-types.d.ts"));
+    copyFileSync(
+      path.join(root, "src", "engine-globals.d.ts"),
+      path.join(absDir, "engine-globals.d.ts"),
+    );
+    const indexPath = path.join(absDir, "index.d.ts");
+    writeFileSync(indexPath, `import "./engine-globals";\n${readFileSync(indexPath, "utf8")}`);
   } catch {
     rmSync(absDir, { recursive: true, force: true });
     return { materializedDir: null, active: null };