@loopdive/js2 0.57.0

package/dist/codegen/expressions/new-super.d.ts

@@ -0,0 +1,25 @@
+import { ValType } from '../../ir/types.js';
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+import { InnerResult } from '../shared.js';
+declare function compileSuperMethodCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult;
+/**
+ * Compile `super['method'](args)` — resolve to ParentClass_method and call with this.
+ * Same logic as compileSuperMethodCall but the method name comes from a computed key.
+ */
+declare function compileSuperElementMethodCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression, methodName: string): ValType | null;
+/**
+ * Compile `super.prop` — access a parent class property or getter via `this`.
+ * For getter accessors, calls the parent's getter function.
+ * For struct fields, accesses the field on `this` (child struct inherits parent fields).
+ */
+export declare function compileSuperPropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression, propName: string): ValType | null;
+/**
+ * Compile `super[expr]` — access a parent class property via computed key on `this`.
+ * Resolves the key at compile time if possible and delegates to compileSuperPropertyAccess logic.
+ * For dynamic keys, falls back to default value for the access type.
+ */
+export declare function compileSuperElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+declare function compileClassExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ClassExpression): ValType | null;
+declare function compileNewExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.NewExpression): ValType | null;
+export { compileClassExpression, compileNewExpression, compileSuperElementMethodCall, compileSuperMethodCall };

package/dist/codegen/expressions/promise-subclass.d.ts

@@ -0,0 +1,38 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * Returns the resolved class name if `name` (a user-visible identifier or
+ * class-expression alias) denotes a `class … extends Promise` (transitively,
+ * through a chain of user subclasses), else `undefined`.
+ *
+ * Walks the parent chain because `classBuiltinParentMap` only records the
+ * *immediate* builtin parent: for `class B extends A` / `class A extends
+ * Promise`, B maps to "A", not "Promise". `classParentMap` carries the
+ * user-class edges, so we climb until we hit a builtin Promise parent.
+ *
+ * Standalone (WASI) mode has no JS host, so `__promise_subclass_ctor` is
+ * unsatisfiable there — return `undefined` so callers fall back.
+ */
+export declare function resolvePromiseSubclassName(ctx: CodegenContext, name: string): string | undefined;
+/**
+ * Emits an externref that is the cached `__promise_subclass_ctor` for the given
+ * resolved class name (one synthesized `class extends Promise {}` per name).
+ * `resolved` MUST be the name returned by {@link resolvePromiseSubclassName}
+ * (i.e. already alias-resolved through `classExprNameMap`).
+ *
+ * Returns true on success (instruction(s) pushed), false if the import could
+ * not be registered (caller should fall back to its default emission).
+ */
+export declare function emitPromiseSubclassCtor(ctx: CodegenContext, fctx: FunctionContext, resolved: string): boolean;
+/**
+ * Convenience for the value-read position: if `name` denotes a `class extends
+ * Promise`, emit the unified `__promise_subclass_ctor` externref and return
+ * true; else return false (caller falls through to its normal handling).
+ */
+export declare function tryEmitPromiseSubclassValue(ctx: CodegenContext, fctx: FunctionContext, name: string): boolean;
+/**
+ * Receiver-position helper (combinator `thisArg`): same unification, but the
+ * argument arrives as a `ts.Expression`. Only a bare identifier (or class-expr
+ * alias) is eligible. Returns true if it emitted the unified ctor externref.
+ */
+export declare function tryEmitPromiseSubclassReceiver(ctx: CodegenContext, fctx: FunctionContext, argExpr: ts.Expression): boolean;

package/dist/codegen/expressions/proto-override.d.ts

@@ -0,0 +1,63 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * (#1719 CPR) AST-only predicate (no `ctx`) for the module-init statement filter:
+ * true when `target` is `Array.prototype[Symbol.iterator]` / `Array.prototype.values`,
+ * so the override assignment is kept in `__module_init` instead of being dropped.
+ * Matches the LHS shape recognised by `sourceOverridesArrayIterator`.
+ */
+export declare function isArrayProtoIteratorAssignTarget(target: ts.Expression): boolean;
+/**
+ * If `target = value` is an `Array.prototype` iterator override, capture the
+ * lifted RHS closure into `ctx.protoOverrides` (rooted in a module global) and
+ * return `true` (the caller must NOT fall through to the normal element/property
+ * assignment). Returns `false` (no-op) for every other assignment — byte-identical.
+ *
+ * Leaves the override closure externref on the stack as the assignment's value
+ * (an assignment expression evaluates to its RHS).
+ */
+export declare function maybeCaptureArrayProtoOverride(ctx: CodegenContext, fctx: FunctionContext, target: ts.Expression, value: ts.Expression): boolean;
+/**
+ * Returns the rooted override-closure global index for the Array `@@iterator`
+ * override (the CPR drive consults this), or `undefined` when no override was
+ * captured. `values` is treated as an alias for `@@iterator` per §23.1.3.36
+ * (`Array.prototype.values` IS `Array.prototype[@@iterator]`), so either capture
+ * drives array iteration.
+ */
+export declare function arrayIteratorOverrideGlobalIdx(ctx: CodegenContext): number | undefined;
+/**
+ * (#1719 CPR read-drive — option (a)) Fill the reserved `__drive_proto_iterator`
+ * driver body in post-processing, AFTER `emitClosureMethodCallExportN(0)` has
+ * registered `__call_fn_method_0` in `funcMap`. The driver is a thin wrapper:
+ *
+ *   __drive_proto_iterator(thisVal, closure) =
+ *     return __call_fn_method_0(thisVal, closure)
+ *
+ * reusing the proven re-entrancy-safe `__current_this` install/restore dispatch
+ * (#1636-S1) instead of duplicating funcref-type dispatch at each read site. The
+ * override closure is arity-0 (`Array.prototype[@@iterator]()` takes no args), so
+ * arity-0 `__call_fn_method_0` is the exact driver. No-op when the driver was
+ * never reserved (brand clear / no read-drive site).
+ */
+export declare function fillProtoIteratorDriver(ctx: CodegenContext): void;
+/**
+ * (#1719 CPR read-drive) Emit the override drive at an array-destructuring /
+ * for-of / spread observation site. PRECONDITION: the RHS vec ref is on the
+ * stack and the caller has already gated on
+ * `arrayIteratorMaybeOverridden && arrayIteratorOverrideGlobalIdx(ctx)!==undefined`.
+ *
+ * Lowers (§7.4.2 GetIterator + §8.5.2 IteratorBindingInitialization):
+ *   1. `extern.convert_any` the vec → the array-as-`this` externref;
+ *   2. `global.get` the captured override closure;
+ *   3. `call __drive_proto_iterator(array, closure)` → the override-produced
+ *      iterator externref, stashed in `iterLocal`.
+ *
+ * Returns the local holding the iterator externref. The caller drains it via
+ * `__iterator_next` into the binding elements. Standalone-clean: the drive runs
+ * in-Wasm (no host import, no host-Array reflection); only the per-element drain
+ * uses the existing `__iterator_next` host import (dual-mode boundary, same as
+ * for-of). The brand only fires here at the observation boundary, so internal
+ * array iterations inside the override body stay on the typed-vec fast path —
+ * no re-entrancy.
+ */
+export declare function emitArrayProtoIteratorDrive(ctx: CodegenContext, fctx: FunctionContext, overrideGlobalIdx: number): number;

package/dist/codegen/expressions/unary-updates.d.ts

@@ -0,0 +1,21 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * Compile prefix/postfix increment/decrement on member expressions:
+ *   ++obj.x, obj.x++, --obj[i], obj[i]--, etc.
+ *
+ * For prefix: evaluates new value (old +/- 1), stores, returns new value.
+ * For postfix: evaluates old value, stores new value (old +/- 1), returns old value.
+ */
+declare function compileMemberIncDec(ctx: CodegenContext, fctx: FunctionContext, operand: ts.Expression, arithOp: "add" | "sub", mode: "prefix" | "postfix"): ValType | null;
+/**
+ * Compile a prefix UpdateExpression: `++x` or `--x` on any target shape
+ * (identifier, property access, element access, boxed capture, global).
+ *
+ * Caller must have already established that `expr.operator` is either
+ * `PlusPlusToken` or `MinusMinusToken`.
+ */
+declare function compilePrefixUpdate(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PrefixUnaryExpression): ValType | null;
+declare function compilePostfixUnary(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PostfixUnaryExpression): ValType | null;
+export { compileMemberIncDec, compilePostfixUnary, compilePrefixUpdate };

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

@@ -0,0 +1,6 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+import { compileMemberIncDec, compilePostfixUnary } from './unary-updates.js';
+declare function compilePrefixUnary(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PrefixUnaryExpression): ValType | null;
+export { compileMemberIncDec, compilePostfixUnary, compilePrefixUnary };

package/dist/codegen/expressions.d.ts

@@ -0,0 +1,31 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export { compileArrayMethodCall, compileArrayPrototypeCall, emitBoundsCheckedArrayGet, emitClampIndex, emitClampNonNeg, } from './array-methods.js';
+export { compileNumericBinaryOp } from './binary-ops.js';
+export { collectReferencedIdentifiers, collectWrittenIdentifiers } from './closures.js';
+export { getWellKnownSymbolId, resolveComputedKeyExpression, resolveConstantExpression } from './literals.js';
+export { compileObjectDefineProperties, compileObjectDefineProperty, compileObjectKeysOrValues, compilePropertyIntrospection, } from './object-ops.js';
+export { compileElementAccess, compileOptionalPropertyAccess, compilePropertyAccess, emitNullCheckThrow, isProvablyNonNull, } from './property-access.js';
+export { getCol, getLine, resolveEnclosingClassName, valTypesMatch, VOID_RESULT } from './shared.js';
+export { compileNativeStringLiteral, compileNativeStringMethodCall, compileNativeTemplateExpression, compileStringBinaryOp, compileStringLiteral, compileTaggedTemplateExpression, compileTemplateExpression, emitBoolToString, } from './string-ops.js';
+export { coercionInstrs, defaultValueInstrs, pushDefaultValue, pushParamSentinel } from './type-coercion.js';
+export { compileInstanceOf, compileTypeofComparison } from './typeof-delete.js';
+export { compileAssignment, compileCompoundAssignment, compileLogicalAssignment, isCompoundAssignment, } from './expressions/assignment.js';
+export { compileCallExpression, compileIIFE, compileOptionalCallExpression } from './expressions/calls.js';
+export { emitLazyProtoGet, findExternInfoForMember } from './expressions/extern.js';
+export { emitThrowString, getFuncParamTypes } from './expressions/helpers.js';
+export { analyzeTdzAccessByPos, compileIdentifier, computeElidableTopLevelTdzNames, narrowTypeToUnbox, } from './expressions/identifiers.js';
+export { emitUndefined, ensureExternIsUndefinedImport, ensureGetUndefined, ensureLateImport, flushLateImportShifts, patchStructNewForAddedField, shiftLateImportIndices, } from './expressions/late-imports.js';
+export { compileLogicalAnd, compileLogicalOr, compileNullishCoalescing } from './expressions/logical-ops.js';
+export { getIteratorResultValueType, isGeneratorIteratorResultLike, resolveStructName, tryStaticToNumber, } from './expressions/misc.js';
+export { compileClassExpression, compileNewExpression, compileSuperElementAccess, compileSuperPropertyAccess, } from './expressions/new-super.js';
+export { compileMemberIncDec, compilePostfixUnary, compilePrefixUnary } from './expressions/unary.js';
+export declare function resetCompileDepth(): void;
+export declare function compileExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.Expression, expectedType?: ValType): ValType | null;
+/**
+ * Emit a local.set with automatic type coercion.
+ */
+export declare function emitCoercedLocalSet(ctx: CodegenContext, fctx: FunctionContext, localIdx: number, stackType: ValType): void;
+/** Coerce a value on the stack from one type to another */
+export declare function coerceType(ctx: CodegenContext, fctx: FunctionContext, from: ValType, to: ValType, toPrimitiveHint?: "number" | "string" | "default"): void;

package/dist/codegen/fallback-telemetry.d.ts

@@ -0,0 +1,53 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext } from './context/types.js';
+/**
+ * The seven silent-fallback pattern classes from the fail-loud audit
+ * (`plan/log/analysis-2026-06/04-fail-loud-audit.md` §summary table).
+ */
+export type SilentFallbackClass = "null-fallback" | "lookup-miss-skip" | "const-fallback" | "arity-truncation" | "allowlist-miss" | "cap-exceeded-path" | "compiler-catch";
+/** All known classes, in declaration order — the canonical iteration order. */
+export declare const SILENT_FALLBACK_CLASSES: readonly SilentFallbackClass[];
+/**
+ * Per-class → per-site → hit count. Sites are stable string keys of the form
+ * `"<file-stem>:<short-label>"` (e.g. `"unary-updates:incdec-unresolvable-receiver"`)
+ * so the baseline JSON diff is readable and resilient to line moves.
+ */
+export type FallbackCounts = Map<SilentFallbackClass, Map<string, number>>;
+/** Build an empty {@link FallbackCounts} with every class pre-seeded. */
+export declare function createFallbackCounts(): FallbackCounts;
+/**
+ * Classes promoted to hard errors once their corpus baseline hits zero —
+ * the codegen analogue of `STRICT_IR_REASONS` (index.ts). Empty in Phase 0
+ * (telemetry only); Phase 4 flips `lookup-miss-skip`/`null-fallback` in here
+ * as their buckets zero out. A site in a strict class pushes a hard error.
+ */
+export declare const STRICT_FALLBACK_CLASSES: ReadonlySet<SilentFallbackClass>;
+/**
+ * Whether a *strict* class should hard-fail in the current environment.
+ * Auto-on under CI / vitest / `NODE_ENV=test`, mirroring
+ * `irVerifierHardFailureEnabled` (index.ts:934), or forced via
+ * `JS2WASM_STRICT_FALLBACKS=1`. Phase 0 has no strict classes, so this only
+ * matters once a class is promoted.
+ */
+export declare function strictFallbacksEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * Record that a silent fallback was taken at `site`.
+ *
+ * Three escalation levels (identical lifecycle to `STRICT_IR_REASONS`):
+ *   1. always — increments `ctx.fallbackCounts[cls][site]`.
+ *   2. opt-in — when `ctx.trackSilentFallbacks` (or `JS2WASM_LOG_CODEGEN_FALLBACKS=1`),
+ *      pushes a structured *warning* error so the diagnostic surfaces.
+ *   3. strict — when `cls ∈ STRICT_FALLBACK_CLASSES` and {@link strictFallbacksEnabled},
+ *      pushes a *hard* error so the fallback can no longer hide.
+ *
+ * Pure bookkeeping otherwise — it never touches the wasm body, so adding a
+ * call at a site is behavior-preserving in Phase 0.
+ */
+export declare function reportSilentFallback(ctx: CodegenContext, cls: SilentFallbackClass, site: string, node?: ts.Node, detail?: string): void;
+/** Total hits across all classes/sites — used by the gate for a quick summary. */
+export declare function totalFallbackHits(counts: FallbackCounts): number;
+/**
+ * Flatten {@link FallbackCounts} into a stable, JSON-serializable shape for the
+ * baseline file: `{ [class]: { [site]: count } }`, classes and sites sorted.
+ */
+export declare function fallbackCountsToJson(counts: FallbackCounts): Record<string, Record<string, number>>;

package/dist/codegen/fixups.d.ts

@@ -0,0 +1,80 @@
+import { Instr, ValType, WasmModule } from '../ir/types.js';
+import { CodegenContext } from './context/types.js';
+/**
+ * Post-processing pass: mark leaf struct types in subtype hierarchies as final.
+ *
+ * V8 can devirtualize struct.get/struct.set when a type is known to be final
+ * (no subtypes). Struct types without superTypeIdx are already implicitly final
+ * in the Wasm binary encoding. This pass finds struct types that participate in
+ * subtyping (have superTypeIdx set) but are never referenced as a parent by any
+ * other type, and marks them as final so the emitter uses sub_final (0x4F).
+ *
+ * Caveat (#1173): emitting `(sub final $T)` causes Binaryen ≥ 124 (when run
+ * with `--all-features`, e.g. `wasm-opt --all-features -O4`) to convert
+ * `(ref $T)` references into `(ref exact $T)` in the re-emitted binary. The
+ * exact-reference encoding is part of the WasmGC custom-descriptors proposal
+ * and is rejected by wasmtime ≤ 44 with:
+ *   "custom descriptors required for exact reference types"
+ *
+ * The benchmark/standalone path (`--target wasi` → `wasm-opt --all-features`
+ * → `wasmtime`) is the canonical victim. Browsers (V8) accept the exact
+ * encoding, so the devirtualization optimization is preserved there.
+ *
+ * `skipFinal` is intended for callers who know their output will go through a
+ * runtime that doesn't support custom-descriptors (today: wasmtime / standalone
+ * Wasm consumers). Pass `true` to leave subtypes as plain `(sub $parent ...)`
+ * so wasm-opt has nothing to convert into an exact ref.
+ */
+export declare function markLeafStructsFinal(mod: WasmModule, skipFinal?: boolean): void;
+/**
+ * Post-processing pass: repair struct.get/struct.set type mismatches.
+ *
+ * When code generation emits ref.null.extern or local.get of an externref local
+ * immediately before a struct.get/struct.set, Wasm validation fails because
+ * struct.get/struct.set require a reference to the specific struct type.
+ *
+ * This pass fixes two patterns:
+ *
+ * 1. ref.null.extern + struct.get/struct.set → ref.null $typeIdx
+ *    (null externref replaced with typed null for the expected struct type)
+ *
+ * 2. local.get $externref + struct.get/struct.set → local.get + any.convert_extern + ref.cast $typeIdx
+ *    (externref converted to the expected struct reference type)
+ *
+ * 3. call returning externref + struct.get/struct.set → call + any.convert_extern + ref.cast $typeIdx
+ *
+ * Recurses into nested blocks, loops, if/then/else, and try/catch bodies.
+ */
+export declare function repairStructTypeMismatches(mod: WasmModule): number;
+export declare function repairBody(body: Instr[], localTypes: ValType[], mod: WasmModule): number;
+/**
+ * Compute the net stack delta for a single instruction.
+ * Returns (values_pushed - values_consumed). Used by repairStructTypeMismatches
+ * to walk backwards and find the instruction that produces a specific stack value.
+ *
+ * This is a conservative approximation — block/loop/if/try are treated as opaque
+ * (delta 0), which is safe because struct.get/struct.set operands are almost never
+ * produced by branching constructs.
+ */
+export declare function instrStackDelta(instr: Instr, mod: WasmModule): number;
+/**
+ * Post-compilation fixup: reconcile struct.new argument counts.
+ *
+ * During expression compilation, fields can be dynamically added to struct
+ * types (e.g., when a property access finds a field the TS type checker knows
+ * about but wasn't in the original struct definition). This causes the
+ * struct type to have more fields than the constructor's struct.new pushes
+ * values for, resulting in Wasm validation failure.
+ *
+ * This pass scans all function bodies for struct.new instructions on class
+ * struct types and inserts default-value instructions for any missing fields.
+ */
+export declare function fixupStructNewArgCounts(ctx: CodegenContext): void;
+export declare function fixupStructNewResultCoercion(ctx: CodegenContext): void;
+/**
+ * Late-stage fixup: repair extern.convert_any applied to non-anyref values.
+ * extern.convert_any expects anyref input, but various passes can produce
+ * extern.convert_any on externref (redundant) or funcref (invalid — separate hierarchy).
+ * Must run after ALL other codegen/fixup passes.
+ */
+export declare function fixupExternConvertAny(ctx: CodegenContext): void;

package/dist/codegen/fmod.d.ts

@@ -0,0 +1,10 @@
+import { CodegenContext } from './context/types.js';
+/** Reserved name for the f64 remainder helper. */
+export declare const FMOD_FN = "__fmod";
+/**
+ * Ensure the `__fmod` helper function exists in the module and return its
+ * funcIdx. Idempotent — a second call returns the already-registered index.
+ *
+ * Signature: `(f64 a, f64 b) -> f64`.
+ */
+export declare function ensureFmod(ctx: CodegenContext): number;

package/dist/codegen/fnctor-escape-gate.d.ts

@@ -0,0 +1,92 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/** Classification of a `new F()` fnctor allocation site. */
+export type FnctorGateClass = 
+/** (A)∧(B): dynamically consumed, no typed own-field consumer → S3 candidate. */
+"reconstruct"
+/** Has a typed own-field consumer (clause B fails) → never reconstruct (hot path). */
+ | "keep-typed"
+/** No dynamic consumer found (clause A fails) → no reconstruction needed. */
+ | "keep-static";
+/** Result of the #2660 S1 fnctor escape/dynamic-use analysis (frozen before codegen). */
+export interface FnctorEscapeGateResult {
+    /**
+     * Per `new F()` site classification, keyed by the `NewExpression` AST node.
+     * S3 consults this via the node identity at `compileNewFunctionDeclaration`.
+     */
+    readonly sites: ReadonlyMap<ts.NewExpression, FnctorGateClass>;
+    /** Sites approved for reconstruction (`reconstruct`) — the (A)∧(B) set. */
+    readonly approved: ReadonlySet<ts.NewExpression>;
+    /**
+     * Fnctor symbol NAMES that have ≥1 `reconstruct`-classified `new F()` site —
+     * i.e. the constructors S3 will reconstruct as `$Object`. #2660 S2 gates its
+     * per-fnctor prototype `$Object` materialization on this set so it ONLY touches
+     * constructors whose instances need the `$proto` walk; a `keep-typed` /
+     * `keep-static` / never-`new`'d function (e.g. `Test262Error`, a species
+     * `Ctor` used only via `Object.getPrototypeOf`) keeps its existing prototype
+     * behaviour untouched (avoids the identity/harness regressions an unscoped
+     * interception caused).
+     */
+    readonly approvedNames: ReadonlySet<string>;
+    /**
+     * #2660 PART-1 — receiver-expression → `__fnctor_<Name>` struct-name flow map.
+     *
+     * Keyed by every USE-site expression (the identifier nodes) of a LOCAL binding
+     * `const/let/var x = <call>` whose initializer call is a *single-return-
+     * inferable* fnctor-returning method (e.g. `var node = this.startNode()` where
+     * `startNode` is the aliased-prototype method `pp.startNode = function(){ return
+     * new Node(...) }`). The mapped value is the `__fnctor_<Name>` struct name
+     * (the `ctx.structMap` key from `new-super.ts`). It lets the PART-2 dispatch
+     * pin the dynamic `x.<field>` read/write/compound to that one struct instead of
+     * the open-scan `findAlternateStructsForField` — the local-receiver half of the
+     * #2660 substrate (the `this`-receiver half is `FunctionContext.thisStructName`,
+     * resolution case (1)).
+     *
+     * **Conservative-closed**: only bindings whose initializer resolves to a SINGLE
+     * `return new X()` / `return <single-return call>` chain (depth-capped,
+     * memoized) are recorded; anything ambiguous is omitted ⇒ `resolveReceiverStruct`
+     * returns `undefined` ⇒ the consumer stays on the dynamic path. A miss NEVER
+     * yields a wrong struct.
+     *
+     * **INERT in PART-1**: produced here but consulted only by the (as-yet-uncalled)
+     * `resolveReceiverStruct`; no lowering reads it, so emitted Wasm is byte-identical.
+     */
+    readonly receiverStruct: ReadonlyMap<ts.Expression, string>;
+}
+/**
+ * Whether `expr` resolves to a plain function constructor (fnctor) rather than a
+ * `class`. Mirrors the recognition `compileNewExpression` uses to route to
+ * `compileNewFunctionDeclaration`: the callee symbol has a `FunctionDeclaration`
+ * / `FunctionExpression` declaration (or a `var F = function …`), and is not a
+ * class. Returns the resolved constructor symbol when it is a fnctor, else
+ * `undefined`.
+ */
+export declare function resolveFnctorSymbol(checker: ts.TypeChecker, calleeExpr: ts.Expression): ts.Symbol | undefined;
+/**
+ * #2660 PART-1 — resolve the WasmGC struct a member-access RECEIVER expression
+ * concretely is, for the dynamic read/write/compound dispatch to PIN to.
+ *
+ * Resolution order (the consumer pins to the first hit; a miss ⇒ dynamic path):
+ *   1. `this` receiver → `fctx.thisStructName` (the #2681 syntactic prototype
+ *      resolver's result, populated by the PART-2 dispatch slice);
+ *   2. a local receiver in the {@link FnctorEscapeGateResult.receiverStruct} flow
+ *      map (bound from a single-return-inferable fnctor call);
+ *   3. otherwise `undefined` → the consumer keeps its existing dynamic
+ *      (`__extern_get` / open-scan) lowering.
+ *
+ * **Conservative-closed**: a returned name is additionally gated on
+ * `ctx.structMap.has(name)`, so a struct not (yet) registered at the call site
+ * yields `undefined` rather than a dangling pin — a miss NEVER produces a wrong
+ * struct. **INERT in PART-1**: exported for the PART-2 dispatch to consume; no
+ * lowering calls it yet, so emitted Wasm is byte-identical.
+ */
+export declare function resolveReceiverStruct(ctx: CodegenContext, fctx: FunctionContext, recvExpr: ts.Expression): string | undefined;
+/**
+ * #2660 S1 — classify every `new F()` fnctor site in the program.
+ *
+ * @param checker     the program type checker
+ * @param sourceFile  the (already import-preprocessed) module source
+ * @returns a frozen {@link FnctorEscapeGateResult}; empty when no fnctor `new`
+ *          sites exist (so the pass is a no-op for class-only / fnctor-free code).
+ */
+export declare function analyzeFnctorEscapeGate(checker: ts.TypeChecker, sourceFile: ts.SourceFile): FnctorEscapeGateResult;

package/dist/codegen/function-body.d.ts

@@ -0,0 +1,52 @@
+import { ts } from '../ts-api.js';
+import { WasmFunction } from '../ir/types.js';
+import { CodegenContext } from './context/types.js';
+/** Maximum number of instructions for a function body to be considered inlinable */
+export declare const INLINE_MAX_INSTRS = 10;
+/** Set of instruction ops that disqualify a function body from inlining */
+export declare const INLINE_DISALLOWED_OPS: Set<string>;
+/**
+ * #1120: Detect locals that should be allocated as `i32` instead of `f64`
+ * because every value flowing through them is constrained to a 32-bit
+ * signed integer by explicit `| 0` (or other bitwise) coercion.
+ *
+ * The classic pattern, from the iterative Fibonacci benchmark, is:
+ *
+ *     let a = 0;
+ *     let b = 1;
+ *     for (let i = 0; i < n; i++) {
+ *       const next = (a + b) | 0;   // every write is ToInt32-coerced
+ *       a = b;
+ *       b = next;
+ *     }
+ *
+ * Each of `a`, `b`, and `next` only ever holds an int32, so allocating
+ * them as f64 forces the compiler into a heavy `f64 -> ToInt32 -> f64`
+ * round-trip on every iteration. By proving they are i32 we let the
+ * binary-op layer collapse the loop body to native i32 arithmetic.
+ *
+ * Detection rules (conservative; any rule failing leaves the local as f64):
+ *   1. Declared via `let` or `const` (not `var`, not module-global, not param).
+ *   2. Initializer is i32-safe (see `isI32SafeExpr`).
+ *   3. Every assignment / compound-assignment / increment/decrement to the
+ *      local also produces an i32-safe value.
+ *
+ * The set is fixpoint-iterated because membership of one local can depend
+ * on membership of another (e.g. `a = b; b = next;` requires all three
+ * to reach the i32 set together).
+ */
+export declare function collectI32CoercedLocals(decl: ts.FunctionLikeDeclaration): Set<string>;
+/**
+ * After compiling a function, check if it is eligible for call-site inlining.
+ * Criteria:
+ * - Body has <= INLINE_MAX_INSTRS instructions
+ * - No control flow, calls, or local mutations
+ * - No extra locals beyond parameters
+ * - Not a rest-param or capture function
+ */
+export declare function registerInlinableFunction(ctx: CodegenContext, funcName: string, func: WasmFunction): void;
+export declare function compileFunctionBody(ctx: CodegenContext, decl: ts.FunctionDeclaration, func: WasmFunction): void;
+/**
+ * Build throw instructions for TypeError when destructuring null/undefined.
+ * Per JS spec, destructuring null/undefined must throw TypeError.
+ */

package/dist/codegen/generators-native.d.ts

@@ -0,0 +1,92 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext, NativeGeneratorInfo } from './context/types.js';
+/**
+ * (#2571) A native-generator candidate is either a named `function*`
+ * declaration or a class / object-literal generator METHOD. Both expose
+ * `.body` / `.parameters` / `.asteriskToken` / `.name`, so the plan builder and
+ * the state model treat them uniformly; the only method-specific handling is the
+ * synthetic `this` leading param (threaded in `registerNativeGenerator`).
+ */
+export type GeneratorDecl = ts.FunctionDeclaration | ts.MethodDeclaration;
+export declare function isNativeGeneratorCandidate(ctx: CodegenContext, decl: GeneratorDecl): boolean;
+export declare function sourceNeedsGeneratorHostImports(ctx: CodegenContext, sourceFile: ts.SourceFile): boolean;
+/**
+ * Result struct (`{ value, done }`) for a generator whose yields have the given
+ * `elemValType`. The numeric (f64) variant is cached on
+ * `ctx.nativeGeneratorResultTypeIdx` (the historical singleton, kept so the many
+ * f64 callers are unchanged); any other elem type (e.g. the native string ref,
+ * #2171) gets its own `__NativeGeneratorResult_<kind>` struct, cached in
+ * `structMap` by name. Defaults to f64 when no elem type is supplied.
+ */
+export declare function ensureNativeGeneratorResultType(ctx: CodegenContext, elemValType?: ValType): number;
+export declare function registerNativeGenerator(ctx: CodegenContext, decl: GeneratorDecl, functionName: string, paramTypes: ValType[], synthesizedThis?: boolean): NativeGeneratorInfo | null;
+export declare function ensureNativeGeneratorResumeFunction(ctx: CodegenContext, info: NativeGeneratorInfo): number;
+export declare function compileNativeGeneratorFunction(ctx: CodegenContext, fctx: FunctionContext, decl: GeneratorDecl, info: NativeGeneratorInfo): void;
+export declare function tryCompileNativeGeneratorMethodCall(ctx: CodegenContext, fctx: FunctionContext, receiverExpr: ts.Expression, methodName: string, args: readonly ts.Expression[]): ValType | null | undefined;
+export declare function tryCompileNativeGeneratorResultProperty(ctx: CodegenContext, fctx: FunctionContext, resultExpr: ts.Expression, propName: string): ValType | null | undefined;
+/**
+ * Look up a native-generator info by the **TS type** of a for-of subject
+ * expression, mapping the resolved wasm state struct typeIdx back to its
+ * NativeGeneratorInfo. Returns undefined when the subject is not a native
+ * generator value.
+ */
+export declare function nativeGeneratorInfoForForOfSubject(ctx: CodegenContext, subjectType: ValType): NativeGeneratorInfo | undefined;
+/**
+ * #1665 — drive a `for (… of gen())` loop over a Wasm-native generator state
+ * machine WITHOUT the JS-host iterator protocol. The generator state ref is
+ * expected to already be on the stack (the caller compiled the iterable
+ * expression); `subjectType` is its ValType.
+ *
+ * Emits, structurally identical to the host iterator loop but calling the
+ * generator's resume function directly:
+ *
+ *   iter = <subject>
+ *   block:
+ *     loop:
+ *       res = __gen_resume_<g>(iter)        ;; ref $result {value:f64, done:i32}
+ *       if (res.done) br block
+ *       elem = res.value                    ;; f64 (or coerced to elem decl type)
+ *       <body>
+ *       br loop
+ *
+ * Only numeric (f64) yields are supported by the existing native generator
+ * (`isNativeGeneratorCandidate`), so the loop variable is f64. Returns true on
+ * success; false (with the stack untouched-by-contract: caller resets) when the
+ * shape is unsupported so the caller can fall back.
+ */
+export declare function tryCompileNativeGeneratorForOf(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForOfStatement, subjectType: ValType, info: NativeGeneratorInfo): boolean;
+/**
+ * #2169 — materialize a Wasm-native generator into a `__vec` of f64 by driving
+ * its resume function to completion, WITHOUT the JS-host iterator protocol.
+ *
+ * The non-`for-of` iterator consumers (array spread `[...g()]`, `Array.from(g())`,
+ * array-destructuring `[a,b]=g()`) previously treated the generator's state
+ * struct as if it were a `__vec` (reading field 0 as a `$length`), producing a
+ * garbage-length array of defaults / leaking host imports. This helper gives
+ * them the same `next()`-until-`done` drain the for-of driver uses, but
+ * collects the values into a growable backing array and leaves a freshly
+ * constructed `ref $vec_f64` on the stack (so the caller can treat it as a
+ * normal materialized vec).
+ *
+ * Contract: the generator state ref (`subjectType`, a ref/ref_null to the
+ * `info.stateTypeIdx` struct) MUST already be on the stack. On return the stack
+ * top is `(ref <vecTypeIdx>)` of element type f64. Numeric yields only (native
+ * generators are numeric today; non-numeric is #2171 / SF-4).
+ *
+ * The vec struct layout matches `getVecInfo`: field 0 = `$length` (i32),
+ * field 1 = `$data` (ref $arr). `vecTypeIdx`/`arrTypeIdx` are supplied by the
+ * caller (an f64 vec from `getOrRegisterVecType`).
+ *
+ * `trimToLength` (#2169 destructure consumer): when true, the backing array is
+ * resized to EXACTLY `len` before the final `struct.new`, so `array.len(data)`
+ * equals the logical `$length`. The default (false) leaves the capacity-padded
+ * array in place — fine for consumers that read the `$length` field (spread,
+ * Array.from), but the array-destructuring path bounds-checks against
+ * `array.len(data)` (`emitBoundsCheckedArrayGet`), so a capacity-padded array
+ * would make an out-of-length index read a default-initialized `0.0` slot
+ * instead of being OOB, silently skipping binding defaults (`const [a,b=9]=g()`
+ * with one yield). Trimming restores the literal-array invariant the destructure
+ * machinery relies on (backing-array length == logical length).
+ */
+export declare function emitNativeGeneratorToVec(ctx: CodegenContext, fctx: FunctionContext, info: NativeGeneratorInfo, subjectType: ValType, vecTypeIdx: number, arrTypeIdx: number, trimToLength?: boolean): void;

package/dist/codegen/helpers/body-references-own-this.d.ts

@@ -0,0 +1,22 @@
+import { ts } from '../../ts-api.js';
+/**
+ * #2152 — Check whether a node tree references `this` in its OWN function scope.
+ *
+ * A non-arrow `function` / method / accessor / constructor / class rebinds
+ * `this`, so a `this` inside such a nested scope is unrelated to the function
+ * whose body we are scanning — we do NOT descend into those. Arrow functions
+ * are lexically `this`-bound, so a `this` inside a nested arrow DOES refer to
+ * the enclosing function's `this` and counts — we traverse into arrows.
+ *
+ * Used to decide whether a (nested or top-level) function declaration body
+ * should read the `__current_this` module global for `this` (#1636-S1 / #1702):
+ * when such a function is passed by reference as an array-HOF callback
+ * (`arr.filter(callbackfn, thisArg)`), the dispatcher installs the spec
+ * `thisArg` into `__current_this` before the `call_ref`. For direct calls the
+ * global is null and the null-guarded read falls back to `undefined`, so
+ * enabling the read is behavior-preserving for ordinary calls.
+ *
+ * Iterative DFS to avoid stack overflow on deep ASTs (CI cgroup limits,
+ * mirrors `bodyUsesArguments`), memoized so overlapping subtrees stay O(N).
+ */
+export declare function bodyReferencesOwnThis(node: ts.Node): boolean;

package/dist/codegen/helpers/body-uses-arguments.d.ts

@@ -0,0 +1,12 @@
+import { ts } from '../../ts-api.js';
+/**
+ * Check if a node tree references the `arguments` identifier.
+ * Skips nested function declarations and function expressions (which have
+ * their own `arguments` binding), but traverses into arrow functions
+ * because arrows inherit the enclosing function's `arguments`.
+ *
+ * Uses iterative DFS to avoid stack overflow on deeply nested ASTs
+ * (CI cgroup limits, #1085). Results are memoized so repeated calls on
+ * overlapping subtrees collapse from O(N²) to O(N) total (#1086).
+ */
+export declare function bodyUsesArguments(node: ts.Node): boolean;