@loopdive/js2 0.57.0

package/dist/codegen/index.d.ts

@@ -0,0 +1,500 @@
+import { ts } from '../ts-api.js';
+import { MultiTypedAST, TypedAST } from '../checker/index.js';
+import { ValType, WasmModule } from '../ir/types.js';
+import { IrIntegrationError } from '../ir/integration.js';
+import { FallbackCounts } from './fallback-telemetry.js';
+import { CodegenContext, CodegenError, CodegenOptions, ExternClassInfo, FunctionContext, OptionalParamInfo } from './context/types.js';
+import { ensureAnyFromExternHelper, ensureAnyHelpers, ensureAnyToExternHelper, ensureAnyValueType, ensureWrapperTypes, isAnyValue } from './any-helpers.js';
+import { collectClassDeclaration, compileClassBodies } from './class-bodies.js';
+import { destructureParamArray, destructureParamObject, destructureParamObjectExternref } from './destructuring-params.js';
+import { ensureNativeStringExternBridge, ensureNativeStringHelpers, flatStringType, nativeStringType, nativeStringTypeNullable } from './native-strings.js';
+export { collectClassDeclaration, compileClassBodies, destructureParamArray, destructureParamObject, destructureParamObjectExternref, ensureAnyFromExternHelper, ensureAnyHelpers, ensureAnyToExternHelper, ensureAnyValueType, ensureNativeStringExternBridge, ensureNativeStringHelpers, ensureWrapperTypes, flatStringType, isAnyValue, nativeStringType, nativeStringTypeNullable, };
+/**
+ * Report a codegen error with source location extracted from an AST node.
+ * Pushes the error into ctx.errors so it can be propagated to the caller.
+ */
+/**
+ * Extract a compile-time constant from a parameter initializer (#869).
+ * Returns the constant default info if the initializer is a numeric/boolean literal,
+ * undefined/null, or a unary minus on a numeric literal. Returns undefined otherwise.
+ */
+/**
+ * TypedArray constructor names. Most still lower to `(ref null $Vec[f64])`;
+ * native Uint8Array lowers to packed byte storage.
+ */
+export declare const TYPED_ARRAY_NAMES: ReadonlySet<string>;
+export declare function typedArrayVecStorage(ctx: CodegenContext, name: string): {
+    key: string;
+    type: ValType;
+};
+/**
+ * (#2593) The signedness of a packed integer typed-array element, driving the
+ * read opcode: `array.get_s` for signed views (`Int8`/`Int16`/`Int32`),
+ * `array.get_u` for unsigned (`Uint8`/`Uint8Clamped`/`Uint16`/`Uint32`). MUST be
+ * keyed on the TS view NAME, not the storage kind — a signed `Int8Array` and an
+ * unsigned `Uint8Array` share `i8` storage but read with opposite extension.
+ * Returns undefined for non-integer views (Float*, or a non-typed-array name).
+ */
+export declare function typedArrayPackedSignedness(name: string): "s" | "u" | undefined;
+/**
+ * (#1700) Classify a TS type at an export boundary for the runtime
+ * `wrapExports` marshalling step. The Wasm signature for `Uint8Array` and
+ * `number[]` is identical (`(ref null $Vec[f64])`), so we surface the
+ * TS-level distinction as metadata.
+ *
+ * - "uint8array"  → caller may pass JS Uint8Array; result-side wraps as Uint8Array
+ * - "typed-array" → any other TypedArray (Int8Array / Float32Array / ...) — v1
+ *                   treats these like number[] on the return path; tracked for
+ *                   element-fidelity follow-up
+ * - "other"       → not a typed array; wrapper is a no-op for this slot
+ */
+export declare function classifyTypedArrayType(tsType: ts.Type, checker: ts.TypeChecker): import('../ir/types.js').TypedArrayKind;
+/**
+ * (#1719 S1) Whole-program pre-scan for the `ITER_OVERRIDDEN` brand of the
+ * array object-value representation track. Returns true iff the source may
+ * monkeypatch `Array.prototype`'s iterator surface, i.e. it contains:
+ *   (i)  an assignment `Array.prototype[Symbol.iterator] = …` or
+ *        `Array.prototype.values = …` (any element/property access whose
+ *        object is `Array.prototype`), OR
+ *   (ii) `Object.defineProperty(Array.prototype, …)` /
+ *        `Object.defineProperties(Array.prototype, …)`.
+ *
+ * When this returns false (the overwhelming common case), the array
+ * destructuring / spread / for-of fast paths are provably unaffected by any
+ * prototype override and stay byte-identical (see `arrayDstrNeedsIdentity`).
+ * When true, the S2 slice routes a branded array RHS through the host-Array
+ * reflection + host `GetIterator` so the override's `@@iterator` is observed
+ * (§7.4.2 GetIterator, §8.5.2 IteratorBindingInitialization).
+ *
+ * Reused verbatim from the dev-a `issue-1719-impl` scaffolding (the front-end
+ * half the architecture spec endorses keeping). Conservative by design: it
+ * over-approximates (a false positive only costs the S2 slow path, never
+ * correctness) and never under-approximates a literal `Array.prototype` LHS.
+ */
+export declare function sourceOverridesArrayIterator(sourceFile: ts.SourceFile): boolean;
+export declare function extractConstantDefault(initializer: ts.Expression, paramType: ValType): OptionalParamInfo["constantDefault"];
+export declare function irVerifierHardFailureEnabled(env?: Record<string, string | undefined>): boolean;
+export declare function formatIrPathFallbackDiagnostic(err: IrIntegrationError): {
+    readonly message: string;
+    readonly severity: "error" | "warning";
+};
+/** Compile a typed AST into a WasmModule IR */
+export declare function generateModule(ast: TypedAST, options?: CodegenOptions): {
+    module: WasmModule;
+    errors: CodegenError[];
+    fallbackCounts?: FallbackCounts;
+    irPostClaimErrors?: {
+        kind: string;
+        func: string;
+        message: string;
+    }[];
+};
+/**
+ * Compile multiple typed source files into a single WasmModule IR.
+ * All source files share the same codegen context (funcMap, structMap, etc.).
+ * Only functions exported from the entry file become Wasm exports.
+ */
+export declare function generateMultiModule(multiAst: MultiTypedAST, options?: CodegenOptions): {
+    module: WasmModule;
+    errors: CodegenError[];
+    fallbackCounts?: FallbackCounts;
+    irPostClaimErrors?: {
+        kind: string;
+        func: string;
+        message: string;
+    }[];
+};
+/**
+ * (#1483) Emit deferred WASI helper functions. Called after
+ * `collectExternDeclarations` (and any other direct-`addImport` callers)
+ * have registered all module imports, so the funcMap entries written here
+ * are stable for subsequent lookups by lazily-registered helpers.
+ */
+export declare function emitDeferredWasiHelpers(ctx: CodegenContext): void;
+/**
+ * WASI linear-memory layout constants (#1618 collision fix).
+ *
+ * The iovec lives at memory[0..7] and nwritten at memory[8..11] (shared by all
+ * __wasi_write_* helpers). String-literal data segments are bump-allocated in
+ * page 0 from offset 1024 (`wasiAllocStringData`). To avoid aliasing those
+ * segments, the stdin read buffer and the raw-byte write scratch live in
+ * dedicated higher pages:
+ *   - WASI_STDIN_BUF_START  = 64KB  (page 1) — fd_read accumulation buffer
+ *   - WASI_WRITE_SCRATCH_START = 128KB (page 2) — fd_write staging buffer
+ * `registerWasiImports` reserves 3 pages so both always exist.
+ */
+export declare const WASI_STDIN_BUF_START: number;
+export declare const WASI_WRITE_SCRATCH_START: number;
+/**
+ * #2655 — DIRECT `readSync` iovec + nread scratch (page 0). The blocking
+ * `wasi_snapshot_preview1.fd_read(fd, iovs, iovs_len, nread)` syscall needs a
+ * `{ base, len }` iovec (8 bytes) and a `nread` out-slot (4 bytes) in linear
+ * memory. These deliberately use DEDICATED page-0 offsets — NOT the async
+ * reactor's `RL_FDREAD_IOV_OFFSET` (324) / `RL_FDREAD_NREAD_OFFSET` (332) — so a
+ * program that uses BOTH synchronous `readSync` AND the async stdin reactor
+ * never has its two iovec scratches alias. They sit above the reactor's
+ * 160–336 poll/iovec region and below the 1024 string-literal data base, so
+ * they collide with neither the iovec write scratch (0–24), the reactor, nor any
+ * string-literal segment. The read DATA lands in the page-1 stdin buffer
+ * (`WASI_STDIN_BUF_START`) for the GC-array copy path, or straight into the
+ * caller's `ptr+offset` for the linear-backed zero-copy path.
+ */
+export declare const WASI_READSYNC_IOV_OFFSET = 340;
+export declare const WASI_READSYNC_NREAD_OFFSET = 348;
+/**
+ * #1886 Slice B — Ensure the `__lin_u8_alloc(len: i32) -> i32` bump allocator
+ * exists and return its function index (lazy, emitted on first linear-backed
+ * `new Uint8Array`). Allocates `align8(len)` bytes from the page-4 linear arena
+ * pointed at by `$__lin_u8_arena_ptr`, growing memory on demand, and returns
+ * the (8-byte-aligned) base pointer. Mirrors the #1856 align8 + page-grow idiom
+ * from `codegen-linear/runtime.ts`; emitted here because the WasmGC front-end
+ * owns its own memory/globals and cannot call the linear backend bootstrap.
+ *
+ * NOTE: the returned region is NOT explicitly zero-filled — `memory.grow`
+ * zeroes fresh pages, and the arena today only ever grows (no reset yet, see
+ * Slice D), so every byte handed out is freshly-grown zero memory, satisfying
+ * the `new Uint8Array(n)` zero-fill contract. A future arena reset (Slice D)
+ * that reuses slots must `memory.fill` callers' buffers.
+ */
+export declare function reserveLinearU8AllocType(ctx: CodegenContext): void;
+/**
+ * (#2357/#47) Reserve the standalone `$__subview_<elem>` struct types up-front so
+ * their indices are deterministic across codegen passes (see the call site in
+ * `generateModule`). Covers the element kinds standalone TypedArrays use for their
+ * backing arrays: `i8_byte` (Int8/Uint8/Uint8Clamped), `i16_byte`
+ * (Int16/Uint16), `i32_byte` (Int32/Uint32), and `f64` (the float views). (#2593
+ * added the i16/i32 byte views — before that only integer Uint8Array was packed.)
+ * `getOrRegisterSubviewType` only forces the backing ARRAY type (uniquely deduped
+ * per element kind) — it does NOT register or reorder the vec struct, so plain
+ * typed-array resolution is unaffected. Idempotent.
+ */
+export declare function reserveTypedArraySubviewTypes(ctx: CodegenContext): void;
+/**
+ * (#2026 #53) Reserve the `$ObjVecArr` = `(array (mut externref))` type up-front,
+ * at the deterministic type-init point, so the dynamic-`new` runtime-argv path
+ * (`emitDynamicNewFallback`, for `new K(...someVar)`) can reference a STABLE type
+ * index. Minting this type lazily mid-expression — via `ensureObjectRuntime` —
+ * registered it after the deterministic type prefix had been baked, leaving an
+ * unresolved `-1` heap-type ref at binary-emit (the #2043 / subview
+ * type-idx-stability hazard). The type is self-contained (element `externref`,
+ * no type deps), so reserving it alone is zero-helper, zero-import, additive.
+ * `ensureObjectRuntime` adopts this slot (see object-runtime.ts) when present so
+ * the two never collide. Gated to class-bearing sources only (the dynamic-new
+ * fallback can't fire without a class).
+ */
+export declare function reserveObjVecArrType(ctx: CodegenContext): void;
+export declare function ensureLinearU8AllocHelper(ctx: CodegenContext): number;
+/**
+ * #1618: Ensure __wasi_write_any_string(s: ref NativeString) -> void exists and
+ * return its function index (lazy, emitted during expression compilation).
+ *
+ * Writes a *runtime* string (variable, concatenation, template span) to fd=1
+ * (stdout) or fd=2 (stderr). Previously these refs fell through to the
+ * `[object]` placeholder in emitWasiValueToStdout, corrupting the stream.
+ *
+ * Strategy: flatten any AnyString (FlatString / ConsString / Utf8String) to a
+ * NativeString via the existing __str_flatten helper, then encode the WTF-16
+ * code units as UTF-8 bytes directly into linear memory before issuing
+ * fd_write. This keeps WASI string output on the pure-Wasm path (#1470) without
+ * routing through the JS-host `__str_to_mem` / `TextEncoder` bridge.
+ *
+ * Param 0 is typed `ref NativeString` so callers can hand us a value compiled
+ * as `{ kind: "ref", typeIdx: ctx.nativeStrTypeIdx }` directly; __str_flatten
+ * accepts the NativeString supertype (AnyString) and returns the flat form.
+ */
+export declare function ensureWasiWriteAnyStringHelper(ctx: CodegenContext, useStderr?: boolean): number;
+/**
+ * #2639: Ensure `__wasi_write_any_string_fd(s: ref AnyString, fd: i32) -> i32`
+ * exists and return its function index (lazy). Encodes the string to UTF-8 in
+ * the shared linear scratch (the same encoder as the fixed-fd writer) and writes
+ * it to the *runtime* fd. This backs the STRING overload of `node:fs`
+ * `writeSync(fd, str, position?, encoding?)`, where the fd is an arbitrary
+ * integer (not just stdout/stderr). Two modes (#2655):
+ *   - shim (`--link-node-shims`): `writeSync(fd, ptr, len)` returns the byte count.
+ *   - direct (standalone `--target wasi`): build a `{ base=ptr, len }` iovec at
+ *     memory[0..7], call `fd_write(fd, iovs=0, 1, nwritten=8)`, load nwritten.
+ */
+export declare function ensureWasiWriteAnyStringFdHelper(ctx: CodegenContext): number;
+/**
+ * #1617/#1651: Ensure __wasi_write_uint8array(arr: ref __vec_*) -> void
+ * exists and return its function index (lazy).
+ *
+ * Writes raw bytes from a typed-array (Uint8Array) GC object to fd=1 (stdout)
+ * or fd=2 (stderr) with NO trailing newline. Backs the
+ * `process.stdout.write(new Uint8Array([...]))` path (the standard Node API
+ * that supersedes the bespoke `writeStdout` builtin from #1617). A native
+ * Uint8Array compiles to a "vec" struct:
+ *   field 0: length (i32)
+ *   field 1: data    (ref array<i8>) — each element is a byte value
+ *
+ * Legacy f64-backed typed arrays are still accepted; each element is converted
+ * to a byte before staging in linear memory at WASI_WRITE_SCRATCH_START.
+ */
+export declare function ensureWasiWriteUint8ArrayHelper(ctx: CodegenContext, vecTypeIdx: number, useStderr?: boolean): number;
+/**
+ * #1655: Ensure __wasi_write_arraybuffer(buf: ref __vec_i32_byte) -> void
+ * exists and return its function index (lazy).
+ *
+ * Companion to `ensureWasiWriteUint8ArrayHelper` for the ArrayBuffer-backing
+ * representation. Under `--target wasi` / `--target standalone`, an
+ * `ArrayBuffer` is lowered to a vec struct of i32 bytes (one byte per
+ * element, values 0..255 — see dataview-native.ts comment block) rather than
+ * the Uint8Array f64-element shape. The element conversion is therefore a
+ * direct i32 read (no `i32.trunc_sat_f64_s`).
+ */
+export declare function ensureWasiWriteArrayBufferHelper(ctx: CodegenContext, vecTypeIdx: number, useStderr?: boolean): number;
+export declare const STRING_METHODS: Record<string, {
+    params: ValType[];
+    result: ValType;
+}>;
+/** Register wasm:js-string builtin imports (called on demand when strings are used) */
+export declare function addStringImports(ctx: CodegenContext): void;
+/** Parse a RegExp literal text (e.g. "/\\d+/gi") into pattern and flags */
+export declare function parseRegExpLiteral(text: string): {
+    pattern: string;
+    flags: string;
+};
+/** Math methods that need host imports (no native Wasm opcode) */
+export declare const MATH_HOST_METHODS_1ARG: Set<string>;
+export declare const MATH_HOST_METHODS_2ARG: Set<string>;
+/**
+ * Emit the __toUint32 Wasm helper function. Must be called AFTER all imports
+ * that are added directly via addImport (bypassing ensureLateImport's shift
+ * mechanism) have been registered, and BEFORE any user function body that
+ * calls Math.clz32 or Math.imul is compiled. Emitting earlier leaves a stale
+ * funcMap entry because addImport does not shift defined-function indices.
+ *
+ * Implements ES §7.1.7: NaN/±Infinity → 0, otherwise trunc(x) modulo 2^32.
+ */
+export declare function emitToUint32Helper(ctx: CodegenContext): void;
+/** Known constructors handled natively (not needing __new_ imports) */
+export declare const KNOWN_CONSTRUCTORS: Set<string>;
+/** Functional array methods that need host callback bridges */
+export declare const FUNCTIONAL_ARRAY_METHODS: Set<string>;
+/** Register union type helper imports (typeof checks, boxing/unboxing) */
+export declare function addUnionImports(ctx: CodegenContext): void;
+/** Register the iterator protocol host imports if not already registered */
+export declare function addIteratorImports(ctx: CodegenContext): void;
+/** Register array iterator host imports (entries/keys/values) if not already registered */
+export declare function addArrayIteratorImports(ctx: CodegenContext): void;
+/**
+ * Register the generator host imports if not already registered.
+ *
+ * The legacy generator codegen (eager-buffer model) uses these imports to
+ * push yielded values into a JS array on the host side, then wrap that
+ * buffer with `__create_generator` (or `__create_async_generator`) to
+ * produce a Generator-like / AsyncGenerator-like object. The IR path
+ * (slice 7 — #1169f) reuses the same set of imports — extracting this
+ * registration out of `declarations.ts:1014-1062` into a standalone
+ * exported helper so both legacy and IR can call it without duplicating
+ * the import-shape declarations.
+ *
+ * Imports registered (all under `env`):
+ *   - `__gen_create_buffer`   () → externref
+ *   - `__gen_push_f64`        (externref, f64) → ()
+ *   - `__gen_push_i32`        (externref, i32) → ()
+ *   - `__gen_push_ref`        (externref, externref) → ()
+ *   - `__gen_yield_star`      (externref, externref) → ()  (same shape as push_ref)
+ *   - `__create_generator`    (externref, externref) → externref  (buf, pendingThrow)
+ *   - `__create_async_generator` (externref, externref) → externref  (same shape)
+ *   - `__gen_next`            (externref) → externref
+ *   - `__gen_return`          (externref, externref) → externref
+ *   - `__gen_throw`           (externref, externref) → externref
+ *   - `__gen_result_value`    (externref) → externref
+ *   - `__gen_result_value_f64` (externref) → f64
+ *   - `__gen_result_done`     (externref) → i32
+ *   - `__get_caught_exception` () → externref  (for the body's try/catch wrapper)
+ */
+export declare function addGeneratorImports(ctx: CodegenContext, options?: {
+    allowNoJsHost?: boolean;
+}): void;
+/** Register for-in key enumeration host imports if not already registered */
+export declare function addForInImports(ctx: CodegenContext): void;
+/**
+ * Check if a ts.Type is a TypeScript tuple type (e.g. [number, string]).
+ * Tuples are TypeReference types whose target has the Tuple object flag.
+ * The Tuple flag is on the target, not the reference itself.
+ */
+export declare function isTupleType(type: ts.Type): boolean;
+/**
+ * Get the element types of a tuple type.
+ * Returns the resolved ValType for each element position.
+ */
+export declare function getTupleElementTypes(ctx: CodegenContext, tsType: ts.Type): ValType[];
+/**
+ * Get or register a Wasm GC struct type for a tuple type.
+ * Each unique tuple signature (e.g. [f64, externref]) maps to one struct type
+ * with fields named _0, _1, etc.
+ */
+export declare function getOrRegisterTupleType(ctx: CodegenContext, elemTypes: ValType[]): number;
+/**
+ * Detect native type annotations (e.g., `type i32 = number`) from a TS type's
+ * alias symbol. Returns the corresponding Wasm ValType, or null if not a native
+ * type annotation.
+ *
+ * TypeScript preserves the alias symbol on types at the usage site, so
+ * `let x: i32` where `type i32 = number` will have aliasSymbol.name === "i32"
+ * even though the resolved type is `number`.
+ */
+export declare function resolveNativeTypeAnnotation(tsType: ts.Type): ValType | null;
+/**
+ * (#2176) Resolve the type of an identifier reference, preferring the user's
+ * own declaration over an ambient lib (`.d.ts`) global of the same name.
+ *
+ * Root cause: js2wasm analyzes a top-level program as a **script** (no
+ * import/export ⇒ not a module). In script mode a top-level `const name = …`
+ * does NOT shadow the writable global `var name: string` declared in
+ * `lib.dom.d.ts` (both live in the global scope, and TypeScript resolves a
+ * bare reference to the ambient symbol). So `const y = name` types `y` as
+ * `void` (the ambient `name`) instead of `string`, and the colliding-name
+ * read (`` `${name}` ``, `"x" + name`, `const y = name`) loses its real type —
+ * the codegen then registers `y` as an i32 global and the value reads back as
+ * `0`/`undefined`. Runtime values are stored correctly under `$__mod_name`;
+ * only the *type* is poisoned. Common colliders: `name` (→ undefined),
+ * `length`, `top`, `status`, `origin`, etc. from lib.dom.
+ *
+ * Fix: when `getTypeAtLocation(id)` binds to a symbol whose declarations live
+ * ONLY in lib `.d.ts` files, but a user-level binding of that exact name is in
+ * scope (a non-lib declaration), re-derive the type from the user binding so
+ * the read/declaration sees the real type. Falls back to the original type
+ * when no user binding shadows the ambient — zero behavior change for genuine
+ * host-global reads (`window.name`, bare `length` with no user binding).
+ */
+export declare function resolveIdentifierType(ctx: CodegenContext, id: ts.Identifier): ts.Type;
+/**
+ * Resolve a ts.Type to a ValType, using the struct registry and anonymous type map.
+ * Use this instead of mapTsTypeToWasm in the codegen to get real type indices.
+ */
+export declare function resolveWasmType(ctx: CodegenContext, tsType: ts.Type, _depth?: number, _visited?: Set<ts.Type>): ValType;
+/**
+ * Ensure a ts.Type that's an object type is registered as a struct.
+ * For named types already in structMap, this is a no-op.
+ * For anonymous types, auto-registers them with a generated name.
+ */
+export declare function ensureStructForType(ctx: CodegenContext, tsType: ts.Type): void;
+/**
+ * Register built-in collection types (Set, Map, WeakMap, WeakSet) as extern classes
+ * if they weren't already collected from lib .d.ts files. This ensures these types
+ * are available for extern class method dispatch even when lib file scanning fails
+ * (e.g., bundled/browser environments where readLibFile returns empty strings).
+ */
+export declare function registerBuiltinExternClasses(ctx: CodegenContext): void;
+/**
+ * #1238 — Look up a pseudo-extern-class entry by className. Returns
+ * `undefined` when the className isn't registered as a pseudo-extern
+ * class (i.e., it's either a real extern class — query
+ * `ctx.externClasses` for those — or unknown).
+ *
+ * This is the canonical accessor for the synthetic String/Array
+ * registry. Existing consumers of `ctx.externClasses` are intentionally
+ * NOT updated to consult this map: the legacy `new ClassName()` /
+ * extern-method dispatch paths must keep their existing behaviour for
+ * String / Array (they're handled via inline special cases or
+ * `__new_<name>` / `string_<method>` lowercase imports). The pseudo
+ * registry is the IR-only seam, queried by #1232 (String dispatch) and
+ * #1233 (Array dispatch).
+ */
+export declare function getPseudoExternClassInfo(ctx: CodegenContext, className: string): ExternClassInfo | undefined;
+/**
+ * #1238 — TypeMap-keyed receiver-type → extern className lookup. Given an
+ * `IrType` resolved from the propagator's `TypeMap`, return the className
+ * of the matching synthetic extern class (or `null` if no match).
+ *
+ * This is the **MLIR-seam-friendly** dispatch helper: callers route
+ * receiver IrTypes here instead of pattern-matching `atom.kind ===
+ * "string"` inline. A future MLIR optimizer producing the same `IrType`
+ * shape would hit the same lookup, unchanged.
+ *
+ * Returns:
+ *   - `"String"` for `IrType.string` and `IrType.val<externref>`
+ *     (the externref arm covers post-#1169i extern-tagged strings)
+ *   - `"Array"` for `IrType.val<ref|ref_null>` whose typeIdx points at
+ *     a registered vec type (callers must check via their vec resolver)
+ *   - `null` for anything else (including primitives, classes, objects)
+ *
+ * Note: the array path is only metadata. Confirming the receiver IS a
+ * vec (vs. a generic ref) requires the lowerer's vec resolver — this
+ * helper just identifies the target className so the lowerer can pick
+ * which extern entry to consult. Callers should pair this with
+ * `getPseudoExternClassInfo(ctx, target)` to get the method metadata.
+ */
+export declare function resolveMethodDispatchTarget(t: import('../ir/nodes.js').IrType): "String" | "Array" | null;
+/** Collect enum declarations into ctx.enumValues / ctx.enumStringValues */
+export declare function collectEnumDeclarations(ctx: CodegenContext, sourceFile: ts.SourceFile): void;
+/**
+ * Resolve a class member's PropertyName to a static string.
+ * Handles identifiers, private identifiers, string literals, numeric literals,
+ * and computed property names that can be evaluated at compile time.
+ */
+/**
+ * Pre-pass: hoist all `var` declarations in a function body.
+ * Walks statements recursively and pre-allocates a local for each `var`
+ * variable not yet in localMap, so identifiers are valid before their
+ * declaration site (JavaScript var-hoisting semantics).
+ */
+export declare function hoistVarDeclarations(ctx: CodegenContext, fctx: FunctionContext, stmts: ts.NodeArray<ts.Statement> | ts.Statement[]): void;
+/**
+ * Allocate TDZ flags for a let/const destructuring binding pattern so that
+ * `let { x = x } = {}` and similar self/forward references in default
+ * initializers throw ReferenceError per ECMA-262 §13.3.3.7 (#1128).
+ *
+ * Called from `compileObjectDestructuring` / `compileArrayDestructuring` at
+ * entry — BEFORE the binding-element loop allocates the actual binding locals.
+ * Only the TDZ flag is allocated here; the destructuring's own `allocLocal`
+ * for the binding runs later (line ~648 of destructuring.ts) and registers
+ * the binding name in `localMap`. By the time the default initializer is
+ * compiled (after that `allocLocal`), `compileIdentifier` will see both
+ * `localMap.has(name)` and `tdzFlagLocals.get(name)` and apply the TDZ check.
+ *
+ * The TDZ flag is allocated unconditionally for destructured bindings —
+ * +1 i32 local per binding is cheap, and unconditionality avoids subtle
+ * static-analysis gaps inside default initializers where `analyzeTdzAccess`
+ * could otherwise mis-classify the access as "skip".
+ */
+export declare function ensureLetConstBindingPatternTdzFlags(ctx: CodegenContext, fctx: FunctionContext, pattern: ts.BindingPattern): void;
+/**
+ * Pre-pass: hoist all `let`/`const` declarations in a function body with TDZ flags.
+ * Unlike var-hoisting (which makes variables immediately accessible), let/const
+ * hoisting only pre-allocates the local + a TDZ flag so nested functions can
+ * capture the variable. The variable is still in TDZ until the declaration runs.
+ */
+export declare function hoistLetConstWithTdz(ctx: CodegenContext, fctx: FunctionContext, stmts: ts.NodeArray<ts.Statement> | ts.Statement[]): void;
+/**
+ * Check if a let/const variable needs a TDZ flag by analyzing all references.
+ * Returns false if every access to the symbol is provably after the declaration
+ * in straight-line code (same function, no closures, loop-local safe).
+ */
+export declare function needsTdzFlag(ctx: CodegenContext, decl: ts.VariableDeclaration): boolean;
+/**
+ * Check if a function body 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`.
+ */
+export declare function cacheStringLiterals(ctx: CodegenContext, fctx: FunctionContext): void;
+export declare function hasExportModifier(node: ts.Node): boolean;
+export declare function hasDeclareModifier(node: ts.Node): boolean;
+export declare function hasAsyncModifier(node: ts.Node): boolean;
+export declare function hasAbstractModifier(node: ts.Node): boolean;
+export declare function hasStaticModifier(node: ts.Node): boolean;
+/** Check if a function declaration is a generator (function*) */
+export declare function isGeneratorFunction(node: ts.FunctionDeclaration): boolean;
+/**
+ * Unwrap Generator<T> return type to get the yield element type T.
+ * Falls back to externref if the type cannot be unwrapped.
+ */
+export declare function unwrapGeneratorYieldType(type: ts.Type, ctx: CodegenContext): ValType;
+/**
+ * Ensure the stack top is an i32 suitable for use as a condition.
+ * Handles: f64 (truthy != 0), externref (JS truthiness via __is_truthy), null (push 0).
+ */
+export declare function ensureI32Condition(fctx: FunctionContext, condType: ValType | null, ctx?: CodegenContext): void;
+export { popBody, pushBody } from './context/bodies.js';
+export { createCodegenContext } from './context/create-context.js';
+export { reportError } from './context/errors.js';
+export { allocLocal, allocTempLocal, getLocalType, releaseTempLocal } from './context/locals.js';
+export { attachSourcePos, getSourcePos } from './context/source-pos.js';
+export type { ClosureInfo, CodegenContext, CodegenOptions, CodegenResult, ExternClassInfo, FunctionContext, InlinableFunctionInfo, OptionalParamInfo, RestParamInfo, } from './context/types.js';
+export { addImport, addStringConstantGlobal, ensureExnTag, localGlobalIdx, nextModuleGlobalIdx, } from './registry/imports.js';
+export { addFuncType, funcTypeEq, getArrTypeIdxFromVec, getOrRegisterArrayType, getOrRegisterRefCellType, getOrRegisterTemplateVecType, getOrRegisterVecType, } from './registry/types.js';
+export { compileExpression, compileStatement } from './shared.js';

package/dist/codegen/ir-tail-call.d.ts

@@ -0,0 +1,8 @@
+import { CodegenContext } from './context/types.js';
+import { Instr } from '../ir/types.js';
+/**
+ * Apply tail-call optimization to an IR-lowered function body in place.
+ * `funcTypeIdx` is the lowered function's own type index. Returns the rewritten
+ * body (a new top-level array; nested arms are mutated in place).
+ */
+export declare function applyIrTailCalls(ctx: CodegenContext, body: Instr[], funcTypeIdx: number): Instr[];

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

@@ -0,0 +1,44 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Lazily register (or fetch) the `$__IterRec` GC struct type. Mirrors
+ * `ensureNativeGeneratorResultType` (generators-native.ts) — one struct per
+ * module, cached via `ctx.structMap`.
+ */
+export declare function getOrRegisterIterRecType(ctx: CodegenContext): number;
+/**
+ * #1320 Slice 1 — register the four iteration-protocol operations as native
+ * Wasm functions (standalone/WASI). Idempotent: guards on `funcMap.has`.
+ *
+ * Signatures match the JS-host imports exactly so consumer codegen is
+ * byte-identical:
+ *   __iterator(externref) -> externref               (GetIterator)
+ *   __iterator_next(externref) -> (i32 done, externref value)  (IteratorStep)
+ *   __iterator_return(externref) -> ()               (IteratorClose)
+ *   __iterator_rest(externref) -> externref          (drain remainder → vec)
+ *
+ * The argument to `__iterator` is, in Slice 1, an externref-wrapped canonical
+ * externref `$Vec` (the caller box-builds it). `__iterator` wraps it in an
+ * `$IterRec`; `__iterator_next` walks the vec by index.
+ *
+ * (#2038) The `__iterator` / `__iterator_next` bodies are emitted **vec-only**
+ * here — byte-identical to the pre-USER runtime — and `nativeIteratorUserArmPending`
+ * is set so `fillNativeIteratorUserArms` (finalize) rebuilds them with the USER
+ * arm once the closed-struct dispatchers exist. A non-vec subject keeps trapping
+ * (the legacy hard cast) until that fill runs, so a module where the fill is
+ * skipped (e.g. multi-module) never ships a broken iterator.
+ */
+export declare function ensureNativeIteratorRuntime(ctx: CodegenContext): void;
+/**
+ * (#2038, reserve-then-fill #1719) Rebuild the `__iterator` / `__iterator_next`
+ * bodies with the USER `{next()}`-protocol arm, now that the closed-struct
+ * dispatchers (`__call_@@iterator`, `__call_next`, `__sget_value`, `__sget_done`)
+ * and `__is_truthy` have been emitted at finalize. No-op when:
+ *   - the native runtime was never registered (`!nativeIteratorUserArmPending`),
+ *   - any dispatcher is absent (e.g. no custom iterable / `{value,done}` struct in
+ *     the module) — the carrier stays vec-only and byte-identical.
+ *
+ * MUST be called AFTER `emitStructFieldGetters` + `emitIteratorMethodExport` in
+ * the finalize sequence. Storing the carrier funcIdx in `funcMap` (and looking it
+ * up post-shift here) keeps it in lockstep with any late-import index shift.
+ */
+export declare function fillNativeIteratorUserArms(ctx: CodegenContext): void;

package/dist/codegen/json-codec-native.d.ts

@@ -0,0 +1,78 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Emit `__json_stringify_value(v: anyref, depth: i32) -> ref null $AnyString`
+ * and register it in `ctx.funcMap`. Idempotent. Standalone / WASI only.
+ *
+ * A null result encodes "value serialises to JS `undefined`" (function /
+ * symbol / unsupported ref) — the caller's array/object arms apply the §25.5.2
+ * omit-vs-`null` rule.
+ *
+ * Returns the funcIdx.
+ */
+export declare function emitJsonStringifyValue(ctx: CodegenContext): number;
+/**
+ * Emit the pure-Wasm recursive-descent `JSON.parse` codec (#2166 PR-C) and
+ * register `__json_parse_text(s: externref) -> anyref` in `ctx.funcMap`.
+ * Idempotent. Standalone / WASI only.
+ *
+ * The grammar is ECMA-404 / ECMA-262 §25.5.1 (strict JSON — no comments, no
+ * trailing commas, no single quotes). The output uses the SAME value
+ * representation the standalone object runtime and the `__json_stringify_value`
+ * codec consume, so a round-trip `JSON.parse(JSON.stringify(o))` and downstream
+ * property reads (`__extern_get`) work without conversion:
+ *
+ *   - object → a fresh `$Object` (built via `__new_plain_object` +
+ *     `__extern_set`), widened to `anyref`. Members preserve insertion order.
+ *   - array  → a fresh `$ObjVec` (built via `__objvec_new` + `__objvec_push`),
+ *     widened to `anyref`.
+ *   - string → a native `$AnyString` (the unescaped code units), widened to
+ *     `anyref` — the same carrier object/array element reads already see.
+ *   - number → boxed into the `$AnyValue` tagged union (tag 3, f64).
+ *   - true / false → `$AnyValue` tag 4; null → `$AnyValue` tag 0.
+ *
+ * A grammar violation (or trailing non-whitespace) throws a runtime
+ * `SyntaxError` via the standalone `__new_SyntaxError` constructor — matching
+ * §25.5.1 step 3 — instead of trapping. The result `anyref` flows through the
+ * existing `$AnyValue`/object coercion paths in type-coercion.ts.
+ *
+ * Implementation note: the mutually-recursive value/string parsers share a
+ * cursor through a `$JsonP` parser-state struct (`{ data, pos(mut), end }`).
+ * That struct is passed as a bare **`anyref`** parameter (and `ref.cast` back
+ * inside each helper) rather than as `ref $JsonP`. A fresh GC struct type that
+ * appears in a *function-signature* parameter has tripped the dead-type-
+ * elimination remap in this codebase (the func-type param and the in-body
+ * `struct.get` operand can diverge after compaction); keeping the fresh
+ * `$JsonP` index off every signature and confined to `struct.new`/`struct.get`/
+ * `struct.set`/`ref.cast` instruction operands — which `remapTypeIdxInBody`
+ * rewrites uniformly — sidesteps that hazard.
+ *
+ * Returns the `__json_parse_text` funcIdx.
+ */
+export declare function emitJsonParseText(ctx: CodegenContext): number;
+/**
+ * (#2166 PR-D1) Emit the standalone `JSON.parse(text, reviver)` codec —
+ * `__json_parse_text_reviver(text: externref, reviver: externref) -> anyref` —
+ * and the recursive §25.5.1 InternalizeJSONProperty walk
+ * `__internalize_json_property(holder: externref, key: externref,
+ * reviver: externref) -> externref`. Idempotent. Standalone / WASI only.
+ *
+ * The reviver itself is a USER closure (externref). It is invoked via the
+ * reserve/fill `__call_reviver` driver (accessor-driver.ts) which wraps
+ * `__call_fn_method_2(holder, reviver, key, value)` — binding `holder` as `this`
+ * and passing `key`/`value` as the two reviver args (§25.5.1 step 2.c). The fill
+ * runs in finalize after `__call_fn_method_2` is registered; when no arity-2
+ * closure exists the driver degrades to an identity (returns the value), so a
+ * module with no reviver closure still verifies.
+ *
+ * Walk (§25.5.1 InternalizeJSONProperty(holder, key, reviver)):
+ *   val = holder[key]
+ *   if val is an Object: for each own key k (snapshot taken BEFORE recursion,
+ *     §25.5.1 step 2.a.i — a reviver that adds keys doesn't see them):
+ *       elem = InternalizeJSONProperty(val, k, reviver)
+ *       if elem is undefined → delete val[k]   else → val[k] = elem
+ *   if val is an Array ($ObjVec): same over numeric indices with string keys.
+ *   return reviver.call(holder, key, val)
+ *
+ * Returns the funcIdx of `__json_parse_text_reviver`.
+ */
+export declare function emitJsonParseTextReviver(ctx: CodegenContext): number;