@loopdive/js2 0.57.0

package/dist/codegen/expressions/calls.d.ts

@@ -0,0 +1,83 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+import { InnerResult } from '../shared.js';
+import { compileOptionalCallExpression } from './calls-optional.js';
+/**
+ * #2580 M3 Stage A — compile a `[[Prototype]]` argument (the proto operand of
+ * `Object.create(proto)` / `Object.setPrototypeOf(obj, proto)`) so that an
+ * INLINE OBJECT LITERAL proto is built as a native `$Object`, pushing an
+ * externref onto the stack.
+ *
+ * Root cause (standalone): the native `__object_create` / `__object_setPrototypeOf`
+ * helpers write the link field `$Object.$proto` only when the proto value
+ * `ref.test $Object` succeeds (a non-`$Object` externref coerces to null, by
+ * design — see object-runtime.ts `__object_create`/`__object_setPrototypeOf`).
+ * `compileObjectLiteral` lowers an inline literal whose TS contextual type is a
+ * CONCRETE object type (not `any`) to a CLOSED-shape struct (`struct.new <typeIdx>`),
+ * which fails `ref.test $Object`. So `Object.create({foo:7}).foo` and
+ * `Object.setPrototypeOf(o,{foo:7}); o.foo` silently lose the proto link (the
+ * chain walk reads a null `$proto` → property absent → 0). A proto passed via a
+ * `const p:any = {foo:7}` *named variable* already works because the `any`
+ * annotation diverts that literal to the open-`$Object` builder (literals.ts).
+ *
+ * Fix mirrors the merged #2076 `compileObjectAssignArg` precedent: when the proto
+ * is a plain data-property / spread object literal (the same shapes the `$Object`
+ * builder accepts), build it directly as a native `$Object` via
+ * `compileObjectLiteralAsExternref` so `ref.test $Object` succeeds and the link
+ * is recorded. Any other proto expression (identifiers, calls, `null`,
+ * `Foo.prototype`, accessor-bearing literals) keeps the ordinary
+ * `compileExpression` path unchanged. Standalone-only — host/GC mode owns the
+ * `__object_create` JS import and a separate (still-broken, tracked) proto-link
+ * mechanism, untouched here.
+ */
+export declare function compileProtoArg(ctx: CodegenContext, fctx: FunctionContext, arg: ts.Expression): void;
+/**
+ * (#1397) Emit a dynamic-dispatch method call on a wrapper-object receiver:
+ *
+ *   __extern_method_call(receiver, methodName, [])
+ *
+ * Used by the wrapper-reassignment branch at the top of compileMethodCall
+ * to bypass the static fast-paths when source has reassigned the method.
+ * Returns the result type (externref) on success, null if the necessary
+ * runtime imports cannot be registered (caller falls through to the
+ * static path as a best-effort fallback).
+ */
+export declare function emitWrapperDynamicMethodCall(ctx: CodegenContext, fctx: FunctionContext, recvExpr: ts.Expression, methodName: string, callExpr?: ts.CallExpression): ValType | null;
+/**
+ * Reset the __argc and __extras_argv globals to their sentinel values
+ * (-1 / null). Used after closure / indirect call paths where we set the
+ * globals unconditionally but can't be sure the callee consumed them
+ * (its prologue only consumes when the body reads `arguments`). Without
+ * cleanup, a subsequent function that does read `arguments` would
+ * inherit a stale extras_argv and produce a wrong arguments.length.
+ * (#1511)
+ */
+export declare function emitResetArgcExtras(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * For indirect (closure / call_ref) call paths where the callee is not
+ * statically known, set `__argc` and (if there are overflow args) build
+ * `__extras_argv` from the call-site args beyond `paramCount`. The
+ * lifted callee's prologue reads these to compute `arguments.length`
+ * correctly even when more args were passed than the lifted function's
+ * formal signature accepts.
+ *
+ * Must be called AFTER the formal args have been compiled / pushed onto
+ * the stack (or saved to locals), but BEFORE the call_ref. Pair with
+ * `emitResetArgcExtras` after the call to prevent stale-extras leaking
+ * into a subsequent callee that DOES read `arguments`. (#1511)
+ */
+export declare function emitClosureCallArgcExtras(ctx: CodegenContext, fctx: FunctionContext, args: readonly ts.Expression[], paramCount: number): void;
+declare function compileCallExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression, expectedType?: ValType): InnerResult;
+/**
+ * Compile an IIFE (Immediately Invoked Function Expression):
+ *   (function(params) { body })(args)
+ *
+ * Strategy: compile the function expression as a named module-level function
+ * with a unique synthetic name, then emit a direct call to it.
+ * Captures from the enclosing scope are passed as extra leading parameters.
+ *
+ * Returns undefined if the expression is not an IIFE pattern.
+ */
+declare function compileIIFE(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;
+export { compileCallExpression, compileIIFE, compileOptionalCallExpression };

package/dist/codegen/expressions/eval-inline.d.ts

@@ -0,0 +1,24 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+import { InnerResult } from '../shared.js';
+/**
+ * Recursively resolve a compile-time-constant string from an expression.
+ * Returns the string value, or null if the expression is not a constant.
+ */
+export declare function resolveConstantString(expr: ts.Expression): string | null;
+/**
+ * Try to inline `eval("<constant>")` at compile time.
+ *
+ * Returns:
+ *   - InnerResult (ValType or null) on success — caller treats this as the
+ *     compiled call result and does NOT invoke the dynamic-eval fallback.
+ *   - undefined if the call is not eligible (non-literal arg, parse errors,
+ *     etc.) — caller should fall through to the dynamic-eval path.
+ *
+ * On success we always push a single externref value onto the stack (the
+ * result of the inlined script, coerced to externref to match eval's `any`
+ * return type).  When the inlined code is statically unreachable (the last
+ * statement is a throw, etc.) we return `null` so the caller knows no value
+ * was produced.
+ */
+export declare function tryStaticEvalInline(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;

package/dist/codegen/expressions/extern.d.ts

@@ -0,0 +1,67 @@
+import { ts } from '../../ts-api.js';
+import { Instr, ValType } from '../../ir/types.js';
+import { CodegenContext, ExternClassInfo, FunctionContext, RestParamInfo } from '../context/types.js';
+import { InnerResult } from '../shared.js';
+export declare function findExternInfoForMember(ctx: CodegenContext, className: string, memberName: string, kind: "method" | "property"): ExternClassInfo | null;
+declare function compileExternMethodCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;
+/**
+ * Emit a lazy-initialized prototype global access.
+ * On first access, creates a struct instance with default values and stores it
+ * as externref in the global. Subsequent accesses return the same instance.
+ * This gives reference identity for ClassName.prototype === Object.getPrototypeOf(instance).
+ */
+export declare function emitLazyProtoGet(ctx: CodegenContext, fctx: FunctionContext, className: string): boolean;
+/**
+ * (#1395) Emit a lazy-initialized class-object global access. Mirrors
+ * `emitLazyProtoGet` above but for the class identifier itself (not its
+ * prototype). On first access, creates a `$ClassName` struct with default
+ * field values and registers static method names with the runtime's
+ * `_staticMethodNames` allowlist via `__register_class_object`. Subsequent
+ * accesses return the same instance, giving reference identity for
+ * `C === C`.
+ *
+ * Returns `true` if a class-object global was emitted, `false` if no global
+ * was registered for this class (e.g. externref-backed builtin subclasses
+ * from #1366a).
+ */
+export declare function emitLazyClassObjectGet(ctx: CodegenContext, fctx: FunctionContext, className: string): boolean;
+/**
+ * After dynamically adding a field to a struct type, patch all existing
+ * struct.new instructions in compiled function bodies so they push a default
+ * value for the new field. Without this, struct.new expects N values on the
+ * stack but the constructor only pushed N-1.
+ */
+declare function patchStructNewForDynamicField(ctx: CodegenContext, structTypeIdx: number, newFieldType: ValType): void;
+/** Recursively patch struct.new instructions in a body (handles nested if/block/loop). */
+declare function patchStructNewInBody(body: Instr[], structTypeIdx: number, newFieldType: ValType): void;
+/** Return instructions that produce a default value for a given type. */
+declare function defaultValueInstrForType(type: ValType): Instr[];
+/**
+ * Emit a null-guarded struct.get: if the object ref on the stack is null (e.g.
+ * from a failed ref.cast that returned ref.null), produce a default value
+ * instead of trapping. This handles wrong-type-but-not-truly-null cases. If the
+ * source value is truly null/undefined, the TypeError is thrown on the
+ * externref __extern_get path instead.
+ * push a default value instead of trapping.
+ *
+ * Expects the object ref to be on the Wasm stack. Emits:
+ *   local.tee $tmp
+ *   ref.is_null
+ *   if (result fieldType)
+ *     <default_value>
+ *   else
+ *     local.get $tmp
+ *     struct.get typeIdx fieldIdx
+ *   end
+ *
+ * Returns the field's ValType.
+ */
+/**
+ * Emit instructions that throw a TypeError via the Wasm exception tag.
+ * Pushes a null externref as the exception payload and then emits `throw`.
+ * This is used for null/undefined property access, calling non-functions, etc.
+ *
+ * Returns an array of instructions (for use inside if-then blocks).
+ */
+declare function compileSpreadCallArgs(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression, funcIdx: number, restInfo: RestParamInfo | undefined): void;
+export { compileExternMethodCall, compileSpreadCallArgs, defaultValueInstrForType, patchStructNewForDynamicField, patchStructNewInBody, };

package/dist/codegen/expressions/fnctor-prototype.d.ts

@@ -0,0 +1,52 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * Resolve a property-access/assignment receiver to a user-fnctor key (the
+ * resolved symbol name), or `undefined` when it is not a user function
+ * constructor. Mirrors the recognition `analyzeFnctorEscapeGate` /
+ * `compileNewFunctionDeclaration` use, so the read/write key agrees with the
+ * `new F()` lowering. Classes, builtins, arrows, and non-identifier receivers
+ * return `undefined`.
+ */
+export declare function resolveUserFnctorName(ctx: CodegenContext, expr: ts.Expression): string | undefined;
+/**
+ * True when `target` is a `F.prototype = …` (whole reassign) or `F.prototype.p =
+ * …` (per-prop) assignment LHS for a user function constructor `F`. Used by the
+ * module-init collection (declarations.ts) to KEEP such a top-level statement in
+ * `__module_init`: its root identifier `F` is a function (not a module global),
+ * so the generic "assignment to a module global" check drops it, and the write
+ * never reaches `compilePropertyAssignment`/the S2 interception. Mirrors the
+ * `Array.prototype` CPR keep-in-init case. Element-access (`F.prototype[i]=v`) is
+ * not matched (the S2 cluster uses whole-literal / named-prop writes).
+ */
+export declare function isFnctorPrototypeAssignTarget(ctx: CodegenContext, target: ts.Expression): boolean;
+/**
+ * Emit the lazy-initialized prototype `$Object` get: `if (g == null) g =
+ * __new_plain_object(); return g`. Leaves an externref (`$Object`) on the stack.
+ * Returns false (emitting nothing) when `__new_plain_object` is unavailable, so
+ * the caller declines and falls through to the legacy path.
+ *
+ * Exported for #2660 S3: the `new F()` reconstruct lowering (new-super.ts) seeds
+ * the instance's `$proto` from this SAME per-fnctor prototype `$Object`, so the
+ * inherited-read walk and the `F.prototype` read/write share ONE link location
+ * (`$Object.$proto`) and ONE object identity (`Object.getPrototypeOf(new F()) ===
+ * F.prototype`). The lazy-init guarantees the proto is always a real `$Object`
+ * even when `F.prototype` was never explicitly assigned.
+ */
+export declare function emitFnctorProtoGet(ctx: CodegenContext, fctx: FunctionContext, fnctorName: string): boolean;
+/**
+ * READ interception for `F.prototype` (F a user fnctor, standalone). Returns the
+ * per-fnctor prototype `$Object` as an externref, or `undefined` to decline (the
+ * caller continues its normal dispatch).
+ */
+export declare function tryEmitFnctorPrototypeRead(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression, propName: string): ValType | undefined;
+/**
+ * WHOLE-REASSIGN interception for `F.prototype = rhs` (F a user fnctor,
+ * standalone). Builds `rhs` as a native `$Object` (plain object literal) or an
+ * externref, stores it into the per-fnctor prototype global, and leaves the
+ * assigned value on the stack (assignment-expression semantics). Returns
+ * `undefined` to decline. Per-prop writes (`F.prototype.p = v`) are NOT handled
+ * here — they ride the READ interception above.
+ */
+export declare function tryCompileFnctorPrototypeAssign(ctx: CodegenContext, fctx: FunctionContext, target: ts.PropertyAccessExpression, value: ts.Expression): ValType | undefined;

package/dist/codegen/expressions/helpers.d.ts

@@ -0,0 +1,212 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * #1473 — No-JS-host predicate. Both `--target wasi` and `--target standalone`
+ * run without a JS runtime, so neither can rely on host imports such as
+ * `__throw_type_error` / `__new_TypeError` resolving to JS constructors. In
+ * these modes the compiler emits Wasm-native Error constructors instead.
+ */
+export declare function noJsHost(ctx: CodegenContext): boolean;
+/**
+ * Emit a Wasm throw instruction with a string error message.
+ * This replaces `unreachable` traps so that JS try/catch (and assert.throws)
+ * can catch the error instead of getting an uncatchable RuntimeError.
+ */
+export declare function emitThrowString(ctx: CodegenContext, fctx: FunctionContext, message: string): void;
+/**
+ * #1365 — Resolve the class struct that declared a `#name` PrivateIdentifier.
+ *
+ * Per ES2022 §15.7, a private name is lexically scoped to the class body that
+ * declares it. To brand-check `obj.#x`, we need to know which class struct
+ * to test the receiver against.
+ *
+ * Strategy: walk up `node.parent` from the PrivateIdentifier to find the
+ * enclosing class declaration whose body declared `#x`. The TS parser
+ * preserves `parent` links via `setParentNodes`. If multiple nested classes
+ * each declare `#x`, the innermost wins (lexical shadowing — same as
+ * regular variable scope).
+ *
+ * Returns `undefined` when:
+ *   - The PrivateIdentifier isn't lexically inside any class (parser will
+ *     have already caught this as a syntax error, but defensive).
+ *   - The class hasn't been registered with a struct (e.g. external class,
+ *     or compilation order issue).
+ *
+ * Returns the matched class's struct typeIdx and the legacy field name
+ * (`__priv_<text>`) so the caller can emit `ref.test` / `ref.cast` /
+ * `struct.get` against the right slot.
+ */
+export declare function resolveDeclaringClassForPrivateName(ctx: CodegenContext, node: ts.PrivateIdentifier): {
+    className: string;
+    structTypeIdx: number;
+    fieldName: string;
+} | undefined;
+/**
+ * Emit the runtime private-brand predicate for a receiver saved as anyref.
+ *
+ * `ref.test $DeclaringClass` alone is not a full brand check in this compiler:
+ * unrelated classes with identical private-field layout may canonicalize to the
+ * same WasmGC shape. The hidden class tag distinguishes declarations, while
+ * descendant tags remain valid for private names initialized by an ancestor.
+ */
+export declare function emitPrivateBrandPredicate(ctx: CodegenContext, fctx: FunctionContext, receiverLocal: number, className: string, structTypeIdx: number): void;
+/**
+ * (#2102) Error constructors {@link emitThrowJsError} can build. Each maps to a
+ * `__new_<Kind>(message)` host import in JS-host mode and to the in-module WASI
+ * Error constructor under `--target standalone`/`wasi`. The set is the spec's
+ * runtime-check error family (the §10/§22/§23 bounds/integrity/callable checks).
+ */
+export type JsErrorKind = "TypeError" | "RangeError" | "ReferenceError" | "SyntaxError" | "Error";
+/**
+ * (#2102) THE shared "throw a real JS Error instance" lowering. Runtime checks
+ * (bounds / integrity / callable / [[Set]] failures) that the spec requires to
+ * raise a catchable `TypeError`/`RangeError`/… must route through here instead
+ * of emitting an uncatchable Wasm `unreachable`/`ref.cast` trap or a bare string
+ * throw. The thrown ref is a real `<Kind>`-tagged externref (`e instanceof
+ * <Kind>` holds), produced by the same `__new_<Kind>(message)` path `new
+ * <Kind>(msg)` uses, and dispatched through the shared `$exc` tag so the user's
+ * try/catch (and test262 `assert.throws`) catches it.
+ *
+ * Dual-mode: in no-JS-host mode (`--target standalone`/`wasi`) the constructor
+ * is the in-module `emitWasiErrorConstructor` function, so no unsatisfiable
+ * `env::__new_<Kind>` host import is requested. The constructor is registered
+ * BEFORE the funcIdx is resolved so `ensureLateImport` finds the in-module
+ * function in funcMap and does NOT add an `env::__new_<Kind>` host import.
+ * (Consolidates the previously-duplicated #1365 TypeError / #1473
+ * ReferenceError / #2164 RangeError lowerings.)
+ *
+ * Leaves nothing on the value stack (the `throw` is terminal / stack-polymorphic).
+ */
+export declare function emitThrowJsError(ctx: CodegenContext, fctx: FunctionContext, kind: JsErrorKind, message: string): void;
+/**
+ * #1365 — Emit a Wasm throw of a real TypeError INSTANCE (not a bare string).
+ * Thin wrapper over {@link emitThrowJsError}; retained as the canonical call
+ * site name (many uses). Required for spec-compliant `assert.throws(TypeError,
+ * fn)` test262 cases — those check `e instanceof TypeError` on the caught value.
+ */
+export declare function emitThrowTypeError(ctx: CodegenContext, fctx: FunctionContext, message: string): void;
+/**
+ * #1473 — Emit a throw of a ReferenceError INSTANCE for TDZ / unresolved
+ * identifier references. Mirrors `emitThrowTypeError`.
+ *
+ * In no-JS-host mode (`--target wasi` / `--target standalone`), the
+ * ReferenceError is built via the in-module `__new_ReferenceError` function
+ * (emitted by `emitWasiErrorConstructor`), so no `env::__new_ReferenceError`
+ * host import is required. In JS-host mode the same import name resolves to
+ * the JS `ReferenceError` constructor.
+ *
+ * Either way the throw is observable in the user's catch block via the
+ * shared `$exc` tag, and `e instanceof ReferenceError` works through the
+ * `$Error_struct` `$tag` field discrimination.
+ */
+export declare function emitThrowReferenceError(ctx: CodegenContext, fctx: FunctionContext, message: string): void;
+/**
+ * #2164 — Emit a throw of a RangeError INSTANCE. Mirrors `emitThrowTypeError`.
+ * Used by `Date.prototype.toISOString` on an Invalid Date receiver
+ * (ECMA-262 §21.4.4.36 — RangeError "Invalid time value"). In no-JS-host mode
+ * the RangeError is built via the in-module `__new_RangeError` constructor; in
+ * JS-host mode the import resolves to the JS `RangeError`.
+ */
+export declare function emitThrowRangeError(ctx: CodegenContext, fctx: FunctionContext, message: string): void;
+/**
+ * (#2709) Uninitialized-`this` guard for a `super[key]` SuperProperty WRITE /
+ * UPDATE (`super[key] = v`, `super[key]++`) in a *derived* constructor whose
+ * `key` itself contains a `super(...)` call — i.e. the `super[super()] = 0` /
+ * `super[super()]++` shape.
+ *
+ * Per ECMA-262 §13.3.7.1 (Evaluation of SuperProperty), reference resolution
+ * performs `GetThisBinding()` FIRST (step 2), BEFORE the key Expression (step 3)
+ * and the RHS. In a derived class `this` is *uninitialized* until `super(...)`
+ * returns, so `GetThisBinding()` throws a `ReferenceError`. For the
+ * `super[super()]` shape this is provably the outcome in EVERY execution:
+ *   - if `super()` has not yet run, `this` is uninitialized → GetThisBinding
+ *     throws ReferenceError before the key is evaluated;
+ *   - if `super()` HAS already run, the key's inner `super()` is a second
+ *     SuperCall → "Super constructor may only be called once" ReferenceError.
+ * Either way the statement throws a ReferenceError and never completes, so
+ * emitting an unconditional ReferenceError here is spec-correct. The shape
+ * `super[super()] = …` never appears in valid programs, so this is ZERO
+ * regression risk (no currently-passing path reaches it).
+ *
+ * Call at the TOP of the super-element write / update path, before any key/RHS
+ * is emitted. Returns `true` when it emitted the throw (the caller should stop —
+ * the inner `super()` and RHS must NOT be evaluated). Returns `false` (a no-op)
+ * for every other shape, leaving existing behavior byte-identical.
+ */
+export declare function emitSuperUninitializedThisGuard(ctx: CodegenContext, fctx: FunctionContext, keyExpr: ts.Expression | undefined): boolean;
+/**
+ * #1456 — Classify a private property reference for assignment/compound-assignment.
+ *
+ * Per ES2022 §7.3.18 (PrivateElementSet) and §13.15.2
+ * (AssignmentExpression : LHS op= AssignmentExpression):
+ *
+ *   - Private *methods* throw TypeError on any write (`=`, `+=`, …).
+ *   - Private *accessor* with no setter throws TypeError on write.
+ *   - Private *accessor* with no getter throws TypeError on read (matters
+ *     for compound: the read step happens first).
+ *   - Plain private fields read/write through the brand slot as usual.
+ *
+ * We classify the LHS at compile time by looking up the brand-table proxies
+ * we've already populated when the class was registered:
+ *   - `ctx.classMethodSet` — `<Class>_<__priv_name>` for private methods
+ *     (both static and instance share the same `__priv_X` name space; that's
+ *     consistent with how `resolveClassMemberName` mangles them).
+ *   - `ctx.classAccessorSet` — `<Class>_<__priv_name>` for accessors;
+ *     existence of `<Class>_get_<__priv_name>` / `<Class>_set_<__priv_name>`
+ *     in `ctx.funcMap` distinguishes getter-only / setter-only / pair.
+ *
+ * Returns `undefined` if the receiver class cannot be resolved (defensive —
+ * the caller falls back to existing behavior).
+ */
+export type PrivateMemberKind = "method" | "accessor-readonly" | "accessor-writeonly" | "accessor" | "field";
+export declare function classifyPrivateMember(ctx: CodegenContext, name: ts.PrivateIdentifier): {
+    className: string;
+    fieldName: string;
+    kind: PrivateMemberKind;
+} | undefined;
+/**
+ * Check if a TS return type is effectively void for Wasm purposes.
+ * For async functions, the TS checker reports `Promise<void>` which is not
+ * caught by `isVoidType`. This helper unwraps Promise types for async
+ * functions before checking.
+ *
+ * Use this instead of bare `isVoidType(retType)` at all call-return-type
+ * resolution points to prevent emitting `drop` on an empty stack.
+ */
+export declare function isEffectivelyVoidReturn(ctx: CodegenContext, retType: ts.Type, funcName?: string): boolean;
+/**
+ * Get parameter types of a Wasm function by its index.
+ * Handles both imported functions (index < numImportFuncs) and local functions.
+ */
+export declare function getFuncParamTypes(ctx: CodegenContext, funcIdx: number): ValType[] | undefined;
+/**
+ * Check if a Wasm function (by index) has a void return type by inspecting
+ * the actual function type in the module. This is the ground truth for whether
+ * a `call` instruction pushes a value onto the stack.
+ */
+export declare function wasmFuncReturnsVoid(ctx: CodegenContext, funcIdx: number): boolean;
+/** Check whether a function *type* (by type index) has zero results. */
+export declare function wasmFuncTypeReturnsVoid(ctx: CodegenContext, typeIdx: number): boolean;
+/**
+ * Get the actual Wasm return type of a function by inspecting its type definition.
+ * Returns undefined if the function has void return or is not found.
+ * Use this instead of resolveWasmType(retType) at call sites to avoid mismatches
+ * when TS type says 'any' (→ externref) but the Wasm function returns f64/i32.
+ */
+export declare function getWasmFuncReturnType(ctx: CodegenContext, funcIdx: number): ValType | undefined;
+/**
+ * Update a local's declared type to a new type.
+ * Used when a variable is reassigned to a value of a different struct type.
+ */
+export declare function updateLocalType(fctx: FunctionContext, localIdx: number, newType: ValType): void;
+/**
+ * Widen a local's declared type from ref $X to ref_null $X.
+ */
+export declare function widenLocalToNullable(fctx: FunctionContext, localIdx: number): void;
+/**
+ * Emit a local.set with automatic type coercion.
+ * If the value on the stack (stackType) doesn't match the local's declared type,
+ * inserts coercion instructions before the local.set.
+ */
+export declare function emitCoercedLocalSet(ctx: CodegenContext, fctx: FunctionContext, localIdx: number, stackType: ValType): void;

package/dist/codegen/expressions/identifiers.d.ts

@@ -0,0 +1,57 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function emitLocalTdzCheck(ctx: CodegenContext, fctx: FunctionContext, name: string, flagIdx: number): void;
+/**
+ * Compile-time TDZ elision for top-level let/const variables (#906).
+ *
+ * Returns the subset of `candidates` for which TDZ tracking can be statically
+ * compiled away — i.e. every identifier reference in the source file that
+ * resolves to the candidate's declaration is provably after initialization
+ * (analyzeTdzAccess returns "skip"). For these names, the caller can skip
+ * emitting the `__tdz_<name>` global, the `global.set __tdz_<name>` writes
+ * in the module init body, and the runtime check at every read.
+ *
+ * If a candidate has *any* reference that yields "throw" or "check", it stays
+ * tracked at runtime. This preserves observable semantics for genuinely
+ * dynamic or ambiguous cases (e.g. a function declaration that reads the
+ * variable, since hoisted functions could be called before the variable's
+ * initializer runs).
+ */
+export declare function computeElidableTopLevelTdzNames(ctx: CodegenContext, sourceFile: ts.SourceFile, candidates: Set<string>): Set<string>;
+/**
+ * Position-based TDZ analysis for call-site capture checks.
+ * Used when we know the variable name and the call expression position,
+ * but don't have an identifier with a resolved symbol (e.g., pushing
+ * closure captures at a nested function call site).
+ */
+declare function analyzeTdzAccessByPos(ctx: CodegenContext, varName: string, callNode: ts.Node): "skip" | "throw" | "check";
+/** Emit a static TDZ throw (guaranteed violation — no flag check needed). */
+export declare function emitStaticTdzThrow(ctx: CodegenContext, fctx: FunctionContext, name: string): void;
+declare function compileIdentifier(ctx: CodegenContext, fctx: FunctionContext, id: ts.Identifier): ValType | null;
+/**
+ * If the narrowed TS type indicates a concrete primitive, emit an unbox call
+ * and return the unboxed ValType. The externref value must already be on stack.
+ * Returns null if no unboxing is needed (type is still a union or externref).
+ */
+declare function narrowTypeToUnbox(ctx: CodegenContext, fctx: FunctionContext, narrowedType: ts.Type): ValType | null;
+/**
+ * Try to resolve the right-hand side of an instanceof expression to a known
+ * class in our struct system. Returns the class name if found, undefined otherwise.
+ * This mirrors resolveInstanceOfClassName in typeof-delete.ts but is used to
+ * decide whether to use the host fallback.
+ */
+declare function resolveInstanceOfRHS(ctx: CodegenContext, rightExpr: ts.Expression): string | undefined;
+/**
+ * Compile `expr instanceof RHS` using a host import when the RHS class is not
+ * in our struct system (e.g., TypeError, Array, Function, Promise). (#738)
+ * Passes the value as externref and the constructor name as a string constant,
+ * delegating to `__instanceof(value, ctorName) -> i32` host import which
+ * looks up the constructor on the global object.
+ *
+ * For built-in RHS (Array, Error, *Error, Map, ...), tries `tryStaticInstanceOf`
+ * first to short-circuit when the LHS TS type makes the answer compile-time
+ * obvious — important for standalone/WASI mode (#1325).
+ */
+declare function compileHostInstanceOf(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): ValType;
+export { analyzeTdzAccessByPos, compileHostInstanceOf, compileIdentifier, narrowTypeToUnbox, resolveInstanceOfRHS };

package/dist/codegen/expressions/late-imports.d.ts

@@ -0,0 +1,81 @@
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * Shift function indices after a late import addition. This must update all
+ * already-compiled function bodies, the current function body, any saved bodies
+ * from the savedBody swap pattern, and export descriptors.
+ */
+export declare function shiftLateImportIndices(ctx: CodegenContext, fctx: FunctionContext | null, importsBefore: number, added: number): void;
+/**
+ * Add a late import if it does not already exist, deferring the index shift.
+ * Records ctx.pendingLateImportShift.importsBefore on the first deferred addition
+ * so that flushLateImportShifts() can do a single O(B) traversal for all imports
+ * added in the batch, instead of O(I*B) for I individual additions.
+ * Returns the funcIdx of the import (looked up after addImport).
+ */
+export declare function ensureLateImport(ctx: CodegenContext, name: string, paramTypes: ValType[], resultTypes: ValType[]): number | undefined;
+/**
+ * #1677: reconcile native-string helper function indices at the end of the
+ * import-collection finalize phase.
+ *
+ * The native-string runtime helpers (`__str_flatten` & co.) are emitted as
+ * DEFINED functions *mid-finalize* (the first `ensureNativeStringHelpers`
+ * call), recording `ctx.nativeStrHelperImportBase` = the import count at that
+ * instant. Finalize then continues and adds more imports via raw `addImport`
+ * (string methods, parseInt, Promise statics, iterator/generator bridges, …).
+ * Raw `addImport` does NOT shift defined-function indices (the #618 revert
+ * deliberately removed that), so every helper body's internal `call` to a
+ * sibling helper — and every `nativeStrHelpers` map entry — is now stale-low by
+ * exactly `(numImportFuncs - base)`.
+ *
+ * This reconciliation runs once, after finalize is otherwise complete, and
+ * applies that single uniform delta via the same `shiftLateImportIndices`
+ * walker the compilation-phase late-import path uses — unifying the two shift
+ * regimes (#1666 root cause). It is a no-op unless native-string helpers were
+ * emitted, so the default GC path is never touched; and because it shifts
+ * `funcIdx >= base` (sibling-helper calls) but not `funcIdx < base` (calls to
+ * imports added before the helpers), it cannot corrupt the Math.* host
+ * trampoline path that the #618 naive `addImport` shift broke.
+ */
+export declare function reconcileNativeStrFinalizeShift(ctx: CodegenContext): void;
+/**
+ * Flush any pending late import shifts. Performs a single traversal of all
+ * function bodies to shift indices, instead of one traversal per import.
+ * Must be called after a batch of ensureLateImport() calls before any
+ * funcIdx values are used in emitted instructions.
+ */
+export declare function flushLateImportShifts(ctx: CodegenContext, fctx: FunctionContext | null): void;
+/**
+ * Ensure the __get_undefined host import exists, returning its funcIdx.
+ * This import returns the actual JS `undefined` value as externref,
+ * allowing Wasm to distinguish null from undefined at runtime.
+ *
+ * Under native-strings mode (auto-on for `--target standalone`/`wasi`) there is
+ * no JS host to satisfy this import, and undefined is conflated with null (same
+ * convention as `__extern_is_undefined` → bare `ref.is_null`). Returning
+ * `undefined` here makes callers fall back to the native `ref.null.extern`
+ * sentinel via `emitUndefined`, which (a) keeps standalone host-import-free and
+ * (b) avoids adding a late import *after* the native-string helpers were emitted
+ * — that post-helper import otherwise drives `reconcileNativeStrFinalizeShift`
+ * an extra time and off-by-ones the baked `__str_flatten`→`__str_copy_tree`
+ * call (#329: `let g: any; g = function(){…}; g()` invalid wasm).
+ */
+export declare function ensureGetUndefined(ctx: CodegenContext): number | undefined;
+/**
+ * Emit instructions that push the JS `undefined` value onto the stack.
+ * Uses the __get_undefined host import when available; falls back to
+ * ref.null.extern (indistinguishable from null) in standalone mode.
+ */
+export declare function emitUndefined(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Ensure the __extern_is_undefined host import exists, returning its funcIdx.
+ * This import checks if an externref value is JS `undefined` (not null).
+ */
+export declare function ensureExternIsUndefinedImport(ctx: CodegenContext): number | undefined;
+/**
+ * After dynamically adding a field to a struct type, patch all existing
+ * struct.new instructions for that type by inserting a default value
+ * instruction immediately before each struct.new.  This ensures the
+ * operand count matches the (now larger) field list.
+ */
+export declare function patchStructNewForAddedField(ctx: CodegenContext, fctx: FunctionContext, typeIdx: number, fieldType: ValType): void;

package/dist/codegen/expressions/logical-ops.d.ts

@@ -0,0 +1,18 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileLogicalAnd(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): ValType;
+export declare function compileLogicalOr(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): ValType;
+export declare function compileNullishCoalescing(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): ValType;
+/**
+ * Emit code to sync a parameter local's value into the mapped arguments array (#849).
+ * Called after local.tee for parameter assignments in functions with mapped arguments.
+ * The expression result is on the stack; we save it, do the sync, then restore it.
+ */
+declare function emitMappedArgParamSync(ctx: CodegenContext, fctx: FunctionContext, paramIdx: number, resultType: ValType): void;
+/**
+ * Emit code to sync an arguments element write back to the parameter local (#849).
+ * Called after array.set in compileElementAssignment when target is the arguments object.
+ */
+declare function emitMappedArgReverseSync(ctx: CodegenContext, fctx: FunctionContext, idxLocal: number, valLocal: number): void;
+export { emitMappedArgParamSync, emitMappedArgReverseSync };

package/dist/codegen/expressions/misc.d.ts

@@ -0,0 +1,27 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+import { getIteratorResultValueType, isGeneratorIteratorResultLike, resolveStructName, resolveStructNameForExpr } from '../property-access.js';
+import { InnerResult } from '../shared.js';
+export { getIteratorResultValueType, isGeneratorIteratorResultLike, resolveStructName, resolveStructNameForExpr };
+declare function compileConditionalExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ConditionalExpression): ValType | null;
+/**
+ * Optional property access: obj?.prop
+ * Compiles obj, checks if null → returns null, else accesses property normally.
+ */
+/**
+ * Compile a `yield expr` expression inside a generator function.
+ * Pushes the yielded value into the __gen_buffer (a JS array managed by the host).
+ * The yield expression itself evaluates to void (we don't support receiving
+ * values via yield in this initial implementation).
+ */
+declare function compileYieldExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.YieldExpression): InnerResult;
+/** Check if an expression is statically known to be NaN at compile time */
+/**
+ * Try to statically determine the numeric value of an expression.
+ * Handles: numeric literals, NaN, Infinity, -Infinity, object-with-valueOf, {}.
+ * Returns undefined if the value cannot be determined at compile time.
+ */
+export declare function tryStaticToNumber(ctx: CodegenContext, expr: ts.Expression, visitedDecls?: Set<ts.Node>): number | undefined;
+declare function isStaticNaN(ctx: CodegenContext, expr: ts.Expression): boolean;
+export { compileConditionalExpression, compileYieldExpression, isStaticNaN };