@loopdive/js2 0.57.0

package/dist/codegen/builtin-tags.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Built-in type-tag registry for `instanceof` short-circuit evaluation.
+ *
+ * Built-in JS types like `Array`, `Error`, `TypeError`, `Map` etc. are not
+ * emitted as user classes (no entry in `ctx.classTagMap`), so the existing
+ * struct-tag-based `instanceof` codegen cannot resolve them. The compiler
+ * falls back to a `__instanceof` host import, which is unavailable in
+ * standalone / WASI mode.
+ *
+ * This module provides:
+ *   - a stable registry of well-known built-in type names (with hierarchy info)
+ *   - static-evaluation helpers that let `compileHostInstanceOf` short-circuit
+ *     to a constant `i32.const 0` or `i32.const 1` whenever the LHS TypeScript
+ *     type (or stack value type) is provably (in)compatible with the RHS
+ *     constructor.
+ *
+ * The numeric tag values are reserved as **negative integers** so they cannot
+ * collide with user-class tags assigned by `ctx.classTagCounter` (which starts
+ * at 0 and increments). This leaves room for a future Phase 2 that actually
+ * stores these tags in WasmGC structs (e.g., a $Error wrapper struct for
+ * thrown exceptions).
+ *
+ * Phase-1 scope (this module): the registry and static elimination only.
+ * Phase-2 scope (later): tagged WasmGC wrapper structs for thrown errors so
+ *   `catch (e) { if (e instanceof TypeError) ... }` works without a JS host.
+ *
+ * See plan/issues/sprints/50/1325-instanceof-builtin-type-tag-registry.md.
+ */
+/**
+ * Reserved tag values for built-in JS constructors. Negative integers so they
+ * do not collide with user class tags (which start at 0 and count up).
+ *
+ * Phase 1 does NOT yet write these tags into WasmGC structs — they are only
+ * used for static reasoning. Phase 2 will tag thrown-error wrapper structs
+ * with these values so pure-Wasm `catch (e) instanceof TypeError` works.
+ */
+export declare const BUILTIN_TYPE_TAGS: {
+    readonly Object: -1;
+    readonly Function: -2;
+    readonly Array: -3;
+    readonly Boolean: -4;
+    readonly Number: -5;
+    readonly String: -6;
+    readonly Error: -10;
+    readonly TypeError: -11;
+    readonly RangeError: -12;
+    readonly SyntaxError: -13;
+    readonly URIError: -14;
+    readonly EvalError: -15;
+    readonly ReferenceError: -16;
+    readonly AggregateError: -17;
+    readonly Map: -20;
+    readonly Set: -21;
+    readonly WeakMap: -22;
+    readonly WeakSet: -23;
+    readonly WeakRef: -24;
+    readonly Date: -30;
+    readonly RegExp: -31;
+    readonly Promise: -40;
+    readonly ArrayBuffer: -50;
+    readonly SharedArrayBuffer: -51;
+    readonly DataView: -52;
+    readonly Int8Array: -70;
+    readonly Uint8Array: -71;
+    readonly Uint8ClampedArray: -72;
+    readonly Int16Array: -73;
+    readonly Uint16Array: -74;
+    readonly Int32Array: -75;
+    readonly Uint32Array: -76;
+    readonly Float32Array: -77;
+    readonly Float64Array: -78;
+    readonly BigInt64Array: -79;
+    readonly BigUint64Array: -80;
+};
+export type BuiltinTypeName = keyof typeof BUILTIN_TYPE_TAGS;
+/**
+ * Returns true if `name` is a known built-in JS constructor name in the
+ * registry. Caller should already have checked it isn't a user class.
+ */
+export declare function isBuiltinTypeName(name: string): name is BuiltinTypeName;
+/**
+ * Returns true if `child` is `parent` or transitively a built-in subclass of
+ * `parent` (per the registry's BUILTIN_PARENT chain). Used to statically
+ * decide e.g. `new TypeError() instanceof Error` → true.
+ *
+ * Returns false for unknown names (caller should still fall through to the
+ * host import or to a `false` constant).
+ */
+export declare function isBuiltinSubtype(child: string, parent: string): boolean;
+/**
+ * Returns the parent constructor name for a built-in, or undefined if it has
+ * no parent in the registry. Exposed for tests / debugging.
+ */
+export declare function getBuiltinParent(name: string): BuiltinTypeName | undefined;
+/**
+ * Built-in constructors for which we emit subclass support via the existing
+ * `__new_<Name>(args...) -> externref` host imports. The subclass instance
+ * is represented as externref (NOT a WasmGC struct), and the host returns a
+ * real JS object with the right internal slots.
+ *
+ * Scope:
+ *   - #1366a: Error family (Error, TypeError, RangeError, …).
+ *   - #1366b: container builtins (Array, Map, Set, WeakMap, WeakSet, Promise,
+ *     RegExp, ArrayBuffer). These all route through the same single-arg
+ *     `__new_<Name>(arg) -> externref` host import; the runtime's
+ *     `extern_class new` resolver (`runtime.ts:1604`) constructs the real
+ *     built-in via `new globalThis[Name](...)` after stripping trailing nulls.
+ *
+ * Limitations (deferred to #1366c/d):
+ *   - `instanceof Sub` for non-Error subclasses: the host instance's
+ *     `[[Prototype]]` is the parent's, not Sub's, so `subInst instanceof Sub`
+ *     resolves via the static reasoning path (`expressions.ts:714`) rather
+ *     than runtime prototype-chain walking.
+ *   - `Symbol.species` is honoured by the host's spec-conforming method
+ *     impls automatically (since the instance IS a real Array/Map/etc.), but
+ *     methods that return "a new instance of the same kind" return the
+ *     parent type, not Sub.
+ *   - Dynamic spread (`super(...args)` or `new Sub(...args)`) only forwards up
+ *     to the parent constructor's statically known import arity. Array-literal
+ *     spread is flattened, but arbitrary iterable spreading is still deferred.
+ */
+export declare const BUILTIN_PARENTS_HOST_CONSTRUCTIBLE: ReadonlySet<BuiltinTypeName>;
+/**
+ * Returns true if `name` is a built-in JS constructor that can act as a
+ * parent for a host-constructible subclass (#1366a/#1366b). The subclass
+ * instance is externref-backed and `super(...)` lowers to `__new_<Name>(...)`.
+ */
+export declare function isHostConstructibleBuiltin(name: string): boolean;
+/**
+ * (#2620) The native-collection builtins. In `nativeStrings` mode
+ * (`--target standalone`/`wasi`) these are served by the WasmGC-native
+ * Map/Set runtime (map-runtime.ts / set-runtime.ts / weak-collections-runtime.ts,
+ * #1103a/#2162) and are deliberately NOT registered as externClasses — base
+ * `new Set([...])` is intercepted to the native `$Map`-backed instance instead
+ * of leaking a `__new_Set` host import.
+ *
+ * A *subclass* (`class X extends Set {}`), however, still routes through the
+ * generic host-constructible path (these names ARE in
+ * `BUILTIN_PARENTS_HOST_CONSTRUCTIBLE`): under standalone that both leaks the
+ * `__new_<Name>` host import AND desyncs the synthetic `<Class>_<method>`
+ * accessor across the late-import shift (the #2043 index-shift class → invalid
+ * Wasm). A native subclass (native construction + direct `[[SetData]]`
+ * set-algebra + native iteration + `instanceof` discrimination) is the
+ * value-rep/collection-runtime substrate (#2162-scale), tracked separately.
+ * Until then, a standalone subclass of one of these is refused at compile time
+ * (clean CE, never invalid Wasm / never a leaked host import). See the
+ * refusal in class-bodies.ts.
+ */
+export declare const NATIVE_COLLECTION_BUILTINS: ReadonlySet<string>;
+/**
+ * (#2620) Returns true if `name` is a native-collection builtin
+ * (Set/Map/WeakMap/WeakSet) — used to refuse a standalone subclass of one of
+ * them (see {@link NATIVE_COLLECTION_BUILTINS}).
+ */
+export declare function isNativeCollectionBuiltin(name: string): boolean;
+/**
+ * (#2029) The primitive-wrapper builtins whose standalone SUBCLASS construction
+ * is broken. `Number` and `Boolean` are in
+ * `BUILTIN_PARENTS_HOST_CONSTRUCTIBLE` so a `class N extends Number {}` takes
+ * the externref-backed host path under `--target standalone`/`wasi`, lowering
+ * `super()`/`new Sub()` to `call $__new_Number` — but the standalone
+ * `__new_Number`/`__new_Boolean` internals take an **f64** argument, while the
+ * synthetic `<Class>_new` forwarder passes the constructor's externref local
+ * (`local.get $0`). The arg types don't match → `wasm-validator error in
+ * function N_new: call param types must match` (invalid Wasm — the binary still
+ * serializes but dies at instantiate/validate). No native primitive-wrapper
+ * *subclass* box exists standalone yet.
+ *
+ * `String` is deliberately NOT in this set: its standalone
+ * `__new_String(externref) -> externref` is externref-in/externref-out, which
+ * the externref forwarder matches exactly — `class S extends String {}` already
+ * compiles, instantiates with an empty import object, and answers
+ * `new S() instanceof S` → `true` standalone (verified on main). Refusing it
+ * would regress a working case.
+ *
+ * Until a native wrapper-box subclass substrate lands (value-rep follow-up,
+ * pairs with #1629b boxed-primitive work), a standalone subclass of
+ * `Number`/`Boolean` is refused at compile time (clean CE, never invalid Wasm —
+ * the #1888 dual-mode invariant). gc/host mode is unaffected (the externClass
+ * host path handles the subclass there). See the refusal in class-bodies.ts.
+ */
+export declare const PRIMITIVE_WRAPPER_SUBCLASS_UNSUPPORTED: ReadonlySet<string>;
+/**
+ * (#2029) Returns true if `name` is a primitive-wrapper builtin whose
+ * standalone subclass construction is not yet supported (Number/Boolean) —
+ * used to refuse a standalone subclass of one of them. `String` is excluded
+ * (it works standalone). See {@link PRIMITIVE_WRAPPER_SUBCLASS_UNSUPPORTED}.
+ */
+export declare function isPrimitiveWrapperSubclassUnsupported(name: string): boolean;

package/dist/codegen/case-convert-native.d.ts

@@ -0,0 +1,12 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Ensure the per-character simple-case mapper `__case_simple_{upper,lower}` and
+ * the string-level `__str_toUpperCase`/`__str_toLowerCase` rewrites are emitted.
+ * Idempotent. Requires an i32 array type (the same `array (mut i32)` the runtime
+ * uses for vectors) — we register a dedicated immutable i32 array type for the
+ * tables.
+ *
+ * Called from ensureNativeStringHelpers; `strTypeIdx`/`strDataTypeIdx` are the
+ * NativeString struct + its i16 backing-array type indices.
+ */
+export declare function emitNativeCaseConversion(ctx: CodegenContext, strTypeIdx: number, strDataTypeIdx: number, anyStrTypeIdx: number): void;

package/dist/codegen/case-tables.d.ts

@@ -0,0 +1,4 @@
+export declare const UPPER_CASE_RUNS: readonly number[];
+export declare const LOWER_CASE_RUNS: readonly number[];
+export declare const UPPER_CASE_SPECIAL: readonly number[];
+export declare const LOWER_CASE_SPECIAL: readonly number[];

package/dist/codegen/class-bodies.d.ts

@@ -0,0 +1,41 @@
+import { ts } from '../ts-api.js';
+import { FieldDef } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export declare function resolveClassMemberName(ctx: CodegenContext, name: ts.PropertyName): string | undefined;
+export { classMemberFuncKey } from './class-member-keys.js';
+/** Collect all function declarations and interfaces */
+/** Collect a class declaration or class expression: register struct type, constructor, and methods */
+export declare function collectClassDeclaration(ctx: CodegenContext, decl: ts.ClassDeclaration | ts.ClassExpression, syntheticName?: string): void;
+/**
+ * For a generic function, find the first call site in the source and resolve
+ * concrete param/return types from the checker's instantiated signature.
+ * Returns null if no call site is found (function stays with erased types).
+ */
+export declare const INTERNAL_FIELD_NAMES: Set<string>;
+/**
+ * Default property flags: writable (bit 0) + enumerable (bit 1) + configurable (bit 2).
+ * Matches PROP_FLAG_WRITABLE | PROP_FLAG_ENUMERABLE | PROP_FLAG_CONFIGURABLE from object-ops.ts.
+ */
+export declare const PROP_FLAGS_DEFAULT = 7;
+/**
+ * Build the per-shape default property flags table.
+ * Iterates all struct types registered via structMap (classes, anonymous objects,
+ * interfaces, type aliases) and creates a Uint8Array of default flags for each.
+ * One byte per user-visible field; internal fields (__tag) are excluded.
+ *
+ * This table is purely compile-time metadata with zero runtime overhead.
+ * Future subtasks (#797c Object.defineProperty, #797d Object.keys) will
+ * emit code that reads from this table at runtime.
+ */
+export declare function buildShapePropFlagsTable(ctx: CodegenContext): void;
+/** Scan all function bodies for ref.func instructions and record their targets */
+export declare function collectDeclaredFuncRefs(ctx: CodegenContext): void;
+/** Compile constructor and method bodies for a class declaration */
+export declare function compileClassBodies(ctx: CodegenContext, decl: ts.ClassDeclaration | ts.ClassExpression, funcByName: Map<string, number>, syntheticName?: string): void;
+/**
+ * Compile a super(args) call inside a child constructor.
+ * This runs the parent constructor's field-initialization logic inline:
+ * for each parent field, evaluate the corresponding super argument and
+ * store it into the child struct (which includes parent fields at the start).
+ */
+export declare function compileSuperCall(ctx: CodegenContext, fctx: FunctionContext, childClassName: string, selfLocal: number, callExpr: ts.CallExpression, _allFields: FieldDef[], onHost?: boolean): void;

package/dist/codegen/class-member-keys.d.ts

@@ -0,0 +1,33 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Class members register in `ctx.funcMap` under `${className}_${member}` keys
+ * (`A_m` for `A.m`, `A_new` for the ctor, `A_get_v` for a getter, …). A
+ * top-level user `function A_m() {}` would claim the same flat string key, and
+ * `ensureSiblingFunctionsRegistered` then *silently skips* registering the user
+ * function because `funcMap.has("A_m")` is already true — so `A_m()` call sites
+ * resolve to the class member's funcIdx (wrong signature → validation trap).
+ *
+ * The fix keeps the funcMap key **byte-identical** (`A_m`) in the overwhelming
+ * common case (no user function of that name), and only when a real collision
+ * exists relocates the *class member's* funcMap key to a form a user identifier
+ * cannot produce (`__cm$A_m`). The user function keeps the bare `A_m` key (it
+ * is no longer skipped, because the class member vacated `A_m`), so its many
+ * bare-call / export / ref.func consumers are untouched.
+ *
+ * IMPORTANT: this relocates ONLY the `funcMap` funcIdx key. The parallel
+ * membership sets (`classMethodSet`, `staticMethodSet`, `classAccessorSet`,
+ * `staticProps`, …) and the per-name metadata maps (`funcOptionalParams`,
+ * `funcRestParams`, `funcUsesArguments`, …) keep the legacy
+ * `${className}_${member}` string — the sets answer "is this name a class
+ * member?" (collision-free), and the method-dispatch consumer reads the
+ * metadata by the same legacy `fullName`, so producer and consumer agree.
+ * Producers and consumers of the funcMap **funcIdx** must both route the legacy
+ * name through this helper so they agree on the relocated key.
+ *
+ * Known residual (out of scope, does NOT trap): if a program declares BOTH a
+ * class member `A.m` *and* a user `function A_m()` *and both* carry optional /
+ * rest params, the two share the legacy `funcOptionalParams[A_m]` slot. This
+ * affects only optional-arg backfill for that pathological name clash; the
+ * funcIdx (the trap cause) is correctly separated.
+ */
+export declare function classMemberFuncKey(ctx: CodegenContext, fullName: string): string;

package/dist/codegen/class-to-primitive.d.ts

@@ -0,0 +1,39 @@
+import { CodegenContext } from './context/types.js';
+export declare const CLASS_TO_PRIMITIVE = "__class_to_primitive";
+/**
+ * Reserve the `__class_to_primitive(externref obj, i32 stringHint) -> externref`
+ * placeholder and return its funcIdx. Body is a bare `unreachable` until
+ * `fillClassToPrimitive` patches it (after `__call_valueOf`/`__call_toString`
+ * are registered). Idempotent. Standalone only — the JS-host lane reduces class
+ * instances via the host `_hostToPrimitive` OrdinaryToPrimitive loop, so this
+ * driver is never reached there.
+ */
+export declare function reserveClassToPrimitive(ctx: CodegenContext): number;
+/**
+ * Fill the reserved `__class_to_primitive` body now that the per-struct
+ * `__call_valueOf` / `__call_toString` dispatchers are registered (after
+ * `emitToPrimitiveMethodExports`). Implements §7.1.1.1 OrdinaryToPrimitive over
+ * the nominal-struct dispatchers:
+ *
+ *   // hint==string → try toString first, else valueOf; otherwise valueOf first.
+ *   first  = stringHint ? __call_toString : __call_valueOf
+ *   second = stringHint ? __call_valueOf  : __call_toString
+ *   r = first(obj);   if (r != null) return r       // a method matched → primitive
+ *   r = second(obj);  if (r != null) return r
+ *   return obj                                       // neither matched — unchanged
+ *
+ * `__call_*` return a boxed primitive externref on a struct match, or
+ * `ref.null.extern` on no match — so a non-null result is exactly "this class
+ * had this method, here is its (already-boxed-primitive) result". A class with
+ * neither method falls through to `return obj` (today's behaviour, no
+ * regression). The §7.1.1.1 step-6 "must return a primitive" TypeError walk for
+ * a method that returns an object is intentionally NOT replicated here: the
+ * standalone class dispatchers box only primitive method results, and the
+ * dynamic-`$Object` path (which DOES do the full walk) is unaffected.
+ *
+ * No-op when the driver was not reserved or the dispatchers are missing — the
+ * placeholder `unreachable` stays (it is unreachable from any live arm, because
+ * `__to_primitive` only `call`s the driver when it itself was emitted in the
+ * standalone class-capable path).
+ */
+export declare function fillClassToPrimitive(ctx: CodegenContext): void;

package/dist/codegen/closed-method-dispatch.d.ts

@@ -0,0 +1,42 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Reserve (or fetch) the closed-struct dispatcher `__call_m_<name>_<arity>`
+ * funcIdx with a placeholder body. The real body is built by
+ * {@link fillClosedMethodDispatch} at finalize. Idempotent; records the
+ * (method name, arity) pair in `ctx.closedMethodDispatchNames` (encoded as
+ * `<name>/<arity>`). Returns the reserved funcIdx.
+ *
+ * The dispatcher signature is `(recv: externref, arg0..arg{arity-1}: externref)
+ * -> externref`; the call site coerces each argument to externref before the
+ * call, and the fill side coerces each back to the method's declared param type.
+ *
+ * Only meaningful under `ctx.standalone || ctx.wasi` — callers gate on that.
+ */
+export declare function reserveClosedMethodDispatch(ctx: CodegenContext, methodName: string, arity?: number): number;
+/**
+ * (#2151 Slice 4) Reserve (or fetch) the VARARG closed-struct dispatcher
+ * `__call_m_<name>_vararg(recv: externref, args: externref) -> externref` for a
+ * DYNAMIC-spread method call `o.m(...xs)` whose arity is unknown at compile time.
+ *
+ * The fill (in {@link fillClosedMethodDispatch}) type-switches over every closed
+ * struct having `<Struct>_<name>` exactly like the fixed-arity dispatcher, but
+ * sources each declared param from `__extern_get_idx(args, i)` (0..K-1, K = that
+ * method's declared param count) instead of from a fixed dispatcher param. The
+ * bottom arm forwards the SAME `args` externref to
+ * `__extern_method_call(recv, "<name>", args)` for the open-`$Object` case.
+ *
+ * Like the fixed-arity reserve, all fallback-arm dependencies are registered NOW
+ * (during compilation) so the fill only READS funcMap — `ensureObjVecBuilders`
+ * pulls in the object runtime including `__extern_get_idx` / `__extern_length`,
+ * which the per-struct arms read args through. Idempotent. Only meaningful under
+ * `ctx.standalone || ctx.wasi`.
+ */
+export declare function reserveClosedMethodDispatchVararg(ctx: CodegenContext, methodName: string): number;
+/**
+ * Fill every reserved `__call_m_<name>_<arity>` AND `__call_m_<name>_vararg`
+ * dispatcher body at FINALIZE. Mirrors `fillApplyClosure` (object-runtime.ts).
+ * Must run AFTER all object-literal struct types and their `<Struct>_<name>`
+ * method funcs are registered, and after `addUnionImports` (so
+ * `__box_number`/`__box_boolean` exist). No-op when nothing was reserved.
+ */
+export declare function fillClosedMethodDispatch(ctx: CodegenContext): void;

package/dist/codegen/closures.d.ts

@@ -0,0 +1,285 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { ClosureInfo, CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Collect names that are LOCALLY DECLARED inside a function-like node's scope.
+ * Used to compute the shadow set for free-variable analysis.
+ *
+ * Includes:
+ *   - parameter binding identifiers (function-scoped)
+ *   - `var` declarations anywhere in the body (function-scoped)
+ *   - top-level `function`/`class` declarations in the body
+ *
+ * Does NOT cross nested function boundaries.
+ *
+ * Conservatively excludes block-scoped `let`/`const` since they only shadow
+ * within their block, and adding them to the function-wide shadow set would
+ * incorrectly mask legitimate outer captures.
+ */
+export declare function collectFunctionOwnLocals(funcLike: ts.Node, out: Set<string>): void;
+/**
+ * Collect all identifiers referenced in a node.
+ *
+ * If `shadowed` is provided, identifiers in that set are NOT collected. The
+ * walker also detects nested function scopes and augments the shadow set with
+ * each nested function's own locals so that references inside them to names
+ * shadowed by nested var/param decls aren't incorrectly attributed to the
+ * outer scope.
+ *
+ * Callers analyzing free variables of a function-like body should compute the
+ * function's own locals via `collectFunctionOwnLocals` and pass them as the
+ * initial `shadowed` set, since the walker enters the body without crossing
+ * the boundary itself.
+ */
+export declare function collectReferencedIdentifiers(node: ts.Node, names: Set<string>, shadowed?: ReadonlySet<string>): void;
+/**
+ * Collect identifiers that are WRITTEN to within a node tree.
+ * Detects: assignment (=, +=, etc.), ++, --.
+ *
+ * Scope-aware in the same sense as `collectReferencedIdentifiers`: writes to
+ * names shadowed by nested function scopes are not collected.
+ */
+export declare function collectWrittenIdentifiers(node: ts.Node, names: Set<string>, shadowed?: ReadonlySet<string>): void;
+/**
+ * Promote captured locals to globals for getter/setter accessor functions.
+ *
+ * When an object literal getter/setter references variables from the enclosing
+ * function scope, those variables need to be accessible as Wasm globals (since
+ * the getter/setter is compiled as a separate Wasm function).
+ *
+ * This function:
+ * 1. Scans the accessor body for referenced identifiers
+ * 2. For each that maps to a local in the enclosing fctx, creates a Wasm global
+ * 3. Copies the local's current value into the global
+ * 4. Removes the name from localMap so subsequent code uses the global
+ * 5. Registers in ctx.capturedGlobals for resolution in the accessor body
+ */
+export declare function promoteAccessorCapturesToGlobals(ctx: CodegenContext, fctx: FunctionContext, accessorBody: ts.Block | undefined, extraNodes?: readonly ts.Node[]): void;
+/** Collect all identifier names from a binding pattern (destructuring parameter) */
+export declare function collectBindingPatternNames(pattern: ts.BindingPattern, names: Set<string>): void;
+/** Check if a name is defined in any of the arrow's own parameters (including destructuring) */
+export declare function isOwnParamName(arrow: ts.ArrowFunction | ts.FunctionExpression, name: string): boolean;
+/**
+ * Emit destructuring code for an arrow function parameter that uses a binding pattern.
+ * The parameter value is already in a local at `paramIdx`; this emits instructions to
+ * extract fields/elements into new locals in the lifted function context.
+ */
+export declare function emitArrowParamDestructuring(ctx: CodegenContext, fctx: FunctionContext, param: ts.ParameterDeclaration, paramIdx: number, paramType: ValType): void;
+/**
+ * Emit default-value initialization for arrow/closure function parameters.
+ * Similar to the logic in compileFunctionBody but operates on the lifted fctx.
+ */
+export declare function emitArrowParamDefaults(ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression, paramOffset: number): void;
+/**
+ * Emit default-value initialization for method/setter parameters with initializers.
+ * For each param with a default value, check if the caller omitted it
+ * (externref -> ref.is_null, i32 -> i32.eqz, f64 -> f64.eq 0.0) and if so
+ * compile the initializer expression and assign it to the param local.
+ */
+export declare function emitMethodParamDefaults(ctx: CodegenContext, fctx: FunctionContext, params: ts.NodeArray<ts.ParameterDeclaration>, paramOffset: number): void;
+/** Check if an arrow/function expression is used as a callback argument to a call
+ *  that targets a HOST import (not a user-defined function). User-defined functions
+ *  should receive closures via the GC struct path, not the __make_callback host path. */
+export declare function isHostCallbackArgument(node: ts.Node, ctx: CodegenContext): boolean;
+/**
+ * Returns true if the arrow's parent CallExpression is a stored-callback host
+ * method (DisposableStack.defer/use/adopt etc.). The callback is not invoked
+ * synchronously by the call that registers it, so its captured-mutable
+ * writebacks must be persistent. (#1695)
+ */
+export declare function isDeferredCallbackArgument(node: ts.Node, ctx: CodegenContext): boolean;
+export declare function compileArrowFunction(ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression): ValType | null;
+/** Compile an arrow function as a first-class closure value (Wasm GC struct + funcref) */
+export declare function compileArrowAsClosure(ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression): ValType | null;
+/** Compile an arrow function as a host callback via __make_callback.
+ *  Captures are bundled into a per-instance GC struct (not shared globals). */
+/**
+ * (#2128) Collect the names a callback body WRITES that resolve to locals of
+ * the enclosing function — i.e. its mutable captures. Used by the
+ * object-literal accessor path to pre-compute, across a whole get/set pair,
+ * which locals must be captured through a SHARED ref cell so the getter
+ * observes the setter's writes.
+ */
+export declare function collectMutatedCaptureNames(fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression): Set<string>;
+/** (#2128) Per-literal registry of shared capture ref cells — see compileArrowAsCallback. */
+export type SharedRefCellMap = Map<string, {
+    refCellLocal: number;
+    refCellTypeIdx: number;
+    valType: ValType;
+}>;
+export declare function compileArrowAsCallback(ctx: CodegenContext, fctx: FunctionContext, arrow: ts.ArrowFunction | ts.FunctionExpression, options?: {
+    needsThis?: boolean;
+    deferredInvocation?: boolean;
+    /**
+     * (#2128) Locals to capture mutably (via ref cell) even when THIS
+     * callback only reads them — a sibling callback in the same object
+     * literal writes them, and both must see one shared cell.
+     */
+    forceMutableCaptures?: Set<string>;
+    /**
+     * (#2128) Per-object-literal shared-cell registry. The first callback
+     * capturing a name mutably creates the cell and records it here; sibling
+     * callbacks reuse it so mutations are visible across the get/set pair.
+     * Scoped to one literal compilation — do NOT share across loop-iteration
+     * callback creations (per-iteration `let` semantics need fresh cells).
+     */
+    sharedRefCells?: SharedRefCellMap;
+}): ValType | null;
+/** A captured local that must flow into an async continuation. */
+export interface AsyncCapture {
+    readonly name: string;
+    readonly type: ValType;
+    readonly localIdx: number;
+}
+/** Result of synthesizing an async continuation `__cb_N` function. */
+export interface SyntheticContinuation {
+    /** Callback id — the host dispatches `__cb_${cbId}(captures, awaitValue)`. */
+    readonly cbId: number;
+    /** Capture struct type index (field i holds capture[i]), or -1 if no captures. */
+    readonly capStructTypeIdx: number;
+    /** The captures, in struct-field order. */
+    readonly captures: readonly AsyncCapture[];
+}
+/**
+ * (#1042) Synthesize an async-continuation function for the CPS state machine.
+ *
+ * Unlike {@link compileArrowAsCallback} this is driven by an explicit statement
+ * list + capture set (not an arrow AST node). It emits an exported
+ * `__cb_${cbId}(captures: externref, awaitValue: externref) -> externref`
+ * function compatible with the `__make_callback` host bridge: the host invokes
+ * it with the settled promise value as `awaitValue`. The function restores
+ * captured locals from the capture struct, binds the awaited result to
+ * `resumeBinding` (if any), runs `segmentStmts`, and returns `ref.null.extern`
+ * (the host ignores a continuation's result).
+ *
+ * Returns the cbId + capture-struct info so the caller emits the creation site
+ * (`i32.const cbId` + capture struct + `extern.convert_any` + `__make_callback`).
+ *
+ * Captures are immutable snapshots (value-copied into the struct) — async
+ * continuations don't write back to the suspended frame, so no ref cells.
+ */
+export declare function compileSyntheticAsyncContinuation(ctx: CodegenContext, outerFctx: FunctionContext, segmentStmts: readonly ts.Statement[], captures: readonly AsyncCapture[], resumeBinding: {
+    name: string;
+    type: ValType;
+} | null, options?: {
+    returnAwaitValue?: boolean;
+}): SyntheticContinuation;
+/**
+ * Look up a function's parameter and result types from its index.
+ */
+export declare function getFuncSignature(ctx: CodegenContext, funcIdx: number): {
+    params: ValType[];
+    results: ValType[];
+} | null;
+/**
+ * Get or create the closure struct type and lifted func type for wrapping
+ * plain functions with a given signature. Struct type and func type are shared
+ * across all functions with the same signature, but each function gets its own
+ * trampoline.
+ */
+export declare function getOrCreateFuncRefWrapperTypes(ctx: CodegenContext, userParams: ValType[], resultTypes: ValType[]): {
+    structTypeIdx: number;
+    liftedFuncTypeIdx: number;
+    closureInfo: ClosureInfo;
+} | null;
+/**
+ * Emit a closure struct wrapping a plain function. Creates a per-function
+ * trampoline that delegates to the original function.  Struct types are shared
+ * across functions with the same signature so they can be reassigned.
+ * Pushes the closure struct ref onto the stack and returns its type.
+ */
+export declare function emitFuncRefAsClosure(ctx: CodegenContext, fctx: FunctionContext, funcName: string, funcIdx: number): ValType | null;
+/**
+ * (#2025) Eagerly register the `__new_TypeError` import + the message string
+ * the first time an extractable method-as-closure trampoline is built, so the
+ * trampoline's null-`this` arm can emit a CATCHABLE TypeError throw with
+ * stable, shift-tracked indices (no late-import registration during the
+ * fragile finalize rebuild). Idempotent. Requires a live `fctx` so the flush
+ * lands the deferred index shift onto the surrounding function being compiled.
+ */
+export declare function ensureNullThisTypeError(ctx: CodegenContext, fctx: FunctionContext | null): void;
+/**
+ * #1118: Emit an object-literal method as a first-class closure value.
+ *
+ * Object-literal methods are compiled as Wasm functions with signature
+ * `(self_obj, ...userParams) → ret`. When the method is read as a value
+ * (e.g. `var f = obj.m;` or stored in the obj's own struct field), we
+ * need a closure-struct ref whose funcref takes `(closure_self, …userParams)`.
+ *
+ * The two signatures differ in their first param: the method expects the
+ * object's struct ref, the closure value passes its own closure struct.
+ * We bridge them with a trampoline that drops `closure_self` and pushes
+ * `ref.null <objStruct>` for the method's `self_obj` slot, then forwards
+ * the user params and tail-calls the method.
+ *
+ * The trampoline implements method extraction with unbound `this` — JS
+ * spec says `var f = obj.m; f();` invokes `m` with `this = undefined`
+ * (strict mode) or `this = globalThis` (sloppy). For methods that don't
+ * reference `this` (the common test262 yield-star pattern), the null
+ * `self_obj` is fine; methods that DO use `this` will trap inside the
+ * body, mirroring spec semantics.
+ *
+ * Returns the closure-struct ref ValType (which the caller can convert
+ * to externref via `extern.convert_any` if the field type expects it).
+ */
+export declare function emitObjectMethodAsClosure(ctx: CodegenContext, fctx: FunctionContext, methodName: string, methodFuncIdx: number, objStructTypeIdx: number): ValType | null;
+/**
+ * (#1602) Rebuild every object-method-as-closure trampoline body against the
+ * method's FINAL signature. Must run after all function bodies are compiled
+ * (so `func.typeIdx` re-resolution has settled) and BEFORE late-import index
+ * shifting, since the rebuilt body re-emits `call methodFuncIdx` at the current
+ * (pre-shift) index — the shift machinery then walks it like any other body.
+ *
+ * The trampoline's own signature (its wrapper func type) is left untouched; we
+ * only fix the forwarding body so its `local.get` count and the `call`'s
+ * operand types match the method's resolved params. The wrapper's user-param
+ * count is invariant (derived from the same method), so the trampoline param
+ * indices stay valid; only the per-arg coercion is what could drift, and any
+ * coercion the call needs is applied by mirroring the method's param types.
+ */
+export declare function finalizeMethodTrampolines(ctx: CodegenContext): void;
+/**
+ * (#1394) Emit a cached singleton closure for a class method, preserving
+ * identity: every emit of `C.prototype.<method>` (or `instance.<method>`
+ * as a value) returns the same externref so JS's `===` works (e.g.
+ * `c.m === C.prototype.m`). 478 tests under
+ * `language/{expressions,statements}/class/elements/*` exercise this
+ * exact assertion via `verifyProperty(C.prototype, "m", { value: m })`.
+ *
+ * The cache is a per-class-method module-level externref global,
+ * lazily initialised on first access (matches the existing
+ * `emitLazyProtoGet` pattern). The canonical trampoline is registered
+ * once per method too — its name is
+ * `__obj_meth_tramp_${methodName}_cached`, distinct from the legacy
+ * per-call-site `__obj_meth_tramp_${methodName}_${counter}` that
+ * `emitObjectMethodAsClosure` emits.
+ *
+ * Returns `true` if the access was emitted; `false` if the method's
+ * signature couldn't be resolved (caller should fall back).
+ */
+export declare function emitCachedMethodClosureAccess(ctx: CodegenContext, fctx: FunctionContext, methodName: string, methodFuncIdx: number, objStructTypeIdx: number): boolean;
+/**
+ * (#1340) Emit a cached singleton closure for a top-level function declaration
+ * used as a first-class value. Mirrors `emitCachedMethodClosureAccess` (#1394)
+ * for the function-decl case.
+ *
+ * Without caching, every textual occurrence of `foo` (in value position)
+ * compiled a fresh `struct.new $closure_struct`, so `foo === foo` was false
+ * and sidecar writes on `foo.prototype` keyed by the struct identity never
+ * round-tripped (test262 Iterator helpers misclassified as `wasm_compile`).
+ *
+ * One externref cache global per function name, lazily initialised on first
+ * read; all later reads return the same externref. Call dispatch is unchanged
+ * (resolved via `funcMap` + direct `call funcIdx`); only the value-context
+ * read uses the cached closure.
+ *
+ * Only safe for captureless functions — captures must be filled at the
+ * per-construction site, not once at module init.
+ *
+ * Returns the closure struct's `ref` ValType when the cached access was
+ * emitted (so downstream consumers like array-methods.ts can take the
+ * direct `call_ref` fast path against the closure's funcref slot rather
+ * than the externref-bridge slow path through `__call_2_f64`). Returns
+ * `null` when the signature couldn't be resolved (caller falls back).
+ */
+export declare function emitCachedFuncClosureAccess(ctx: CodegenContext, fctx: FunctionContext, funcName: string, funcIdx: number): ValType | null;