@loopdive/js2 0.57.0

package/dist/codegen/json-runtime.d.ts

@@ -0,0 +1,35 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Emit `__json_quote_string(s: externref) -> externref` and register it in
+ * `ctx.funcMap`. Idempotent. Must run after `ensureNativeStringHelpers` (called
+ * here) so `__str_flatten` exists, and before any function body that calls it.
+ *
+ * Algorithm: flatten the input to a `$NativeString`, walk its `[off, off+len)`
+ * code units twice — first to size the output buffer, then to fill it — so the
+ * output `$__str_data` is allocated exactly once at the right capacity.
+ */
+export declare function emitJsonQuoteString(ctx: CodegenContext): number;
+/**
+ * Emit `__json_parse_primitive(s: externref) -> ref $AnyValue` and register it
+ * in `ctx.funcMap`. Idempotent. Parses a runtime string holding a single JSON
+ * primitive (number / `true` / `false` / `null`) entirely in Wasm — no
+ * `env::JSON_parse` host import — and boxes the result into the host-free
+ * `$AnyValue` tagged union (#1599 Phase 2):
+ *
+ *   - `"null"`             → tag 0 (null)
+ *   - `"true"` / `"false"` → tag 4 (boolean), i32val 1 / 0
+ *   - JSON number          → tag 3 (f64), f64val = parsed value
+ *   - anything else        → `unreachable` (Wasm trap; matches a SyntaxError
+ *                             throw under the standalone no-host contract)
+ *
+ * The caller (`tryEmitJsonParsePrimitive` in expressions/calls.ts) gates this
+ * on `ctx.standalone || ctx.wasi` and a string-typed argument, and returns the
+ * `ref $AnyValue` type so the existing AnyValue→primitive coercion path in
+ * type-coercion.ts unboxes it to number / boolean as the consumer requires.
+ *
+ * Must run after `ensureNativeStringHelpers` (called here) so `__str_flatten`
+ * exists, and before any function body that calls it.
+ *
+ * Spec: ECMA-262 §25.5.2 `JSON.parse` / `ParseJSON`, ECMA-404 JSON grammar.
+ */
+export declare function emitJsonParsePrimitive(ctx: CodegenContext): number;

package/dist/codegen/json-standalone.d.ts

@@ -0,0 +1,25 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * #2166 — resolve a `JSON.stringify` `space` argument (3rd parameter) to a
+ * compile-time number or string, so the static stringify path can produce the
+ * indented form. Returns `undefined` when the value isn't statically known
+ * (caller then refuses / keeps the compact form gate). Per §25.5.2 only the
+ * first 10 characters of a string space (or `min(10, floor(n))` for a number)
+ * are used; JS's own `JSON.stringify` applies that, so we just forward.
+ */
+export declare function staticSpaceValue(ctx: CodegenContext, expr: ts.Expression): number | string | undefined;
+/**
+ * (#2166 PR-B) Resolve a static `space` argument to the per-level indent unit
+ * string (the "gap") per §25.5.2 step 6: a Number → `min(10, floor(n))` spaces
+ * (≤0 / NaN → ""); a String → its first 10 code units. Returns `""` for any
+ * gap that produces no indentation (the dynamic-graph codec then serialises
+ * compactly). The caller passes the gap to `__json_stringify_root_indent`.
+ */
+export declare function jsonGapFromStaticSpace(space: number | string): string;
+export declare function isJsonParseCall(expr: ts.Expression): expr is ts.CallExpression;
+export declare function tryEmitJsonStringifyStatic(ctx: CodegenContext, fctx: FunctionContext, arg: ts.Expression, replacerArg?: ts.Expression, spaceArg?: ts.Expression): ValType | null | undefined;
+export declare function tryEmitJsonParseLiteral(ctx: CodegenContext, fctx: FunctionContext, call: ts.CallExpression): ValType | null | undefined;
+export declare function tryEmitJsonParsePropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression): ValType | null | undefined;
+export declare function tryEmitJsonParseElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null | undefined;

package/dist/codegen/linear-uint8-analysis.d.ts

@@ -0,0 +1,46 @@
+import { ts } from '../ts-api.js';
+/** Result of the linear-safe `Uint8Array` analysis (frozen before codegen). */
+export interface LinearUint8Result {
+    /**
+     * Symbols of every binding (local variable or parameter) proven linear-safe.
+     * Codegen consults this by `checker.getSymbolAtLocation(idNode)`.
+     */
+    safeBindings: Set<ts.Symbol>;
+    /**
+     * For each function whose signature is linear-rewritten, the set of
+     * parameter indices that are linear-backed. Keyed by the function's own
+     * symbol. Callers use this to lower call arguments to `(ptr, len)` pairs and
+     * to rewrite the callee's wasm param list.
+     */
+    linearParams: Map<ts.Symbol, Set<number>>;
+    /**
+     * The **Slice-B-eligible** subset of {@link safeBindings}: a `new
+     * Uint8Array(...)` *local* whose every use stays inside its declaring
+     * function — element load/store, `.length`, and `process.std*.{read,write}`
+     * I/O only — and which is **never** passed as an argument to a user function
+     * (nor is itself a parameter). These can be backed by linear memory
+     * intraprocedurally with no call-site or signature changes.
+     *
+     * A buffer that flows through a user-function parameter is in `safeBindings`
+     * + `linearParams` (the Slice-C interprocedural signature-rewrite targets)
+     * but is deliberately **excluded** here: backing it linearly without the
+     * C-phase signature rewrite would hand a `(ptr,len)` local to a callee that
+     * still expects a GC array, an invalid-Wasm type mismatch. Slice B consumes
+     * this set; Slice C will widen consumption to all of `safeBindings`.
+     */
+    localOnlyBindings: Set<ts.Symbol>;
+}
+/**
+ * Build the linear-safe analysis for a WASI source file.
+ *
+ * Algorithm (monotone, terminates — classifications only ever demote):
+ *  1. Collect every candidate binding: `new Uint8Array(...)` variable inits and
+ *     `Uint8Array` parameters of non-exported user functions. Exported
+ *     functions' params are NOT candidates (their ABI is observable).
+ *  2. Seed every candidate as linear-safe.
+ *  3. Fixpoint: walk each function body. A candidate binding/param is demoted
+ *     if it has any disqualifying use, OR is passed to a callee parameter that
+ *     is currently demoted. Repeat until no demotions occur in a full pass.
+ *  4. Freeze: the survivors are the linear-safe set.
+ */
+export declare function analyzeLinearUint8(checker: ts.TypeChecker, sourceFile: ts.SourceFile, nodeFsSyncNames?: ReadonlySet<string>): LinearUint8Result;

package/dist/codegen/linear-uint8-arena.d.ts

@@ -0,0 +1,7 @@
+import { Instr } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+export declare function containsLinearU8Allocation(ctx: CodegenContext, node: ts.Node | undefined): boolean;
+export declare function emitLinearU8ArenaMark(ctx: CodegenContext, fctx: FunctionContext, name?: string): number | undefined;
+export declare function linearU8ArenaResetInstrs(ctx: CodegenContext, markLocalIdx: number | undefined): Instr[];
+export declare function emitLinearU8ArenaReset(ctx: CodegenContext, fctx: FunctionContext, markLocalIdx: number | undefined): void;

package/dist/codegen/linear-uint8-codegen.d.ts

@@ -0,0 +1,103 @@
+import { ValType } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * True when this `Uint8Array` binding is proven linear-safe by the #1886
+ * analysis. Slice C rewrites matching function params to `(ptr,len)`, so the
+ * codegen can consume the full safe set rather than Slice B's local-only
+ * subset. Returns false outside WASI or when the analysis did not run.
+ */
+export declare function isLinearSafeBinding(ctx: CodegenContext, node: ts.Node): boolean;
+/**
+ * `new Uint8Array(n)` / `new Uint8Array([a,b,…])` for a linear-safe local being
+ * declared as `nameNode`. Allocates `(ptr, len)` i32 locals, calls
+ * `__lin_u8_alloc(n)`, and (for the array-literal form) stores the literal
+ * bytes. Registers the buffer in `fctx.linearU8Buffers` and leaves NOTHING on
+ * the value stack (the binding lives in the two i32 locals). Returns true if it
+ * handled the `new`; false to fall through to the GC path.
+ *
+ * Caller contract: invoked from the variable-declaration lowering for a
+ * `const/let x = new Uint8Array(...)` where `isLocalLinearNewBinding(x)` holds.
+ */
+export declare function tryEmitLinearU8New(ctx: CodegenContext, fctx: FunctionContext, nameNode: ts.Identifier, newExpr: ts.NewExpression): boolean;
+/**
+ * `b[i]` read for a linear-backed buffer → `i32.load8_u (ptr + trunc(i))`,
+ * widened to f64 to match the observable element value type the GC path
+ * returns. Returns the result ValType, or `null` if `b` is not linear-backed.
+ */
+export declare function tryEmitLinearU8ElementGet(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+/**
+ * `b[i] = v` for a linear-backed buffer → `i32.store8 (ptr + trunc(i)),
+ * trunc(v) & 0xff`, leaving **nothing** on the stack and returning
+ * `VOID_RESULT`. Returns `null` if `b` is not a linear-backed buffer (caller
+ * falls through to GC).
+ *
+ * The assignment compiles as a statement (the common case — e.g. the
+ * native-messaging frame builder writes `buf[i] = (buf[i] + 1) & 255`). Unlike
+ * the GC `array.set` path, this does NOT push the assigned value as the
+ * expression result: `x = buf[i] = v` value-of-assignment is not yet supported
+ * for linear-backed buffers (out of scope for the I/O-buffer workloads this
+ * targets — the analysis only admits buffers that never appear as a bare
+ * identifier). See the `return VOID_RESULT` note below for why pushing the value
+ * broke void-function completion.
+ *
+ * Evaluation order matches JS + the GC path: index expression first, then the
+ * value expression, then the store.
+ */
+export declare function tryEmitLinearU8ElementSet(ctx: CodegenContext, fctx: FunctionContext, target: ts.ElementAccessExpression, valueExpr: ts.Expression): InnerResult;
+/**
+ * #2045 C.8 — compound element write `b[i] op= rhs` (`+=`, `++`, `--`, …) for a
+ * linear-backed buffer → read-modify-write at a single computed address.
+ *
+ * Without this, `compileElementCompoundAssignment` compiled the buffer
+ * expression as a value (materialising the GC representation) and wrote the
+ * result back through the externref/GC path — which never touched the linear
+ * memory, so `b[0] += 1` silently kept the old byte (read 5, computed 6, stored
+ * nowhere). This emits the same `i32.load8_u` read and `i32.store8` write as the
+ * plain get/set, sharing one `addr = ptr + trunc(i)` so the index is evaluated
+ * once and the read and write hit the same byte.
+ *
+ * `emitOp` is invoked with the current element value already on the stack as
+ * f64; it must push the rhs and emit the compound operator, leaving the result
+ * f64 on the stack (the caller passes a closure over `emitCompoundOp` + the rhs
+ * expression to avoid an assignment.ts↔linear-uint8-codegen.ts import cycle).
+ *
+ * Leaves the **assigned f64 value** on the stack and returns `{kind:"f64"}` so
+ * `b[i] op= rhs` works in both statement and expression position (matching the
+ * GC/externref compound paths, which also push the result). Note the value is
+ * the full f64 result, not the truncated stored byte — same as the GC array
+ * path's compound result. Returns `null` if `b` is not a linear-backed buffer.
+ */
+export declare function tryEmitLinearU8ElementCompound(ctx: CodegenContext, fctx: FunctionContext, target: ts.ElementAccessExpression, emitOp: () => void): ValType | null;
+/**
+ * #2045 C.8 — prefix/postfix `++`/`--` on a linear-backed element
+ * (`b[i]++`, `++b[i]`, `b[i]--`, `--b[i]`) → read-modify-write at one address.
+ *
+ * The generic prefix/postfix element handlers begin with
+ * `compileExpression(target.expression)` and require a `ref`/`ref_null` array —
+ * a linear buffer is a `(ptr,len)` pair, so they error/throw. This emits the
+ * linear read-modify-write directly: load `b[i]`, add/sub 1, store the low byte,
+ * and leave the **old** value (postfix) or the **new** value (prefix) on the
+ * stack as f64 — matching JS update-expression semantics. Returns `null` if `b`
+ * is not a linear-backed buffer (caller falls through to the GC handlers).
+ */
+export declare function tryEmitLinearU8ElementUpdate(ctx: CodegenContext, fctx: FunctionContext, target: ts.ElementAccessExpression, isIncrement: boolean, isPrefix: boolean): ValType | null;
+/** `b.length` for a linear-backed buffer → `len` widened to f64. */
+export declare function tryEmitLinearU8Length(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression): ValType | null;
+/** Accessor used by the WASI I/O intrinsics to get a buffer's (ptr, len) locals. */
+export declare function getLinearU8Buffer(ctx: CodegenContext, fctx: FunctionContext, node: ts.Node): {
+    ptrLocalIdx: number;
+    lenLocalIdx: number;
+} | undefined;
+/**
+ * Zero-copy `process.stdout/stderr.write(buf)` for a linear-backed buffer.
+ * `fd_write` reads straight from `ptr` for `len` bytes — no GC→linear staging
+ * copy. Returns `true` if handled (and leaves the i32 `1` write-result on the
+ * stack, matching the GC write path), `false` if `buf` is not linear-backed.
+ *
+ * `writeSinkIdx` is the func to call: `node:fs::writeSync(fd,ptr,len)` under the
+ * node shims, or `wasi_snapshot_preview1.fd_write` inline. `fd` is 1 (stdout) or
+ * 2 (stderr).
+ */
+export declare function tryEmitLinearU8StdWrite(ctx: CodegenContext, fctx: FunctionContext, bufArg: ts.Expression, writeSinkIdx: number, fd: number): boolean;

package/dist/codegen/linear-uint8-signatures.d.ts

@@ -0,0 +1,26 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+type FnDecl = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration;
+export declare function isLinearU8SafeBinding(ctx: CodegenContext, node: ts.Node): boolean;
+export declare function isLinearU8LocalOnlyBinding(ctx: CodegenContext, node: ts.Node): boolean;
+export declare function isLinearU8RepresentableNew(ctx: CodegenContext, newExpr: ts.NewExpression): boolean;
+export declare function getLinearU8ParamIndicesForDeclaration(ctx: CodegenContext, decl: FnDecl): Set<number> | undefined;
+export declare function getLinearU8ParamIndicesForCall(ctx: CodegenContext, call: ts.CallExpression): Set<number> | undefined;
+export declare function functionHasLinearU8Params(ctx: CodegenContext, name: string): boolean;
+export declare function expandLinearU8ParamTypes(ctx: CodegenContext, decl: FnDecl, sourceParamTypes: ValType[]): ValType[];
+export declare function wasmParamIndexForSourceParam(sourceIndex: number, linearParams: Set<number> | undefined, leadingParams?: number): number;
+export declare function sourceParamCountFromExpanded(wasmParamCount: number, linearParams: Set<number> | undefined, leadingParams?: number): number;
+/**
+ * #2045: look up a linear-backed buffer by the binding's `ts.Symbol`, resolved
+ * from the identifier `node`. Symbol identity is scope-correct, so a param
+ * `buf` and an inner-block `const buf` (distinct symbols, same text) no longer
+ * collide — the previous name-keyed map addressed whichever was registered last
+ * in both shadowing directions (silent corruption).
+ */
+export declare function getLinearU8Buffer(ctx: CodegenContext, fctx: FunctionContext, node: ts.Node): {
+    ptrLocalIdx: number;
+    lenLocalIdx: number;
+} | undefined;
+export declare function registerLinearU8Buffer(fctx: FunctionContext, sym: ts.Symbol, ptrLocalIdx: number, lenLocalIdx: number): void;
+export {};

package/dist/codegen/literals.d.ts

@@ -0,0 +1,115 @@
+import { default as ts } from 'typescript';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Ensure that a struct registered for an object literal includes fields for
+ * computed property names that TypeScript cannot statically resolve.
+ * When TS returns 0 properties (e.g. { [1+1]: 2 }), we resolve the computed
+ * keys at compile time and create proper struct fields.
+ */
+export declare function ensureComputedPropertyFields(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression, tsType: ts.Type): void;
+/**
+ * Last-resort fallback: compile an object literal as an externref plain object via host imports.
+ * Used when the TS type can't be mapped to a WasmGC struct (e.g., `{...null}`, `{...yield}`,
+ * or bundled JS objects with types too wide for struct inference).
+ *
+ * Creates a new plain object via __new_plain_object, then:
+ * - For spread assignments: calls __object_assign(target, source) to copy properties
+ * - For regular properties: calls __set_prop(target, key, value)
+ *
+ * Returns externref, or null if the host import is unavailable.
+ */
+export declare function compileObjectLiteralAsExternref(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression): ValType | null;
+/**
+ * (#2358) Reify a NOMINAL object struct (its ref already on the Wasm stack) into
+ * a dynamic `$Object` externref, copying each field as an own-property — so the
+ * native `__to_primitive` helper (which recognises only `$Object` via
+ * `ref.test objectTypeIdx`) can reduce a typed object that has crossed the
+ * externref boundary as an `any` value (e.g. an any-typed parameter, where the
+ * concrete typeIdx is erased inside the callee). The struct-instance analogue of
+ * `compileObjectLiteralAsExternref` (which builds the same `$Object` from AST
+ * props): both go through `__new_plain_object` + `__extern_set`, so the resulting
+ * object is read by the exact same native helpers.
+ *
+ * Returns true on success (struct consumed, `$Object` externref left on the
+ * stack); false if it declined (nothing emitted — caller must fall back to
+ * `extern.convert_any`). Declines when the struct type is unknown or the object
+ * runtime helpers are unavailable.
+ *
+ * This is a value-semantics COPY: it does not preserve nominal reference
+ * identity across the round-trip. The caller gates it to objects that carry a
+ * user ToPrimitive method (`valueOf`/`@@toPrimitive`/`toString`), for which
+ * value semantics suffice; plain data structs keep `extern.convert_any`.
+ */
+export declare function materializeStructAsDynamicObject(ctx: CodegenContext, fctx: FunctionContext, structTypeIdx: number): boolean;
+export declare function compileObjectLiteral(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression): ValType | null;
+/**
+ * Try to evaluate an expression to a constant numeric or string value at compile time.
+ * Supports: numeric literals, string literals, simple arithmetic (+, -, *, /),
+ * and const variable references.
+ * Returns the resolved value (number or string) or undefined if not resolvable.
+ */
+export declare function resolveConstantExpression(ctx: CodegenContext, expr: ts.Expression): number | string | undefined;
+/**
+ * Resolve the property name of an ObjectLiteralElementLike to a static string.
+ * Handles identifiers, string literals, and computed property names that can be
+ * evaluated at compile time (string literal expressions, const variables, enum members).
+ * Returns undefined if the name cannot be statically resolved.
+ */
+export declare function resolvePropertyNameText(ctx: CodegenContext, prop: ts.ObjectLiteralElementLike): string | undefined;
+/**
+ * Map a well-known Symbol property name (e.g. "iterator") to a reserved
+ * property key string "@@iterator" for use as struct field names.
+ */
+export declare function resolveWellKnownSymbol(name: string): string | undefined;
+/**
+ * Get the i32 constant for a well-known symbol, or undefined if not well-known.
+ */
+export declare function getWellKnownSymbolId(name: string): number | undefined;
+/**
+ * Ensure the __symbol_counter mutable global exists (lazy init).
+ * Starts at 100 so well-known symbol IDs (1-12) never collide.
+ */
+export declare function ensureSymbolCounter(ctx: CodegenContext): number;
+/**
+ * Compile a Symbol() call — returns a unique i32 by incrementing a global counter.
+ * The description argument (if any) is evaluated for side effects but discarded.
+ */
+export declare function compileSymbolCall(ctx: CodegenContext, fctx: FunctionContext, args: readonly ts.Expression[]): ValType;
+/**
+ * Try to evaluate a computed key expression to a static string at compile time.
+ * Supports:
+ * - String literals: ["x"]
+ * - Const variable references: [key] where const key = "x"
+ * - Enum member access: [MyEnum.Key]
+ */
+export declare function resolveComputedKeyExpression(ctx: CodegenContext, expr: ts.Expression): string | undefined;
+/**
+ * Resolve the property name of a getter/setter accessor to a static string.
+ * Handles identifiers, string literals, numeric literals, and computed property names.
+ */
+export declare function resolveAccessorPropName(ctx: CodegenContext, name: ts.PropertyName): string | undefined;
+/**
+ * Compile an empty object literal ({}) that has widened properties from
+ * later property assignments (e.g. `var obj = {}; obj.x = 42;`).
+ * Registers a struct type with the widened fields and emits struct.new
+ * with default values for each field.
+ */
+export declare function compileWidenedEmptyObject(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression, widenedProps: {
+    name: string;
+    type: ValType;
+}[]): ValType | null;
+export declare function compileObjectLiteralForStruct(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ObjectLiteralExpression, typeName: string): ValType | null;
+/**
+ * Compile a tuple literal [a, b, c] to a Wasm GC struct.new instruction.
+ * Each element is compiled to its corresponding field type.
+ */
+export declare function compileTupleLiteral(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ArrayLiteralExpression, tupleType: ts.Type): ValType | null;
+export declare function compileArrayLiteral(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ArrayLiteralExpression): ValType | null;
+/**
+ * Compile Array(n) or Array(a,b,c) function calls (non-new).
+ * Array(n) creates a sparse array of length n (all slots undefined/default).
+ * Array(a,b,c) creates [a, b, c].
+ * These have identical semantics to new Array(...).
+ */
+export declare function compileArrayConstructorCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): ValType | null;

package/dist/codegen/map-runtime.d.ts

@@ -0,0 +1,142 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * (#2162) `$Map` / `$MapEntry` field layout, exported so the for-of entries
+ * driver (statements/loops.ts) can walk the entries vector natively without
+ * re-deriving the constants. `entries` is the `$MapEntry[]` backing array;
+ * `entryCount` is the high-water mark (live + tombstoned); a `$MapEntry` stores
+ * `key`, `value`, and a `hash` whose top bit (`tombstoneBit`) flags deletion.
+ */
+export declare const MAP_LAYOUT: {
+    readonly M_ENTRIES: 1;
+    readonly M_ENTRYCOUNT: 2;
+    readonly M_LIVECOUNT: 3;
+    readonly F_KEY: 0;
+    readonly F_VALUE: 1;
+    readonly F_HASH: 3;
+    readonly TOMBSTONE_BIT: 1073741824;
+};
+/**
+ * Register the WasmGC struct/array types backing the native Map. Idempotent.
+ * Stores the type indices on `ctx`. Mirrors `ensureWrapperTypes` /
+ * `ensureNativeStringHelpers` type-registration.
+ */
+export declare function ensureMapRuntimeTypes(ctx: CodegenContext): void;
+/**
+ * Emit the full Map runtime (hash, equality, lookup, construction, methods,
+ * iterators). Idempotent. MUST run before any user body that references a Map
+ * helper, and after the native-string helpers so `__str_equals` is available
+ * (string-key equality reuses it).
+ */
+export declare function ensureMapHelpers(ctx: CodegenContext): void;
+/**
+ * (#1103a) Coerce a freshly-compiled Map key/value argument to `anyref` — the
+ * uniform slot type the runtime stores. Numbers arrive as `f64` and are boxed
+ * via `__box_number` (the contract `__same_value_zero` / `__hash_anyref`
+ * assume); native strings and other GC refs are already anyref subtypes;
+ * externrefs externalize via `any.convert_extern`.
+ */
+/**
+ * (#2162) Re-exported for the Set runtime, which reuses the Map backing store
+ * and needs the identical key/value → anyref boxing for its element arg.
+ */
+export declare function coerceSetArgToAnyref(ctx: CodegenContext, fctx: FunctionContext, t: ValType | null): void;
+/**
+ * (#2162) Re-exported for the WeakMap/WeakSet runtime, which reuses the Map
+ * backing store and needs the identical key/value → anyref boxing.
+ */
+export declare function coerceMapKeyToAnyref(ctx: CodegenContext, fctx: FunctionContext, t: ValType | null): void;
+/**
+ * (#2606 Bug A) Compile a `Set`/`Map` element/key/value argument to an anyref
+ * for the native collection helpers, handling `null`/`undefined` literals.
+ *
+ * Root cause: `compileExpression(<null/undefined literal>)` reports ValType
+ * `externref` but emits a **typed** `ref.null` instruction on the stack (a
+ * concrete bottom, not a real externref). `coerceArgToAnyref`'s `externref` arm
+ * then emits `any.convert_extern`, which fails validation — "any.convert_extern
+ * expected type externref, found ref.null of type (ref null N)" — so
+ * `s.add(null)` / `s.has(null)` / `s.has(undefined)` failed to compile
+ * standalone (#2606).
+ *
+ * Fix: for a null/undefined-literal argument, skip `compileExpression` and emit
+ * a canonical `ref.null NONE_HEAP` — the same `none`-bottom anyref-subtype the
+ * runtime already stores for absent/`undefined` entries (lines 657/912/919/1120)
+ * and for the absent-arg case above. A stored `none`-null is then `ref.eq`-equal
+ * to a queried `none`-null, so SameValueZero null/undefined equality works once
+ * the representation is uniform.
+ */
+export declare function compileCollectionElementArg(ctx: CodegenContext, fctx: FunctionContext, argExpr: ts.Expression | undefined): void;
+/**
+ * (#1103a) Intercept a `Map.prototype.*` method call in standalone /
+ * `nativeStrings` mode and route it to the WasmGC-native Map runtime
+ * (`ensureMapHelpers`). Mirrors the RegExp pre-externClass interception in
+ * `expressions/calls.ts`: returns the result `InnerResult` when handled, or
+ * `undefined` to let the generic extern/host path proceed.
+ *
+ * Slice 1 covers `set` / `get` / `has` / `delete` / `clear` for number and
+ * string keys/values. `forEach` / `for-of` and `new Map(iterable)` are slice 2
+ * (need the `$MapIter` drive + `__map_new_from_arr`).
+ *
+ * Receiver and arguments are compiled here (the caller has not pushed them).
+ */
+export declare function tryCompileNativeMapMethodCall(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression): InnerResult | undefined;
+/**
+ * (#1103a) Intercept the `Map.prototype.size` accessor in standalone /
+ * `nativeStrings` mode → `__map_size` (returns i32). Receiver is compiled
+ * here. Returns the result ValType when handled, else `undefined`.
+ */
+export declare function tryCompileNativeMapSizeGet(ctx: CodegenContext, fctx: FunctionContext, receiver: ts.Expression): InnerResult | undefined;
+/**
+ * (#2162) Intercept `Map.prototype.forEach` / `Set.prototype.forEach` in
+ * standalone / `nativeStrings` mode and drive the callback over the native
+ * `$Map` backing store. Spec 24.1.3.5 / 24.2.3.6: invoke
+ * `callbackfn(value, key, collection)` for every live entry in insertion order
+ * (a Set passes the value as both `value` and `key`). The `thisArg` 2nd
+ * argument is accepted but, like the array-method native callbacks, only honored
+ * when the callback closes over `this` itself — out of scope for this slice.
+ *
+ * Reuses the entries-vector walk from `__map_iter_next` (index 0..entryCount,
+ * skipping tombstones via `F_HASH & TOMBSTONE_BIT`) and the closure-call shape
+ * from `array-methods.ts` (push coerced args, `call_ref` the closure funcref).
+ * The callback must be a Wasm closure (arrow / function expr / named fn);
+ * otherwise we bail so the generic path can try.
+ *
+ * `isSet` selects the key passed to the callback: for a Set, value === key.
+ */
+export declare function tryCompileNativeCollectionForEach(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression, isSet: boolean): InnerResult | undefined;
+/**
+ * (#2162) Compile `map.keys()` / `map.values()` / `map.entries()` (and the Set
+ * equivalents) in standalone / `nativeStrings` mode by eagerly materializing a
+ * canonical externref `$Vec` of the requested projection — mirroring the array
+ * iterator pattern (`compileNativeArrayIterator`, array-methods.ts). The vec is
+ * returned as a `ref $Vec`, so the for-of vec-struct fast path
+ * (`compileForOfArrayTentative`) and array spread consume it directly with no
+ * `__iterator` round-trip.
+ *
+ * Projection per `kind`:
+ *   - "keys"    → each entry's KEY (for a Set, key === value)
+ *   - "values"  → each entry's VALUE (for a Set, value === key)
+ *   - "entries" → a 2-element `$ObjVec` `[key, value]` pair per entry, so a
+ *     consumer's `pair[0]`/`pair[1]` and `[k, v]` destructuring read back
+ *     through the native `__extern_get_idx`/`__extern_length` arm — exactly as
+ *     the array `.entries()` path builds its pairs.
+ *
+ * The result array is sized to `liveCount` (the exact non-tombstone count, what
+ * `size` returns), then filled by walking the entries vector with a separate
+ * write cursor, skipping tombstones.
+ *
+ * Returns the vec `ValType` when handled, or `undefined` to let the generic
+ * extern/host path proceed. The receiver (and no arguments) are compiled here.
+ */
+export declare function compileNativeCollectionIterator(ctx: CodegenContext, fctx: FunctionContext, propAccess: ts.PropertyAccessExpression, callExpr: ts.CallExpression, kind: "keys" | "values" | "entries", isSet: boolean): InnerResult | undefined;
+/**
+ * (#2162) Core of the collection-iterator materialization: given the *receiver*
+ * expression (compiled here), emit a canonical externref `$Vec` of the `kind`
+ * projection and return its `ValType`. Shared by the `keys/values/entries`
+ * method dispatch and the bare `for (… of map/set)` path (which passes the
+ * iterable expression directly). Returns `undefined` if the receiver does not
+ * lower to the native `$Map` struct.
+ */
+export declare function emitCollectionIteratorVec(ctx: CodegenContext, fctx: FunctionContext, receiver: ts.Expression, kind: "keys" | "values" | "entries", isSet: boolean): InnerResult | undefined;

package/dist/codegen/math-helpers.d.ts

@@ -0,0 +1,7 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Emit pure Wasm implementations for the requested Math methods.
+ * Methods are added as module functions (not imports) and registered
+ * in ctx.funcMap under "Math_<method>".
+ */
+export declare function emitInlineMathFunctions(ctx: CodegenContext, needed: Set<string>): void;

package/dist/codegen/member-get-dispatch.d.ts

@@ -0,0 +1,42 @@
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * Reserve (or fetch) the member-get dispatcher `__get_member_<name>(recv) ->
+ * externref` funcIdx with a placeholder body. The real body is built by
+ * {@link fillMemberGetDispatch} at finalize. Idempotent; records the property
+ * name in `ctx.memberGetDispatchNames`. Returns the reserved funcIdx, or
+ * `undefined` if the `__extern_get` fallback import can't be registered.
+ *
+ * ALL fill-body deps are registered NOW (reserve time) so the fill only READS
+ * funcMap (no funcIdx churn at finalize):
+ *   - `__extern_get` (the terminal host-read fallback),
+ *   - the property-name string constant (the fallback's key),
+ *   - `__box_number` (union import — a per-struct arm box-coerces an f64/i32
+ *     field result up to externref via `coercionInstrs`).
+ *
+ * (#2674-residual / #2043 late-import index-shift hardening) The
+ * `ensureLateImport`/`addUnionImportsViaRegistry` calls below register imports
+ * that shift the function index space. The READ call sites bake the returned
+ * `funcIdx` into a DETACHED instruction array (the `buildFallback` terminal) AND
+ * immediately follow it with a `coercionInstrs(…, fctx)` that may itself allocate
+ * locals and register more late imports — both of which assume a SETTLED index
+ * space. Unlike the WRITE side (which pushes straight into `fctx.body`, so the
+ * body-level batched flush reaches it), a detached array left across a dangling
+ * `pendingLateImportShift` is fragile: when another import-adding pass runs before
+ * the body's deferred flush (the failure mode that surfaced only when #2075 was
+ * batched with another import-adding PR in the merge_group — `local index out of
+ * range at __module_init`, the #2043 class), the staged indices desync. So when a
+ * caller passes its `fctx`, FLUSH the pending shift here (ensure→flush discipline,
+ * matching `buildVecFromExternref`/`emitUndefined`) so the dispatcher's imports
+ * settle before the caller emits anything further. No-op when there is no pending
+ * shift or the helpers were already registered (idempotent reserve).
+ */
+export declare function reserveMemberGetDispatch(ctx: CodegenContext, propName: string, fctx?: FunctionContext): number | undefined;
+/**
+ * Fill every reserved `__get_member_<name>` dispatcher body at FINALIZE, after
+ * every struct type (incl. late-registered fnctor structs) is known. READ-ONLY
+ * over funcMap. No-op when no read site reserved a dispatcher.
+ *
+ * Body local layout: param 0 = recv (externref), local 1 = `__any` (anyref, the
+ * converted receiver tested against each struct candidate).
+ */
+export declare function fillMemberGetDispatch(ctx: CodegenContext): void;

package/dist/codegen/member-set-dispatch.d.ts

@@ -0,0 +1,28 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Reserve (or fetch) the member-set dispatcher `__set_member_<name>(recv, val)`
+ * funcIdx with a placeholder body. The real body is built by
+ * {@link fillMemberSetDispatch} at finalize. Idempotent; records the property
+ * name in `ctx.memberSetDispatchNames`. Returns the reserved funcIdx.
+ *
+ * ALL of the fill body's dependencies are registered NOW (at reserve time) so
+ * the fill only READS funcMap — registering imports/globals at FINALIZE would
+ * shift baked call/global indices (the addUnionImports hazard the reserve-then-
+ * fill pattern exists to avoid):
+ *   - `__extern_set_strict` (the terminal sidecar/accessor-throw fallback),
+ *   - the property-name string constant (the fallback's key),
+ *   - `__box_number`/`__unbox_number` (union imports — the per-struct arms may
+ *     unbox the externref value into an f64/i32 field via `coercionInstrs`).
+ */
+export declare function reserveMemberSetDispatch(ctx: CodegenContext, propName: string, strict: boolean): number | undefined;
+/**
+ * Fill every reserved `__set_member_<name>` dispatcher body at FINALIZE, after
+ * every struct type (incl. late-registered fnctor structs) is known. READ-ONLY
+ * over funcMap (all deps registered at reserve time), so no funcIdx churn. Sets
+ * the placeholder body to the full `ref.test`/`struct.set` chain. No-op when no
+ * write site reserved a dispatcher.
+ *
+ * Body local layout: param 0 = recv (externref), param 1 = val (externref),
+ * local 2 = `__any` (anyref, the converted receiver tested against each struct).
+ */
+export declare function fillMemberSetDispatch(ctx: CodegenContext): void;