@loopdive/js2 0.57.0

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

@@ -0,0 +1,171 @@
+import { CodegenContext } from './context/types.js';
+export declare const FLAG_INTERNAL = 16;
+/**
+ * Reserved own-key under which a boxed primitive wrapper stores its internal
+ * `[[PrimitiveValue]]` slot (#1910/#1472 S2). Uses the spec internal-slot
+ * spelling so it cannot collide with an ordinary identifier-shaped key created
+ * by user code in any realistic program; the entry is additionally flagged
+ * FLAG_INTERNAL so even an explicit `o["[[PrimitiveValue]]"]` user write is
+ * distinguishable, and it is non-enumerable so enumeration never observes it.
+ */
+export declare const WRAPPER_PRIMITIVE_KEY = "[[PrimitiveValue]]";
+/**
+ * Type indices for the open-object runtime structs/arrays, allocated once per
+ * module by `ensureObjectRuntime`. Stored on the context so subsequent slices
+ * (keys/values/delete/for-in) can reference the same types.
+ */
+export interface ObjectRuntimeTypes {
+    propEntryTypeIdx: number;
+    propMapTypeIdx: number;
+    objectTypeIdx: number;
+    /** `$ObjVec` struct {len: i32, data: (ref (array (mut externref)))} — the
+     *  growable externref vector that backs standalone `Object.keys/values/entries`
+     *  enumeration results (#1472 Phase B Blocker B). */
+    objVecTypeIdx: number;
+    /** Backing `(array (mut externref))` for `$ObjVec.data`. */
+    objVecArrTypeIdx: number;
+    /** (#1100) `$ProxyTraps` struct — 4 funcref fields (get/set/has/apply) for the
+     *  standalone Proxy meta-object Phase 1. Null fields forward to the ordinary
+     *  [[Get]]/[[Set]]/[[Has]]/[[Call]] on the target. */
+    proxyTrapsTypeIdx: number;
+    /** (#1100) `$Proxy` struct — subtype of `$Object` carrying the proxy tag,
+     *  target, handler, traps, and revoked bit. A proxy IS-A object, so every
+     *  `ref.test $Object` still matches it. */
+    proxyTypeIdx: number;
+}
+/**
+ * Idempotently register the open-object runtime types + helper functions as
+ * defined Wasm functions in `ctx.funcMap` (under the host-import names the call
+ * sites already look up). Safe to call repeatedly; only the first call emits.
+ *
+ * MUST run after `ensureNativeStringHelpers` (it depends on `__str_flatten` /
+ * `__str_equals` and the `$NativeString` type indices) — we call it here to
+ * guarantee that. Because this path adds only DEFINED functions (no imports),
+ * the freshly-allocated func indices sit above every existing function and no
+ * index shift is required (same invariant as `addUnionImportsAsNativeFuncs`).
+ *
+ * That invariant only holds when NO late-import batch is pending: a deferred
+ * `ensureLateImport` shift (ctx.pendingLateImportShift) would later add its
+ * delta to every funcIdx >= its importsBefore — including the indices this
+ * function is about to bake with the post-batch `numImportFuncs` — leaving
+ * funcMap and every internal sibling call one regime too high while the
+ * function itself sits lower (#2039: `__obj_find` calling `__new_plain_object`
+ * instead of `__obj_hash`, 146 invalid-Wasm test262 binaries). So we end any
+ * pending batch first; registration then happens in a clean, final regime.
+ */
+export declare function ensureObjectRuntime(ctx: CodegenContext): ObjectRuntimeTypes;
+/**
+ * (#1100) Fill the reserved Proxy trap-invoke driver bodies at FINALIZE, AFTER
+ * `emitClosureMethodCallExportN(2..4)` have registered `__call_fn_method_2/3/4`
+ * in `funcMap`. Each driver is a thin wrapper around the closure-call bridge
+ * that threads the handler as `this` and forwards the spec trap args:
+ *
+ *   __proxy_call_get(handler, trap, target, key, receiver)
+ *       = __call_fn_method_3(handler, trap, target, key, receiver)
+ *   __proxy_call_set(handler, trap, target, key, value, receiver)
+ *       = __call_fn_method_4(handler, trap, target, key, value, receiver)
+ *   __proxy_call_has(handler, trap, target, key)
+ *       = __call_fn_method_2(handler, trap, target, key)
+ *
+ * No-op when the proxy runtime was never reserved (`ctx.proxyDispatchReserved`).
+ * When a driver WAS reserved but the matching dispatcher was never emitted (no
+ * closure of that arity exists — so no real trap of that arity could have been
+ * installed either), the body is filled with `ref.null.extern` so the module
+ * still verifies — mirrors `fillAccessorDrivers` / `fillApplyClosure`.
+ */
+export declare function fillProxyDispatch(ctx: CodegenContext): void;
+/**
+ * #1472 Phase B Slice 3 — the native `$ObjVec` builder funcIdxs that the
+ * `Object.assign(target, ...sources)` / object-spread call sites use to build
+ * the variadic `...sources` list under `--target standalone`. In JS-host mode
+ * those sites build a real JS array via the `__js_array_new` / `__js_array_push`
+ * host imports and hand it to `__object_assign`; standalone has no JS array, so
+ * they build a `$ObjVec` (which the native `__object_assign` iterates via
+ * `ref.test $ObjVec`) instead. Returns `{ newIdx, pushIdx }`, registering the
+ * object runtime on first call. Signatures match the host imports exactly —
+ * `__objvec_new : () -> externref`, `__objvec_push : (externref, externref) ->
+ * void` — so the only call-site change is *which funcIdx* the existing builder
+ * code calls.
+ */
+export declare function ensureObjVecBuilders(ctx: CodegenContext): {
+    newIdx: number;
+    pushIdx: number;
+};
+/**
+ * (#1888 Slice 1) Reserve the `__apply_closure(externref fn, externref recv,
+ * externref args) -> externref` arity-bridge funcIdx with a placeholder
+ * `unreachable` body, registered in `funcMap`. The real body (an arity switch
+ * on `__extern_length(args)` dispatching to `__call_fn_method_0..4`) is filled
+ * by `fillApplyClosure` at FINALIZE, because the `__call_fn_method_N` exports
+ * it calls are only emitted there (after `closureInfoByTypeIdx` is complete).
+ * Mirrors the `reserveProtoIteratorDriver`/`fillProtoIteratorDriver` pattern
+ * (#1719). Idempotent. Sets `ctx.applyClosureReserved`.
+ */
+export declare function reserveApplyClosure(ctx: CodegenContext): number;
+/**
+ * (#1888 Slice 1) Fill the reserved `__apply_closure` bridge body at FINALIZE,
+ * AFTER `emitClosureMethodCallExportN(0..4)` have registered
+ * `__call_fn_method_0..4` in `funcMap`. The bridge reads the dynamic arg count
+ * from `__extern_length(args)` and dispatches to the matching this-threaded
+ * closure dispatcher:
+ *
+ *   n = i32(__extern_length(args))
+ *   if n==0: __call_fn_method_0(recv, fn)
+ *   if n==1: __call_fn_method_1(recv, fn, idx0)
+ *   ... up to 4 ...
+ *   else (n>4): return undefined (sentinel)
+ *
+ * S1 SCOPE — NO THROWS. This bridge returns the undefined sentinel
+ * (`ref.null.extern`) for the not-a-function and arity-overflow cases rather
+ * than raising a `TypeError`. Reason: emitting a spec-correct throw here would
+ * pull `__new_TypeError` + the exn tag + a string constant into the object
+ * runtime, and those late registrations land AFTER the string helpers have
+ * already baked `call` targets at finalize — shifting func indices and
+ * corrupting the module ("__str_flatten expected (ref null 5) found i32"). That
+ * is the #1839/#117/#1886 late-registration-index-shift class. Carving S1
+ * without throws keeps the bridge dependency-free of late error machinery, so
+ * the module verifies cleanly. The spec-correct `TypeError` throws (ES §7.3.14
+ * step 2 "is not a function", and arity-overflow) plus the index-shift fix are
+ * the S2 fast-follow. Each `__call_fn_method_N` arm is only emitted when that
+ * export was registered (no closure of arity ≤ N ⇒ no dispatcher ⇒ that arm
+ * returns the undefined sentinel). No-op when `__apply_closure` was never
+ * reserved.
+ */
+export declare function fillApplyClosure(ctx: CodegenContext): void;
+/**
+ * (#1904) Fill the standalone native `__extern_is_array` predicate after all
+ * user functions and late runtime helpers have registered their WasmGC carrier
+ * types. Implements the non-Proxy subset of ES §7.2.2 IsArray that can exist in
+ * standalone: primitives/non-array objects return false, and compiler-emitted
+ * array carriers (`__vec_*`, template vectors, `$ObjVec`) return true.
+ */
+export declare function fillExternIsArray(ctx: CodegenContext): void;
+/**
+ * (#2190) Fill `__extern_get_idx`'s typed-`__vec_<elemKind>` indexing arms after
+ * every module-local array carrier is registered. Sibling of the #2189
+ * `.length`-through-the-boundary fix: a real array literal lowers to a
+ * `__vec_<elemKind>` struct, and a NUMERIC index on it through the externref
+ * boundary (`(arr as any)[i]`) routes here. Without these arms, only `$ObjVec`
+ * (enumeration results) and array-like `$Object` are recognised, so a boxed
+ * `__vec_f64`/`__vec_<str>` falls through to null (number→0, ref→null).
+ *
+ * Unlike `.length` (one i32 at field 0, readable uniformly via the `$__vec_base`
+ * supertype), element reads are element-type-polymorphic: each carrier has a
+ * different `data` array element type and the loaded element must be boxed to
+ * externref per kind. So we emit one `ref.test`/`ref.cast` arm per carrier with
+ * its own bounds check + per-kind boxing (`boxVecElementToExternref`).
+ *
+ * Standalone only (gated by `ctx.externGetIdxReserved`, set in standalone). Edits
+ * the body in place — no funcIdx churn, so cached call targets stay valid.
+ */
+export declare function fillExternGetIdxVecArms(ctx: CodegenContext): void;
+/**
+ * Names of the object-runtime host imports that `ensureObjectRuntime` provides
+ * Wasm-native implementations for. `ensureLateImport` routes these here under
+ * `ctx.standalone` (mirrors `UNION_NATIVE_HELPER_NAMES` for the #1471 boxing
+ * helpers) so existing call sites resolve to the native func with no per-site
+ * change. Internal helpers (`__obj_hash`, `__obj_find`, `__obj_insert`,
+ * `__obj_grow`) are NOT in this set — they are never requested via
+ * `ensureLateImport`.
+ */
+export declare const OBJECT_RUNTIME_HELPER_NAMES: ReadonlySet<string>;

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

@@ -0,0 +1,10 @@
+import { CodegenContext } from './context/types.js';
+/**
+ * Emit native `parseInt` / `parseFloat` functions and register them in
+ * `ctx.funcMap` (and a dedicated set on ctx for idempotency). Must run before
+ * any function bodies that `call ctx.funcMap.get("parseInt")` are compiled, and
+ * after `ensureNativeStringHelpers` (which it calls) so `__str_flatten` exists.
+ *
+ * @param which Set of names to emit — subset of {"parseInt","parseFloat"}.
+ */
+export declare function emitNativeParseNumber(ctx: CodegenContext, which: Set<string>): void;

package/dist/codegen/peephole.d.ts

@@ -0,0 +1,6 @@
+import { WasmModule } from '../ir/types.js';
+/**
+ * Run peephole optimizations on all function bodies in a WasmModule.
+ * Returns the total number of instructions eliminated.
+ */
+export declare function peepholeOptimize(mod: WasmModule): number;

package/dist/codegen/property-access.d.ts

@@ -0,0 +1,294 @@
+import { ts } from '../ts-api.js';
+import { Instr, ValType } from '../ir/types.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * #2020: resolve an inherited static-property global by walking the class
+ * parent chain (classParentMap), retrying `<Ancestor>_<prop>` at each level.
+ * Static fields, like static methods, are inherited: `class B extends A {}`
+ * sees `A`'s static fields through `B`. Returns the owning ancestor's global
+ * index, or undefined when no ancestor declares the property. Callers run the
+ * own-class lookup first, so own statics correctly shadow inherited ones.
+ */
+export declare function resolveInheritedStaticProp(ctx: CodegenContext, className: string, propName: string): number | undefined;
+/**
+ * (#2201) ES §13.15.2 NamedEvaluation for the logical-assignment operators
+ * (`&&=`, `||=`, `??=`): when the LHS is a bare IdentifierReference and the RHS
+ * is an *anonymous* function/arrow/class definition, the resulting function
+ * inherits the LHS identifier as its `.name`.
+ *
+ * This compiler resolves `.name` statically from a binding's initializer, which
+ * misses the logical-assignment form (`var value = 1; value &&= function(){}`)
+ * because the variable's initializer is not the function. Here we scan the
+ * declaration's source for a logical-assignment `<id> &&=/||=/??= <fn>` targeting
+ * the same symbol and apply NamedEvaluation. A *named* function/class RHS keeps
+ * its own name (the LHS identifier is ignored, per spec).
+ *
+ * Returns the inferred `.name` string, or undefined when no qualifying
+ * logical-assignment is found.
+ */
+export declare function resolveLogicalAssignmentName(ctx: CodegenContext, id: ts.Identifier, sym: ts.Symbol): string | undefined;
+/**
+ * (#2201) True when `node` is a `<id>.name` read whose receiver `<id>` is the
+ * target of a logical-assignment NamedEvaluation (`id &&=/||=/??= <fn>`). Such a
+ * read lowers (via the property-access `.name` static resolver above) to a
+ * native-string ref, but the receiver's *TS* type is `number`/`any`, so an
+ * equality like `id.name === "x"` would otherwise fall through to `ref.eq`
+ * (struct identity → always false). Used by the binary-op equality dispatch to
+ * route it to content-based string equality — mirrors the catch-bound Error
+ * `.message`/`.name`/`.stack` handling (#2192).
+ */
+export declare function isLogicalAssignNamedEvalNameRead(ctx: CodegenContext, node: ts.Expression): boolean;
+/**
+ * Consume an externref value and push the Array.isArray boolean result.
+ *
+ * Spec basis: ECMA-262 §23.1.2.3 delegates to IsArray (§7.2.2).
+ *
+ * Two regimes (#2047 — unified):
+ *
+ * - **`--target standalone`**: route through the in-module native
+ *   `__extern_is_array` helper. That helper is reserved with the object runtime
+ *   and *filled at finalize* (`fillExternIsArray`) with the COMPLETE, filtered
+ *   array-carrier list, so a value-read of `Array.isArray` taken before a later
+ *   array type (e.g. `boolean[]` → `__vec_i32`) is registered no longer bakes an
+ *   incomplete `ref.test` chain. This both fixes the first-emission snapshot bug
+ *   (`const f = Array.isArray; f(boolean[])` ⇒ `false`) and excludes the
+ *   exclusively-non-array byte carriers (`i32_byte` ArrayBuffer/DataView,
+ *   `i8_byte` Uint8Array) per §7.2.2.
+ * - **Host / WASI**: keep the inline `ref.test` chain over every registered vec
+ *   type (it detects compiled WasmGC array values materialised into an externref
+ *   slot — #1678), ORed in host mode with the real JS `Array.isArray` host
+ *   predicate for foreign JS arrays (#1328). Host output is unchanged.
+ */
+export declare function emitArrayIsArrayExternrefPredicate(ctx: CodegenContext, fctx: FunctionContext): void;
+/**
+ * Resolve the struct name for a TypeScript type by consulting structMap,
+ * classExprNameMap, and anonTypeMap.
+ */
+export declare function resolveStructName(ctx: CodegenContext, tsType: ts.Type): string | undefined;
+/**
+ * Resolve a struct name for a property access/assignment target expression,
+ * with fallbacks for widened variables and `this` in function constructors.
+ */
+export declare function resolveStructNameForExpr(ctx: CodegenContext, fctx: FunctionContext, expression: ts.Expression): string | undefined;
+/**
+ * (#1239) Same role as `resolveStructName(ctx, type)`, but consults
+ * `ctx.externrefAccessorVars` first so an Identifier holding an
+ * accessor-bearing object literal force-bails to the externref path.
+ *
+ * Use this at every site that previously called `resolveStructName(ctx,
+ * <type-of-some-expression>)` when the underlying expression is
+ * available, so the externref-tag override propagates uniformly.
+ *
+ * Sites without an expression (synthesized type arguments etc.) keep
+ * calling `resolveStructName` directly — they can't involve an
+ * accessor-tagged variable by construction.
+ */
+export declare function resolveEffectiveStructName(ctx: CodegenContext, expression: ts.Expression | undefined, fallbackType: ts.Type): string | undefined;
+/**
+ * Check if a type looks like an IteratorResult (has .value and .done properties)
+ * even if the type checker doesn't resolve it as IteratorResult directly.
+ * This handles cases where the type is a union (IteratorYieldResult | IteratorReturnResult).
+ */
+export declare function isGeneratorIteratorResultLike(ctx: CodegenContext, type: ts.Type, propName: string): boolean;
+/**
+ * Get the value type T from IteratorResult<T>.
+ * Returns the ValType for the value, or null if not determinable.
+ */
+export declare function getIteratorResultValueType(ctx: CodegenContext, type: ts.Type): ValType | null;
+/**
+ * Returns true when the expression is guaranteed to produce a non-null value,
+ * allowing the caller to skip runtime null guards.
+ *
+ * Provably non-null cases:
+ *  - `new Foo()`          — constructor always returns an object
+ *  - `{ x: 1 }`          — object literals are never null
+ *  - `[1, 2]`            — array literals are never null
+ *  - `"str"` / template  — string literals are never null
+ *  - Parenthesized wrapper around any of the above
+ */
+export declare function isProvablyNonNull(expr: ts.Expression, checker?: ts.TypeChecker): boolean;
+export declare function typeErrorThrowInstrs(ctx: CodegenContext, node?: ts.Node): Instr[];
+/**
+ * Emit a null check on the ref currently on the stack. If null, throws
+ * TypeError via the exception tag. If non-null, the ref remains on the stack.
+ * The `refType` should be the nullable ref type of the value on the stack.
+ *
+ * Stack: [ref_null T] -> [ref_null T]  (non-null at runtime after this point)
+ */
+export declare function emitNullCheckThrow(ctx: CodegenContext, fctx: FunctionContext, refType: ValType, node?: ts.Node): void;
+/**
+ * (#2655) Symmetric WRITE counterpart to the read-side multi-struct dispatch
+ * (`findAlternateStructsForField` + `struct.get` chain at the `__extern_get`
+ * fallback). The member-READ path resolves `any`/`externref` receivers that are
+ * actually typed WasmGC structs via `struct.get <slot>`; the member-WRITE path
+ * historically went straight to `__extern_set`, which `_safeSet` routes to a
+ * JS-side SIDECAR map — it CANNOT write the WasmGC struct slot. Result: reads
+ * see the slot, writes update the sidecar, and the two diverge (acorn's
+ * `this.pos += 1` loop never advances → infinite loop).
+ *
+ * This emits, for each struct candidate that has a field named `propName`:
+ *   local.get <recvAnyLocal>
+ *   ref.test <structTypeIdx>
+ *   (if (then  local.get recvAny; ref.cast struct; local.get <valExtLocal>;
+ *              <coerce externref -> fieldType>; struct.set struct <slot> )
+ *       (else  <next candidate, or the externSetFallback> ))
+ *
+ * `recvAnyLocal` must hold the receiver as `anyref` (caller does
+ * `local.get objExt; any.convert_extern; local.set recvAny`). `valExtLocal`
+ * holds the value as `externref` (boxed). `externSetFallback` is the terminal
+ * else-arm (the existing `__extern_set`/`__extern_set_strict` sequence) — still
+ * required for genuine host externrefs and dynamic-only (sidecar) properties.
+ *
+ * Returns `true` if at least one struct.set arm was emitted (caller must NOT
+ * also emit its own `__extern_set` — it's already the else-arm here), or `false`
+ * when there are no struct candidates (caller emits its `__extern_set` as
+ * before).
+ */
+export declare function emitAlternateStructSetDispatch(ctx: CodegenContext, fctx: FunctionContext, recvExtLocal: number, valExtLocal: number, propName: string, strict: boolean): boolean;
+/**
+ * Find all struct types (other than excludeTypeIdx) that have a field named
+ * propName.  Returns an array of {structTypeIdx, fieldIdx, fieldType} for
+ * each matching struct type.  Used for multi-struct dispatch when the primary
+ * ref.test fails (the object may be a valid GC struct of a different type).
+ * When excludeTypeIdx is -1, no type is excluded (useful for the externref path
+ * where there is no primary struct type).
+ */
+export declare function findAlternateStructsForField(ctx: CodegenContext, propName: string, excludeTypeIdx: number): {
+    structTypeIdx: number;
+    fieldIdx: number;
+    fieldType: ValType;
+    mutable: boolean;
+}[];
+export declare function emitNullGuardedStructGet(ctx: CodegenContext, fctx: FunctionContext, objType: ValType, fieldType: ValType, typeIdx: number, fieldIdx: number, propName?: string, throwOnNull?: boolean): void;
+export declare function emitExternrefToStructGet(ctx: CodegenContext, fctx: FunctionContext, fieldType: ValType, structTypeIdx: number, fieldIdx: number, propName?: string, throwOnNull?: boolean): void;
+export declare function compileOptionalPropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression): ValType | null;
+/** Helper: compile extern property get when receiver is already on stack */
+export declare function compileExternPropertyGetFromStack(ctx: CodegenContext, fctx: FunctionContext, objType: ts.Type, propName: string): void;
+/**
+ * (#2192 follow-up) Recognize a receiver expression that is itself a caught-Error
+ * string-field read — i.e. `<catchBinding>.message` / `.name` / `.stack`. In
+ * standalone mode the #2077/#2192 fast path lowers that read to a `$Error_struct`
+ * `struct.get` coerced to a native-string ref (`$AnyString`), so at the VALUE
+ * level the result IS a string. But the receiver's static TS type is `any` (the
+ * catch binding is `any`), so the `.length` / string-method dispatch sites —
+ * which gate on `isStringType(<static type>)` — never fire, and
+ * `e.message.length` / `e.message.charCodeAt(0)` fall through to the host
+ * `__extern_get` path (null standalone → 0). This predicate lets those consumer
+ * sites treat such a receiver as string-typed and route through the
+ * native-string path.
+ *
+ * Scope: standalone/WASI only (the fast path that produces a string ref is
+ * standalone-gated), `message`/`name`/`stack` only (the fields the read fast path
+ * handles), and only when the inner receiver is a catch binding (so a plain
+ * `obj.message` on a real object is unaffected — it keeps its own typed path).
+ * `.cause` is intentionally NOT covered: it is not a `$Error_struct` field yet
+ * (deferred follow-up).
+ */
+export declare function receiverIsCaughtErrorStringRead(ctx: CodegenContext, recv: ts.Expression): boolean;
+/**
+ * (#2187) Recognize a receiver IDENTIFIER whose TS static type is `any`/`unknown`
+ * but whose compiled local/param **ValType is a native-string ref**
+ * (`$AnyString` / `$NativeString`). This is the general "TS type vs local
+ * ValType disagreement" case behind the #2072 value-rep family: e.g. a for-of
+ * loop var bound from a string-yielding generator (`for (const v of g())`)
+ * infers `any` (no lib types in standalone) yet is compiled to a `(ref null
+ * $AnyString)` local. Without this, `v.length` / `v.charCodeAt(0)` gate on
+ * `isStringType(<static type>)` → false → the read falls to the generic
+ * externref/`__extern_get` path and returns 0.
+ *
+ * Strictly gated: standalone/WASI only (where native string refs exist), only a
+ * bare identifier (so a `.foo` property read or a real object keeps its own
+ * typed path), only when the TS type is `any`/`unknown` (a concrete non-string
+ * type is unaffected), and only when the resolved local ValType is exactly the
+ * native string ref type. Returns false for everything else — byte-identical for
+ * the common case.
+ */
+export declare function receiverIsNativeStringValType(ctx: CodegenContext, fctx: FunctionContext, recv: ts.Expression): boolean;
+/**
+ * (#2576, extends #2187) Generalisation of {@link receiverIsNativeStringValType}
+ * (which only catches a bare identifier whose *compiled local ValType* is a
+ * native string ref) to *any* `any`/`unknown`-typed receiver whose *runtime*
+ * value may be a native `$AnyString` even though no local ValType says so —
+ * object property values (`o.v`), generator yield reads, catch bindings, indexed
+ * element reads (`Object.values(o)[0]`), nested reads (`o.a.b`). These compile to
+ * an opaque `externref`, so the value can only be recognised at runtime: callers
+ * MUST emit a `ref.test $AnyString` guard (see
+ * {@link emitGuardedNativeStringLength} and `compileGuardedNativeStringMethodCall`)
+ * and keep the prior behaviour in the else arm for non-string values.
+ *
+ * Narrow scope: `any`/`unknown` only (NOT `object`/`{}`, NOT unions containing
+ * `string`), native-string mode only (host/gc mode's generic `__extern_get`
+ * already returns the correct length from the real JS value).
+ */
+export declare function receiverMayBeNativeStringAtRuntime(ctx: CodegenContext, recv: ts.Expression): boolean;
+/**
+ * (#2731) Symmetric mirror of `tryEmitDeleteAwareDynamicGet` for the WRITE side.
+ *
+ * In a module that contains a member-`delete`, `ctx.moduleUsesDelete` routes
+ * `any`/`unknown`-receiver property READS through the tombstone-aware host
+ * `__extern_get` (above). The corresponding WRITE had no symmetric gate, so
+ * `o.x = 9` still took the native `struct.set` fast-path
+ * (`emitAlternateStructSetDispatch`), which **bypasses `_safeSet`** — the host
+ * function where the delete-tombstone (`_wasmStructDeletedKeys`) is cleared on
+ * re-assignment (`runtime.ts`). Result: `delete o.x; o.x = 9` left the tombstone
+ * set, so every tombstone-consulting reader (`__extern_get`, `__for_in_has`,
+ * `_wasmStructHasOwn`, `__object_keys`) suppressed the re-added key
+ * (`o.x === undefined`, `"x" in o === false`, for-in dropped `x`).
+ *
+ * This reroutes the `any`-receiver write through the strict host setter
+ * `__extern_set_strict` → `_safeSet`, which clears the tombstone, writes the
+ * sidecar, AND mirrors the native field via `__sset_<key>` — so read/write stay
+ * symmetric. Returns the assignment-result type when handled, else `undefined`
+ * (caller falls through to the native struct-set dispatch). Gated identically to
+ * the read side: `moduleUsesDelete && !standalone`, `any`/`unknown` receiver,
+ * non-reserved-accessor, non-callable property. Delete-free modules are
+ * untouched (`moduleUsesDelete` false → byte-identical).
+ */
+export declare function tryEmitDeleteAwareDynamicSet(ctx: CodegenContext, fctx: FunctionContext, target: ts.PropertyAccessExpression, value: ts.Expression, objType: ts.Type, propName: string): ValType | undefined;
+export declare function compilePropertyAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.PropertyAccessExpression): ValType | null;
+/**
+ * Emit a bounds-checked array.get.  Stack must contain [arrayref, i32 index].
+ * If the index is out of bounds (< 0 or >= array.len), a default value for the
+ * element type is produced instead of trapping.
+ */
+export declare function emitBoundsGuardedArraySet(fctx: FunctionContext, vecLocal: number, vecTypeIdx: number, idxLocal: number, valLocal: number, arrTypeIdx: number): void;
+/**
+ * Check if an element access expression matches a safe bounds-check-eliminated
+ * pattern from a for-loop (e.g., arr[i] inside `for (...; i < arr.length; ...)`).
+ */
+export declare function isSafeBoundsEliminated(fctx: FunctionContext, expr: ts.ElementAccessExpression): boolean;
+/**
+ * (#1742) Read-site guard-convert for a `this`-receiver that lowered to an
+ * externref but, at runtime, may carry a compiled WasmGC value (a `$vec` array
+ * or a named struct).
+ *
+ * When a closure body reads `this[i]` / `this.length` / `this.member` and `this`
+ * resolves to the `__current_this` module global (host-dispatched via
+ * `__call_fn_method_N`, #1636-S1), the resolved value is a literal **externref**.
+ * The realistic override `Array.prototype[Symbol.iterator] = function*(){…this[0]…}`
+ * has no `this:` annotation, so TS infers `this: any` → externref; a static-type
+ * gate NEVER fires (CPR_DEBUG-confirmed). The discriminator MUST therefore be a
+ * **runtime `ref.test`**, not the static type.
+ *
+ * Emits `any.convert_extern` then, for each candidate `targetTypeIdx`, a
+ * `ref.test`-guarded branch: on the FIRST hit the value is `ref.cast` to that
+ * concrete ref and `thenEmit(concreteType)` runs the vec/struct read; if NONE
+ * match the value is a genuine host externref and `elseEmit()` runs the host read
+ * path. Both arms must leave a single value of `resultType` (read-site-guard
+ * steer, NOT resolve-at-source — a real host `this` passes through unchanged).
+ * Generic over receiver shape — consumed by #1719 (vec) and #1629 (struct getters).
+ *
+ * Stack: [externref] -> [resultType].
+ */
+export declare function emitThisReceiverGuardConvert(ctx: CodegenContext, fctx: FunctionContext, targetTypeIdxs: number[], resultType: ValType, thenEmit: (concreteType: ValType) => void, elseEmit: () => void): void;
+/**
+ * Optional element access `a?.[i]` (#2050). On a nullish base the index
+ * expression — and any side effects in it — must NOT evaluate, and the result
+ * is undefined-equivalent (§13.3.9 Optional Chains). Sibling of
+ * compileOptionalPropertyAccess: tee the base into a local, branch on
+ * `ref.is_null`, and emit the index + read only in the non-null arm.
+ */
+export declare function compileOptionalElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+export declare function compileElementAccess(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression): ValType | null;
+/** Inner element access logic — assumes objType is on the stack and non-null */
+export declare function compileElementAccessBody(ctx: CodegenContext, fctx: FunctionContext, expr: ts.ElementAccessExpression, objType: ValType): ValType | null;

package/dist/codegen/raw-wasi-api.d.ts

@@ -0,0 +1,13 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+import { InnerResult } from './shared.js';
+/**
+ * Recognize + lower a call to a raw `wasi_snapshot_preview1` binding —
+ * `fd_read`/`fd_write` (→ a direct WASI import call) or one of the inline
+ * linear-memory accessors `store32`/`load32`/`store8`/`load8` (→ a single memory
+ * instruction). Returns the result, or `undefined` when this isn't a raw-WASI
+ * call we handle (the generic compiler then proceeds). Byte-neutral for any
+ * program that doesn't import the raw module — `ctx.wasiRawImports` is empty, so
+ * the early returns fire immediately.
+ */
+export declare function tryCompileRawWasiCall(ctx: CodegenContext, fctx: FunctionContext, expr: ts.CallExpression): InnerResult | undefined;

package/dist/codegen/regex/bytecode.d.ts

@@ -0,0 +1,140 @@
+/**
+ * #1539 Phase 2a — Regex bytecode opcode definitions.
+ *
+ * The standalone (pure-WasmGC) RegExp engine compiles a pattern to a flat
+ * `number[]` program at compile time (TypeScript), then interprets it at run
+ * time with a single hand-authored Wasm backtracking VM (`__regex_run`). The
+ * program is a Pike/Thompson-style instruction stream with explicit
+ * backtracking ops; see `src/codegen/regex/compile.ts` for the emitter and
+ * `src/codegen/native-regex.ts` for the VM.
+ *
+ * Each instruction is a fixed-width record of 3 i32 slots: `[op, a, b]`. A
+ * flat layout keeps the Wasm interpreter trivial (program-counter steps by 3)
+ * and lets the whole program live in one WasmGC `array i32`.
+ */
+/** Instruction opcodes. Values are stable — they are baked into the emitted
+ *  Wasm VM dispatch (`__regex_run`). Do not renumber without updating both. */
+export declare enum ReOp {
+    /** `[CHAR, codeUnit, 0]` — match one specific UTF-16 code unit. */
+    CHAR = 0,
+    /** `[ANY, dotAll, 0]` — match any code unit; when `dotAll`=0, not `\n`/`\r`/U+2028/U+2029. */
+    ANY = 1,
+    /** `[CLASS, classIdx, negated]` — match against the class table entry. */
+    CLASS = 2,
+    /** `[SPLIT, x, y]` — try pc=x first, on backtrack try pc=y. */
+    SPLIT = 3,
+    /** `[JMP, x, 0]` — unconditional jump to pc=x. */
+    JMP = 4,
+    /** `[SAVE, slot, 0]` — record current input position into capture slot. */
+    SAVE = 5,
+    /** `[MATCH, 0, 0]` — accept. */
+    MATCH = 6,
+    /** `[BOL, 0, 0]` — assert beginning-of-line (`^`). multiline handled in 2c. */
+    BOL = 7,
+    /** `[EOL, 0, 0]` — assert end-of-line (`$`). multiline handled in 2c. */
+    EOL = 8,
+    /** `[CHARI, foldedCodeUnit, 0]` — match one code unit, ASCII-case-insensitive. */
+    CHARI = 9,
+    /** `[WBOUND, negated, 0]` — assert a word boundary (`\b`; `\B` when
+     *  `negated`=1). Word characters are `[0-9A-Za-z_]` (§22.2.2.6 IsWordChar,
+     *  ASCII — Unicode case folding lands with the `u` flag in 2d). #1912. */
+    WBOUND = 10,
+    /** `[BACKREF, groupIdx, caseInsensitive]` — match the text captured by group
+     *  `groupIdx` (§22.2.2.9 BackreferenceMatcher). An unset group matches the
+     *  empty string. `caseInsensitive`=1 compares ASCII-folded units. #1912. */
+    BACKREF = 11,
+    /** `[LOOKAROUND, subPc, flags]` — zero-width assertion (§22.2.2.4 Assertion
+     *  `(?=) (?!) (?<=) (?<!)`). Runs the sub-program starting at instruction
+     *  `subPc` as a fresh anchored attempt at the current position via a
+     *  recursive `__regex_run` call (atomic — no backtrack entries leak out).
+     *  `flags` bit 0 = negated, bit 1 = lookbehind (sub-program is compiled
+     *  REVERSED and executed with direction -1). Captures written by a
+     *  successful positive lookaround persist; everything else restores the
+     *  pre-assertion capture state. #1911. */
+    LOOKAROUND = 12,
+    /** `[PROGRESS, slot, 0]` — empty-iteration guard for nullable quantifiers
+     *  (§22.2.2.3.1 RepeatMatcher: a min=0 iteration that consumes nothing
+     *  fails, ending the loop). `slot` is a scratch capture slot into which the
+     *  loop entry recorded `sp` via a preceding SAVE; if the current `sp` equals
+     *  that recorded value the body matched empty, so this op FAILS the
+     *  iteration (backtracking to the quantifier's exit arm). Only emitted for
+     *  star/plus whose body can match the empty string. #1959. */
+    PROGRESS = 13,
+    /** `[CLEAR, loSlot, hiSlot]` — reset capture slots `loSlot..hiSlot`
+     *  (inclusive) to -1. §22.2.2.3.1 RepeatMatcher clears the quantified
+     *  subtree's capture set on each repetition entry, so only the final
+     *  iteration's participation is observable. Emitted at the head of every
+     *  star/plus/repeat body that contains capture groups; the slot range is the
+     *  group span `[2*lo, 2*hi+1]`. Backtrack-aware via the usual caps snapshot
+     *  (CLEAR mutates `caps`, which SPLIT snapshots). #1960. */
+    CLEAR = 14
+}
+/** Slots per instruction in the flat program array. */
+export declare const INSTR_WIDTH = 3;
+/**
+ * A character-class entry, compiled to a flat run-length table consumed by the
+ * VM. Ranges are inclusive `[lo, hi]` UTF-16 code-unit pairs. A single char is
+ * `[c, c]`. The VM walks the table for a CLASS op.
+ *
+ * The class table is emitted as a separate flat `number[]`:
+ *   [ classCount,
+ *     class0_rangeCount, class0_lo0, class0_hi0, class0_lo1, class0_hi1, ...,
+ *     class1_rangeCount, ... ]
+ * and `ReOp.CLASS`'s `a` operand indexes into a `classOffsets` array the
+ * compiler returns so the VM can find a class's run by offset.
+ */
+export interface CharClass {
+    /** Inclusive code-unit ranges. */
+    ranges: Array<[number, number]>;
+    /** When true the class is negated (`[^...]`). */
+    negated: boolean;
+}
+/** A fully compiled regex program ready to embed in a `$NativeRegExp`. */
+export interface CompiledRegex {
+    /** Flat instruction stream: `INSTR_WIDTH` ints per instruction. */
+    prog: number[];
+    /**
+     * Flat class table. Layout per class: `[rangeCount, lo0, hi0, lo1, hi1, …]`.
+     * `ReOp.CLASS` operand `a` is the *start offset* into this table (not an
+     * index), and `b` is the negated flag. Empty when no classes are used.
+     */
+    classTable: number[];
+    /** Number of capture groups including group 0 (the whole match). */
+    nGroups: number;
+    /** Extra scratch slots appended after the `2*nGroups` capture slots, one per
+     *  nullable star/plus, used by `ReOp.PROGRESS` to detect empty iterations
+     *  (#1959). The VM allocates `2*nGroups + nScratch` slots; scratch slots are
+     *  never reported as captures. */
+    nScratch: number;
+    /** Flags bitfield: g=1 i=2 m=4 s=8 u=16 y=32 d=64 v=128. */
+    flags: number;
+    /**
+     * Named capture groups: `name → 1-based capture index` (#2588). Empty when
+     * the pattern has no `(?<name>…)` groups. The named-group set is statically
+     * known at compile time, so the standalone backend materialises the `groups`
+     * result object and resolves `$<name>` substitution from this map (no runtime
+     * name→index machinery needed).
+     */
+    groupNames: Map<string, number>;
+}
+/** Flags bitfield bit positions (mirrors the spec flag order). */
+export declare const RE_FLAG_G = 1;
+export declare const RE_FLAG_I = 2;
+export declare const RE_FLAG_M = 4;
+export declare const RE_FLAG_S = 8;
+export declare const RE_FLAG_U = 16;
+export declare const RE_FLAG_Y = 32;
+export declare const RE_FLAG_D = 64;
+export declare const RE_FLAG_V = 128;
+/** Parse a JS flags string into the bitfield. Throws on duplicate/unknown. */
+export declare function parseFlags(flags: string): number;
+/**
+ * Raised when the pattern uses a feature outside the Phase-2a subset. The
+ * codegen entry points catch this and emit a clean #1539-phased compile error
+ * (the "narrowed refusal" the architect requires) instead of producing wrong
+ * Wasm.
+ */
+export declare class RegexUnsupportedError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}