[tsgen] Fix exporting HEAP variables as any in TSD (#26462)

Exporting HEAP elements like HEAP8 inside TypeScript definitions were
previously generating as `any` types because TSD emitter fallbacks
assumed unknown signatures for runtime methods without docs.

To solve this, move high-level HEAP array definitions into libcore.js
with explicit JSDoc type tags, treating them as library symbols. This
allows the TSD generation to gather correct typed signatures.

Also includes casts for Closure Compiler warnings encountered.

Fixes #24941

Author: brendandahl

src/lib/libbootstrap.js

@@ -15,6 +15,19 @@ assert(Object.keys(LibraryManager.library).length === 0);
 addToLibrary({
   $callRuntimeCallbacks: () => {},
 
+  $HEAP8: undefined,
+  $HEAPU8: undefined,
+  $HEAP16: undefined,
+  $HEAPU16: undefined,
+  $HEAP32: undefined,
+  $HEAPU32: undefined,
+  $HEAPF32: undefined,
+  $HEAPF64: undefined,
+#if WASM_BIGINT
+  $HEAP64: undefined,
+  $HEAPU64: undefined,
+#endif
+
   $wasmMemory: 'memory',
 
   $ExitStatus: class {

src/lib/libcore.js

@@ -21,6 +21,31 @@
 // new function with an '_', it will not be found.
 
 addToLibrary({
+  // HEAP definitions are here to help with TypeScript type generation.
+  $HEAP8__docs: '/** @type {!Int8Array} */',
+  $HEAP8: undefined,
+  $HEAPU8__docs: '/** @type {!Uint8Array} */',
+  $HEAPU8: undefined,
+  $HEAP16__docs: '/** @type {!Int16Array} */',
+  $HEAP16: undefined,
+  $HEAPU16__docs: '/** @type {!Uint16Array} */',
+  $HEAPU16: undefined,
+  $HEAP32__docs: '/** @type {!Int32Array} */',
+  $HEAP32: undefined,
+  $HEAPU32__docs: '/** @type {!Uint32Array} */',
+  $HEAPU32: undefined,
+  $HEAPF32__docs: '/** @type {!Float32Array} */',
+  $HEAPF32: undefined,
+  $HEAPF64__docs: '/** @type {!Float64Array} */',
+  $HEAPF64: undefined,
+#if WASM_BIGINT
+  // BigInt64Array type is not correctly defined in closure
+  $HEAP64__docs: '/** not-@type {!BigInt64Array} */',
+  $HEAP64: undefined,
+  $HEAPU64__docs: '/** not-@type {!BigUint64Array} */',
+  $HEAPU64: undefined,
+#endif
+
   // JS aliases for native stack manipulation functions and tempret handling
   $stackSave__deps: ['emscripten_stack_get_current'],
   $stackSave: () => _emscripten_stack_get_current(),

src/modules.mjs

@@ -495,16 +495,6 @@ function exportRuntimeSymbols() {
     'callMain',
     'abort',
     'wasmExports',
-    'HEAPF32',
-    'HEAPF64',
-    'HEAP8',
-    'HEAPU8',
-    'HEAP16',
-    'HEAPU16',
-    'HEAP32',
-    'HEAPU32',
-    'HEAP64',
-    'HEAPU64',
   ];
 
   if (SUPPORT_BIG_ENDIAN) {

src/runtime_common.js

@@ -78,33 +78,6 @@ if (ENVIRONMENT_IS_NODE && {{{ ENVIRONMENT_IS_WORKER_THREAD() }}}) {
 #endif
 
 // Memory management
-var
-/** @type {!Int8Array} */
-  HEAP8,
-/** @type {!Uint8Array} */
-  HEAPU8,
-/** @type {!Int16Array} */
-  HEAP16,
-/** @type {!Uint16Array} */
-  HEAPU16,
-/** @type {!Int32Array} */
-  HEAP32,
-/** @type {!Uint32Array} */
-  HEAPU32,
-/** @type {!Float32Array} */
-  HEAPF32,
-/** @type {!Float64Array} */
-  HEAPF64;
-
-#if WASM_BIGINT
-// BigInt64Array type is not correctly defined in closure
-var
-/** not-@type {!BigInt64Array} */
-  HEAP64,
-/* BigUint64Array type is not correctly defined in closure
-/** not-@type {!BigUint64Array} */
-  HEAPU64;
-#endif
 
 #if SUPPORT_BIG_ENDIAN
 /** @type {!DataView} */

test/codesize/audio_worklet_wasm.expected.js

@@ -1,4 +1,4 @@
-var m = globalThis.Module || "undefined" != typeof Module ? Module : {}, p = !!globalThis.AudioWorkletGlobalScope, t = "em-ww" == globalThis.name || p, u, z, I, J, G, E, w, X, F, D, C, Y, A, Z;
+var m = globalThis.Module || "undefined" != typeof Module ? Module : {}, p = !!globalThis.AudioWorkletGlobalScope, t = "em-ww" == globalThis.name || p, u, z, J, E, G, I, w, X, F, D, C, Y, A, Z;
 
 function v(a) {
     u = a;

test/codesize/test_codesize_cxx_ctors1.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 19214,
-  "a.out.js.gz": 7982,
+  "a.out.js.gz": 7981,
   "a.out.nodebug.wasm": 132866,
   "a.out.nodebug.wasm.gz": 49893,
   "total": 152080,
-  "total_gz": 57875,
+  "total_gz": 57874,
   "sent": [
     "__cxa_throw",
     "_abort_js",

test/codesize/test_codesize_cxx_ctors2.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 19191,
-  "a.out.js.gz": 7968,
+  "a.out.js.gz": 7966,
   "a.out.nodebug.wasm": 132286,
   "a.out.nodebug.wasm.gz": 49547,
   "total": 151477,
-  "total_gz": 57515,
+  "total_gz": 57513,
   "sent": [
     "__cxa_throw",
     "_abort_js",

test/codesize/test_codesize_cxx_except.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 22875,
-  "a.out.js.gz": 8959,
+  "a.out.js.gz": 8956,
   "a.out.nodebug.wasm": 172744,
   "a.out.nodebug.wasm.gz": 57379,
   "total": 195619,
-  "total_gz": 66338,
+  "total_gz": 66335,
   "sent": [
     "__cxa_begin_catch",
     "__cxa_end_catch",

test/codesize/test_codesize_cxx_except_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 19025,
-  "a.out.js.gz": 7906,
+  "a.out.js.gz": 7908,
   "a.out.nodebug.wasm": 148139,
   "a.out.nodebug.wasm.gz": 55264,
   "total": 167164,
-  "total_gz": 63170,
+  "total_gz": 63172,
   "sent": [
     "_abort_js",
     "_tzset_js",

test/codesize/test_codesize_cxx_except_wasm_legacy.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 19099,
-  "a.out.js.gz": 7926,
+  "a.out.js.gz": 7930,
   "a.out.nodebug.wasm": 145945,
   "a.out.nodebug.wasm.gz": 54892,
   "total": 165044,
-  "total_gz": 62818,
+  "total_gz": 62822,
   "sent": [
     "_abort_js",
     "_tzset_js",