@loopdive/js2 0.57.0

package/dist/codegen/registry/imports.d.ts

@@ -0,0 +1,46 @@
+import { Import } from '../../ir/types.js';
+import { CodegenContext } from '../context/types.js';
+/**
+ * Register an import (`module.name`) on the current module.
+ *
+ * Under `ctx.strictNoHostImports` (auto-on for `--target wasi`, controllable
+ * via `--no-host-imports` / `--allow-host-imports` on the CLI; see #1524),
+ * any `env`-module import that is not on the dual-mode allowlist
+ * (`src/codegen/host-import-allowlist.ts`) is rejected with a structured
+ * compile error referencing the tracking issue. The error is pushed onto
+ * `ctx.errors`; the import itself is silently dropped to avoid producing a
+ * module that references a nonexistent function index. Downstream code that
+ * attempts to `call` the dropped function will fail validation if the
+ * caller did not check `result.success` before consuming the binary.
+ *
+ * `wasi_snapshot_preview1` imports are always allowed; they are the canonical
+ * WASI ABI, not JS-host bindings.
+ *
+ * `wasm:js-string` / `string_constants` are JS-host bindings but are usually
+ * not requested under strict mode because `nativeStrings` is auto-enabled.
+ * If they ARE requested under strict mode, the gate rejects them with a
+ * dedicated error pointing the user at the nativeStrings option.
+ */
+export declare function addImport(ctx: CodegenContext, module: string, name: string, desc: Import["desc"]): void;
+/**
+ * Register a string literal as a global import from the "string_constants"
+ * namespace and repair already-compiled module-global references if needed.
+ *
+ * In `nativeStrings` mode (auto-on for `--target wasi`), no JS host runtime
+ * exists to satisfy the import, so we skip the import and just record the
+ * string in `stringGlobalMap` with the sentinel `-1` (the same convention
+ * used by `collectStringLiterals` finalize). Call sites that materialize a
+ * string constant onto the stack must check the sentinel and use the native
+ * string path (`compileNativeStringLiteral` + `extern.convert_any` for the
+ * externref-typed throw payload) instead of `global.get`. (#1174)
+ */
+export declare function addStringConstantGlobal(ctx: CodegenContext, value: string): void;
+/** Return the absolute Wasm global index for a new module-defined global. */
+export declare function nextModuleGlobalIdx(ctx: CodegenContext): number;
+/** Convert an absolute Wasm global index to a local module-globals array index. */
+export declare function localGlobalIdx(ctx: CodegenContext, absIdx: number): number;
+/**
+ * Lazily register the exception tag used by throw/try-catch.
+ * The tag has signature (externref) — all thrown values are externref.
+ */
+export declare function ensureExnTag(ctx: CodegenContext): number;

package/dist/codegen/registry/types.d.ts

@@ -0,0 +1,59 @@
+import { FuncTypeDef, ValType } from '../../ir/types.js';
+import { CodegenContext } from '../context/types.js';
+export declare function addFuncType(ctx: CodegenContext, params: ValType[], results: ValType[], name?: string): number;
+export declare function funcTypeEq(t: FuncTypeDef, params: ValType[], results: ValType[]): boolean;
+/**
+ * Get or register a Wasm array type for a given element kind.
+ * Reuses existing registrations so each element type only gets one array type.
+ */
+export declare function getOrRegisterArrayType(ctx: CodegenContext, elemKind: string, elemTypeOverride?: ValType): number;
+/**
+ * (#2186) Get or register the shared `$__vec_base` supertype struct — a single
+ * `(length i32)` field that every concrete `__vec_<elemKind>` subtypes. This
+ * gives standalone runtime helpers a uniform `ref.test $__vec_base` /
+ * `ref.cast $__vec_base` → `struct.get 0` path to read a boxed array's length
+ * regardless of its element kind (the array-length-through-externref boundary
+ * fix). Declared open (`superTypeIdx: -1`) so vecs can extend it. Idempotent.
+ */
+export declare function getOrRegisterVecBaseType(ctx: CodegenContext): number;
+/**
+ * Get or register a vec struct type wrapping a Wasm GC array.
+ * The vec struct has {length: i32, data: (ref $__arr_<elemKind>)}.
+ */
+export declare function getOrRegisterVecType(ctx: CodegenContext, elemKind: string, elemTypeOverride?: ValType): number;
+/**
+ * (#2159 / #2357 / #47) Get or register the `$__subview_<elemKind>` struct — a
+ * TypedArray `subarray` view that SHARES the parent's backing array:
+ *   `{length: i32, data: (ref null $__arr_<elemKind>), byteOffset: i32}`.
+ *
+ * `length` is field 0 (subtypes `$__vec_base`) so uniform `.length` reads and the
+ * externref-length helper keep working. `data` holds the PARENT's backing array
+ * DIRECTLY (shared — no copy); `byteOffset` is the element offset of the window
+ * into that array. We deliberately store the array type (`$__arr_<elemKind>`,
+ * uniquely deduped per element kind) rather than a concrete vec struct idx,
+ * because the same element kind can be registered behind multiple vec struct
+ * indices in a module (hoist-time vs body-time) — pinning to the array type makes
+ * the subview idx-stable. Element access on a `$__subview` receiver reads
+ * `data[byteOffset + i]`; a plain vec reads `vec.data[i]` unchanged. The
+ * discrimination is by the receiver's static ValType.typeIdx at COMPILE time, so
+ * the plain-array hot path is untouched. Keyed per element kind. Idempotent.
+ */
+export declare function getOrRegisterSubviewType(ctx: CodegenContext, elemKind: string, elemTypeOverride?: ValType): number;
+/** (#2357) The backing array type idx for a `$__subview_<elem>` struct (field 1). */
+export declare function getSubviewArrTypeIdx(ctx: CodegenContext, subviewTypeIdx: number): number;
+/** (#2357) True iff `typeIdx` is a registered `$__subview_<elem>` struct. */
+export declare function isSubviewTypeIdx(ctx: CodegenContext, typeIdx: number): boolean;
+/**
+ * Get or register the template vec struct type for tagged template string arrays.
+ */
+export declare function getOrRegisterTemplateVecType(ctx: CodegenContext): number;
+/**
+ * Get or register a ref cell struct type for mutable closure captures.
+ */
+export declare function getOrRegisterRefCellType(ctx: CodegenContext, valType: ValType): number;
+/** Get the raw array type index from a vec struct type index. */
+export declare function getArrTypeIdxFromVec(ctx: CodegenContext, vecTypeIdx: number): number;
+/**
+ * Register the WasmGC types for native strings (rope/cons-string support).
+ */
+export declare function registerNativeStringTypes(ctx: CodegenContext): void;

package/dist/codegen/set-algebra.d.ts

@@ -0,0 +1,17 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * Emit the 7 set-algebra helpers (idempotent). Names registered in
+ * `ctx.mapHelpers`: `__set_union` / `__set_intersection` / `__set_difference` /
+ * `__set_symmetricDifference` / `__set_isSubsetOf` / `__set_isSupersetOf` /
+ * `__set_isDisjointFrom`. Each is `(ref $Map, ref $Map) -> {ref $Map | i32}`.
+ */
+export declare function ensureSetAlgebraHelpers(ctx: CodegenContext): void;
+/**
+ * (#2162) Intercept an ES2025 Set set-algebra method call in standalone /
+ * nativeStrings mode. Both the receiver and the single argument must type as a
+ * Set (the WasmGC `$Map` struct); otherwise return undefined to let the generic
+ * path try. Receiver + arg are compiled here.
+ */
+export declare function tryCompileNativeSetAlgebraCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;

package/dist/codegen/set-runtime.d.ts

@@ -0,0 +1,74 @@
+import { ValType } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * Emit the `__set_add(m, v) -> ref $Map` helper (idempotent). `Set.add` stores
+ * the element as both key and value so the shared Map lookup/iteration sees a
+ * normal entry; the return value is the map itself (Set.add is chainable and
+ * returns the Set, spec 24.2.3.1).
+ */
+export declare function ensureSetHelpers(ctx: CodegenContext): void;
+/**
+ * (#2604) `[[SetData]]` brand-check for a reflectively-invoked Set method
+ * receiver (`Set.prototype.METHOD.call(recv, …)` / `inst.METHOD.call(recv, …)`).
+ * Consumes the just-compiled receiver value (`recvType` describes what is on the
+ * stack) and leaves a non-null `(ref $Map)` — the validated backing struct — on
+ * the stack.
+ *
+ * Spec 24.2.3.* step "If S does not have a [[SetData]] internal slot, throw a
+ * TypeError": uses a NON-TRAPPING `ref.test $Map` (0/1, never traps on
+ * null/primitive/wrong-struct) then branches — a miss throws a *catchable*
+ * `TypeError` (NOT `ref.cast`, which would trap `illegal cast`, which test262
+ * `assert.throws(TypeError, …)` does not accept). On a hit the value is
+ * `ref.cast`-ed (safe — the test passed) to `(ref $Map)`.
+ *
+ * NOTE: a real `Map`/`WeakSet` is ALSO `$Map`-backed and passes `ref.test $Map`;
+ * distinguishing Set from Map/Weak by struct alone is not possible without a
+ * kind tag (the `does-not-have-setdata-internal-slot-{map,weakset}.js` sub-rows,
+ * a documented stretch — #2604). The primitive / plain-object / array / null
+ * rows (the bulk) flip here.
+ */
+export declare function emitSetBrandCheck(ctx: CodegenContext, fctx: FunctionContext, recvType: ValType | null): void;
+/**
+ * (#2162) Intercept a `Set.prototype.*` method call in standalone /
+ * `nativeStrings` mode and route it to the WasmGC-native Set/Map runtime.
+ * Returns the result `InnerResult` when handled, or `undefined` to let the
+ * generic extern/host path proceed (JS-host mode, or unsupported methods).
+ *
+ * Receiver and arguments are compiled here.
+ */
+export declare function tryCompileNativeSetMethodCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;
+/**
+ * (#2604) Reflective `Set.prototype.METHOD.call(recv, …)` /
+ * `inst.METHOD.call(recv, …)` dispatch with a `[[SetData]]` brand-check.
+ *
+ * The direct `s.METHOD(v)` shape is handled by {@link tryCompileNativeSetMethodCall}
+ * (gated on the receiver's static `className === "Set"`); the reflective `.call`
+ * shape never reaches it, so neither the native dispatch nor the spec brand-check
+ * (24.2.3.* "If S does not have a [[SetData]] internal slot, throw a TypeError")
+ * fires. This handler recognises the `.call` form, compiles the FIRST `.call`
+ * argument as the receiver, brand-checks it ({@link emitSetBrandCheck} →
+ * catchable TypeError on a non-Set), then routes the remaining args to the same
+ * `__set_add`/`__map_has`/`__map_delete`/`__map_clear` helpers.
+ *
+ * Returns the result `InnerResult` when handled, or `undefined` to fall through.
+ * Scoped to add/has/delete/clear (the bulk of the ~84-row brand-check bucket);
+ * forEach/keys/values/entries reflective forms fall through (rarer). `.apply`
+ * (packed-args) is deferred — only `.call` is intercepted here.
+ */
+/**
+ * (#2604) Cheap syntactic predicate (NO codegen): does `expr` match the
+ * reflective Set data-method `.call` shape this module dispatches? The caller
+ * (calls.ts) uses it to gate an `addUnionImports` BEFORE invoking
+ * {@link tryCompileSetReflectiveCall} — the arg-boxing (`__box_number`) the
+ * dispatch emits must be registered up-front (the direct path relies on
+ * extern.ts doing the same), since adding it mid-body would shift indices.
+ */
+export declare function isSetReflectiveCallShape(ctx: CodegenContext, expr: ts.CallExpression): boolean;
+export declare function tryCompileSetReflectiveCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;
+/**
+ * (#2162) Intercept the `Set.prototype.size` accessor in standalone /
+ * `nativeStrings` mode → `__map_size` (returns i32). Receiver compiled here.
+ */
+export declare function tryCompileNativeSetSizeGet(ctx: CodegenContext, fctx: FunctionContext, receiver: ts.Expression): InnerResult | undefined;

package/dist/codegen/shared.d.ts

@@ -0,0 +1,111 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/** Sentinel: expression compiled successfully but produces no value (void) */
+export declare const VOID_RESULT: unique symbol;
+export type InnerResult = ValType | null | typeof VOID_RESULT;
+/**
+ * When `this` is typed as `any` (e.g., in function constructors), resolve the
+ * struct name from the local's ref type index. Used as a fallback when
+ * resolveStructName returns undefined for `this`-property accesses/assignments.
+ */
+/**
+ * Skip "transparent" wrapper expressions that have no runtime effect — parens,
+ * `as`/`<T>` casts, `satisfies`, and non-null `!` — to reach the underlying
+ * expression. The local stand-in for `ts.skipOuterExpressions` (not surfaced by
+ * the project's ts-api shim). Used to let `(this as any).x` / `(B as any).c`
+ * resolve to the same receiver as `this.x` / `B.c` (#2020/#2027).
+ */
+export declare function skipTransparentExpressions(expr: ts.Expression): ts.Expression;
+export declare function resolveThisStructName(ctx: CodegenContext, fctx: FunctionContext): string | undefined;
+/** Check if two ValTypes are structurally equal */
+export declare function valTypesMatch(a: ValType, b: ValType): boolean;
+export declare function getLine(node: ts.Node): number;
+export declare function getCol(node: ts.Node): number;
+/**
+ * Fail fast at compile entry if any required codegen delegate is still its
+ * throwing stub (#2146). Without this, a missing registration surfaces only
+ * deep inside codegen — as an obscure "X not yet registered" — when (and if)
+ * the relevant feature happens to be exercised by the input program.
+ *
+ * Call this once per top-level codegen entry (`generateModule` /
+ * `generateMultiModule`). It is O(slots) and has no effect in the normal path
+ * where `src/compiler.ts` eagerly imports the registrar modules.
+ */
+export declare function assertCodegenRegistrationsComplete(): void;
+type CompileExpressionFn = (ctx: CodegenContext, fctx: FunctionContext, expr: ts.Expression, expectedType?: ValType) => ValType | null;
+export declare function registerCompileExpression(fn: CompileExpressionFn): void;
+export declare function compileExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.Expression, expectedType?: ValType): ValType | null;
+type CompileArrowAsClosureFn = (ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression) => ValType | null;
+export declare function registerCompileArrowAsClosure(fn: CompileArrowAsClosureFn): void;
+export declare function compileArrowAsClosure(ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression): ValType | null;
+type EmitBoundsCheckedArrayGetFn = (fctx: FunctionContext, arrTypeIdx: number, elementType: ValType, ctx?: CodegenContext, useUndefinedSentinel?: boolean) => void;
+export declare function registerEmitBoundsCheckedArrayGet(fn: EmitBoundsCheckedArrayGetFn): void;
+export declare function emitBoundsCheckedArrayGet(fctx: FunctionContext, arrTypeIdx: number, elementType: ValType, ctx?: CodegenContext, useUndefinedSentinel?: boolean): void;
+/**
+ * Best-effort name of the class lexically enclosing `fctx`. Prefers the
+ * explicit `enclosingClassName` carried on the context; otherwise falls back to
+ * the `${Class}_${method}` naming convention baked into compiled method names.
+ */
+export declare function resolveEnclosingClassName(fctx: FunctionContext): string | undefined;
+type CoerceTypeFn = (ctx: CodegenContext, fctx: FunctionContext, from: ValType, to: ValType, toPrimitiveHint?: "number" | "string" | "default") => void;
+export declare function registerCoerceType(fn: CoerceTypeFn): void;
+export declare function coerceType(ctx: CodegenContext, fctx: FunctionContext, from: ValType, to: ValType, toPrimitiveHint?: "number" | "string" | "default"): void;
+type MaterializeStructAsObjectFn = (ctx: CodegenContext, fctx: FunctionContext, structTypeIdx: number) => boolean;
+export declare function registerMaterializeStructAsObject(fn: MaterializeStructAsObjectFn): void;
+export declare function materializeStructAsObject(ctx: CodegenContext, fctx: FunctionContext, structTypeIdx: number): boolean;
+type EnsureLateImportFn = (ctx: CodegenContext, name: string, paramTypes: ValType[], resultTypes: ValType[]) => number | undefined;
+type FlushLateImportShiftsFn = (ctx: CodegenContext, fctx: FunctionContext | null) => void;
+export declare function registerEnsureLateImport(fn: EnsureLateImportFn): void;
+export declare function registerFlushLateImportShifts(fn: FlushLateImportShiftsFn): void;
+export declare function ensureLateImport(ctx: CodegenContext, name: string, paramTypes: ValType[], resultTypes: ValType[]): number | undefined;
+export declare function flushLateImportShifts(ctx: CodegenContext, fctx: FunctionContext | null): void;
+/**
+ * Check if a ValType is the any-value boxed type used for TS `any`.
+ */
+export declare function isAnyValue(type: ValType, ctx: CodegenContext): boolean;
+type EnsureAnyHelpersFn = (ctx: CodegenContext) => void;
+export declare function registerEnsureAnyHelpers(fn: EnsureAnyHelpersFn): void;
+type AddUnionImportsFn = (ctx: CodegenContext) => void;
+export declare function registerAddUnionImports(fn: AddUnionImportsFn): void;
+export declare function addUnionImportsViaRegistry(ctx: CodegenContext): void;
+export declare function ensureAnyHelpers(ctx: CodegenContext): void;
+type ResolveComputedKeyExpressionFn = (ctx: CodegenContext, expr: ts.Expression) => string | undefined;
+export declare function registerResolveComputedKeyExpression(fn: ResolveComputedKeyExpressionFn): void;
+export declare function resolveComputedKeyExpression(ctx: CodegenContext, expr: ts.Expression): string | undefined;
+type CompileStatementFn = (ctx: CodegenContext, fctx: FunctionContext, stmt: ts.Statement) => void;
+export declare function registerCompileStatement(fn: CompileStatementFn): void;
+export declare function compileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.Statement): void;
+type EnsureBindingLocalsFn = (ctx: CodegenContext, fctx: FunctionContext, pattern: ts.BindingPattern) => void;
+export declare function registerEnsureBindingLocals(fn: EnsureBindingLocalsFn): void;
+export declare function ensureBindingLocals(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.BindingPattern): void;
+type HoistFunctionDeclarationsFn = (ctx: CodegenContext, fctx: FunctionContext, stmts: ts.NodeArray<ts.Statement> | ts.Statement[]) => void;
+export declare function registerHoistFunctionDeclarations(fn: HoistFunctionDeclarationsFn): void;
+export declare function hoistFunctionDeclarations(ctx: CodegenContext, fctx: FunctionContext, stmts: ts.NodeArray<ts.Statement> | ts.Statement[]): void;
+type EmitNestedBindingDefaultFn = (ctx: CodegenContext, fctx: FunctionContext, nestedLocal: number, valueType: ValType, initializer: ts.Expression) => void;
+export declare function registerEmitNestedBindingDefault(fn: EmitNestedBindingDefaultFn): void;
+export declare function emitNestedBindingDefault(ctx: CodegenContext, fctx: FunctionContext, nestedLocal: number, valueType: ValType, initializer: ts.Expression): void;
+type EmitDefaultValueCheckFn = (ctx: CodegenContext, fctx: FunctionContext, fieldType: ValType, localIdx: number, initializer: ts.Expression, targetType?: ValType, objectPropertySemantics?: boolean) => void;
+export declare function registerEmitDefaultValueCheck(fn: EmitDefaultValueCheckFn): void;
+export declare function emitDefaultValueCheck(ctx: CodegenContext, fctx: FunctionContext, fieldType: ValType, localIdx: number, initializer: ts.Expression, targetType?: ValType, objectPropertySemantics?: boolean): void;
+type EmitArgumentsObjectFn = (ctx: CodegenContext, fctx: FunctionContext, paramTypes: ValType[], paramOffset: number, unmapped?: boolean) => void;
+export declare function registerEmitArgumentsObject(fn: EmitArgumentsObjectFn): void;
+/**
+ * `unmapped`: when true (strict-mode functions, §10.4.4) the param↔arguments
+ * sync is suppressed so writes to `arguments[i]` do not flow back into the
+ * named parameter (#779e). Defaults to false (sloppy, mapped).
+ */
+export declare function emitArgumentsObject(ctx: CodegenContext, fctx: FunctionContext, paramTypes: ValType[], paramOffset: number, unmapped?: boolean): void;
+type CompileStringLiteralFn = (ctx: CodegenContext, fctx: FunctionContext, value: string, node?: ts.Node) => ValType | null;
+export declare function registerCompileStringLiteral(fn: CompileStringLiteralFn): void;
+export declare function compileStringLiteral(ctx: CodegenContext, fctx: FunctionContext, value: string, node?: ts.Node): ValType | null;
+type CompileSuperPropertyAccessFn = (ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression, propName: string) => ValType | null;
+export declare function registerCompileSuperPropertyAccess(fn: CompileSuperPropertyAccessFn): void;
+export declare function compileSuperPropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression, propName: string): ValType | null;
+type CompileSuperElementAccessFn = (ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression) => ValType | null;
+export declare function registerCompileSuperElementAccess(fn: CompileSuperElementAccessFn): void;
+export declare function compileSuperElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+type AddStringImportsFn = (ctx: CodegenContext) => void;
+export declare function registerAddStringImports(fn: AddStringImportsFn): void;
+export declare function addStringImportsDelegate(ctx: CodegenContext): void;
+export {};

package/dist/codegen/stack-balance.d.ts

@@ -0,0 +1,43 @@
+import { WasmModule } from '../ir/types.js';
+export type FixupKind = "drop-excess" | "default-value-lossy" | "branch-type-coerce" | "branch-type-cast" | "call-arg-coerce" | "struct-field-coerce" | "local-set-coerce";
+/** A single located fixup the pass applied while repairing emitter output. */
+export interface FixupEvent {
+    readonly kind: FixupKind;
+    /** Name of the function (or `func#N`) the fixup was applied in. */
+    readonly func: string;
+    /** Human-readable detail (e.g. `f64 default for missing branch value`). */
+    readonly detail: string;
+    /** True for repairs that can change runtime semantics (currently the const-default arm). */
+    readonly lossy: boolean;
+}
+/**
+ * Events collected during the most recent `stackBalance(mod)` run (#1918).
+ * Returns a copy so callers can't mutate the collector. `stackBalance` resets
+ * it at the start of every run, so this reflects exactly one module's repairs.
+ */
+export declare function getFixupEvents(): FixupEvent[];
+/** Aggregate fixup events into per-kind counts (#1918). Always includes every kind. */
+export declare function summarizeFixups(events: readonly FixupEvent[]): Record<FixupKind, number>;
+/** A strict-balance diagnostic ready to push onto a codegen error sink (#1918). */
+export interface StrictBalanceDiagnostic {
+    readonly message: string;
+    readonly line: 0;
+    readonly column: 0;
+    readonly severity: "error" | "warning";
+}
+/**
+ * Strict-balance mode (#1918). Controlled by `JS2WASM_STRICT_BALANCE`:
+ *
+ *   unset / "0" / "off"  — silent (default; preserves existing behaviour)
+ *   "1" / "true" / "warn" — every fixup becomes a located severity-"warning"
+ *   "error" / "strict"    — every fixup becomes a severity-"error" (fails the
+ *                            compile); for CI experiments and new code that
+ *                            should never need a repair.
+ *
+ * Returns the diagnostics to surface. The caller (`src/codegen/index.ts`,
+ * which holds `ctx`) pushes them onto `ctx.errors` — strict errors then fail
+ * the WasmGC compile through the existing `severity === "error"` gate, which
+ * `mod.codegenErrors` does NOT reach on the WasmGC path (see #2090).
+ */
+export declare function strictBalanceDiagnostics(events: readonly FixupEvent[]): StrictBalanceDiagnostic[];
+export declare function stackBalance(mod: WasmModule): number;

package/dist/codegen/statements/control-flow.d.ts

@@ -0,0 +1,25 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileReturnStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ReturnStatement): void;
+export declare function compileIfStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.IfStatement): void;
+export declare function compileSwitchStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.SwitchStatement): void;
+/**
+ * Destructure a for-of element stored in `elemLocal` into the bindings of a
+ * destructuring pattern. Handles both object and array binding patterns with
+ * default values.
+ */
+export declare function compileLabeledStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.LabeledStatement): void;
+export declare function compileBreakStatement(_ctx: CodegenContext, fctx: FunctionContext, stmt: ts.BreakStatement): void;
+export declare function compileContinueStatement(_ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ContinueStatement): void;
+/**
+ * Evaluate a condition expression at compile time if possible.
+ * Returns true/false for constant conditions, undefined if not constant.
+ *
+ * Handles:
+ * - `"x" === "y"`, `"x" !== "y"` (string literal comparisons)
+ * - `true`, `false` literals
+ * - `!<constant>` (prefix logical not)
+ * - `"x" == "y"`, `"x" != "y"` (loose equality on string literals)
+ * - `&&` and `||` with constant operands
+ */
+export declare function evaluateConstantCondition(expr: ts.Expression): boolean | undefined;

package/dist/codegen/statements/destructuring.d.ts

@@ -0,0 +1,177 @@
+import { ts } from '../../ts-api.js';
+import { ValType } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * (#1719 S1) Gate predicate for the array object-value representation track.
+ *
+ * Returns true iff array destructuring of a **typed vec / tuple RHS** must
+ * route through the host-Array reflection + host `GetIterator` lane instead of
+ * the backing-store fast path — i.e. when the program's `ITER_OVERRIDDEN`
+ * whole-program brand (`ctx.arrayIteratorMaybeOverridden`, set by
+ * `sourceOverridesArrayIterator`) is set AND the RHS is not a string.
+ *
+ * The string exclusion is load-bearing: a string is not an Array, so a
+ * monkeypatched `Array.prototype[@@iterator]` cannot affect string
+ * destructuring, and routing a string through the array iterator lane would
+ * regress string dstr (per the architecture spec).
+ *
+ * **S1 status (this PR):** this predicate establishes the *placement and
+ * string guard* the architecture spec mandates keeping from dev-a's
+ * scaffolding, but the routing target it gates is supplied by **S2** (the
+ * host-Array reflection helper + host `GetIterator`). Until S2 lands, callers
+ * evaluate this predicate but fall through to the existing fast path — so the
+ * predicate is correct and unit-tested while the codegen is behaviorally a
+ * no-op (zero test delta, the spec's S1 requirement). When
+ * `ctx.arrayIteratorMaybeOverridden` is false (the common case) this is always
+ * false, guaranteeing byte-identical output.
+ *
+ * Spec: §7.4.2 GetIterator, §8.5.2 IteratorBindingInitialization.
+ */
+export declare function arrayDstrNeedsIdentity(ctx: CodegenContext, isStringRHS: boolean): boolean;
+/**
+ * (#1719 CPR read-drive) Drive a captured `Array.prototype[@@iterator]` override
+ * for a typed-vec/tuple array-destructuring RHS, so the override's custom
+ * iterator (not the backing store) supplies the binding values
+ * (§8.5.2 IteratorBindingInitialization). PRECONDITION: the vec ref is on the
+ * stack and the caller gated on `arrayDstrNeedsIdentity && override-captured`.
+ *
+ * Scope (CPR-1): the binding pattern is all **identifier** elements (with optional
+ * `= default`) and elisions, **no rest / no nested** pattern — exactly the shape
+ * of the 71 `*-iter-val-array-prototype.js` tests. Returns `false` (caller falls
+ * through to the backing-store fast path) for rest/nested patterns so those are
+ * not regressed; CPR-2 widens the shape.
+ *
+ * Lowering: drive override → iterator (in-Wasm, `__drive_proto_iterator`), then
+ * per element `__iterator_next` → `(i32 done, externref value)`; on `done` the
+ * element takes its default (or `undefined`), else `value` coerced to the binding
+ * local's type. The brand only fires at this observation boundary, so internal
+ * array iterations inside the override body stay on the typed-vec fast path — no
+ * re-entrancy / no infinite loop.
+ */
+export declare function tryEmitArrayProtoIteratorReadDrive(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.ArrayBindingPattern, resultType: ValType, 
+/**
+ * (#1719 CPR-2) When provided, the array value is read from this local instead
+ * of consumed from the stack — lets the for-of-head / parameter dstr sites
+ * (whose value lives in a local) reuse this exact drive+drain. `undefined` ⇒
+ * the decl-dstr caller's convention (vec ref already on the stack).
+ */
+srcLocal?: number): boolean;
+export declare function ensureBindingLocals(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.BindingPattern): void;
+/**
+ * After destructuring, sync any bound locals that have corresponding module
+ * globals. Destructuring stores values into locals, but module-level variables
+ * need to also be written via global.set so other functions can read them.
+ */
+export declare function syncDestructuredLocalsToGlobals(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.BindingPattern): void;
+/**
+ * Wrap a set of destructuring instructions in a null guard.
+ *
+ * For `ref_null` source types the instructions are only executed when the
+ * reference is non-null:
+ *
+ *   local.get $srcLocal
+ *   ref.is_null
+ *   if (then: [] else: <instrs>)
+ *
+ * For non-nullable refs the instructions are emitted directly.
+ *
+ * `emitFn` should populate `fctx.body` with the instructions to guard.
+ * The helper temporarily swaps `fctx.body` so the caller's body is not
+ * modified by `emitFn`.
+ */
+export declare function emitNullGuard(ctx: CodegenContext, fctx: FunctionContext, srcLocal: number, isNullable: boolean, emitFn: () => void, srcKind?: ValType["kind"]): void;
+/**
+ * Ensure __async_iterator is available; return its function index.
+ *
+ * JS-host mode: register `env.__async_iterator`
+ *   (obj) => obj[Symbol.asyncIterator]?.() ?? obj[Symbol.iterator]()
+ *
+ * (#2038) Standalone / WASI: there is no JS host to satisfy that import, and
+ * feeding the host carrier to the native `__iterator_next` traps `illegal cast`.
+ * Per §7.4.3 GetIterator(async) + §27.1.4.1 CreateAsyncFromSyncIterator, for a
+ * **sync-backed** async iterable (the dominant test262 shape — `for await (x of
+ * [literals])` and `for await (x of syncIterable)`) the async iterator is the
+ * sync iterator with each value `Await`-ed; for an already-settled value
+ * `Await(v) = v`, so the async wrapper degenerates to the *identity* native
+ * iterator. So in standalone we return the SAME native `__iterator` the sync
+ * for-of consumer uses (now USER-`{next()}`-carrier aware). The per-element
+ * `Await` is layered by the for-await CPS lowering around the loop body and is a
+ * no-op for settled values — no `env.__async_iterator` / `env.Promise_resolve`
+ * leak. Genuinely-pending-Promise async iterables stay deferred to the standalone
+ * Promise runtime (PR-C).
+ */
+export declare function ensureAsyncIterator(ctx: CodegenContext, fctx: FunctionContext): number | undefined;
+/**
+ * Ensure __extern_is_undefined import is available.
+ * Returns the function index, or undefined if registration failed.
+ * JS impl: (v: unknown) => v === undefined ? 1 : 0
+ */
+export declare function ensureExternIsUndefined(ctx: CodegenContext, fctx: FunctionContext): number | undefined;
+/**
+ * Emit a check for whether an externref value should trigger a default value.
+ * Per JS spec, destructuring defaults apply when the value is `undefined`.
+ * We check both ref.is_null (wasm null, e.g. uninitialized array slots) and
+ * JS undefined (non-null externref wrapping the JS undefined value).
+ *
+ * Precondition: externref value on the stack and saved in tmpLocal.
+ * Postcondition: i32 on the stack (1 = use default, 0 = has value).
+ */
+export declare function emitExternrefDefaultCheck(ctx: CodegenContext, fctx: FunctionContext, tmpLocal: number): void;
+/**
+ * Emit a default-value check for a nested binding pattern in array destructuring.
+ *
+ * When an array element is a nested binding pattern with a default initializer
+ * (e.g. `[{ x, y } = defaults]`), we need to check if the extracted value is
+ * null/undefined and if so, compile the initializer and store it as the value
+ * before the nested destructuring runs.
+ */
+export declare function emitNestedBindingDefault(ctx: CodegenContext, fctx: FunctionContext, nestedLocal: number, valueType: ValType, initializer: ts.Expression): void;
+/**
+ * Emit a default-value check for a destructured binding.
+ *
+ * The stack must contain the extracted field/element value.  For externref
+ * types we check `ref.is_null || __extern_is_undefined` — JS destructuring
+ * defaults apply when the value is `undefined`.  For f64 we check for NaN
+ * (the "undefined" sentinel).  For i32 there is no reliable sentinel so we
+ * just assign directly.
+ *
+ * @param fieldType - the Wasm type of the value currently on the stack
+ * @param localIdx  - destination local for the bound variable
+ * @param initializer - the TS default-value expression
+ * @param targetType  - optional override for the type hint passed to compileExpression
+ * @param objectPropertySemantics - when true, the value originates from an
+ *   object property read (KeyedBindingInitialization §13.3.3.7), where every
+ *   declared field exists and a `null` value is a genuine JS `null` — NOT a
+ *   "missing" hole. Per spec the default fires only on `undefined`, so JS
+ *   `null` (encoded as wasm-null / ref.null.extern) must NOT trigger it. For
+ *   `ref`/`ref_null` fields we therefore convert to externref and use the
+ *   strict `__extern_is_undefined` predicate instead of `ref.is_null` (which
+ *   would wrongly fire for `null`). Array/iterator binding (§13.3.3.6) leaves
+ *   this false: a wasm-null element there can mean "iterator exhausted /
+ *   missing", which DOES fire the default.
+ */
+export declare function emitDefaultValueCheck(ctx: CodegenContext, fctx: FunctionContext, fieldType: ValType, localIdx: number, initializer: ts.Expression, targetType?: ValType, objectPropertySemantics?: boolean): void;
+export declare function compileObjectDestructuring(ctx: CodegenContext, fctx: FunctionContext, decl: ts.VariableDeclaration): void;
+/**
+ * Destructure an externref value using the shared param-destructure helper
+ * (`destructureParamObject` in decl mode).
+ *
+ * Fallback for when the source type is unknown/any/externref (no struct info
+ * available). The externref on the WasmGC stack is stashed into a temp local
+ * and handed to `destructureParamObject`, which routes through its externref
+ * branch — including the `ref.test`/`struct.get` fast path for known struct
+ * types, per-element null/undefined guards, NamedEvaluation of function/class
+ * defaults, and enumerable-correct rest collection. This replaces the legacy
+ * twin that had drifted from the param path (#1553c — root causes 1, 2, 4, 8).
+ *
+ * @deprecated Internal callers (nested patterns, for-of/for-in heads) still
+ * reach this shim; the export is retained for compile compatibility until
+ * #1553d removes it. New code should call `destructureParamObject` directly.
+ */
+export declare function compileExternrefObjectDestructuringDecl(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.ObjectBindingPattern, resultType: ValType): void;
+/**
+ * Destructure an externref value using __extern_get(obj, boxed_index) for each element.
+ * Handles cases where the RHS is dynamically typed (e.g. arguments, iterators, function returns).
+ */
+export declare function compileExternrefArrayDestructuringDecl(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.ArrayBindingPattern, resultType: ValType): void;
+export declare function compileArrayDestructuring(ctx: CodegenContext, fctx: FunctionContext, decl: ts.VariableDeclaration): void;

package/dist/codegen/statements/exceptions.d.ts

@@ -0,0 +1,11 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileThrowStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ThrowStatement): void;
+export declare function compileTryStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.TryStatement): void;
+/** Compile a function declaration nested inside another function.
+ *  Lifts the function to module level. If it captures outer-scope variables,
+ *  uses a closure struct (like arrow closures). Otherwise uses a direct call. */
+/**
+ * Handle a ClassDeclaration in statement position (inside for loops, if blocks, etc.).
+ * Collects the class struct/methods and compiles their bodies immediately.
+ */

package/dist/codegen/statements/functions.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codegen/statements/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/codegen/statements/loops.d.ts

@@ -0,0 +1,7 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileWhileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.WhileStatement): void;
+export declare function compileForStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForStatement): void;
+export declare function compileDoWhileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.DoStatement): void;
+export declare function compileForOfStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForOfStatement): void;
+export declare function compileForInStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.ForInStatement): void;