@loopdive/js2 0.57.0

package/dist/cli.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, basename, dirname } from "node:path";
+function getCliVersion() {
+  const bundledVersion = typeof __JS2WASM_CLI_VERSION__ === "string" ? __JS2WASM_CLI_VERSION__ : void 0;
+  if (bundledVersion) return bundledVersion;
+  const require2 = createRequire(import.meta.url);
+  const pkg = require2("../package.json");
+  return pkg.version ?? "0.0.0";
+}
+const args = process.argv.slice(2);
+if (args.includes("--ts7")) {
+  process.env.JS2WASM_TS7 = "1";
+}
+const { compile } = await import("./index.js");
+const { buildDefaultDefines } = await import("./define-substitution-BcUeKC2A.js").then((n) => n.d);
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(getCliVersion());
+  process.exit(0);
+}
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  console.log(`Usage: js2wasm <input.ts> [options]
+
+Compile a TypeScript file to WebAssembly (GC proposal).
+
+Options:
+  -o, --out <dir>   Output directory (default: same as input)
+  --target <t>      Host/output target — the single host axis (#2736):
+                      web   (default) WasmGC / JS-host browser surface (DOM
+                            ambient globals in scope);
+                      node  a real Node host (Node ambient surface, no DOM);
+                      deno  a real Deno host (Deno ambient surface, no DOM);
+                      wasi  standalone WASI Preview 1 (fd-based host calls).
+                    Also accepts the backend-lowering names gc / linear /
+                    standalone (orthogonal backend choice; gc is the default
+                    backend for web/node/deno).
+  --standalone      Shorthand for --target standalone (pure WasmGC, no JS host,
+                    no WASI). Forces nativeStrings: true and refuses to emit
+                    wasm:js-string or env JS-host imports.
+  --allocator <a>   Linear backend allocator (#1856): bump (default,
+                    allocate-and-exit arena, smallest binary) or arena-reset
+                    (same arena + __arena_reset/__arena_used exports for hosts
+                    reusing one instance across short-lived tasks). Linear
+                    target only.
+  --allow-fs        Allow node:fs JS-host imports (readFileSync, writeFileSync)
+                    for non-WASI targets (#1491). Off by default to prevent
+                    accidental capability leakage.
+  --utf8-storage    Dual i8/i16 string storage (#1588): store strings proven
+                    UTF-8 (literals, JSON, decoder results, ...) as i8-backed
+                    Utf8String for a cheaper Component Model boundary. Implies
+                    nativeStrings on the WasmGC backend. Off by default
+                    (byte-identical output when off).
+  --wat             Emit only WAT (no binary)
+  --no-wat          Skip WAT output
+  --no-dts          Skip .d.ts output
+  --wit             Generate WIT interface file for Component Model
+  --wit-package <p> Package name for --wit output (ns:name[@version]).
+                    Implies --wit. Defaults to js2wasm:<input-basename>.
+  -v, --verbose     List every dropped host-import warning individually instead
+                    of collapsing them into a one-line summary (WASI/strict mode)
+  -O, --optimize    Run Binaryen wasm-opt optimizer (on by default at -O3)
+  -O1..-O4          Set optimization level (1-4)
+  --no-optimize, -O0
+                    Disable the optimizer; emit raw codegen output. Optimization
+                    is ON by default; this restores the pre-#1950 behaviour.
+                    (No-op when binaryen/wasm-opt is unavailable — that path
+                    already degrades to a one-line note, never a failure.)
+  --link-node-shims (WASI, #2625/#2633) Emit the per-module linkable node:<mod>
+                    shims instead of inlining the host APIs. Std-IO goes through
+                    node:fs: the module imports readSync/writeSync + its memory
+                    from node:fs (no wasi_snapshot_preview1 for stream IO) and
+                    links node-fs.wasm. console.log / process.std*.write lower to
+                    writeSync(1|2, …); stdin is readSync(0, …). Off by default —
+                    the inline fd_read/fd_write path is self-contained.
+  --emulate <env>   Emulate a host runtime's globals so they type-check without
+                    @types/node. 'node' = ambient process/etc.; 'none' = off.
+                    Auto-enabled (type-level only) when the source imports a
+                    'node:' builtin (use 'none' to disable that); otherwise off,
+                    and using process warns to add this flag (#2603).
+  --platform <p>    DEPRECATED (#2736): alias for --target {web,node,deno}.
+                    'web' = DOM globals (window/document/…) in scope (today's
+                    default); 'node'/'deno' = DOM globals NOT in scope (so
+                    window.stop is a type error) and Node-style API emulation on
+                    (implies --emulate node). Prefer --target; this prints a
+                    deprecation warning. Unset preserves today's behaviour.
+  --no-host-imports Strict dual-mode: reject JS-host 'env' imports not on
+                    the allowlist (#1524). Implied by --target wasi.
+  --allow-host-imports
+                    Escape hatch: disable strict dual-mode for a WASI build
+                    (debug-only). Useful when temporarily mixing host + WASI
+                    imports while migrating to standalone mode.
+  --define K=V      Substitute identifier path K with literal V before parsing.
+                    Repeatable. Example:
+                      --define process.env.NODE_ENV='"production"'
+                    String values must include their own quotes.
+  --mode <m>        Shorthand for --define-style production/development build.
+                    'production' sets process.env.NODE_ENV="production" and
+                    typeof process / typeof window to "undefined".
+                    'development' sets process.env.NODE_ENV="development".
+  --ts7             Use @typescript/native-preview (TypeScript 7 Go-port) as
+                    the parser/checker frontend (preview; full migration
+                    tracked in #1029). Equivalent to JS2WASM_TS7=1.
+  -q, --quiet       Suppress the post-compile "how to run" hint
+  -v, --version     Print version and exit
+  -h, --help        Show this help
+
+Output files:
+  <name>.wasm       WebAssembly binary
+  <name>.wat        WebAssembly text format
+  <name>.d.ts       TypeScript declarations
+  <name>.imports.js createImports() helper`);
+  process.exit(0);
+}
+let inputPath;
+let outDir;
+let emitWat = true;
+let emitDts = true;
+let watOnly = false;
+let verbose = false;
+let optimize = 3;
+let target;
+let allocator;
+let emitWit = false;
+let witPackageName;
+let allowFs = false;
+let quiet = false;
+let utf8Storage = false;
+let strictNoHostImports;
+let linkNodeShims = false;
+let emulateNode = false;
+let emulateExplicit = false;
+let platform;
+const defines = {};
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "-o" || arg === "--out") {
+    outDir = args[++i];
+  } else if (arg === "--target" || arg.startsWith("--target=")) {
+    const t = arg.startsWith("--target=") ? arg.slice("--target=".length) : args[++i];
+    if (t === "gc" || t === "linear" || t === "wasi" || t === "standalone") {
+      target = t;
+    } else if (t === "web" || t === "node" || t === "deno") {
+      platform = t;
+    } else {
+      console.error(`Unknown target: ${t} (expected web, node, deno, wasi, gc, linear, or standalone)`);
+      process.exit(1);
+    }
+  } else if (arg === "--standalone") {
+    target = "standalone";
+  } else if (arg === "--allocator") {
+    const a = args[++i];
+    if (a === "bump" || a === "arena-reset") {
+      allocator = a;
+    } else {
+      console.error(`Unknown allocator: ${a} (expected bump or arena-reset)`);
+      process.exit(1);
+    }
+  } else if (arg === "--wat") {
+    watOnly = true;
+  } else if (arg === "--no-wat") {
+    emitWat = false;
+  } else if (arg === "--no-dts") {
+    emitDts = false;
+  } else if (arg === "--wit") {
+    emitWit = true;
+  } else if (arg === "--wit-package") {
+    const pkg = args[++i];
+    if (!pkg) {
+      console.error("--wit-package requires a package name argument");
+      process.exit(1);
+    }
+    witPackageName = pkg;
+    emitWit = true;
+  } else if (arg.startsWith("--wit-package=")) {
+    const pkg = arg.slice("--wit-package=".length);
+    if (!pkg) {
+      console.error("--wit-package requires a package name argument");
+      process.exit(1);
+    }
+    witPackageName = pkg;
+    emitWit = true;
+  } else if (arg === "--allow-fs") {
+    allowFs = true;
+  } else if (arg === "--quiet" || arg === "-q") {
+    quiet = true;
+  } else if (arg === "--utf8-storage") {
+    utf8Storage = true;
+  } else if (arg === "--link-node-shims") {
+    linkNodeShims = true;
+  } else if (arg === "--emulate" || arg.startsWith("--emulate=")) {
+    const env = arg.startsWith("--emulate=") ? arg.slice("--emulate=".length) : args[++i];
+    if (env === "node") {
+      emulateNode = true;
+      emulateExplicit = true;
+    } else if (env === "none") {
+      emulateNode = false;
+      emulateExplicit = true;
+    } else {
+      console.error(`Unknown --emulate value: ${env ?? "(missing)"} (expected: node | none)`);
+      process.exit(1);
+    }
+  } else if (arg === "--platform" || arg.startsWith("--platform=")) {
+    const p = arg.startsWith("--platform=") ? arg.slice("--platform=".length) : args[++i];
+    if (p === "node" || p === "web" || p === "deno") {
+      platform = p;
+      console.error(`warning: --platform is deprecated; use --target ${p} instead.`);
+    } else {
+      console.error(`Unknown --platform value: ${p ?? "(missing)"} (expected: node | web | deno)`);
+      process.exit(1);
+    }
+  } else if (arg === "--no-host-imports") {
+    strictNoHostImports = true;
+  } else if (arg === "--allow-host-imports") {
+    strictNoHostImports = false;
+  } else if (arg === "--verbose" || arg === "-v") {
+    verbose = true;
+  } else if (arg === "-O" || arg === "--optimize") {
+    optimize = true;
+  } else if (arg === "--no-optimize" || arg === "-O0") {
+    optimize = false;
+  } else if (/^-O[1-4]$/.test(arg)) {
+    optimize = parseInt(arg.slice(2));
+  } else if (arg === "--define") {
+    const kv = args[++i];
+    if (!kv) {
+      console.error("--define requires a KEY=VALUE argument");
+      process.exit(1);
+    }
+    const eq = kv.indexOf("=");
+    if (eq < 0) {
+      console.error(`--define expected KEY=VALUE, got: ${kv}`);
+      process.exit(1);
+    }
+    defines[kv.slice(0, eq)] = kv.slice(eq + 1);
+  } else if (arg.startsWith("--define=")) {
+    const kv = arg.slice("--define=".length);
+    const eq = kv.indexOf("=");
+    if (eq < 0) {
+      console.error(`--define expected KEY=VALUE, got: ${kv}`);
+      process.exit(1);
+    }
+    defines[kv.slice(0, eq)] = kv.slice(eq + 1);
+  } else if (arg === "--mode") {
+    const m = args[++i];
+    if (m !== "production" && m !== "development") {
+      console.error(`Unknown --mode: ${m} (expected production or development)`);
+      process.exit(1);
+    }
+    Object.assign(defines, buildDefaultDefines(m));
+  } else if (arg === "--ts7") ;
+  else if (!arg.startsWith("-")) {
+    inputPath = arg;
+  } else {
+    console.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  }
+}
+if (!inputPath) {
+  console.error("Error: no input file specified");
+  process.exit(1);
+}
+if (target === "standalone" && allowFs) {
+  console.error("error: --standalone and --allow-fs are mutually exclusive");
+  process.exit(1);
+}
+if (allocator !== void 0 && target !== "linear") {
+  console.error("error: --allocator requires --target linear");
+  process.exit(1);
+}
+const absInput = resolve(inputPath);
+const source = readFileSync(absInput, "utf-8");
+if (!emulateExplicit && !emulateNode && /['"]node:[A-Za-z0-9_./-]+['"]/.test(source)) {
+  emulateNode = true;
+  console.error("note: auto-enabled Node API emulation (found a `node:` import). Pass --emulate none to disable.");
+}
+const name = basename(absInput, ".ts");
+const dir = outDir ? resolve(outDir) : dirname(absInput);
+const result = await compile(source, {
+  ...optimize ? { optimize } : {},
+  ...target ? { target } : {},
+  ...allocator ? { allocator } : {},
+  ...emitWit ? { wit: witPackageName ? { packageName: witPackageName } : true } : {},
+  ...allowFs ? { allowFs: true } : {},
+  ...utf8Storage ? { utf8Storage: true } : {},
+  ...linkNodeShims ? { linkNodeShims: true } : {},
+  ...emulateNode ? { emulateNode: true } : {},
+  ...platform ? { platform } : {},
+  fileName: absInput,
+  ...strictNoHostImports !== void 0 ? { strictNoHostImports } : {},
+  ...Object.keys(defines).length > 0 ? { define: defines } : {}
+});
+if (!result.success) {
+  for (const e of result.errors) {
+    const severity = e.severity === "warning" ? "warning" : "error";
+    const where = e.file ?? absInput;
+    console.error(`${where}:${e.line}:${e.column} - ${severity}: ${e.message}`);
+  }
+  process.exit(1);
+}
+const isAllowlistWarning = (msg) => msg.includes("not on the dual-mode allowlist");
+let suppressedAllowlist = 0;
+const warnCounts = /* @__PURE__ */ new Map();
+for (const e of result.errors) {
+  if (e.severity !== "warning") continue;
+  if (!verbose && isAllowlistWarning(e.message)) {
+    suppressedAllowlist++;
+    continue;
+  }
+  warnCounts.set(e.message, (warnCounts.get(e.message) ?? 0) + 1);
+}
+for (const [msg, count] of warnCounts) {
+  console.error(count > 1 ? `warning: ${msg} (${count}×)` : `warning: ${msg}`);
+}
+if (suppressedAllowlist > 0) {
+  console.error(
+    `warning: ${suppressedAllowlist} host import(s) not on the dual-mode allowlist were dropped (no-op under WASI/strict mode; not in the emitted .wasm). Re-run with --verbose to list them.`
+  );
+}
+if (watOnly) {
+  process.stdout.write(result.wat);
+  process.exit(0);
+}
+let emittedWasmPath;
+{
+  const wasmPath = resolve(dir, `${name}.wasm`);
+  writeFileSync(wasmPath, result.binary);
+  console.log(`${wasmPath}  (${result.binary.byteLength} bytes)`);
+  emittedWasmPath = wasmPath;
+}
+if (emitWat) {
+  const watPath = resolve(dir, `${name}.wat`);
+  writeFileSync(watPath, result.wat);
+  console.log(`${watPath}  (${result.wat.length} chars)`);
+}
+if (emitDts) {
+  const dtsPath = resolve(dir, `${name}.d.ts`);
+  writeFileSync(dtsPath, result.dts);
+  console.log(`${dtsPath}  (${result.dts.length} chars)`);
+}
+{
+  const helperPath = resolve(dir, `${name}.imports.js`);
+  writeFileSync(helperPath, result.importsHelper);
+  console.log(`${helperPath}  (${result.importsHelper.length} chars)`);
+}
+if (emitWit && result.wit) {
+  const witPath = resolve(dir, `${name}.wit`);
+  writeFileSync(witPath, result.wit);
+  console.log(`${witPath}  (${result.wit.length} chars)`);
+}
+if (!quiet && emittedWasmPath) {
+  if (target === "wasi" || target === "standalone" || target === "linear") {
+    console.log(`
+To run: wasmtime -W gc=y,function-references=y,tail-call=y,exceptions=y ${emittedWasmPath}`);
+  } else {
+    console.log(
+      `
+This is a JS-host build (default --target gc) — it needs the generated ${name}.imports.js helper. To run with Node.js:
+  node --experimental-wasm-imported-strings -e "import('./${name}.imports.js').then(async ({ createImports }) => { const { instance } = await WebAssembly.instantiate(require('fs').readFileSync('${emittedWasmPath}'), createImports()); /* call instance.exports.* */ })"
+For a pure-Wasm build runnable under Wasmtime, recompile with --standalone.`
+    );
+  }
+}

package/dist/codegen/accessor-driver.d.ts

@@ -0,0 +1,97 @@
+import { CodegenContext } from './context/types.js';
+/** Reserved name for the accessor-get driver (arity-0 getter wrapper). */
+export declare const CALL_ACCESSOR_GET = "__call_accessor_get";
+/** Reserved name for the accessor-set driver (arity-1 setter wrapper). */
+export declare const CALL_ACCESSOR_SET = "__call_accessor_set";
+/**
+ * (#2166 PR-D1) Reserved name for the JSON reviver driver (arity-2 method
+ * wrapper: `reviver.call(holder, key, value)`).
+ */
+export declare const CALL_REVIVER = "__call_reviver";
+/**
+ * (#2166 PR-D2) Reserved name for the JSON `toJSON` driver (arity-1 method
+ * wrapper: `value.toJSON(key)`).
+ */
+export declare const CALL_TO_JSON = "__call_to_json";
+/**
+ * (#2166 PR-D3) Reserved name for the JSON `stringify` replacer driver (arity-2
+ * method wrapper: `replacer.call(holder, key, value)`).
+ */
+export declare const CALL_REPLACER = "__call_replacer";
+/**
+ * Reserve the `__call_accessor_get` driver placeholder and return its funcIdx.
+ *
+ * Signature: `(externref recv, externref getter) -> externref`.
+ * The body is left as a bare `unreachable` and filled by `fillAccessorDrivers`
+ * in post-processing. The reservation must run while `ensureObjectRuntime` is
+ * emitting `__extern_get`, so the append-position funcIdx is stable before any
+ * accessor arm emits its `call`.
+ *
+ * Idempotent: a second call returns the already-reserved funcIdx.
+ */
+export declare function reserveAccessorGetDriver(ctx: CodegenContext): number;
+/**
+ * Reserve the `__call_accessor_set` driver placeholder and return its funcIdx.
+ *
+ * Signature: `(externref recv, externref setter, externref value) -> ()`.
+ * Setters return no value (the assignment expression result is the RHS, handled
+ * at the call site), so the driver result type is empty. Body filled by
+ * `fillAccessorDrivers`. Idempotent.
+ */
+export declare function reserveAccessorSetDriver(ctx: CodegenContext): number;
+/**
+ * (#2166 PR-D1) Reserve the `__call_reviver` driver placeholder and return its
+ * funcIdx.
+ *
+ * Signature: `(externref holder, externref key, externref value) -> externref`.
+ * Filled by `fillAccessorDrivers` to wrap `__call_fn_method_2(holder, reviver,
+ * key, value)` — but note the reviver closure itself is NOT a driver param: the
+ * §25.5.1 walk threads it separately and the driver receives `holder` as the
+ * `this` and `key`/`value` as the two reviver args, with the reviver closure
+ * passed as the dispatcher's 2nd operand by the codec via a 4th hidden param.
+ * To keep the driver arity fixed we instead make the reviver the FIRST arg and
+ * holder the receiver: see `fillAccessorDrivers`. Idempotent.
+ */
+export declare function reserveReviverDriver(ctx: CodegenContext): number;
+/**
+ * (#2166 PR-D2) Reserve the `__call_to_json` driver placeholder and return its
+ * funcIdx.
+ *
+ * Signature: `(externref value, externref method, externref key) -> externref`.
+ * Filled by `fillAccessorDrivers` to wrap `__call_fn_method_1(value, method,
+ * key)` — `value` bound as the `toJSON` receiver (`this`), `key` the §25.5.2
+ * SerializeJSONProperty step-2.b argument. Idempotent.
+ */
+export declare function reserveToJsonDriver(ctx: CodegenContext): number;
+/**
+ * (#2166 PR-D3) Reserve the `__call_replacer` driver placeholder and return its
+ * funcIdx.
+ *
+ * Signature: `(externref holder, externref replacer, externref key,
+ * externref value) -> externref`. The replacer function is invoked as
+ * `replacer.call(holder, key, value)` (§25.5.2 SerializeJSONProperty step 3),
+ * so `holder` binds as `this` and `key`/`value` are the two arguments — exactly
+ * the reviver driver's shape. Filled by `fillAccessorDrivers` wrapping
+ * `__call_fn_method_2`. Idempotent.
+ */
+export declare function reserveReplacerDriver(ctx: CodegenContext): number;
+/**
+ * Fill the reserved accessor driver bodies in post-processing, AFTER
+ * `emitClosureMethodCallExportN(0)` / `(1)` have registered
+ * `__call_fn_method_0` / `__call_fn_method_1` in `funcMap`. Each driver is a
+ * thin wrapper that forwards to the matching closure-method dispatcher, reusing
+ * the proven re-entrancy-safe `__current_this` install/restore (#1636-S1)
+ * instead of duplicating funcref-type dispatch inside the object runtime:
+ *
+ *   __call_accessor_get(recv, getter) = return __call_fn_method_0(recv, getter)
+ *   __call_accessor_set(recv, setter, value) =
+ *       __call_fn_method_1(recv, setter, value)  ; drop result
+ *
+ * No-op when the corresponding driver was never reserved (no accessor arm
+ * needs it). When the driver WAS reserved but the matching dispatcher was never
+ * emitted (no closure of that arity exists — so no real getter/setter closure
+ * could have been installed either), the body is filled with a valid fallback
+ * (return-undefined for get; bare return for set) so the module still verifies —
+ * mirrors `fillProtoIteratorDriver`'s null fallback.
+ */
+export declare function fillAccessorDrivers(ctx: CodegenContext): void;

package/dist/codegen/any-helpers.d.ts

@@ -0,0 +1,72 @@
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Register the $AnyValue struct type for boxing `any` typed values.
+ * The struct has a tag field to distinguish the boxed type at runtime,
+ * plus payload fields for each possible value kind.
+ *
+ * Called lazily — only emitted when the module actually uses `any`-typed values.
+ */
+export declare function ensureAnyValueType(ctx: CodegenContext): void;
+/**
+ * (#2106 S1.0) Push the standalone `$undefined` singleton (a `ref $AnyValue`,
+ * tag 1) onto the stack. Returns `false` (emitting nothing) when not in
+ * standalone/native-strings mode or the singleton was not reserved — callers
+ * then fall back to their existing `ref.null.extern` / host-`__get_undefined`
+ * path. INERT until S1.1 routes `emitUndefined` here.
+ */
+export declare function emitUndefinedSingleton(ctx: CodegenContext, fctx: FunctionContext): boolean;
+/**
+ * (#2106 S1.0) Test whether the `ref $AnyValue` on top of the stack is the
+ * `$undefined` singleton (tag === 1). Consumes the ref, leaves an i32. Returns
+ * `false` (emitting nothing) when the singleton is unavailable. INERT until S1.1
+ * routes the `=== undefined` / `typeof === "undefined"` consumers here.
+ */
+export declare function emitIsUndefinedSingleton(ctx: CodegenContext, fctx: FunctionContext): boolean;
+/**
+ * Lazily register wrapper struct types for Number, String, Boolean.
+ * Each wrapper is a struct with a single `value` field holding the primitive.
+ * Also registers WrapperX_valueOf functions that extract the value.
+ * Must be called before resolveWasmType is used for wrapper types.
+ */
+export declare function ensureWrapperTypes(ctx: CodegenContext): void;
+/**
+ * Emit valueOf helper functions for wrapper types.
+ * Must be called after all imports are registered (so function indices are stable)
+ * but before user functions that call valueOf.
+ */
+export declare function emitWrapperValueOfFunctions(ctx: CodegenContext): void;
+/**
+ * Check if a ValType represents a boxed `any` value (ref $AnyValue).
+ */
+export declare function isAnyValue(type: ValType, ctx: CodegenContext): boolean;
+export declare function ensureAnyFromExternHelper(ctx: CodegenContext): number | undefined;
+/**
+ * (#1461/#54) Native standalone `(externref, externref) -> i32` strict-equality
+ * (`===`, StrictEqualityComparison) over two boxed externref values. The pure-Wasm
+ * replacement for the `__host_eq` host import in the array-like search arm
+ * (`indexOf`/`lastIndexOf`). Composes the two existing engine-owned helpers:
+ * `__any_from_extern` (recovers a boxed externref primitive — number/boolean/
+ * string/null/object — into a uniform `(ref $AnyValue)`) then `__any_strict_eq`
+ * (===-compares two `$AnyValue`, numeric class unified via `f64.eq` ⇒ NaN≠NaN,
+ * strings by content, objects by identity). Standalone-only; returns undefined
+ * otherwise (caller keeps the host import).
+ */
+export declare function ensureExternStrictEqHelper(ctx: CodegenContext): number | undefined;
+/**
+ * (#1461/#54) Native standalone `(externref, externref) -> i32` SameValueZero
+ * (§7.2.11) over two boxed externref values — the pure-Wasm replacement for the
+ * `__same_value_zero` host import in the array-like `includes` search arm.
+ * SameValueZero differs from `===` ONLY in `NaN`: SameValueZero(NaN, NaN) is
+ * true (and +0/−0 are equal under both, which `f64.eq` already gives). So:
+ * `__extern_strict_eq(a, b) || (a and b are both NaN numbers)`. The NaN test
+ * recovers both via `__any_from_extern`, checks tag ∈ {2,3} (number) and the
+ * f64 self-inequality (`x !== x`).
+ */
+export declare function ensureExternSameValueZeroHelper(ctx: CodegenContext): number | undefined;
+export declare function ensureAnyToExternHelper(ctx: CodegenContext): number | undefined;
+/**
+ * Emit inline wasm helper functions for boxing/unboxing `any` values.
+ * Called lazily when any-typed operations are first encountered.
+ */
+export declare function ensureAnyHelpers(ctx: CodegenContext): void;

package/dist/codegen/array-element-typing.d.ts

@@ -0,0 +1,46 @@
+import { ts } from '../ts-api.js';
+/**
+ * Return true if `expr` provably produces a 32-bit signed integer at runtime,
+ * given that `i32Locals` is the set of locals already known to hold i32.
+ *
+ * Recognised i32-safe forms (mirrors `isI32SafeExpr` in function-body.ts but
+ * is intentionally narrower — we err on the side of disqualification):
+ *   - integer numeric literal in [-2^31, 2^31)
+ *   - identifier referencing a known-i32 local
+ *   - bitwise `|`, `&`, `^`, `<<`, `>>` (always produce int32 per ECMAScript)
+ *   - comparison ops (return boolean = i32)
+ *   - unary `+` / `-` / `~` of an i32-safe operand
+ *   - `+` / `-` / `*` of two i32-safe operands (overflow wraps; receiver is i32)
+ *   - parenthesised / `as`-cast / non-null-asserted i32-safe expr
+ *
+ * Note: `>>>` is intentionally excluded — it produces uint32 which can sit
+ * above 2^31 and would be reinterpreted as a negative i32 on store. The
+ * conservative choice is to disqualify (the array would then stay f64).
+ */
+export declare function isI32SafeExprForArray(expr: ts.Expression | undefined, i32Locals: ReadonlySet<string>, depth?: number): boolean;
+/**
+ * Compute the set of `let arr: number[] = []`-style locals in `decl` whose
+ * element storage can safely lower to `i32` instead of `f64`.
+ *
+ * Pre-conditions for promotion (all must hold):
+ *   1. The declaration has an explicit `number[]` (or `Array<number>`) type
+ *      annotation. Without the annotation, downstream codegen still picks
+ *      f64 from the contextual type and the override would not flow to the
+ *      assignment-site `compileExpression(value, arrDef.element)` path.
+ *   2. The initializer is `[]`, `new Array(n?)`, or `Array(n?)`.
+ *   3. The local is not captured in any nested function (closures break
+ *      cross-scope type assumptions, exactly as for #1120 scalar locals).
+ *   4. The local is never used outside whitelisted positions:
+ *        - `arr[i]` (read)            (parent: ElementAccessExpression as receiver)
+ *        - `arr[i] = E`                (parent of `arr` is the LHS access)
+ *        - `arr.length`               (PropertyAccessExpression as receiver)
+ *        - `arr.push(E)` / `arr[i]++` / etc. — only `arr.push(E)` is allowed,
+ *          and only when E is i32-safe. All other method calls disqualify.
+ *   5. Every `arr[i] = E` has E i32-safe per `isI32SafeExprForArray`.
+ *   6. The local is never the LHS of a plain assignment (`arr = ...` after
+ *      the declaration) — the candidate-collection step already restricts
+ *      to let/const, but a single-let `let arr: number[]` could still be
+ *      reassigned. We catch this in the use scan because a bare identifier
+ *      reference on the LHS of `=` is not in the whitelist.
+ */
+export declare function collectI32SpecializedArrays(decl: ts.FunctionLikeDeclaration, i32CoercedLocals: ReadonlySet<string>): Set<string>;

package/dist/codegen/array-holes.d.ts

@@ -0,0 +1,69 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { Instr } from '../ir/types.js';
+/**
+ * Cheap AST pre-scan: set `ctx.usesArrayHoles` when the program contains any
+ * array-literal elision (`OmittedExpression`). Runs once before body
+ * compilation (mirrors `scanForNewTarget`). When clear — the common case — the
+ * hole read-guard is never emitted and every array read stays byte-identical.
+ *
+ * Setting the flag in a pre-pass (rather than lazily at the first hole-store)
+ * is what lets a `a[i]` element *read* in one function emit the `$Hole → undefined`
+ * guard even though the hole-bearing literal lives in a *different* function
+ * compiled later — function compilation order is not source order, so a per-site
+ * lazy flag would desync reads against stores.
+ */
+export declare function scanForArrayHoles(ctx: CodegenContext, root: ts.Node): void;
+/**
+ * Lazily register the `$Hole` struct type and the `$__hole` singleton global.
+ * Idempotent — returns the absolute global index, caches both the type index
+ * (`ctx.holeTypeIdx`) and the global index (`ctx.holeGlobalIdx`).
+ *
+ * Registered **late** (during body compilation, after class collection) and
+ * **once**, per `project_type_index_shift_and_deadelim`: pushing a struct type
+ * mid-class-collection would desync class struct typeidxs. Both call sites
+ * (literal store + element read) run inside `compileDeclarations`, so the type
+ * is always appended after the class struct types are fixed.
+ *
+ * The global is **immutable** with a constant `struct.new $Hole` initializer —
+ * a valid WasmGC constant init expression for a zero-field immutable struct, so
+ * `$Hole`'s ref identity is fixed at instantiation and every `global.get`
+ * yields the same ref (required for `ref.test`/`ref.eq` identity). A const init
+ * never contains a `call`, so it is immune to late-import index shifts.
+ */
+export declare function ensureHoleType(ctx: CodegenContext): number;
+/**
+ * Push the `$Hole` sentinel as an `externref`, ready to store into an
+ * externref-element vec slot (`array.new_fixed` / `array.set`).
+ * Stack: `[] → [externref]`.
+ */
+export declare function emitHoleSentinel(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Read-boundary mapping: if the externref on the stack is the `$Hole` sentinel,
+ * replace it with `undefined`; otherwise leave it unchanged.
+ * Stack: `[externref] → [externref]`.
+ *
+ * The single most important correctness rule for sparse arrays — the sentinel
+ * must never leak past a value-producing read. Reusable across S1 (element read,
+ * join) and the later HOF / destructuring slices.
+ */
+export declare function emitHoleToUndefined(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Detached-`Instr[]` form of {@link emitHoleToUndefined}, for call sites that
+ * assemble a callback-arg / loop-body instruction list off `fctx.body` (e.g.
+ * `buildClosureCallInstrs`). Allocates the scratch temp via `fctx` and resolves
+ * the `undefined` value up front (flushing any late-import shift into the
+ * current body BEFORE the funcIdx is baked into the returned instrs), so the
+ * sequence can be spliced anywhere. Stack: `[externref] → [externref]`.
+ */
+export declare function holeToUndefinedInstrs(ctx: CodegenContext, fctx: FunctionContext): Instr[];
+/**
+ * Instruction list form of the hole test for the array-join fold, where the
+ * element-to-string conversion is assembled as a detached `Instr[]` (not pushed
+ * onto `fctx.body`). Given the element `externref` already on the (virtual)
+ * stack, returns instrs that leave `i32` = 1 iff the element is `$Hole`.
+ * Caller wraps `whenHole` / `whenPresent` in the `if`. Registers `$Hole` on
+ * demand (caller gates on `usesArrayHoles`), so the `ref.test` typeidx is valid
+ * even if no hole-literal has been compiled yet in this module.
+ */
+export declare function holeTestInstrs(ctx: CodegenContext): Instr[];