@loopdive/js2 0.57.0

package/dist/codegen/statements/nested-declarations.d.ts

@@ -0,0 +1,78 @@
+import { ts } from '../../ts-api.js';
+import { ValType, WasmFunction } from '../../ir/types.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileNestedClassDeclaration(ctx: CodegenContext, fctx: FunctionContext, decl: ts.ClassDeclaration): void;
+interface CompileNestedFunctionOptions {
+    reuseReservedEntry?: WasmFunction;
+}
+export declare function compileNestedFunctionDeclaration(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.FunctionDeclaration, opts?: CompileNestedFunctionOptions): void;
+export declare function hoistFunctionDeclarations(ctx: CodegenContext, fctx: FunctionContext, stmts: ts.NodeArray<ts.Statement> | ts.Statement[], _eagerBoxFuncNames?: Set<string>): void;
+/**
+ * Register (on first use) a module-level mutable global that carries
+ * "extra" runtime arguments from a call site to a callee whose body reads
+ * `arguments`. The global is consumed (read + reset to null) in the
+ * callee's prologue (#1053).
+ *
+ * Type: `(mut (ref null $vec_externref))` — a WasmGC vec of externref.
+ */
+export declare function ensureExtrasArgvGlobal(ctx: CodegenContext): {
+    globalIdx: number;
+    vecTypeIdx: number;
+};
+/**
+ * Lazily register a `(mut i32)` module global `__argc` that callers set
+ * to the actual call-site argument count before invoking a function whose
+ * body reads `arguments`. The callee reads this to set `arguments.length`
+ * correctly (instead of using the formal parameter count).
+ */
+export declare function ensureArgcGlobal(ctx: CodegenContext): number;
+/**
+ * Cache the call-site argument count once at function entry for parameter
+ * default checks. The raw -1 sentinel is preserved in the local; callers use
+ * that to mean "unknown host/module-init caller".
+ */
+export declare function cacheParamDefaultArgc(ctx: CodegenContext, fctx: FunctionContext): number;
+export declare function paramDefaultNeedsArgc(type: ValType | undefined): boolean;
+export declare function emitParamDefaultArgMissingCheck(fctx: FunctionContext, argcLocal: number, argIndex: number): void;
+export declare function emitF64ParamSentinelCheck(fctx: FunctionContext, paramIdx: number): void;
+export declare function maybeSetArgcForKnownCall(ctx: CodegenContext, fctx: FunctionContext, funcName: string, actualArgCount: number, paramCount: number): void;
+/**
+ * (#1636-S1) Lazily register a `(mut externref)` module global
+ * `__current_this` used by `__call_fn_method_N` to thread a host-supplied
+ * `this`-value into a Wasm closure body. The dispatcher save+restores the
+ * previous value across the inner `call_ref`, and `ThisKeyword` resolution
+ * reads this global when no local `this` binding is in scope (free-closure
+ * fallback). Default value is `ref.null.extern` (= JS `null`), which is
+ * compatible with the prior "undefined fallback" behaviour for the vast
+ * majority of references that compare strictly against null/undefined.
+ */
+export declare function ensureCurrentThisGlobal(ctx: CodegenContext): number;
+/**
+ * Emit code to build a vec struct from `args[startIdx..]` and
+ * store it in the `__extras_argv` module global. Used at call sites when
+ * the callee reads `arguments` and the caller passes more runtime args
+ * than the callee's formal param count (#1053).
+ */
+export declare function emitSetExtrasArgv(ctx: CodegenContext, fctx: FunctionContext, args: ts.Expression[], startIdx: number): void;
+/**
+ * Shared arguments-vec construction: compiles formal params, concatenates
+ * extras from the `__extras_argv` global (#1053), and stores the final vec
+ * struct in `argsLocalIdx`. Used by both emitArgumentsObject and the
+ * function-body.ts inline path.
+ */
+export declare function emitArgumentsVecBody(ctx: CodegenContext, fctx: FunctionContext, paramTypes: ValType[], paramOffset: number, locals: {
+    vecTypeIdx: number;
+    arrTypeIdx: number;
+    argsLocalIdx: number;
+    arrTmpIdx: number;
+}): void;
+/**
+ * Emit code to create an `arguments` vec struct from function parameters.
+ * paramOffset is the number of leading params to skip (e.g. captures).
+ *
+ * Uses an externref-backed vec so that all parameter types (f64, i32,
+ * externref, ref) are preserved as externref values.  This matches JS
+ * semantics where `arguments[n]` returns the original value.
+ */
+export declare function emitArgumentsObject(ctx: CodegenContext, fctx: FunctionContext, paramTypes: ValType[], paramOffset: number, unmapped?: boolean): void;
+export {};

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

@@ -0,0 +1,38 @@
+import { ts } from '../../ts-api.js';
+import { Instr } from '../../ir/types.js';
+import { FunctionContext, NullGuardFact } from '../context/types.js';
+/**
+ * Adjust the depth of all entries in the catchRethrowStack by `delta`.
+ * Called wherever breakStack entries are bulk-adjusted for block nesting changes.
+ */
+export declare function adjustRethrowDepth(fctx: FunctionContext, delta: number): void;
+/**
+ * Collect instructions emitted by `emitFn` into a separate array without
+ * appending them to the current `fctx.body`.  This replaces the pervasive
+ * "save body / swap / restore" pattern that was duplicated dozens of times.
+ */
+export declare function collectInstrs(fctx: FunctionContext, emitFn: () => void): Instr[];
+/** Saved state for a block scope: localMap + optional TDZ/const flags */
+export interface BlockScopeSave {
+    locals: Map<string, number> | null;
+    tdzFlags: Map<string, number> | null;
+    constBindings: Map<string, boolean> | null;
+    nullGuardAliases: Map<string, NullGuardFact | null> | null;
+}
+/**
+ * Collect the names of block-scoped (let/const) variable declarations that
+ * are direct children of a block (not nested blocks — those handle their own).
+ */
+export declare function collectBlockScopedNames(stmt: ts.Block): string[];
+/**
+ * Save localMap (and TDZ flag) entries for block-scoped names that shadow
+ * existing locals.  Also removes the shadow entries from localMap (and
+ * tdzFlagLocals) so that compileVariableStatement will allocate fresh locals.
+ * Returns the saved state to restore after the block.
+ */
+export declare function saveBlockScopedShadows(fctx: FunctionContext, block: ts.Block): BlockScopeSave | null;
+/**
+ * Restore localMap (and TDZ flag) entries that were saved before entering
+ * a block scope.
+ */
+export declare function restoreBlockScopedShadows(fctx: FunctionContext, saved: BlockScopeSave | null): void;

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

@@ -0,0 +1,43 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+/**
+ * #1452 — Walk a binding pattern (array / object / nested / rest) and yield
+ * every identifier name that the pattern binds. `{a: y}` introduces `y`,
+ * not `a`. `[...rest]` introduces `rest`. Used to drive the bulk TDZ-flip
+ * step that runs after a binding-pattern destructure completes.
+ */
+export declare function collectPatternBindingNames(name: ts.BindingName): Iterable<string>;
+/**
+ * #1452 — After a binding-pattern destructure completes, flip every
+ * declared identifier's TDZ flag to "initialized". The dedicated
+ * destructuring helpers already emit `emitLocalTdzInit` for the
+ * struct-path object form, but the externref array fallback, the
+ * vec/tuple-struct array forms, and the rest-element branches do not.
+ * Walking the pattern once here is safer than peppering every
+ * code path with individual calls.
+ */
+export declare function emitTdzInitForBindingPattern(fctx: FunctionContext, pattern: ts.BindingName): void;
+/**
+ * Emit instructions to set a TDZ flag global to 1 (initialized) for a module-level
+ * let/const variable. No-op if the variable doesn't have a TDZ flag.
+ */
+export declare function emitTdzInit(ctx: CodegenContext, fctx: FunctionContext, name: string): void;
+/**
+ * Emit instructions to set a local TDZ flag to 1 (initialized) for a function-level
+ * let/const variable. No-op if the variable doesn't have a local TDZ flag.
+ *
+ * Also calls `emitTdzInit` for the module-global case — this is needed when
+ * destructuring at the module level (walkStmtForLetConst pre-pass may register
+ * a TDZ flag in either tdzGlobals or tdzFlagLocals depending on scope).
+ *
+ * If the flag has been boxed in an i32 ref cell (because it was captured by
+ * a closure — see #1177), the set must go through `struct.set` so the
+ * mutation propagates to every closure that captured the same ref cell.
+ */
+export declare function emitLocalTdzInit(fctx: FunctionContext, name: string): void;
+/**
+ * Emit a TDZ check for a module-level let/const variable read.
+ * If the TDZ flag is 0 (uninitialized), throw a ReferenceError.
+ * No-op if the variable doesn't have a TDZ flag.
+ */
+export declare function emitTdzCheck(ctx: CodegenContext, fctx: FunctionContext, name: string): void;

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

@@ -0,0 +1,3 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, FunctionContext } from '../context/types.js';
+export declare function compileVariableStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.VariableStatement): void;

package/dist/codegen/statements.d.ts

@@ -0,0 +1,9 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export { compileExternrefArrayDestructuringDecl, compileExternrefObjectDestructuringDecl, emitDefaultValueCheck, emitExternrefDefaultCheck, emitNestedBindingDefault, ensureBindingLocals, } from './statements/destructuring.js';
+export { bodyUsesArguments } from './helpers/body-uses-arguments.js';
+export { emitArgumentsObject, hoistFunctionDeclarations } from './statements/nested-declarations.js';
+export { collectInstrs } from './statements/shared.js';
+export { emitTdzCheck } from './statements/tdz.js';
+/** Compile a statement, appending instructions to the function body */
+export declare function compileStatement(ctx: CodegenContext, fctx: FunctionContext, stmt: ts.Statement): void;

package/dist/codegen/string-builder.d.ts

@@ -0,0 +1,131 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * #1761 — presize info for a string-builder whose final length is provably a
+ * runtime-known linear function of a loop bound. When the build loop is a
+ * canonical `for (let i = 0; i < BOUND; i++)` (step +1) whose body appends a
+ * statically-fixed number of code units per iteration and never exits early,
+ * the final buffer length is exactly `BOUND * unitsPerIter`. Presizing the
+ * WasmGC i16 buffer to that length up front eliminates every doubling
+ * reallocation AND lets the per-append `len+1 > cap` cap-check be removed
+ * (the capacity is proven sufficient for all appends). See #1746 lever #3.
+ */
+export interface StringBuilderPresizeInfo {
+    /** Loop-invariant bound expression, evaluated once at buffer-init time. */
+    boundExpr: ts.Expression;
+    /** Constant code-unit count appended per loop iteration (the exact total
+     *  is `boundExpr * unitsPerIter`). */
+    unitsPerIter: number;
+}
+/**
+ * Scan a function body for `let s = ""; for (...) s += <expr>` patterns and
+ * return the set of qualifying VariableDeclaration nodes. Caller stores this
+ * as `fctx.pendingStringBuilders` so `compileVariableStatement` can detect
+ * the rewrite when it reaches the matching declarator.
+ *
+ * When `presizeOut` is provided, any builder whose final length is provably a
+ * runtime-known linear function of a loop bound (#1761) is additionally
+ * recorded there keyed by its declaration, so the init site can presize the
+ * buffer and the append sites can drop the cap-check.
+ *
+ * Only scans `nativeStrings` mode — caller should gate on `ctx.nativeStrings`.
+ */
+export declare function detectStringBuilders(ctx: CodegenContext, fnBody: ts.Block | ts.SourceFile | undefined, presizeOut?: Map<ts.VariableDeclaration, StringBuilderPresizeInfo>): Set<ts.VariableDeclaration>;
+/**
+ * Emit the buffer-init sequence for a string-builder binding. Allocates
+ * `${name}$buf`, `${name}$len`, `${name}$cap`, `${name}$mat` locals,
+ * registers them in `fctx.stringBuilders`, and emits initialization that
+ * sets `buf := array.new_default 16`, `len := 0`, `cap := 16`, `mat := null`.
+ *
+ * #1761: when `presize` is supplied, the buffer is allocated once at the
+ * provably-final length `bound * unitsPerIter` instead of the doubling
+ * initial 16, the recorded capacity matches, and `sb.presized` is set so the
+ * append sites drop the per-append `len+1 > cap` cap-check (the capacity is
+ * proven sufficient for every append). `bound` is evaluated once here, before
+ * the loop runs — sound because the analysis proved it loop-invariant. A
+ * non-positive bound yields a 0-length buffer; the loop then runs 0 times and
+ * appends nothing, so the empty buffer is correct (any later read of the
+ * never-grown builder materialises a 0-length string).
+ *
+ * Caller is responsible for calling this from the variable-statement
+ * dispatcher when it sees a decl present in `fctx.pendingStringBuilders`,
+ * and for ensuring native string helpers have been emitted (so
+ * `__str_buf_next_cap` is available when a later append needs it).
+ */
+export declare function compileStringBuilderInit(ctx: CodegenContext, fctx: FunctionContext, name: string, presize?: StringBuilderPresizeInfo): void;
+/**
+ * Append a string-typed expression to a string-builder binding. The RHS
+ * value is left-on-stack as `ref $AnyString` by the caller via
+ * `coerceRhsToAnyStringRef`; this helper consumes it and emits:
+ *
+ *   1. Flatten the RHS so we have access to `data`/`off`/`len`.
+ *   2. needed = sb.len + rhs.len
+ *   3. If needed > sb.cap, grow `sb.buf` to a doubled capacity and copy
+ *      the existing prefix in.
+ *   4. array.copy(sb.buf, sb.len, rhs.data, rhs.off, rhs.len)
+ *   5. sb.len = needed
+ *   6. Invalidate sb.mat (set to null) so the next read re-materializes.
+ *
+ * The result is `ref_null $AnyString` (always pushes ref.null) — for the
+ * common statement-level `s += "x";` the caller drops it. If used as an
+ * expression value, this is a behavioural change vs. the legacy concat
+ * path (which returned the new string ref). The detector only matches
+ * `s += <expr>` as a side-effecting statement — uses where the expression
+ * value is consumed are conservative and rare; they will materialize via
+ * the next identifier read.
+ */
+export interface StringBuilderInfo {
+    bufLocalIdx: number;
+    lenLocalIdx: number;
+    capLocalIdx: number;
+    materializedLocalIdx: number;
+    /**
+     * #1761: when true, the buffer was presized to the provably-final length, so
+     * every append's `len+N > cap` cap-check / grow branch is statically known
+     * to be unreachable and is omitted. When false (or absent), appends keep the
+     * doubling grow path.
+     */
+    presized?: boolean;
+}
+export declare function compileStringBuilderAppend(ctx: CodegenContext, fctx: FunctionContext, rhsAnyStrType: ValType, sb: StringBuilderInfo): void;
+/**
+ * #1744 — single-code-unit append fast path.
+ *
+ * Appends ONE i16 code unit to the string-builder buffer without allocating
+ * an intermediate `$NativeString`. The caller has already pushed the code
+ * unit (an `i32` in 0..0xFFFF) onto the stack; this consumes it and emits:
+ *
+ *   1. cu = <stack top>                      ; stash the code unit
+ *   2. if (sb.len + 1 > sb.cap) grow buffer  ; same doubling policy as append
+ *   3. sb.buf[sb.len] = cu
+ *   4. sb.len = sb.len + 1
+ *   5. sb.mat = null                         ; invalidate the cache
+ *
+ * This is the hot path for `buf += X.charAt(i)` / `buf += "<1 char>"`: the
+ * generic `compileStringBuilderAppend` would otherwise materialise a 1-char
+ * `$NativeString` (`array.new_fixed` + `struct.new`) per iteration just to
+ * copy a single character out of it (~40k throwaway allocations on the
+ * string-hash benchmark). Reading the code unit directly and `array.set`ing
+ * it removes both the allocation and the per-iteration `__str_flatten` on the
+ * result.
+ *
+ * Correctness: this is a verbatim code-unit copy. `charAt` is itself
+ * code-unit-indexed (it returns the WTF-16 unit at the index, splitting
+ * surrogate pairs), so copying the raw unit into the i16 buffer is exactly
+ * what the string-roundtrip path does — no surrogate handling differs.
+ */
+export declare function emitStringBuilderAppendCodeUnit(ctx: CodegenContext, fctx: FunctionContext, sb: StringBuilderInfo): void;
+/**
+ * Materialize the current contents of a string builder into a `ref $NativeString`
+ * (compatible with `ref $AnyString`). Pushes the materialized ref onto the
+ * stack. Caches the result in `sb.mat` so repeated reads (e.g.
+ * `s.length` then `s.charCodeAt(...)` in the same expression) reuse one
+ * struct allocation. The cache is invalidated by `compileStringBuilderAppend`.
+ *
+ * Returns the value type of the pushed ref so the caller can stitch it into
+ * the surrounding expression.
+ */
+export declare function emitStringBuilderRead(ctx: CodegenContext, fctx: FunctionContext, sb: StringBuilderInfo): ValType;
+/** Helper to look up an active builder by binding name. */
+export declare function getBuilderInfo(fctx: FunctionContext, name: string): StringBuilderInfo | undefined;

package/dist/codegen/string-ops.d.ts

@@ -0,0 +1,87 @@
+import { ValType } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext, HoistedCharRead } from './context/types.js';
+export declare function compileStringLiteral(ctx: CodegenContext, fctx: FunctionContext, value: string, node?: ts.Node): ValType | null;
+/**
+ * Materialize a string literal as a NativeString GC struct in fast mode.
+ * Emits array.new_fixed with the WTF-16 code units, then struct.new.
+ */
+export declare function compileNativeStringLiteral(ctx: CodegenContext, fctx: FunctionContext, value: string): ValType;
+export declare function compileTemplateExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.TemplateExpression): ValType | null;
+/**
+ * Compile a template expression in fast mode, using native string concat.
+ * Number substitutions are converted via number_toString (returns externref)
+ * then marshaled to native string.
+ */
+export declare function compileNativeTemplateExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.TemplateExpression): ValType | null;
+/**
+ * Compile a tagged template expression: tag`hello ${x} world`
+ * Desugars to: tag(["hello ", " world"], x)
+ *
+ * Implementation: build a WasmGC externref array (vec struct) of string parts,
+ * then call the tag function with the array as first arg and substitutions
+ * as remaining args. NO host imports needed.
+ */
+export declare function compileTaggedTemplateExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.TaggedTemplateExpression): ValType | null;
+/**
+ * Emit wasm code to convert a boolean (i32) on the stack to a string.
+ * Produces "true" or "false" string constant (externref) via if/else.
+ */
+export declare function emitBoolToString(ctx: CodegenContext, fctx: FunctionContext): ValType;
+export declare function compileStringBinaryOp(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression, op: ts.SyntaxKind): ValType | null;
+/**
+ * #2682: if `expr` is `recv.charCodeAt(i)` where `recv` is the loop-invariant
+ * receiver and `i` the in-bounds-proven induction variable of an active
+ * canonical string-read loop, return that loop's hoisted-descriptor proof.
+ * Otherwise return null. Both the i32-pure-leaf path (binary-ops.ts) and the
+ * f64 charCodeAt lowering below consult this. The match is deliberately exact —
+ * the argument must be the SAME induction identifier (not `i+1`, not a literal)
+ * so the dropped OOB branch stays sound.
+ */
+export declare function matchHoistedCharRead(fctx: FunctionContext, expr: ts.Expression): HoistedCharRead | null;
+/**
+ * #2682: emit the hoisted-descriptor charCodeAt read, leaving an i32 char code
+ * on the stack. The receiver was flattened once before the loop and `i` is
+ * proven `0 <= i < len`, so this is a bare `array.get_u(dataLocal, offLocal + i)`
+ * — no `__str_flatten`, no `.data`/`.off` struct.get reload, no OOB/NaN branch.
+ * Caller must have matched via {@link matchHoistedCharRead}.
+ */
+export declare function emitHoistedCharCodeAtRead(ctx: CodegenContext, fctx: FunctionContext, entry: HoistedCharRead, idxArg: ts.Expression): void;
+/**
+ * Compile a method call on a native string in fast mode.
+ * Handles: charCodeAt (inline), charAt, substring, slice (native helpers),
+ * and delegates other methods to host via marshal.
+ */
+export declare function compileNativeStringMethodCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression, propAccess: ts.PropertyAccessExpression, method: string, 
+/**
+ * (#2576, extends #2187) Optional receiver emitter. When provided, the method
+ * arms push the receiver via this callback instead of re-compiling
+ * `propAccess.expression`. Used by {@link compileGuardedNativeStringMethodCall}
+ * to feed a pre-evaluated, guard-cast `$AnyString` receiver (so an `any`-typed
+ * receiver is evaluated exactly once and only after a runtime `ref.test
+ * $AnyString` succeeds). The callback must push one value (a native-string ref
+ * / `$AnyString`) and return its ValType, mirroring `compileExpression`.
+ */
+receiverOverride?: () => ValType | null): ValType | null;
+/**
+ * (#2576, extends #2187) Runtime-guarded native string method dispatch for an
+ * `any`/unknown receiver whose value MAY be a native `$AnyString` at runtime
+ * (object property values, generator yield reads, catch bindings, indexed
+ * element reads — see `receiverMayBeNativeStringAtRuntime`). The static
+ * `isStringType` / `receiverIsNativeStringValType` gates miss these (the value
+ * is an opaque externref), so without this the call fell to the host/dynamic
+ * path (null/0 standalone).
+ *
+ * Evaluates the receiver EXACTLY ONCE into an externref temp (preserving side
+ * effects and ordering), then `ref.test $AnyString`:
+ *   - hit  → cast the saved externref to `$AnyString` and run the normal native
+ *            method lowering against it (via `compileNativeStringMethodCall`'s
+ *            receiver override — the receiver is NOT re-compiled),
+ *   - miss → the method's spec default for its result type (so a non-string
+ *            `any` — array, number, null — does not trap and yields a benign
+ *            default rather than a wrong value).
+ *
+ * Standalone/WASI native-string mode only; the caller gates on
+ * `ctx.nativeStrings && ctx.anyStrTypeIdx >= 0`.
+ */
+export declare function compileGuardedNativeStringMethodCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression, propAccess: ts.PropertyAccessExpression, method: string): ValType | null;

package/dist/codegen/struct-accessor-closure.d.ts

@@ -0,0 +1,36 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * (#1888 S5c) Master gate — keep the struct-accessor closure rework DARK until
+ * C1-C5 are wired + validated. Flip to `true` in the C5 PR once the S5c RED
+ * tests pass and S5b/GC regression guards hold.
+ */
+export declare const S5C_STRUCT_ACCESSOR_CLOSURE = true;
+/** Module-global name for a struct accessor's getter closure slot. */
+export declare function structAccessorGetGlobalName(structName: string, propName: string): string;
+/** Module-global name for a struct accessor's setter closure slot. */
+export declare function structAccessorSetGlobalName(structName: string, propName: string): string;
+/**
+ * Compile a struct accessor getter/setter as a host-free CLOSURE and leave its
+ * externref (capture-bearing `$Closure`, ready to box into a per-(struct,prop)
+ * global) on the stack. Returns `false` when the lift could not be performed
+ * (caller falls back). Mirrors the standalone branch of object-ops.ts
+ * `emitAccessorFn` so the open-`$Object` S5b arm and the struct arm share one
+ * lift; only the storage target differs (S5b → `__defineProperty_accessor`
+ * arg; S5c struct → `global.set $__acc_get/set_…`).
+ *
+ * The closure's body captures outer-scope reads into its `$self` struct
+ * (compileArrowAsClosure) and observes `this` via `__current_this` at invoke
+ * time (#1636-S1) — so the dispatched value carries the env the bare-fn lacked.
+ */
+export declare function buildAccessorClosure(ctx: CodegenContext, fctx: FunctionContext, fn: ts.FunctionExpression | ts.ArrowFunction): boolean;
+/**
+ * Reserve (idempotently) the per-(struct,prop) nullable `(mut externref)` module
+ * global holding a struct accessor's getter or setter closure, and record it in
+ * `ctx.structAccessorClosure[key]`. Returns the global index. Initialised to
+ * `ref.null.extern`; the C2 define-site `global.set`s the lifted closure.
+ *
+ * `kind` selects the get vs set slot. Reusing an already-reserved slot (e.g. a
+ * redefine of the same accessor) returns the existing index.
+ */
+export declare function ensureStructAccessorGlobal(ctx: CodegenContext, structName: string, propName: string, kind: "get" | "set"): number;

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

@@ -0,0 +1,55 @@
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Ensure the symbol description table's array type and lazy global exist.
+ * Idempotent. Sets `ctx.symbolDescArrTypeIdx` and `ctx.symbolDescGlobalIdx`.
+ */
+export declare function ensureSymbolDescTable(ctx: CodegenContext): void;
+/**
+ * Emit code that stores a description for a symbol id into the native table.
+ *
+ * Stack in:  `[i32 id, ref_null $AnyString desc]`  (desc on top)
+ * Stack out: `[]`
+ *
+ * Allocates the table on first use and grows it (×2 until it fits, copying the
+ * existing slots) when `id >= table.len`.
+ */
+export declare function emitSymbolDescStore(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Emit code that loads the description for a symbol id from the native table.
+ *
+ * Stack in:  `[i32 id]`
+ * Stack out: `[ref_null $AnyString]`  (null when the table is unallocated, the
+ *            id is out of range, or the slot was never set — all of which the
+ *            `.description` accessor treats as `undefined`).
+ */
+export declare function emitSymbolDescLoad(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * (#2163) Ensure the native `Symbol.for` / `Symbol.keyFor` registry exists:
+ * two parallel growable arrays (slot→key `$AnyString`, slot→symbol id i32) plus
+ * a count global, and the two runtime helper functions `__symbol_for_native`
+ * and `__symbol_keyfor_native`. Idempotent.
+ *
+ * The registry reuses the description-table key types and the native
+ * `__str_equals` (content equality, flattens cons-strings) for the key lookup.
+ * A registered symbol's description is its key (§20.4.2.2 step 4b), so
+ * `__symbol_for_native` also stores the key in the description table.
+ */
+export declare function ensureSymbolRegistry(ctx: CodegenContext): {
+    forIdx: number;
+    keyForIdx: number;
+};
+/**
+ * (#2163) Emit `Symbol.prototype.toString` (§20.4.3.3 → SymbolDescriptiveString,
+ * §20.4.3.3.1) in `noJsHost` mode, producing the native string
+ * `"Symbol(" + (desc ?? "") + ")"`.
+ *
+ * Stack in:  `[i32 id]`            (the symbol's i32 counter id)
+ * Stack out: `[ref $AnyString]`    (the descriptive string)
+ *
+ * `desc` is read from the native description side table (`emitSymbolDescLoad`);
+ * a missing description (`undefined`) contributes the empty string, matching
+ * `Symbol().toString() === "Symbol()"`. Zero host imports — the prefix/suffix
+ * are inline native-string literals concatenated via the native `__str_concat`
+ * helper (same lowering template literals use).
+ */
+export declare function emitSymbolToString(ctx: CodegenContext, fctx: FunctionContext): void;

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

@@ -0,0 +1,8 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+export declare function compileTemporalNewExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.NewExpression): ValType | null | undefined;
+export declare function tryCompileTemporalPropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression): ValType | undefined;
+export declare function tryCompileTemporalStaticCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;
+export declare function tryCompileTemporalMethodCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;

package/dist/codegen/timsort.d.ts

@@ -0,0 +1,2 @@
+import { CodegenContext } from './context/types.js';
+export declare function ensureTimsortHelper(ctx: CodegenContext, vecTypeIdx: number, arrTypeIdx: number, elemKind: "i32" | "f64"): number;

package/dist/codegen/type-coercion.d.ts

@@ -0,0 +1,123 @@
+import { Instr, ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext, OptionalParamInfo } from './context/types.js';
+/**
+ * Emit a guarded ref.cast: use ref.test to check if the cast will succeed.
+ * If it fails, push ref.null instead of trapping with "illegal cast".
+ * The value on the stack should be an anyref (from any.convert_extern).
+ * The result is always ref_null $typeIdx (nullable) to accommodate the null fallback.
+ *
+ * Usage: push externref, call any.convert_extern, then call this function.
+ */
+export declare function emitGuardedRefCast(fctx: FunctionContext, typeIdx: number): void;
+/**
+ * Emit a guarded funcref cast: use ref.test to check if the cast will succeed.
+ * If it fails, push ref.null instead of trapping with "illegal cast".
+ * The value on the stack should be a funcref (from struct.get of a closure field).
+ * The result is always ref_null $funcTypeIdx (nullable).
+ *
+ * Unlike emitGuardedRefCast, this uses funcref locals (not anyref) since
+ * funcref is NOT a subtype of anyref in the WasmGC type hierarchy.
+ */
+export declare function emitGuardedFuncRefCast(fctx: FunctionContext, funcTypeIdx: number): void;
+/**
+ * Callback type for compiling a string literal onto the Wasm stack.
+ * Used by coerceType when it needs to push a @@toPrimitive hint string.
+ * The caller (expressions.ts) passes its local compileStringLiteral function.
+ * @deprecated No longer needed — coerceType now emits hint strings directly via global.get.
+ */
+export type CompileStringLiteralFn = (ctx: CodegenContext, fctx: FunctionContext, value: string) => void;
+/**
+ * Check if a type index corresponds to a vec struct (__vec_*) and return its
+ * array type index and element type if so.
+ */
+export declare function getVecInfo(ctx: CodegenContext, typeIdx: number): {
+    arrTypeIdx: number;
+    elemType: ValType;
+} | null;
+/**
+ * Build instructions to construct a vec struct from a JS array (externref).
+ * Uses __extern_length + __extern_get to read elements and build the WasmGC array.
+ * Returns instruction array producing ref_null $vecType on the stack. (#792)
+ */
+export declare function buildVecFromExternref(ctx: CodegenContext, fctx: FunctionContext, externLocal: number, vecTypeIdx: number, vecInfo: {
+    arrTypeIdx: number;
+    elemType: ValType;
+}): Instr[];
+/**
+ * Coerce a Wasm value on the stack from one type to another.
+ *
+ * @param toPrimitiveHint Optional ToPrimitive hint ("number", "string", or "default").
+ *   When converting ref → f64 or ref → externref, the hint determines which string
+ *   is passed to [Symbol.toPrimitive]. If not specified, defaults to "number" for
+ *   f64 targets and "string" for externref targets.
+ * @param compileStringLiteralFn Deprecated — no longer used, kept for API compat.
+ */
+export declare function coerceType(ctx: CodegenContext, fctx: FunctionContext, from: ValType, to: ValType, toPrimitiveHint?: "number" | "string" | "default", compileStringLiteralFn?: CompileStringLiteralFn): void;
+/**
+ * #1806 Phase 1 (string-hint slice) — OrdinaryToPrimitive over a compile-time
+ * resolvable object struct in the **string** direction, for `--target standalone`
+ * / WASI (native-strings) mode where there is no JS host `__to_primitive`.
+ *
+ * Mirrors the closure/method dispatch of {@link tryToStringFallback} (the
+ * numeric-hint walker) but produces a string instead of an f64, so that
+ * `obj + "s"`, `` `${obj}` `` and `String(obj)` invoke the object's own
+ * `@@toPrimitive("string")` / `toString` instead of falling through to the
+ * `$__any_to_string` helper, which can only emit `"[object Object]"` for a
+ * struct it cannot introspect.
+ *
+ * Per ECMA-262 §7.1.1.1 OrdinaryToPrimitive with hint "string": try `toString`
+ * first, then `valueOf`. We dispatch (in precedence order):
+ *   1. the `toString` closure field (object-literal method) via call_ref
+ *   2. a named `${name}_toString` method in funcMap
+ * Each result is normalised to a `ref $AnyString` (the native string the concat
+ * / template path expects). On success the struct ref on top of the stack is
+ * consumed and a `ref $AnyString` is left; returns true. When neither form is
+ * statically resolvable, the struct ref is left untouched and the function
+ * returns false so the caller can fall back to `$__any_to_string`.
+ *
+ * NOTE: a user `[Symbol.toPrimitive]` ("string"-hint precedence over toString)
+ * is intentionally NOT handled here yet — its hint argument must be marshalled
+ * as a native string in standalone/native-strings mode, which the existing
+ * `pushStringHint` (externref-global) path does not satisfy. Left to a follow-up
+ * so this slice stays regression-free; objects with only `toString`/`valueOf`
+ * (the dominant cluster) are covered.
+ *
+ * Expects the struct ref on top of the Wasm stack; consumes it only on success.
+ */
+export declare function tryStructToString(ctx: CodegenContext, fctx: FunctionContext, from: ValType): boolean;
+/**
+ * Emit a safe externref-to-f64 conversion that handles GC struct references.
+ *
+ * When an externref might hold a WasmGC struct (e.g., from `extern.convert_any`
+ * on an object literal), calling the JS host `Number(v)` throws
+ * "Cannot convert object to primitive value". This function emits inline Wasm
+ * that uses `__typeof_number` to check if the externref is a JS number before
+ * calling `__unbox_number`. For non-number externrefs (including GC structs),
+ * it returns NaN per JS ToNumber semantics for objects without valueOf.
+ *
+ * Expects one externref on the stack; leaves one f64.
+ */
+export declare function emitSafeExternrefToF64(ctx: CodegenContext, fctx: FunctionContext): void;
+export declare function pushDefaultValue(fctx: FunctionContext, type: ValType, ctx?: CodegenContext): void;
+/**
+ * Push the caller-side default for a missing optional parameter (#869).
+ *
+ * For constant defaults (number literal, boolean, null, undefined):
+ *   Emit the constant value directly — no sentinel needed, callee never checks.
+ *
+ * For expression defaults (non-constant initializer):
+ *   Fall back to the sNaN sentinel (0x7FF00000DEADC0DE) for f64 params.
+ *   The callee detects this via i64.reinterpret_f64 + i64.eq and evaluates the expression.
+ *
+ * For params without initializers (just `?`):
+ *   Emit the type's zero value (0, ref.null, etc.).
+ */
+export declare function pushParamSentinel(fctx: FunctionContext, type: ValType, ctx?: CodegenContext, optInfo?: OptionalParamInfo): void;
+export declare function defaultValueInstrs(vt: ValType): Instr[];
+/**
+ * Generate Instr[] to coerce a value from one Wasm type to another.
+ * Used in pre-built instruction arrays (e.g. array method callback loops)
+ * where we can't call coerceType() which pushes to fctx.body.
+ * Returns an empty array if no coercion is needed.
+ */
+export declare function coercionInstrs(ctx: CodegenContext, from: ValType, to: ValType, fctx?: FunctionContext): Instr[];