@loopdive/js2 0.57.0

package/dist/codegen/async-scheduler.d.ts

@@ -0,0 +1,349 @@
+import { Instr } from '../ir/types.js';
+import { ClosureInfo, CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * #1326 — Sentinel state values for `$Promise.state`. Match the JS spec
+ * tri-state: pending → fulfilled (final), or pending → rejected (final).
+ * State transitions other than from pending are illegal per spec and
+ * silently ignored by Phase 1B's resolve/reject emit code.
+ */
+export declare const PROMISE_STATE_PENDING = 0;
+export declare const PROMISE_STATE_FULFILLED = 1;
+export declare const PROMISE_STATE_REJECTED = 2;
+/**
+ * #1326 — Default microtask queue capacity. The Phase 1C-A queue is a pair
+ * of WasmGC arrays (one funcref, one externref) sized at allocation time
+ * and grown via `__microtask_grow` on overflow. 8,192 slots covers typical
+ * async kernels (most chains are <100 entries deep) without forcing a grow
+ * on first use.
+ */
+export declare const MICROTASK_QUEUE_INITIAL_SLOTS = 8192;
+/**
+ * #1326 — Shared per-context state for the async scheduler. Cached on
+ * `ctx.asyncScheduler` (created lazily on first access) so 1B/1C
+ * emitters share registered indices without re-registering.
+ *
+ * Phase 1C-A populates the queue infrastructure fields lazily on the first
+ * `ensureMicrotaskQueue` call. Phase 1C-B will add wrapper-cache fields.
+ */
+export interface AsyncSchedulerState {
+    /** $Promise WasmGC struct typeIdx, or -1 until registered (Phase 1A). */
+    promiseTypeIdx: number;
+    /** $__arr_externref typeIdx (queue captures + args buffer, Phase 1A). */
+    microtaskArgsArrTypeIdx: number;
+    /** $__arr_mt_func typeIdx — funcref array for queued callbacks. -1 until queue is registered. */
+    microtaskFuncArrTypeIdx: number;
+    /** $__mt_func_type typeIdx — `(externref, externref) → externref`, the uniform wrapper signature. -1 until queue is registered. */
+    microtaskFuncTypeIdx: number;
+    /** Wasm global index for the queue head pointer (next entry to drain). -1 until registered. */
+    microtaskHeadGlobalIdx: number;
+    /** Wasm global index for the queue tail pointer (next free slot). -1 until registered. */
+    microtaskTailGlobalIdx: number;
+    /** Wasm global index for the queue's current capacity. -1 until registered. */
+    microtaskCapGlobalIdx: number;
+    /** Wasm global index for the funcref array (or ref.null until allocated). -1 until registered. */
+    microtaskFuncsGlobalIdx: number;
+    /** Wasm global index for the captures array. -1 until registered. */
+    microtaskCapsGlobalIdx: number;
+    /** Wasm global index for the args array. -1 until registered. */
+    microtaskArgsGlobalIdx: number;
+    /** Function index of `__microtask_enqueue(funcref, externref, externref)`. -1 until registered. */
+    enqueueFuncIdx: number;
+    /** Function index of `__drain_microtasks()`. -1 until registered. */
+    drainFuncIdx: number;
+    /** Function index of `__microtask_grow(i32)`. -1 until registered. */
+    growFuncIdx: number;
+    /** `$PromiseCallback` pending-callback linked-list node type. -1 until registered. */
+    promiseCallbackTypeIdx: number;
+    /** `$__then_caps` task-captures type (`callback`, `chained`). -1 until registered. */
+    thenCapsTypeIdx: number;
+    /** Function index of `__promise_fulfill((ref $Promise), externref) -> externref`. */
+    promiseFulfillFuncIdx: number;
+    /** Function index of `__promise_reject((ref $Promise), externref) -> externref`. */
+    promiseRejectFuncIdx: number;
+    /** Function index of the identity fulfillment task wrapper. */
+    identityFulfillWrapperFuncIdx: number;
+    /** Function index of the identity rejection task wrapper. */
+    identityRejectWrapperFuncIdx: number;
+    /** Counter for generated `__then_fulfill_N` / `__then_reject_N` wrappers. */
+    thenWrapperCounter: number;
+    /** Whether `__drain_microtasks` has been added to the module's exports. */
+    drainExported: boolean;
+    /** `$__arr_timer_func` funcref-array typeIdx (timer callback storage). -1 until registered. */
+    timerFuncArrTypeIdx: number;
+    /** `$__arr_i64` i64-array typeIdx (timer deadlines + interval periods). -1 until registered. */
+    timerI64ArrTypeIdx: number;
+    /** `$__arr_i32` i32-array typeIdx (timer cancelled flags). -1 until registered. */
+    timerI32ArrTypeIdx: number;
+    /** Wasm global: count of live timer slots (high-water; cancelled lazily). -1 until registered. */
+    timerCountGlobalIdx: number;
+    /** Wasm global: current capacity of the timer arrays. -1 until registered. */
+    timerCapGlobalIdx: number;
+    /** Wasm global: deadlines i64 array (ref.null until first add). -1 until registered. */
+    timerDeadlinesGlobalIdx: number;
+    /** Wasm global: callbacks funcref array. -1 until registered. */
+    timerCallbacksGlobalIdx: number;
+    /** Wasm global: captures externref array. -1 until registered. */
+    timerCapturesGlobalIdx: number;
+    /** Wasm global: interval periods i64 array (0 = one-shot). -1 until registered. */
+    timerIntervalsGlobalIdx: number;
+    /** Wasm global: cancelled i32 flags array. -1 until registered. */
+    timerCancelledGlobalIdx: number;
+    /** Func idx of `__timer_add(deadlineNs i64, cb funcref, cap externref, intervalNs i64) -> i32`. -1 until registered. */
+    timerAddFuncIdx: number;
+    /** Func idx of `__timer_cancel(id i32)`. -1 until registered. */
+    timerCancelFuncIdx: number;
+    /** Func idx of `__timer_peek_deadline() -> i64` (i64 max when none pending). -1 until registered. */
+    timerPeekDeadlineFuncIdx: number;
+    /** Func idx of `__timer_fire_due(nowNs i64)` — fires all due timers, re-arms intervals. -1 until registered. */
+    timerFireDueFuncIdx: number;
+    /** Func idx of `__run_event_loop()` — the reactor driver. -1 until registered. */
+    runLoopFuncIdx: number;
+    /** Func idx of the monotonic-now reader `__rl_now_ns() -> i64` (CLOCK_MONOTONIC). -1 until registered. */
+    runLoopNowFuncIdx: number;
+    /** Whether the timer heap was ever registered (drives run-loop emission + _start wiring). */
+    timerHeapRegistered: boolean;
+    /**
+     * Whether the run loop should wait on fd0-readable OR the nearest timer
+     * (multi-subscription `poll_oneoff`) instead of the Phase-1 single-clock
+     * sleep, and drain fd0 into an internal stdin buffer each tick. Set BEFORE
+     * `ensureTimerHeap` runs so the run-loop body is built in the fd-reactor
+     * shape. When false, the run loop is byte-identical to Phase 1.
+     */
+    stdinReactor: boolean;
+    /** Wasm global: 1 once fd0's non-blocking flag has been set (set-once guard). -1 until registered. */
+    stdinNonblockSetGlobalIdx: number;
+    /** Wasm global: 1 while fd0 is still subscribed (not at EOF); 0 after EOF. -1 until registered. */
+    stdinFdActiveGlobalIdx: number;
+    /** Wasm global: byte count currently buffered in the internal stdin region (write cursor). -1 until registered. */
+    stdinBufLenGlobalIdx: number;
+    /** Wasm global: read cursor into the internal stdin region (Phase-3 consumer advances it). -1 until registered. */
+    stdinBufPosGlobalIdx: number;
+    /** Func idx of `__rl_stdin_drain() -> i32` — fd_read available bytes into the internal buffer; returns bytes read (0 = EOF). -1 until registered. */
+    stdinDrainFuncIdx: number;
+    /** Func idx of `__rl_poll_fd0_or_clock(deadlineNs i64, nowNs i64) -> i32` — 1 if fd0 readable, 0 if timeout/no-fd. -1 until registered. */
+    pollFd0OrClockFuncIdx: number;
+    /**
+     * Wasm global (nullable funcref, `$__mt_func_type` signature): the
+     * `process.stdin` Readable's "pump" callback. The run loop calls it once per
+     * tick AFTER `__rl_stdin_drain` fills the internal buffer (so the pump runs as
+     * loop work, not synchronously inside `poll_oneoff`). Null until the library
+     * registers a reader via `__wasiStdinSetReader(cb)`. -1 until registered.
+     */
+    stdinReaderHookGlobalIdx: number;
+    /**
+     * Wasm global (externref): the closure-captures struct for the reader hook
+     * (the bound Readable instance). The run loop passes it as the hook's first
+     * arg so the pump can reach its `this`. -1 until registered.
+     */
+    stdinReaderCapGlobalIdx: number;
+}
+/**
+ * #1326 — Get or register the `$Promise` WasmGC struct type. The struct
+ * has three fields:
+ *   - state: i32 (0=pending, 1=fulfilled, 2=rejected)
+ *   - value: externref (fulfilled value or rejection reason)
+ *   - callbacks: externref (nullable `$PromiseCallback` linked list for
+ *     pending `.then` continuations)
+ *
+ * Returns the registered struct's typeIdx, cached for re-use.
+ */
+export declare function getOrRegisterPromiseType(ctx: CodegenContext): number;
+/**
+ * #1326 — Get or register the microtask-queue arg-vec type. Phase 1A
+ * registered the WasmGC array type; Phase 1C-A re-uses it for both the
+ * captures buffer and the args buffer (both are externref arrays).
+ */
+export declare function getOrRegisterMicrotaskQueueType(ctx: CodegenContext): number;
+/**
+ * #1326 Phase 1C-A — Idempotently register the microtask queue (types,
+ * globals, helper functions). Safe to call from anywhere in the codegen
+ * pipeline, but callers must keep in mind that the new function indices
+ * land at the END of the current `ctx.mod.functions` array — registering
+ * mid-function-body emit shifts subsequent funcIdx values, so callers in
+ * Phase 1C-B should invoke this BEFORE any function bodies that reference
+ * the registered indices.
+ */
+export declare function ensureMicrotaskQueue(ctx: CodegenContext): void;
+/**
+ * #1326 Phase 1C-A — Compile a call to `__microtask_enqueue(fn, caps, arg)`
+ * into the caller's body. Caller-supplied `funcRefInstrs` push a funcref;
+ * `capsInstrs` push an externref carrying any closure-state captures the
+ * drain-time callback will need; `argInstrs` push the externref value to
+ * pass to the callback.
+ *
+ * Used by the standalone `.then` integration to schedule drain-time
+ * continuations.
+ */
+export declare function emitMicrotaskEnqueue(ctx: CodegenContext, fctx: FunctionContext, funcRefInstrs: Instr[], capsInstrs: Instr[], argInstrs: Instr[]): void;
+/**
+ * #1326 Phase 1C-A — Compile a call to `__drain_microtasks()` into the
+ * caller's body. Drains until the queue is empty. Safe to call when the
+ * queue was never initialised — the body short-circuits on a null funcs
+ * global.
+ */
+export declare function emitDrainMicrotasks(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * #1326 Phase 1C-A — If the microtask queue was registered for this
+ * compilation unit, export `__drain_microtasks` so standalone callers can
+ * invoke it after their top-level entrypoint. Idempotent.
+ */
+export declare function exportDrainMicrotasksIfRegistered(ctx: CodegenContext): void;
+/**
+ * #1326 Phase 1C-A — Auto-drain hook for WASI `_start`. Returns the funcIdx
+ * of `__drain_microtasks` when the queue is registered, or `null` when not
+ * (queue was never used by this module; no drain call needed). Callers
+ * append `{ op: "call", funcIdx: <returned> }` to the `_start` body right
+ * after the main/`__module_init` call.
+ */
+export declare function getDrainFuncIdxForWasiStart(ctx: CodegenContext): number | null;
+/**
+ * #2632 — Idempotently register the timer table (types, globals, helpers) and
+ * the run-loop driver. MUST be called in the deferred-helper phase (after
+ * `__wasi_sleep_ms` + `clock_time_get` are registered, before user bodies
+ * compile) so the `__timer_add` / `__timer_cancel` func indices referenced at
+ * timer call sites are final. Depends on `ensureMicrotaskQueue` (the loop
+ * drains microtasks each tick).
+ */
+export declare function ensureTimerHeap(ctx: CodegenContext): void;
+/**
+ * #2632 Phase 2 — emit a `__wasiStdinReadByte()` lowering at a call site.
+ * Pushes an i32 onto the caller stack: the next buffered stdin byte (0..255),
+ * or -1 when the internal buffer is empty. The reactor (running in `_start`)
+ * drains fd0 into the buffer; a timer/microtask callback reads it one byte at a
+ * time via this primitive. This is the internal-buffer access path Phase 3's
+ * `process.stdin` Readable will build `.read()` on top of.
+ */
+export declare function emitStdinReadByte(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * #2632 Phase 3 — emit `__wasiStdinAvailable()` at a call site. Pushes an i32:
+ * the number of bytes currently buffered and unread (`len - pos`). The library
+ * `Readable` uses this to decide whether `.read(size)` can satisfy the request.
+ */
+export declare function emitStdinAvailable(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * #2632 Phase 3 — emit `__wasiStdinEof()` at a call site. Pushes an i32: 1 when
+ * fd0's readable side has hit EOF (the reactor dropped the subscription:
+ * `__stdin_fd_active == 0`) AND every buffered byte has been consumed
+ * (`pos >= len`); else 0. The library `Readable` uses this to emit `'end'` and
+ * to make `.read()` return all-remaining at EOF rather than null-on-short.
+ */
+export declare function emitStdinEof(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * #2735 — emit `__wasiStdinStop()` at a call site: a NON-EOF reactor exit
+ * trigger. Drops the fd0 subscription by clearing `__stdin_fd_active` (mirrors
+ * the EOF clear in `buildStdinDrainBody`), so the run loop's next `pending`
+ * test — `(next != I64_MAX) | fd0_active` — falls through and `_start` returns
+ * cleanly EVEN THOUGH stdin never reached EOF. Without this the fd-readiness
+ * reactor's ONLY termination path is stdin EOF, which hangs the real
+ * Native-Messaging case (the peer keeps the pipe open and signals shutdown
+ * in-band). Backs `process.stdin.destroy()` and the `process.exit()` pre-exit
+ * drop. Stack-neutral; a no-op (and safe to call unconditionally) when the
+ * reactor isn't active for this module (the global was never registered).
+ */
+export declare function emitStdinStop(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * #2735 — true when the fd0 stdin reactor is active for this module (the
+ * Phase-2 globals were registered). Lets the WASI `process.exit` lowering
+ * decide whether to drop the fd0 subscription before `proc_exit` WITHOUT
+ * forcing the reactor onto a program that only calls `process.exit` and never
+ * touches stdin.
+ */
+export declare function isStdinReactorActive(ctx: CodegenContext): boolean;
+/**
+ * #2632 Phase 3 — emit `__wasiStdinSetReader(cb)` at a call site. Stores the
+ * pump funcref + its closure captures into the reactor-tick-hook globals, so the
+ * run loop invokes `cb(captures, null)` each tick after draining fd0. The
+ * caller pushes the wrapped `$__mt_func_type` funcref (`cbFuncRefInstrs`) and
+ * the closure-captures externref (`capInstrs`). Returns nothing.
+ */
+export declare function emitStdinSetReader(ctx: CodegenContext, fctx: FunctionContext, cbFuncRefInstrs: Instr[], capInstrs: Instr[]): void;
+/**
+ * #2632 Phase 2 — mark the stdin reactor active for this module. MUST be called
+ * BEFORE `ensureTimerHeap` so the run-loop body is built in the fd-reactor
+ * shape and the Phase-2 globals/helpers register. Idempotent.
+ */
+export declare function enableStdinReactor(ctx: CodegenContext): void;
+/**
+ * #2632 — Emit a `setTimeout`/`setInterval` registration at a call site.
+ * Pushes the timer id (i32) onto the caller stack. `cbFuncRefInstrs` push the
+ * uniform `$__mt_func_type` funcref; `capInstrs` push the closure-captures
+ * externref; `deadlineInstrs` push the absolute deadline (i64 ns);
+ * `intervalInstrs` push the re-arm period (i64 ns, 0 = one-shot).
+ */
+export declare function emitTimerAdd(ctx: CodegenContext, fctx: FunctionContext, deadlineInstrs: Instr[], cbFuncRefInstrs: Instr[], capInstrs: Instr[], intervalInstrs: Instr[]): void;
+/** #2632 — Emit a `clearTimeout`/`clearInterval` at a call site. Consumes the
+ *  id already pushed by `idInstrs`. */
+export declare function emitTimerCancel(ctx: CodegenContext, fctx: FunctionContext, idInstrs: Instr[]): void;
+/** #2632 — The monotonic-now reader func idx (`__rl_now_ns() -> i64`), or -1.
+ *  Timer call sites read it to compute `deadlineNs = now + ms*1e6`. */
+export declare function getRunLoopNowFuncIdx(ctx: CodegenContext): number;
+/**
+ * #2632 — Synthesise a uniform `$__mt_func_type` timer-callback wrapper for a
+ * user closure. The timer table stores the closure struct itself as the
+ * `captures` externref; this wrapper (param 0 = caps externref = the closure
+ * struct, param 1 = value externref = unused/null) decodes the struct and
+ * invokes the closure via `call_ref` with default args for every parameter
+ * (a timer callback receives no arguments in Node — extra `setTimeout` args
+ * are out of Phase-1 scope). Returns the wrapper func idx.
+ *
+ * Mirrors the `.then` wrapper shape (closure call_ref = `[self, ...args,
+ * typed_funcref]`) but without promise settlement.
+ */
+export declare function emitTimerCallbackWrapper(ctx: CodegenContext, info: ClosureInfo): number;
+/**
+ * #2632 — Run-loop hook for WASI `_start`. Returns the funcIdx of
+ * `__run_event_loop` when the timer heap was registered (the loop supersedes
+ * the one-shot drain — it drains microtasks itself), else `null` so the caller
+ * falls back to the bare drain.
+ */
+export declare function getRunLoopFuncIdxForWasiStart(ctx: CodegenContext): number | null;
+/**
+ * #1326 Phase 1B — emit standalone-mode `Promise.resolve(value)` as a
+ * Wasm-native `$Promise` GC struct construction. The caller has
+ * already pushed `value` (as externref) onto the Wasm stack via
+ * `valueInstrs`; this helper appends:
+ *   - i32.const 1                  (state = FULFILLED)
+ *   - <valueInstrs>                (value = caller's pushed externref)
+ *   - ref.null extern              (callbacks placeholder — Phase 1C-B
+ *                                   will upgrade to a typed pending list)
+ *   - struct.new $Promise          (consumes 3 stack values)
+ *   - extern.convert_any           (lift (ref $Promise) → externref so
+ *                                   downstream consumers keep working)
+ *
+ * The return is on the Wasm stack as `externref`. Internal helpers
+ * (`Promise.then`, `Promise.all`, etc.) `ref.cast` it back to
+ * `(ref $Promise)` to read the state/value/callbacks fields.
+ */
+export declare function emitStandalonePromiseResolve(ctx: CodegenContext, fctx: FunctionContext, valueInstrs: Instr[]): void;
+/**
+ * #1326 Phase 1B — emit standalone-mode `Promise.reject(reason)` as a
+ * Wasm-native `$Promise` GC struct construction. Symmetric to
+ * `emitStandalonePromiseResolve` but with `state = REJECTED`.
+ */
+export declare function emitStandalonePromiseReject(ctx: CodegenContext, fctx: FunctionContext, reasonInstrs: Instr[]): void;
+export interface StandalonePromiseThenCallback {
+    instrs: Instr[];
+    closureInfo: ClosureInfo;
+}
+/**
+ * #1326 Phase 1C-B — emit standalone-mode `promise.then(onFulfilled,
+ * onRejected?)`.
+ *
+ * The emitted code constructs a new pending chained `$Promise`, captures the
+ * user closure (if callable) plus that chained promise in `$__then_caps`, then:
+ *   - already-fulfilled receiver: enqueue fulfillment wrapper immediately
+ *   - already-rejected receiver: enqueue rejection wrapper immediately
+ *   - pending receiver: prepend a `$PromiseCallback` node to receiver.callbacks
+ *
+ * Drain-time wrappers invoke the closure through WasmGC `call_ref`, settle the
+ * chained promise, and enqueue any callbacks that were attached to the chained
+ * promise while it was pending. Missing/non-callable handlers use identity
+ * fulfill / pass-through reject wrappers.
+ */
+export declare function emitStandalonePromiseThen(ctx: CodegenContext, fctx: FunctionContext, promiseInstrs: Instr[], onFulfilled: StandalonePromiseThenCallback | null, onRejected?: StandalonePromiseThenCallback | null): void;
+/**
+ * #1326 — Check whether standalone-mode Promise codegen is active.
+ * Auto-enables in WASI target mode (the JS host imports for Promise are
+ * unavailable); opt-in elsewhere via a flag.
+ */
+export declare function isStandalonePromiseActive(ctx: CodegenContext): boolean;

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

@@ -0,0 +1,78 @@
+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 compileBinaryExpression(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): InnerResult;
+/**
+ * (#2058) Emit `+` for two operands where at least one is a dynamic externref
+ * (an `any`/`unknown`/boxed value). The operands are already on the Wasm stack
+ * (left below right). Per §13.15.3 ApplyStringOrNumericBinaryOperator a runtime
+ * string on either side must CONCATENATE, not coerce to f64 — so we cannot take
+ * the externref-numeric f64 fast path.
+ *
+ * JS-host mode delegates to `__host_add` (JS `+`), which gives ToPrimitive, the
+ * string-if-either-is-string rule, and object valueOf/toString ordering for
+ * free. Standalone/WASI has no JS host, so we build the operation in-module from
+ * the union-native typeof/unbox probes + native string concat. If neither host
+ * nor native-string support is available we fall back to the legacy f64 add
+ * (status quo — no regression).
+ *
+ * Returns the value type left on the stack (`externref` for the host/native
+ * paths — a boxed number-or-string the caller stores into the `any` slot — or
+ * `f64` for the legacy numeric fallback).
+ */
+export declare function emitAnyAdd(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression): ValType;
+/**
+ * (#2059) Emit a relational (`<`,`<=`,`>`,`>=`) for two operands where at least
+ * one is a dynamic externref (an `any`/`unknown` value). Operands are compiled
+ * here (not yet on the stack). Per §7.2.13 IsLessThan two string operands compare
+ * lexicographically and a string-vs-number compares numerically — the f64 paths
+ * would ToNumber both sides (`Number("a")` → NaN) and yield `false`.
+ *
+ * JS-host delegates to `__host_compare` (JS `<`/`>`), which returns a 4-way
+ * result -1/0/1/2 (2 = NaN/undefined-incomparable). Standalone builds §7.2.13 in
+ * module: both-string → native `__str_compare`, else ToNumber + f64. Returns i32
+ * (the boolean relational result).
+ */
+export declare function emitAnyRelational(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression, op: ts.SyntaxKind): ValType;
+export declare function compileNumericBinaryOp(ctx: CodegenContext, fctx: FunctionContext, op: ts.SyntaxKind, expr: ts.BinaryExpression): ValType;
+/**
+ * Emit JS ToInt32: reduce f64 modulo 2^32 then truncate to i32.
+ * Handles NaN→0, Infinity→0, and large values that wrap.
+ * Stack: [f64] → [i32]
+ */
+export declare function emitToInt32(fctx: FunctionContext): void;
+/**
+ * (#2593) ToUint8Clamp (§7.1.x, the `Uint8ClampedArray` element conversion). Input
+ * f64 on the stack → clamped i32 in [0, 255]. NOT modulo: NaN→0, ≤0→0, ≥255→255,
+ * else round-HALF-TO-EVEN (1.5→2, 2.5→2, 0.5→0). Differs from every other integer
+ * view (which truncate modulo via the packed `array.set`), so `Uint8ClampedArray`
+ * writes route through this helper before the store.
+ */
+export declare function emitToUint8Clamp(fctx: FunctionContext): void;
+/**
+ * Emit JS remainder (`a % b`) on f64 operands as a call to the Wasm-native
+ * `__fmod` helper, which computes the *exact* IEEE-754 remainder
+ * ([Number::remainder §6.1.6.1.6](https://tc39.es/ecma262/#sec-numeric-types-number-remainder)).
+ * Stack: [a_f64, b_f64] -> [result_f64].
+ *
+ * The previous inline formula `a - trunc(a/b)*b` (+ copysign) was not fmod: it
+ * drifted by ULPs, collapsed to 0 for large `a/b`, and overflowed to ±Infinity
+ * when `a/b` exceeded f64 range. `__fmod` handles all of those plus the #216
+ * edge cases (`x % Inf`, `-0 % x`, `Inf % x`, `x % 0`, `NaN % x`) internally.
+ * See `fmod.ts` for the algorithm and correctness notes (#2056).
+ */
+export declare function emitModulo(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Emit `a % b` on i32 operands without the Wasm traps of bare `i32.rem_s`.
+ *
+ * `i32.rem_s` traps when `b == 0` and on the signed-overflow case
+ * `INT_MIN % -1`. JS yields NaN and 0 respectively for the corresponding
+ * Number operation; in i32 fast mode the result must be an i32 (no NaN
+ * representation), so we emit 0 for both trapping cases. 0 is the
+ * mathematically-correct value for `INT_MIN % -1`, and the i32 truncation of
+ * JS's NaN result is also 0, so this is the least-surprising i32 behaviour.
+ *
+ * Stack: [a_i32, b_i32] -> [result_i32]. See #1825.
+ */
+export declare function emitSafeI32Rem(fctx: FunctionContext): void;

package/dist/codegen/binding-info.d.ts

@@ -0,0 +1,31 @@
+import { ts } from '../ts-api.js';
+/**
+ * Computes a function node's own locals into a caller-supplied set. Injected by
+ * `closures.ts` (which owns the actual collection logic) so this module does
+ * not duplicate the scope-walking rules. Pure function of `funcLike`.
+ */
+type OwnLocalsCollector = (funcLike: ts.Node, out: Set<string>) => void;
+/**
+ * Register the own-locals collector. Called once during module init from
+ * `closures.ts`. Separating registration from use avoids an import cycle
+ * (`closures.ts` already imports a great deal; this keeps the dependency
+ * one-directional).
+ */
+export declare function registerOwnLocalsCollector(fn: OwnLocalsCollector): void;
+/**
+ * The memoized own-locals set for a function-like node.
+ *
+ * Returns the same `ReadonlySet` instance for repeated calls on the same node
+ * within a compile. Returns an empty set for non-function nodes (mirroring the
+ * underlying collector, which no-ops when the node is not a function-scope
+ * boundary). The returned set MUST NOT be mutated by callers — use
+ * {@link addFunctionOwnLocals} when you need to accumulate into your own set.
+ */
+export declare function getFunctionOwnLocals(funcLike: ts.Node): ReadonlySet<string>;
+/**
+ * Add a function-like node's own locals to `out`, going through the memoized
+ * cache. Behavior-identical to calling the raw collector with `out`, but the
+ * per-node walk runs at most once per compile.
+ */
+export declare function addFunctionOwnLocals(funcLike: ts.Node, out: Set<string>): void;
+export {};

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

@@ -0,0 +1,98 @@
+import { Instr, ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * A string representation strategy: the minimal per-representation seam the
+ * shared builtin lowerings need. Each builtin lane picks one of the concrete
+ * reprs ({@link hostStringRepr} / {@link nativeStringRepr}); everything else
+ * — the fold structure, the separator placement, the empty-string fallback —
+ * is shared.
+ */
+export interface StringRepr {
+    /** Wasm type of a value produced by this representation's string operations. */
+    readonly resultType: ValType;
+    /**
+     * Materialize a string literal (separator, empty string, …) onto the stack.
+     * Host repr emits a `string_constants` global; native repr emits a
+     * `$NativeString` cast up to `$AnyString`.
+     */
+    literal(value: string): Instr[];
+    /**
+     * Concatenate two operands. `a` and `b` are instruction sequences that each
+     * leave exactly one {@link resultType} value on the stack; the returned
+     * sequence leaves their concatenation. Host repr calls the `wasm:js-string`
+     * `concat` builtin; native repr calls the pure-Wasm `__str_concat` helper.
+     */
+    concat(a: Instr[], b: Instr[]): Instr[];
+}
+/**
+ * Host (JS-string) representation: results are `externref`, concatenation is
+ * the `wasm:js-string` `concat` builtin, literals are `string_constants`
+ * globals. Returns `undefined` if the `concat` builtin is not registered (the
+ * caller must already have ensured string support).
+ */
+export declare function hostStringRepr(ctx: CodegenContext): StringRepr | undefined;
+/**
+ * Native-string (standalone / WASI) representation: results are
+ * `(ref $AnyString)`, concatenation is the pure-Wasm `__str_concat` helper,
+ * literals are inline `$NativeString` values cast up to `$AnyString`. Zero
+ * host imports. Returns `undefined` if the native string helpers cannot be
+ * provisioned.
+ */
+export declare function nativeStringRepr(ctx: CodegenContext): StringRepr | undefined;
+/**
+ * Shared variadic string-concatenation primitive (#2088).
+ *
+ * Folds `parts[0] ++ parts[1] ++ … ++ parts[n-1]` left-to-right using the
+ * representation's `concat`. Each `parts[i]` is an instruction sequence that
+ * leaves exactly one `repr.resultType` value on the stack. Used by the
+ * `String.fromCharCode` / `String.fromCodePoint` lanes (each argument's code
+ * unit becomes a one-char string `part`); the spec's left-to-right argument
+ * evaluation order is preserved because the parts are already compiled in
+ * order by the caller.
+ *
+ * With a single part this is the identity (no `concat` call), matching the
+ * spec for a 1-argument call. Callers must pass at least one part.
+ */
+export declare function emitVariadicStringConcat(repr: StringRepr, parts: Instr[][]): Instr[];
+/** Locals threaded through {@link emitStringJoinFold}. */
+export interface JoinFoldLocals {
+    /** i32 — current iteration index. */
+    iTmp: number;
+    /** i32 — element count. */
+    lenTmp: number;
+    /** `repr.resultType` — accumulator (also the eventual return). */
+    resultTmp: number;
+    /** `repr.resultType` — separator. */
+    sepTmp: number;
+}
+/**
+ * Shared array-join fold (#2088).
+ *
+ * Emits, into `fctx.body`, the canonical join loop shared by every `join`
+ * representation:
+ *
+ *   for (i = 0; i < len; i++)
+ *     result = (i == 0) ? toStr(elem_i)
+ *                       : concat(concat(result, sep), toStr(elem_i))
+ *
+ * followed by the empty-array fallback (`result` left null / unset ⇒ `""`,
+ * never `null`, which downstream string consumers would render as `"null"` —
+ * the #1968 bug). `elemToStr` is the only representation- *and* element-type-
+ * specific input: an instruction sequence that loads element `iTmp` from the
+ * backing array and leaves its string form (a `repr.resultType` value) on the
+ * stack.
+ *
+ * The caller is responsible for:
+ *   - allocating + initializing the locals in `locals` (sep, result="", i=0),
+ *   - setting `lenTmp` from the receiver length,
+ *   - emitting any post-fold conversion (e.g. native `extern.convert_any`).
+ *
+ * Because both the host and native `join` lanes emit their loop body here, a
+ * bug in this function regresses both lanes simultaneously.
+ */
+export declare function emitStringJoinFold(ctx: CodegenContext, fctx: FunctionContext, repr: StringRepr, locals: JoinFoldLocals, elemToStr: Instr[]): void;
+/**
+ * Allocate the standard join-fold locals for `repr`. The accumulator and
+ * separator carry `repr.resultType`; the index/length are i32.
+ */
+export declare function allocJoinFoldLocals(fctx: FunctionContext, repr: StringRepr, tag: string): JoinFoldLocals;

package/dist/codegen/builtin-static-globals.d.ts

@@ -0,0 +1,8 @@
+import { ValType } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export declare function isSupportedBuiltinNamespace(name: string): boolean;
+export declare function isSupportedBuiltinStaticProperty(builtinName: string, propName: string): boolean;
+export declare function resolveBuiltinNamespaceValueName(ctx: CodegenContext, expr: ts.Expression): string | undefined;
+export declare function emitBuiltinStaticMethodValue(ctx: CodegenContext, fctx: FunctionContext, builtinName: string, propName: string): ValType | null;
+export declare function emitBuiltinNamespaceObject(ctx: CodegenContext, fctx: FunctionContext, builtinName: string): ValType | null;