@loopdive/js2 0.57.0

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

@@ -0,0 +1,98 @@
+import { Instr, ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Resolve (and lazily seed) the builtin brand id for `name`. Asserts the brand
+ * band stays disjoint from every registered class tag — a collision would
+ * silently mis-dispatch (#2175 Risk 2). Returns `undefined` for an unbranded
+ * name (caller falls through to the refusal).
+ */
+export declare function getBuiltinBrand(ctx: CodegenContext, name: string): number | undefined;
+export declare const NATIVE_PROTO_FIELD_BRAND = 0;
+export declare const NATIVE_PROTO_FIELD_IS_CLASS = 1;
+export declare const NATIVE_PROTO_FIELD_CTOR = 2;
+export declare const NATIVE_PROTO_FIELD_PARENT = 3;
+export declare const NATIVE_PROTO_FIELD_MEMBER_CSV = 4;
+export declare const NATIVE_PROTO_FIELD_NAME = 5;
+/**
+ * Register the single `$NativeProto` struct type once and stash its idx on
+ * `ctx.nativeProtoTypeIdx`. Mirrors the lazy one-time registration of
+ * `ensureStandaloneRegExpStruct`. There is exactly one `$NativeProto` heap type,
+ * so iso-recursive canonicalization is a non-issue for the metadata itself —
+ * identity rides the `$brand` *value*, not the type.
+ */
+export declare function registerNativeProtoType(ctx: CodegenContext): number;
+/**
+ * The per-builtin contract consumed by the shared core. A builtin registers one
+ * descriptor; the core uses it to populate the `$NativeProto` and to drive
+ * method/getter closure bodies. Registered lazily (the builtin calls
+ * `registerNativeProtoBuiltin` from its own module on first reflective demand)
+ * so the core has no import dependency on any specific builtin.
+ */
+export interface NativeProtoBuiltinGlue {
+    /** Stable brand id (from BUILTIN_BRAND_TABLE). */
+    brand: number;
+    /** The proto's [[class]]/brand name (for `$name`, e.g. "RegExp"). */
+    name: string;
+    /** Own member-name CSV for the proto object (string-named members; `@@<id>`
+     *  sentinels for well-known-symbol members — see spec §"Symbol cell"). */
+    memberCsv: string;
+    /** Which members are accessor getters (`kind:"getter"`) vs data methods
+     *  (`kind:"method"`). `@@<id>` symbol members are always `"method"`. */
+    memberKind: (member: string) => "getter" | "method";
+    /** Static arity advertised by a member's closure value (`fn.length`). */
+    memberLength: (member: string) => number;
+    /**
+     * Emit a method/getter closure BODY into `fctx`, given the externref `this`
+     * already bound to closure-param index 1 and any further args at indices
+     * 2.. . The implementation runs the brand-recovery prologue (externref `this`
+     * → backing struct, or a catchable TypeError on a wrong `this`) and then the
+     * member body. Returns the closure's result ValType, or `null` on a refusal.
+     */
+    emitMemberBody: (ctx: CodegenContext, fctx: FunctionContext, member: string, kind: "getter" | "method") => ValType | null;
+}
+/** A builtin registers its glue once (idempotent). */
+export declare function registerNativeProtoBuiltin(ctx: CodegenContext, glue: NativeProtoBuiltinGlue): void;
+/** Look up a registered builtin's glue by brand. */
+export declare function getNativeProtoBuiltinGlue(ctx: CodegenContext, brand: number): NativeProtoBuiltinGlue | undefined;
+/**
+ * Emit a lazy-initialized `$NativeProto` object read for a *builtin* brand. On
+ * first access, builds the struct (brand, isClass=0, ctor=null, parent=null,
+ * memberCsv=<native string>, name=<native string>), boxes it via
+ * `extern.convert_any`, and stashes it in a module global; subsequent reads
+ * return the same externref (reference identity for `RegExp.prototype ===
+ * RegExp.prototype`). Pure Wasm — NO host import (the contrast with
+ * `emitLazyProtoGet`, which calls `__register_prototype`). Leaves an externref
+ * on the stack. Returns `false` if the brand has no registered glue.
+ */
+export declare function emitLazyNativeProtoGet(ctx: CodegenContext, fctx: FunctionContext, brand: number): boolean;
+/**
+ * (#2175) Brand-keyed native-method-closure factory. `kind`:
+ *   - `"method"`  — `(ref $wrap, externref this, ...externref args) -> result`;
+ *                   first emits the brand-recovery prologue then the member body.
+ *   - `"getter"`  — `(ref $wrap, externref this) -> result` accessor getter,
+ *                   returned as a descriptor's `.get`.
+ *
+ * The closure is a `__fn_wrap`-style struct produced by
+ * `getOrCreateFuncRefWrapperTypes`, so it is `call_ref`-dispatchable through the
+ * existing closure call path. Keyed in `ctx.funcMap` as
+ * `__proto_method_<brand>_<member>` / `__proto_method_<brand>_get_<member>`.
+ * Tags the funcIdx with `{name,length}` in `ctx.nativeClosureMeta` so the
+ * existing `.length`/`.name`-on-function reads resolve the closure's arity/name.
+ *
+ * Returns the `{ type, funcIdx }` for `ref.func` + `struct.new`, or `null` if
+ * the brand has no glue / the member body refuses.
+ */
+export declare function ensureStandaloneNativeMethodClosure(ctx: CodegenContext, brand: number, member: string, kind: "method" | "getter"): {
+    type: {
+        kind: "ref";
+        typeIdx: number;
+    };
+    funcIdx: number;
+} | null;
+/**
+ * Emit the catchable-TypeError throw used by a brand-recovery prologue on a
+ * wrong `this`. Shared so per-builtin glue can reuse the exact shape (a real
+ * TypeError instance via the in-module `__new_TypeError`, then `throw $exc`),
+ * never a `ref.cast` trap (#2100 M2 / §22.2.6.4.1 step 2).
+ */
+export declare function emitBrandCheckTypeError(ctx: CodegenContext, body: Instr[], message: string): void;

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

@@ -0,0 +1,158 @@
+import { Instr } from '../ir/types.js';
+import { CodegenContext } from './context/types.js';
+/** i32 array type used for program, class table, and capture slots. */
+export declare function regexI32ArrayType(ctx: CodegenContext): number;
+/**
+ * Emit the backtracking VM `__regex_run` and its dependencies. Returns the
+ * `__regex_run` function index.
+ *
+ * Signature:
+ *   __regex_run(prog: ref array<i32>, classTable: ref array<i32>,
+ *               nSlots: i32, strData: ref array<i16>, strOff: i32, strLen: i32,
+ *               startIdx: i32, caps: ref array<i32>,
+ *               entryPc: i32, dir: i32) -> i32
+ *
+ * `caps` is caller-allocated, length `nSlots`, pre-filled with -1. On a match
+ * (1 returned) the slots hold `[g0s,g0e,g1s,g1e,…]`; -1 = unset. This is one
+ * anchored attempt at `startIdx`; the start-position scan lives in the
+ * higher-level helpers (`__regex_search`).
+ *
+ * #1911: `entryPc` selects the (sub-)program, `dir` the scan direction (+1
+ * forward, -1 for lookbehind sub-programs — consuming ops read the unit at
+ * sp-1 and decrement). LOOKAROUND recursively calls this function on its
+ * sub-program at the current position; the recursion is what makes
+ * lookarounds atomic (no backtrack entries leak into the outer attempt).
+ */
+export declare function ensureRegexRun(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_search(prog, classTable, nSlots, strData, strOff, strLen,
+ * startIdx, sticky, caps) -> i32`.
+ *
+ * Drives the start-position scan: tries `__regex_run` at each position from
+ * `startIdx` to `strLen`; returns 1 with `caps` filled on the first match, 0
+ * otherwise. When `sticky` is non-zero (the `y` flag) only `startIdx` is tried.
+ * Mirrors `search` in regex/vm.ts. `caps` must be re-initialised to -1 before
+ * each attempt — done inside the loop via `array.fill`.
+ */
+export declare function ensureRegexSearch(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_replace(prog, classTable, nGroups, strData, strOff, strLen,
+ * subject, replacement, global) -> ref $NativeString` (#1539 Phase 2c).
+ *
+ * Implements `String.prototype.replace` / `replaceAll` for a backend-created
+ * RegExp with a **literal** (non-`$`-pattern, non-function) replacement string
+ * (ECMA-262 §22.1.3.19 / §22.2.6.11 with the `$`-substitution and function
+ * replacer paths refused at the call site). Walks the subject with
+ * `__regex_search`, accumulating `result = … + slice[lastEnd, matchStart) +
+ * replacement` for each match and appending `slice[lastEnd, len)` at the end.
+ * `global != 0` replaces every match (advancing past empty matches by 1 per
+ * §22.2.6.11 AdvanceStringIndex); otherwise only the first.
+ *
+ * Returns a `$NativeString` — no array boundary, so no `__make_iterable` /
+ * host import is pulled in standalone.
+ */
+export declare function ensureRegexReplace(ctx: CodegenContext): number;
+/** Struct name for the match-result vec subtype (#1914). */
+export declare const REGEXP_MATCH_VEC_STRUCT = "__regexp_match_vec";
+/** Field indices of `$__regexp_match_vec` (base vec prefix + result fields). */
+export declare const MATCH_VEC_FIELD_INDEX = 2;
+export declare const MATCH_VEC_FIELD_INPUT = 3;
+export declare const MATCH_VEC_FIELD_GROUPS = 4;
+export declare const MATCH_VEC_FIELD_INDICES = 5;
+/**
+ * Ensure the `$__regexp_match_vec` struct type (#1914) — the match-result
+ * shape for standalone `exec`/`match`.
+ *
+ * A WasmGC **subtype** of the nullable-native-string vec (`__vec_ref_<anyStr>`,
+ * fields `{length, data}`), extended with the spec result fields of
+ * §22.2.7.2 RegExpBuiltinExec ("index" = match start, "input" = the subject
+ * string). Subtyping (not a sibling struct) is load-bearing: every existing
+ * vec consumer (element access, `.length`, iteration) keeps working on the
+ * result via subsumption, and only `.index`/`.input` property reads need the
+ * subtype's extra fields. Mirrors the `__template_vec_externref` precedent in
+ * registry/types.ts (the base vec is flipped to a non-final root on demand).
+ */
+export declare function ensureRegexMatchVecType(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_capture_array(nGroups, subject, caps) -> ref $__regexp_match_vec`
+ * (#1539 Phase 2b, result shape per #1914).
+ *
+ * Materializes capture slots from a populated caps array as a native string
+ * vec: element 0 is the full match, element N is capture N, and unmatched
+ * captures are null `(ref null $AnyString)`, which the standalone compiler
+ * already treats as `undefined` for native-string values. The returned struct
+ * is the match-vec subtype carrying `index` (= caps[0], the match start) and
+ * `input` (the flattened subject) per §22.2.7.2 RegExpBuiltinExec.
+ */
+export declare function ensureRegexCaptureArray(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_split(prog, classTable, nGroups, strData, strOff, strLen,
+ * subject, lim) -> ref $vec_nstr` (#1913, full §22.2.6.14 semantics).
+ *
+ * Implements the SplitMatch walk: split points where the separator matches,
+ * capture values (incl. unmatched → undefined elements) interleaved after
+ * each split slice, every append capped at `lim` (ToUint32 of the limit
+ * argument; compare unsigned so the spec default 2^32-1 is just -1), and the
+ * empty-separator rule — a match whose END equals the last split point makes
+ * no split and the scan resumes one unit further (this also covers the
+ * empty-pattern "split into chars" behaviour without looping forever).
+ * Empty subject: a separator match on "" yields `[]`, otherwise `[subject]`.
+ */
+export declare function ensureRegexSplit(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_match_all(prog, classTable, nGroups, strData, strOff, strLen,
+ * subject) -> ref null $__regexp_match_vec` (#1913).
+ *
+ * `String.prototype.match` with a GLOBAL regex (§22.2.6.8 step 6): collect
+ * every match's [0] substring, advancing past empty matches per
+ * AdvanceStringIndex; null when there were no matches. The result reuses the
+ * match-vec subtype for type uniformity with the non-global path —
+ * `index`/`input` carry the FIRST match (a documented narrow deviation: per
+ * spec a global match result is a plain Array without those properties).
+ */
+export declare function ensureRegexMatchAll(ctx: CodegenContext): number;
+/** The matchAll outer-vec type idx (`$vec<$__regexp_match_vec>`). Consumers use
+ *  it as the result ValType of `__regex_match_all_arrays`. (#2161) */
+export declare function ensureRegexMatchAllVecType(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_match_all_arrays(prog, classTable, nGroups, strData, strOff,
+ * strLen, subject, nScratch) -> ref $vec<$__regexp_match_vec>` (#2161).
+ *
+ * `String.prototype.matchAll` (§22.2.6.9 / RegExpStringIterator §22.2.9.2) must
+ * yield the **full match array** for every match — each with [0], capture
+ * groups, `.index`, `.input` — i.e. a sequence of capture-ARRAYS, not the [0]
+ * substrings that `__regex_match_all` (the global `match` path) collects.
+ *
+ * This clones the eager `__regex_match_all` AdvanceStringIndex loop verbatim,
+ * but per match calls `__regex_capture_array(nGroups, subject, caps)` (the same
+ * builder `exec`/non-global `match` use) and pushes that match-vec ref into a
+ * growable vec-of-(match-vec-refs). The result is ALWAYS a non-null vec (empty
+ * when there are no matches — matchAll returns an empty iterator, never null),
+ * which the native-vec for-of / spread consumers (#2169) iterate directly,
+ * yielding each indexable match array.
+ */
+export declare function ensureRegexMatchAllArrays(ctx: CodegenContext): number;
+/** Build inline instructions that materialize a `number[]` as a fixed
+ *  `array i32` on the stack (used for prog + classTable literals). */
+export declare function i32ArrayLiteralInstrs(ctx: CodegenContext, values: number[]): Instr[];
+/**
+ * Emit `__regex_get_substitution(subject, slen, nGroups, caps, repl)
+ * -> ref $AnyString` (#1913).
+ *
+ * GetSubstitution (ECMA-262 §22.2.6.11): expand `$$`, `$&`, `` $` ``, `$'`,
+ * and `$n`/`$nn` in the (flattened) replacement string against the populated
+ * caps array. Out-of-range `$n` and `$<` (no named groups in the standalone
+ * engine) pass through literally per spec. Unmatched captures expand to the
+ * empty string. Builds the result with `__str_concat` over O(1)
+ * `__str_substring` views.
+ */
+export declare function ensureRegexGetSubstitution(ctx: CodegenContext): number;
+/**
+ * Emit `__regex_flags_str(flags: i32) -> ref $NativeString` (#1914).
+ *
+ * Builds the `RegExp.prototype.flags` string from the `$NativeRegExp` flags
+ * bitfield per ECMA-262 §22.2.6.4: append one code unit per set flag in the
+ * fixed spec order d, g, i, m, s, u, v, y. The 8-slot i16 buffer is the exact
+ * maximum (one slot per possible flag); `len` counts only appended units.
+ */
+export declare function ensureRegexFlagsStr(ctx: CodegenContext): number;

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

@@ -0,0 +1,146 @@
+import { Instr, ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export declare function nativeStringType(ctx: CodegenContext): ValType;
+/**
+ * Build the inline instruction sequence that materializes a string literal as
+ * a NativeString (FlatString) struct ref. Mirrors `compileNativeStringLiteral`
+ * but returns an `Instr[]` for callers that build instruction streams without
+ * a `FunctionContext` (e.g. throw-instr builders that return `Instr[]`).
+ */
+export declare function nativeStringLiteralInstrs(ctx: CodegenContext, value: string, encoding?: StringEncoding): Instr[];
+/** #1588 PR-B: encoding annotation values the lowering sites consume. Mirrors
+ *  `Encoding` in `src/ir/analysis/encoding.ts` (kept as a local string-union to
+ *  avoid a codegen→ir import cycle). */
+export type StringEncoding = "ascii" | "utf8-guaranteed" | "wtf16";
+/**
+ * Build inline instructions that push a string constant onto the stack as an
+ * externref (the type expected by the throw tag and by host imports). In
+ * nativeStrings mode, materializes the FlatString struct inline and converts
+ * to externref. In legacy mode, emits a plain `global.get` of the
+ * `string_constants` import. Both branches require the value to be present
+ * in `ctx.stringGlobalMap` — call `addStringConstantGlobal(ctx, value)` first.
+ */
+export declare function stringConstantExternrefInstrs(ctx: CodegenContext, value: string): Instr[];
+/**
+ * Get the nullable ValType for a string reference (ref null $AnyString).
+ */
+export declare function nativeStringTypeNullable(ctx: CodegenContext): ValType;
+/**
+ * Get the ValType for a flat string reference (ref $NativeString).
+ */
+export declare function flatStringType(ctx: CodegenContext): ValType;
+/**
+ * Emit native string helper functions into the module.
+ * Called lazily when string operations are first encountered in fast mode.
+ *
+ * IMPORTANT: All imports must be registered BEFORE any module functions,
+ * because wasm function indices are: imports first, then module functions.
+ */
+export declare function ensureNativeStringHelpers(ctx: CodegenContext): void;
+export declare function ensureTextEncodingHelpers(ctx: CodegenContext): {
+    encodeIdx: number;
+    decodeU8Idx: number;
+    vecTypeIdx: number;
+    resultTypeIdx: number;
+};
+/**
+ * (#1780) Register `__textencoder_encode_into_<destElemKey>`: writes UTF-8 bytes
+ * of `source` into the `dest` Uint8Array backing array, never splitting a code
+ * point, and returns a `{ read, written }` result struct. `read` counts UTF-16
+ * code units consumed for fully-written code points; `written` counts bytes
+ * written. Shares the surrogate-decode + UTF-8 emit shape of
+ * `__textencoder_encode`, but writes into a caller-supplied bounded buffer.
+ *
+ * The destination vec storage differs by target: WASI/standalone back
+ * `Uint8Array` with a packed `i8_byte` array (`{ kind: "i8" }`), other targets
+ * with an `f64` array (see `typedArrayVecStorage`). The caller passes the
+ * matching `destElemKey` so the bytes land in the right element representation.
+ */
+export declare function ensureEncodeIntoHelper(ctx: CodegenContext, destElemKey: "f64" | "i8_byte"): {
+    encodeIntoIdx: number;
+    destVecTypeIdx: number;
+    resultTypeIdx: number;
+};
+/**
+ * #1470 — Emit `$__any_to_string(v: anyref) -> ref $AnyString`, the standalone
+ * (no-JS-host) replacement for the `__extern_toString` host import. Dispatches
+ * on the concrete WasmGC type of `v`:
+ *   - ref $AnyString    → returned as-is (already a native string)
+ *   - ref $AnyValue     → switch on the boxed tag:
+ *       0 null      → "null"
+ *       1 undefined → "undefined"
+ *       2 i32 num   → number_toString(f64.convert_i32_s(i32val))
+ *       3 f64 num   → number_toString(f64val)
+ *       4 bool      → "true" / "false"
+ *       5 string    → externval → any.convert_extern → ref.cast $AnyString
+ *       6 ref / else→ "[object Object]"
+ *   - anything else     → "[object Object]"
+ *
+ * Spec-correct dispatch for ordinary objects (walking @@toPrimitive / toString
+ * via the object's vtable) lands with #1472; the Phase-1 fallback here is the
+ * canonical `"[object Object]"` so a standalone module never traps on a string
+ * coercion of an arbitrary value.
+ *
+ * Idempotent — caches the function index under `nativeStrHelpers["__any_to_string"]`.
+ */
+export declare function ensureAnyToStringHelper(ctx: CodegenContext): number;
+/**
+ * #2007 — call-site entry point for the standalone `+`/template concat path.
+ * When a concat operand is a statically-known WasmGC vec (array) ref, emit the
+ * Array.prototype.join lowering **inline into `fctx.body`** and leave a
+ * `ref $AnyString` on the stack. Returns true if it handled the operand.
+ *
+ * The operand value is assumed already on the stack with the given
+ * `vecValType` (a `ref`/`ref_null` to a registered vec struct).
+ *
+ * **Why inline, not a cached helper (#1448).** Emitting into the current
+ * function body is the proven-safe pattern (cf. `compileArrayJoinNative`):
+ * `number_toString` / `__str_concat` indices are read here and the resulting
+ * `call`s live in `fctx.body`, which the late-import `shiftFuncIndices` pass
+ * always walks — so a closure-method operand (`[...].map(fn)`, whose late
+ * import registration desyncs a *separate cached helper's* baked indices) can
+ * no longer produce an invalid module. Nested-array elements (a ref to another
+ * registered vec, common in `[[1,2],[3]]` literals which are closure-free)
+ * recurse into the cached per-vec join helper, which is consistent there.
+ */
+export declare function tryCompileNativeVecConcatOperand(ctx: CodegenContext, fctx: FunctionContext, vecValType: ValType): boolean;
+/**
+ * #1470 — Emit `$__str_to_char_vec(s: ref $AnyString) -> ref $vec_nstr`: the
+ * pure-Wasm String-iterator materializer. Splits the string into single
+ * **code point** strings per §22.1.5.1 (the String Iteration protocol that
+ * `[...s]`, `Array.from(s)` and for-of observe): a well-formed surrogate
+ * pair yields one 2-code-unit string; everything else (BMP scalars and lone
+ * surrogates) yields a 1-code-unit string.
+ *
+ * The result reuses the `ref_<anyStr>` vec registration that `__str_split`
+ * established, so callers get the exact vec shape `string[]` lowers to
+ * (`.length`, indexing, spreads compose without conversion). The backing
+ * array is sized `len` (the code-unit count — an upper bound on the code
+ * point count); the vec's `len` field carries the actual element count, so
+ * trailing unused slots are never observed.
+ *
+ * Returns both the helper funcIdx (current at call time — late-import shifts
+ * keep `nativeStrHelpers` patched, #1839) and the nstr vec type index.
+ */
+export declare function ensureStrToCharVecHelper(ctx: CodegenContext): {
+    funcIdx: number;
+    vecTypeIdx: number;
+};
+export declare function ensureNativeStringExternBridge(ctx: CodegenContext): void;
+/**
+ * Emit `__test_str_from_externref` and `__test_str_to_externref` exported
+ * helpers (#1187). These are the test-runtime bridge that lets vitest tests
+ * pass JS strings into Wasm exports whose native-string params have type
+ * `(ref $AnyString)`, and read native-string results back as JS strings.
+ *
+ * Gated on `ctx.testRuntime && ctx.nativeStrings`. Production builds (with
+ * `testRuntime` unset) never reach this code, so the helpers are absent
+ * from the module entirely — zero runtime overhead.
+ *
+ * Preconditions (set up by the pre-pass in `generateModule`):
+ *   - `addStringImports` has been called → `length`, `charCodeAt`, `concat`,
+ *     `substring` are registered as `wasm:js-string` imports.
+ *   - `String_fromCharCode` is registered as an `env` host import.
+ *   - `ensureNativeStringHelpers` has been called → `__str_flatten` exists.
+ */
+export declare function emitTestRuntimeStringHelpers(ctx: CodegenContext): void;

package/dist/codegen/new-target.d.ts

@@ -0,0 +1,30 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext } from './context/types.js';
+import { Instr } from '../ir/types.js';
+/**
+ * Pre-scan the source for any `new.target` meta-property. Sets
+ * `ctx.usesNewTarget`. Cheap structural walk; runs once before body compilation.
+ */
+export declare function scanForNewTarget(ctx: CodegenContext, root: ts.Node): void;
+/**
+ * Assign (or look up) the stable 1-based class-id for a local class. Ids start
+ * at 1 so the global's `0` initial value never matches a real class — which
+ * keeps `new.target === SomeClass` false when read outside any construction.
+ */
+export declare function getOrAssignClassNewTargetId(ctx: CodegenContext, className: string): number;
+/**
+ * Allocate the mutable i32 `new.target` class-id global if not already present.
+ * Returns its absolute Wasm global index. Only call when `ctx.usesNewTarget`.
+ */
+export declare function ensureNewTargetGlobal(ctx: CodegenContext): number;
+/**
+ * Emit the load of the current `new.target` class-id (an i32). Only meaningful
+ * inside a constructor.
+ */
+export declare function emitNewTargetClassId(ctx: CodegenContext, body: Instr[]): void;
+/**
+ * Emit `i32.const <classId>; global.set __new_target_classid`. Call this right
+ * before pushing the constructor `call` instruction (args already on the
+ * stack). No-op when `new.target` is unused.
+ */
+export declare function emitSetNewTargetBeforeCall(ctx: CodegenContext, body: Instr[], className: string): void;

package/dist/codegen/node-fs-api.d.ts

@@ -0,0 +1,47 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+export declare function tryCompileNodeProcessCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;
+/**
+ * Recognize + lower an imported node:fs `readSync(fd, buf, …)` /
+ * `writeSync(fd, buf, …)` call. Returns the result (a byte count, f64), or
+ * `undefined` when this isn't a node-fs fd-based call we handle (the generic
+ * compiler then proceeds — path-based fs is handled / rejected elsewhere).
+ */
+export declare function tryCompileNodeFsCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;
+/**
+ * #2655 — emit the per-`fd` "read `len` bytes from `fd` into linear `ptrLocal`,
+ * leaving the byte count on the stack as i32". Two modes:
+ *   - shim (`direct=false`): `read_sync(fd, ptr, len)` — the imported shim owns
+ *     the iovec + syscall over the shared memory; it returns the byte count.
+ *   - direct (`direct=true`): build a `{ base=ptr, len }` iovec at
+ *     `WASI_READSYNC_IOV_OFFSET`, call the BLOCKING
+ *     `fd_read(fd, iovs, 1, nread=WASI_READSYNC_NREAD_OFFSET)`, then load nread.
+ *     An errno != 0 yields 0 bytes (read loops treat `r <= 0` as EOF/stop).
+ *
+ * `ptrLocal`/`lenLocal` are i32 locals already holding the destination linear
+ * pointer and the requested length; `fdLocal` holds the fd.
+ */
+export declare function emitFdReadRuntime(fctx: FunctionContext, fdLocal: number, ptrLocal: number, lenLocal: number, sinkIdx: number, direct: boolean): void;
+/**
+ * #2655 — emit the per-`fd` "write `len` bytes from linear `ptrLocal` to `fd`,
+ * leaving the byte count on the stack as i32". Two modes:
+ *   - shim (`direct=false`): `write_sync(fd, ptr, len)` returns the byte count.
+ *   - direct (`direct=true`): build a `{ base=ptr, len }` iovec at memory[0..7],
+ *     call `fd_write(fd, iovs=0, 1, nwritten=8)`, then load nwritten. An
+ *     errno != 0 yields 0 bytes (write loops treat `w <= 0` as stop). The
+ *     memory[0..11] iovec/nwritten scratch matches `emitWasiWriteTail`; a single
+ *     writeSync call never interleaves with another write over it.
+ */
+export declare function emitFdWriteRuntime(ctx: CodegenContext, fctx: FunctionContext, fdLocal: number, ptrLocal: number, lenLocal: number, sinkIdx: number, direct: boolean): void;
+export declare function emitNodeFsResolveGcU8(ctx: CodegenContext, fctx: FunctionContext, bufExpr: ts.Expression): {
+    arrLocal: number;
+    arrTypeIdx: number;
+    lenLocal: number;
+} | null;
+/** Grow linear memory so [scratchStart, scratchStart + lenLocal) is addressable. */
+export declare function ensureScratchPages(fctx: FunctionContext, scratchStart: number, lenLocal: number): void;
+/** for j in [0, countLocal): dest[off + j] = scratch[scratchStart + j] (i8 array). */
+export declare function emitScratchToArrayCopy(fctx: FunctionContext, arrTypeIdx: number, arrLocal: number, offLocal: number, scratchStart: number, countLocal: number): void;
+/** for j in [0, countLocal): scratch[scratchStart + j] = src[off + j] (i8 array). */
+export declare function emitArrayToScratchCopy(fctx: FunctionContext, arrTypeIdx: number, arrLocal: number, offLocal: number, scratchStart: number, countLocal: number): void;

package/dist/codegen/number-format-native.d.ts

@@ -0,0 +1,9 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Emit native number-format functions and register them in `ctx.funcMap`.
+ * `which` is a subset of {number_toString, number_toString_radix,
+ * number_toFixed, number_toPrecision, number_toExponential}. Must run before
+ * any function bodies that call them, and (via ensureNativeStringHelpers) sets
+ * up the NativeString types.
+ */
+export declare function emitNativeNumberFormat(ctx: CodegenContext, which: Set<string>): void;

package/dist/codegen/number-ryu.d.ts

@@ -0,0 +1,27 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * `__num_ryu_digits(value: f64) -> (digits: i64, exp: i32)`
+ *
+ * The Ryū `d2d` shortest-decimal core. `value` is assumed finite and non-zero.
+ * Returns `(digits, exp)` such that `value == ±digits × 10^exp`, where `digits`
+ * is the shortest decimal mantissa (sign dropped — caller tracks it). A faithful
+ * translation of the validated BigInt reference; comments mark each step against
+ * the Adams / dtolnay reference.
+ */
+export declare function emitRyuDigits(ctx: CodegenContext): number;
+/**
+ * `__num_ryu_to_buf(value: f64, neg: i32, buf: ref $strData, pos: i32) -> i32`
+ *
+ * Formats the shortest-roundtrip decimal of a finite, non-zero `value` into the
+ * caller's i16 string buffer at `pos`, writing a leading '-' when `neg`. Returns
+ * the new write position. Implements ECMA-262 §6.1.6.1.13 framing on top of the
+ * `(digits, exp)` produced by `__num_ryu_digits`:
+ *   let k = #digits(digits), n = exp + k.
+ *   - k <= n <= 21         → digits followed by (n-k) zeros               (integer)
+ *   - 0 < n <= 21          → digits[0..n] '.' digits[n..]                 (fixed)
+ *   - -6 < n <= 0          → "0." (-n zeros) digits                       (fixed)
+ *   - otherwise            → digits[0] ['.' digits[1..]] 'e' sign |n-1|   (exp)
+ *
+ * `strDataTypeIdx` is the native-string i16 array type (caller's buffer type).
+ */
+export declare function emitRyuToBuf(ctx: CodegenContext, strDataTypeIdx: number): number;

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

@@ -0,0 +1,94 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * Try to constant-fold `ToBoolean(<expr>)` at compile time. Returns:
+ *   - `true`/`false` if the expression has a statically-known truthiness
+ *   - `undefined` if the value cannot be determined at compile time (caller
+ *     must evaluate at runtime or fall back to the dynamic path).
+ *
+ * Per ES spec §6.2.5.6 step 5.b, every descriptor attribute (writable,
+ * enumerable, configurable) is run through `ToBoolean` before being stored.
+ * Previously the codegen only accepted the `true`/`false` keyword literals
+ * and silently dropped the entire attribute when any other expression
+ * appeared (so `{ configurable: -12345 }` resulted in `configurable: false`
+ * — a silent spec violation triggering 1,000+ test262 failures).
+ */
+export declare function tryConstantFoldToBoolean(init: ts.Expression): boolean | undefined;
+export declare function emitDefinePropertyDescRuntime(ctx: CodegenContext, fctx: FunctionContext, objArg: ts.Expression, propArg: ts.Expression, descArg: ts.Expression, undefinedFields: readonly string[]): ValType | null;
+/**
+ * Check if the first argument to Object.defineProperty / defineProperties
+ * is statically known to be a non-object type (undefined, null, boolean,
+ * number, string).  If so, emit `throw TypeError` and return true.
+ *
+ * Per ES spec (19.1.2.4 step 1): "If Type(O) is not Object, throw a TypeError."
+ */
+export declare function emitNonObjectArgGuard(ctx: CodegenContext, fctx: FunctionContext, argExpr: ts.Expression, methodName: string): boolean;
+/**
+ * Property descriptor flag encoding for the __pf_ side-table:
+ *   bit 0: writable
+ *   bit 1: enumerable
+ *   bit 2: configurable
+ *   bit 3: "defined" marker (always 1 when a descriptor has been stored)
+ *   bit 4: is accessor property (get/set vs data)
+ */
+export declare const PROP_FLAG_WRITABLE: number;
+export declare const PROP_FLAG_ENUMERABLE: number;
+export declare const PROP_FLAG_CONFIGURABLE: number;
+export declare const PROP_FLAG_DEFINED: number;
+export declare const PROP_FLAG_ACCESSOR: number;
+/**
+ * Compute a compile-time flags integer from parsed descriptor booleans.
+ * Unspecified flags default to false per the ES spec for Object.defineProperty.
+ */
+export declare function computeDescriptorFlags(writable: boolean | undefined, enumerable: boolean | undefined, configurable: boolean | undefined, isAccessor: boolean): number;
+/**
+ * Emit code to check existing property flags and throw TypeError if the
+ * Object.defineProperty operation violates the spec. Also stores the new flags.
+ *
+ * Uses __extern_get/set with "__pf_<propName>" keys to store flags as boxed numbers.
+ * Uses "__ne" key to check non-extensibility.
+ *
+ * @param objLocal - local index holding the externref object
+ * @param propName - compile-time property name
+ * @param newFlags - the flags integer for the new descriptor
+ * @param hasValue - whether the new descriptor specifies a value
+ */
+export declare function emitDefinePropertyFlagCheck(ctx: CodegenContext, fctx: FunctionContext, objLocal: number, propName: string, newFlags: number, hasValue: boolean): void;
+/**
+ * Compile Object.defineProperty(obj, prop, descriptor).
+ *
+ * If the descriptor is an object literal with a `value` property, we extract
+ * the value and emit __extern_set(obj, prop, value).
+ * If the descriptor has `get` and/or `set` properties, we compile them as
+ * struct accessor methods (getter/setter functions).
+ * Otherwise we compile all arguments for side effects and return the object unchanged.
+ *
+ * Returns obj (externref).
+ */
+export declare function compileObjectDefineProperty(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): ValType | null;
+/**
+ * Compile Object.defineProperties(obj, descriptors).
+ *
+ * Static path: when descriptors is an object literal, iterate each property
+ * and synthesize individual Object.defineProperty calls at compile time.
+ *
+ * Dynamic fallback: delegate to __defineProperties host import.
+ */
+export declare function compileObjectDefineProperties(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): ValType | null;
+/**
+ * Compile Object.keys(obj) or Object.values(obj) by expanding struct fields
+ * at compile time. Object.keys returns a string[] of field names,
+ * Object.values returns an array of the field values.
+ */
+export declare function compileObjectKeysOrValues(ctx: CodegenContext, fctx: FunctionContext, method: string, expr: ts.CallExpression): ValType | null;
+/**
+ * Compile obj.hasOwnProperty(key) / obj.propertyIsEnumerable(key).
+ * For WasmGC structs all own fields are enumerable, so both methods behave
+ * identically: return true iff `key` names an own field of the struct type.
+ *
+ * Static resolution (string literal arg): constant fold to i32.const 0/1.
+ * Dynamic resolution: runtime string comparison against known field names.
+ */
+export declare function compilePropertyIntrospection(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, expr: ts.CallExpression): InnerResult;