@loopdive/js2 0.57.0

package/dist/ir/verify-alloc.d.ts

@@ -0,0 +1,18 @@
+import { AllocSiteRegistry } from './alloc-registry.js';
+import { IrFunction } from './nodes.js';
+export interface AllocVerifyError {
+    readonly message: string;
+    readonly func: string;
+}
+/** True iff the env/debug flag enables the alloc-provenance walk. */
+export declare function allocVerifyEnabled(): boolean;
+/**
+ * Walk every instr (including nested bodies of if / loops / for-of / try) and
+ * check the two provenance invariants against `registry`.
+ */
+export declare function verifyAllocProvenance(func: IrFunction, registry: AllocSiteRegistry): AllocVerifyError[];
+/**
+ * Throwing wrapper for the integration verify boundaries. No-op unless the
+ * debug flag is on, so it costs nothing in production.
+ */
+export declare function assertAllocProvenance(func: IrFunction, registry: AllocSiteRegistry): void;

package/dist/ir/verify.d.ts

@@ -0,0 +1,7 @@
+import { IrFunction } from './nodes.js';
+export interface IrVerifyError {
+    readonly message: string;
+    readonly func: string;
+    readonly block?: number;
+}
+export declare function verifyIrFunction(func: IrFunction): IrVerifyError[];

package/dist/link/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API for the multi-memory module linker.
+ */
+export { validateIsolation } from './isolation.js';
+export type { IsolationReport, IsolationViolation } from './isolation.js';
+export { link } from './linker.js';
+export type { LinkError, LinkOptions, LinkResult } from './linker.js';
+export { parseObject } from './reader.js';
+export type { CodeEntry, ElementEntry, ExportEntry, FunctionEntry, GlobalEntry, ImportEntry, MemoryEntry, ParsedObject, RelocEntry, SymbolInfo, TableEntry, TagEntry, TypeSection, } from './reader.js';
+export { resolveSymbols } from './resolver.js';
+export type { Resolution, ResolvedSymbol } from './resolver.js';

package/dist/link/isolation.d.ts

@@ -0,0 +1,24 @@
+import { ParsedObject } from './reader.js';
+import { Resolution } from './resolver.js';
+export interface IsolationReport {
+    modules: string[];
+    properties: {
+        importExportOnly: boolean;
+        noSharedGlobals: boolean;
+        memoryIsolation: boolean;
+        noPrivateFunctionAccess: boolean;
+        tableIsolation: boolean;
+    };
+    violations: IsolationViolation[];
+}
+export interface IsolationViolation {
+    property: string;
+    module: string;
+    targetModule: string;
+    symbol: string;
+    message: string;
+}
+/**
+ * Validate isolation properties across a set of linked wasm modules.
+ */
+export declare function validateIsolation(objects: ParsedObject[], resolution: Resolution): IsolationReport;

package/dist/link/linker.d.ts

@@ -0,0 +1,37 @@
+import { IsolationReport } from './isolation.js';
+export interface LinkOptions {
+    /** Name of the entry module (controls which exports appear) */
+    entry?: string;
+    /** Whether to run isolation validation (default: true) */
+    validateIsolation?: boolean;
+}
+export interface LinkResult {
+    binary: Uint8Array;
+    wat: string;
+    success: boolean;
+    errors: LinkError[];
+    isolationReport: IsolationReport;
+}
+export interface LinkError {
+    message: string;
+    module?: string;
+    severity: "error" | "warning";
+}
+/**
+ * Link multiple relocatable .o wasm files into a single module.
+ */
+export declare function link(objects: Map<string, Uint8Array>, options?: LinkOptions): LinkResult;
+/**
+ * #1840 test hook — rewrite a single function body applying only index offsets
+ * (no symbol resolution: pass empty symbols so `resolveIndex` falls through to
+ * `origIdx + baseOffset`). Lets a test verify LEB-width growth, call_indirect
+ * tableidx offsetting, and the memory.size/grow immediate rewrite without
+ * constructing a full multi-module link.
+ */
+export declare function rewriteCodeForTest(body: Uint8Array, off: {
+    funcOffset: number;
+    globalOffset: number;
+    typeOffset: number;
+    tableOffset: number;
+    memoryOffset: number;
+}): Uint8Array;

package/dist/link/reader.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Relocatable Wasm object file (.o) parser.
+ *
+ * Parses LLVM-style wasm object files that include linking metadata
+ * and relocation sections. Extracts all standard wasm sections plus
+ * the "linking" custom section (symbol table) and "reloc.*" custom
+ * sections.
+ */
+export interface ParsedObject {
+    name: string;
+    types: TypeSection[];
+    imports: ImportEntry[];
+    functions: FunctionEntry[];
+    tables: TableEntry[];
+    memories: MemoryEntry[];
+    globals: GlobalEntry[];
+    exports: ExportEntry[];
+    elements: ElementEntry[];
+    tags: TagEntry[];
+    code: CodeEntry[];
+    symbols: SymbolInfo[];
+    relocations: Map<string, RelocEntry[]>;
+}
+export interface TypeSection {
+    params: number[];
+    results: number[];
+}
+export interface ImportEntry {
+    module: string;
+    name: string;
+    kind: number;
+    typeIdx?: number;
+    globalType?: number;
+    globalMutable?: boolean;
+    tableElementType?: number;
+    tableMin?: number;
+    tableMax?: number;
+    memoryMin?: number;
+    memoryMax?: number;
+}
+export interface FunctionEntry {
+    typeIdx: number;
+}
+export interface TableEntry {
+    elementType: number;
+    min: number;
+    max?: number;
+}
+export interface MemoryEntry {
+    min: number;
+    max?: number;
+}
+export interface GlobalEntry {
+    type: number;
+    mutable: boolean;
+    init: Uint8Array;
+}
+export interface ExportEntry {
+    name: string;
+    kind: number;
+    index: number;
+}
+export interface ElementEntry {
+    /**
+     * Raw element-segment flags field (#1841 — the 3-bit value 0-7 per the
+     * WebAssembly spec, not just active flag-0). Determines the segment mode
+     * (active / passive / declarative), whether a tableidx + offset-expr are
+     * present, and whether the payload is funcidx* or expr*.
+     */
+    flags: number;
+    tableIdx: number;
+    /**
+     * Active-segment offset constant-expression bytes (terminated by 0x0b),
+     * present only for active modes (flags 0, 2, 4, 6). `null` for
+     * passive/declarative (flags 1, 3, 5, 7), which have no offset.
+     */
+    offsetExpr: Uint8Array | null;
+    /**
+     * For funcidx-payload segments (flags 0-3): the resolved function indices.
+     * Empty for expr-payload segments (flags 4-7), which keep their raw
+     * expression bytes in `elemExprs` instead.
+     */
+    funcIndices: number[];
+    /** Number of elements in the segment (funcidx count or expr count). */
+    elemCount: number;
+    /**
+     * elemkind (flags 1-3) or reftype (flags 5-7) byte, when the segment
+     * carries one explicitly. `null` for flag 0/4 (funcref implied).
+     */
+    kindByte: number | null;
+    /**
+     * For expr-payload segments (flags 4-7): the raw element-expression bytes
+     * (the `vec(expr)` body, excluding the leading count). Re-emitted verbatim.
+     * `null` for funcidx-payload segments.
+     */
+    elemExprs: Uint8Array | null;
+}
+export interface TagEntry {
+    attribute: number;
+    typeIdx: number;
+}
+export interface CodeEntry {
+    locals: {
+        count: number;
+        type: number;
+    }[];
+    body: Uint8Array;
+}
+export interface SymbolInfo {
+    kind: number;
+    name: string;
+    index: number;
+    flags: number;
+}
+export interface RelocEntry {
+    type: number;
+    offset: number;
+    symbolIndex: number;
+    addend?: number;
+}
+export declare const SYMBOL_BINDING_WEAK = 1;
+export declare const SYMBOL_BINDING_LOCAL = 2;
+export declare const SYMBOL_VISIBILITY_HIDDEN = 4;
+export declare const SYMBOL_UNDEFINED = 16;
+export declare const SYMBOL_EXPORTED = 32;
+export declare const SYMBOL_EXPLICIT_NAME = 64;
+export declare const SYMBOL_NO_STRIP = 128;
+export declare const SYMTAB_FUNCTION = 0;
+export declare const SYMTAB_DATA = 1;
+export declare const SYMTAB_GLOBAL = 2;
+export declare const SYMTAB_SECTION = 3;
+export declare const SYMTAB_EVENT = 4;
+export declare const SYMTAB_TABLE = 5;
+export declare const R_WASM_FUNCTION_INDEX_LEB = 0;
+export declare const R_WASM_TABLE_INDEX_SLEB = 1;
+export declare const R_WASM_TABLE_INDEX_I32 = 2;
+export declare const R_WASM_MEMORY_ADDR_LEB = 3;
+export declare const R_WASM_MEMORY_ADDR_SLEB = 4;
+export declare const R_WASM_MEMORY_ADDR_I32 = 5;
+export declare const R_WASM_TYPE_INDEX_LEB = 6;
+export declare const R_WASM_GLOBAL_INDEX_LEB = 7;
+export declare const R_WASM_FUNCTION_OFFSET_I32 = 8;
+export declare const R_WASM_SECTION_OFFSET_I32 = 9;
+export declare const R_WASM_TAG_INDEX_LEB = 10;
+export declare const R_WASM_TABLE_INDEX_LEB = 15;
+export declare const R_WASM_TABLE_NUMBER_LEB = 20;
+export declare function parseObject(name: string, bytes: Uint8Array): ParsedObject;
+/**
+ * #1841 test hook — parse a raw element-section body (the bytes that follow the
+ * section id + size, i.e. starting at the segment count) and return the parsed
+ * segments plus the final cursor position. The cursor MUST land exactly at the
+ * end of `bytes`; any drift means a flag case desynced the reader. Kept narrow
+ * so the internal `ByteReader` / `parseElementSection` stay unexported.
+ */
+export declare function parseElementSegmentsForTest(bytes: Uint8Array): {
+    elements: ElementEntry[];
+    finalPos: number;
+};

package/dist/link/resolver.d.ts

@@ -0,0 +1,19 @@
+import { ParsedObject } from './reader.js';
+export interface Resolution {
+    /** Map from "moduleIdx:symbolIdx" → resolved target */
+    resolved: Map<string, ResolvedSymbol>;
+    errors: string[];
+}
+export interface ResolvedSymbol {
+    targetModule: number;
+    targetIndex: number;
+    name: string;
+}
+/**
+ * Resolve symbols across a set of parsed wasm object files.
+ *
+ * For each undefined symbol in a module, search other modules for an
+ * exported (or at least non-undefined, non-local) definition with the
+ * same name and kind.
+ */
+export declare function resolveSymbols(objects: ParsedObject[]): Resolution;

package/dist/optimize.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Post-processing pass using Binaryen's wasm-opt optimizer.
+ *
+ * Tries two strategies in order:
+ * 1. The `binaryen` npm package (if installed as an optional peer dependency)
+ * 2. A system `wasm-opt` binary on PATH
+ *
+ * If neither is available, returns the original binary unchanged and emits a warning.
+ */
+export interface OptimizeOptions {
+    /** Optimization level: 1 (-O1), 2 (-O2), 3 (-O3), 4 (-O4). Default: 3 */
+    level?: 1 | 2 | 3 | 4;
+    /** Enable GC proposal (default: true) */
+    gc?: boolean;
+    /** Enable reference types (default: true) */
+    referenceTypes?: boolean;
+    /** Enable exception handling (default: true) */
+    exceptionHandling?: boolean;
+}
+export interface OptimizeResult {
+    binary: Uint8Array;
+    /** true if optimization was applied */
+    optimized: boolean;
+    /** Warning message if optimization was skipped */
+    warning?: string;
+}
+/**
+ * Optimize a Wasm binary using Binaryen.
+ *
+ * This is the only public optimizer entry point (#1763). The previous
+ * synchronous `optimizeBinary` was removed: after the #1757 async-compile
+ * migration every live caller goes through this async path, and the sync
+ * variant only kept alive a dead `createRequire("binaryen")` branch — the
+ * exact bundler hazard #986/#1756 set out to remove. The `binaryen` package
+ * is loaded lazily at runtime (see `getBinaryenModule`) without making
+ * bundlers embed it in standalone artifacts; the system `wasm-opt` CLI
+ * fallback still uses the dynamic node-builtin shim that bundlers
+ * intentionally cannot statically resolve.
+ *
+ * Backend preference + correctness gate (#1941):
+ *   1. Try the **system / bundled `wasm-opt` CLI first**, then the in-process
+ *      binaryen module as a fallback (the reverse of the pre-#1941 order).
+ *      The binaryen-123 JS module emits a stale GC ref-type encoding
+ *      (`0x62` legacy non-null ref) for our closure-dispatch trampolines
+ *      that V8 and wasmtime reject, while the bundled native CLI emits the
+ *      correct `0x64` encoding. The CLI is the trustworthy backend; the
+ *      module is the no-CLI fallback (e.g. browser playgrounds).
+ *   2. **Validate every optimizer result** with `WebAssembly.validate`. If
+ *      the optimized bytes don't validate, the pass miscompiled the module:
+ *      discard them, return the ORIGINAL binary, and emit a fail-loud
+ *      warning. We never ship a binary that doesn't validate, regardless of
+ *      which backend produced it or which binaryen version is installed.
+ */
+export declare function optimizeBinaryAsync(binary: Uint8Array, options?: OptimizeOptions): Promise<OptimizeResult>;

package/dist/optimize.js

@@ -0,0 +1,262 @@
+let _nodeImports = null;
+function getNodeImportsSync() {
+  if (_nodeImports) return _nodeImports;
+  if (typeof process === "undefined" || !process.versions || !process.versions.node) {
+    return null;
+  }
+  try {
+    let req;
+    const getBuiltin = process.getBuiltinModule;
+    if (typeof getBuiltin === "function") {
+      const moduleNs = getBuiltin("node:module");
+      if (moduleNs && typeof moduleNs.createRequire === "function") {
+        req = moduleNs.createRequire(`file://${process.cwd()}/`);
+      }
+    }
+    if (!req || typeof req !== "function") return null;
+    const cp = req("node:child_process");
+    const fs = req("node:fs");
+    const path = req("node:path");
+    const os = req("node:os");
+    _nodeImports = {
+      execFileSync: cp.execFileSync,
+      writeFileSync: fs.writeFileSync,
+      readFileSync: fs.readFileSync,
+      unlinkSync: fs.unlinkSync,
+      rmdirSync: fs.rmdirSync,
+      mkdtempSync: fs.mkdtempSync,
+      join: path.join,
+      tmpdir: os.tmpdir
+    };
+    return _nodeImports;
+  } catch {
+    return null;
+  }
+}
+let _binaryenModulePromise = null;
+function isBrowserLikeRuntime() {
+  return typeof window !== "undefined" || typeof globalThis.WorkerGlobalScope !== "undefined";
+}
+function optimizedBinaryValidates(binary) {
+  const WA = globalThis.WebAssembly;
+  if (!WA || typeof WA.validate !== "function") return true;
+  try {
+    return WA.validate(binary);
+  } catch {
+    return false;
+  }
+}
+async function optimizeBinaryAsync(binary, options = {}) {
+  const level = options.level ?? 3;
+  const gc = options.gc !== false;
+  const referenceTypes = options.referenceTypes !== false;
+  const exceptionHandling = options.exceptionHandling !== false;
+  try {
+    const result = optimizeWithSystemBinary(binary, level, gc, referenceTypes, exceptionHandling);
+    if (result && result.optimized) {
+      if (optimizedBinaryValidates(result.binary)) return result;
+    } else if (result) {
+      return result;
+    }
+  } catch {
+  }
+  try {
+    const binaryen = await getBinaryenModule();
+    if (binaryen) {
+      const result = optimizeWithBinaryenModule(binaryen, binary, level, gc, referenceTypes, exceptionHandling);
+      if (result && result.optimized) {
+        if (optimizedBinaryValidates(result.binary)) return result;
+        return {
+          binary,
+          optimized: false,
+          warning: "wasm-opt produced an invalid binary (it failed WebAssembly.validate); shipping unoptimized output instead. This is a known binaryen-JS-module encoder bug for WasmGC ref types (#1941) — installing a native wasm-opt on PATH avoids it."
+        };
+      }
+      if (result) return result;
+    }
+  } catch {
+  }
+  return {
+    binary,
+    optimized: false,
+    warning: "wasm-opt not available: install the 'binaryen' npm package or add wasm-opt to PATH. Skipping optimization."
+  };
+}
+async function getBinaryenModule() {
+  if (_binaryenModulePromise) return _binaryenModulePromise;
+  _binaryenModulePromise = (async () => {
+    const browserLike = isBrowserLikeRuntime();
+    const globalObject = globalThis;
+    const hadProcess = "process" in globalObject;
+    const hadOwnProcess = Object.prototype.hasOwnProperty.call(globalObject, "process");
+    const previousProcess = globalObject.process;
+    if (browserLike && hadProcess) {
+      try {
+        globalObject.process = void 0;
+      } catch {
+      }
+    }
+    try {
+      const specifier = globalObject.__js2wasmBinaryenModuleSpecifier ?? "binaryen";
+      const mod = await import(
+        /* @vite-ignore */
+        specifier
+      );
+      return mod.default ?? mod;
+    } catch {
+      return null;
+    } finally {
+      if (browserLike) {
+        if (hadProcess && hadOwnProcess) {
+          globalObject.process = previousProcess;
+        } else {
+          globalObject.process = void 0;
+        }
+      }
+    }
+  })();
+  return _binaryenModulePromise;
+}
+function optimizeWithBinaryenModule(binaryen, binary, level, gc, referenceTypes, exceptionHandling) {
+  const featureFlags = binaryen.Features ?? binaryen.features;
+  if (!featureFlags) return null;
+  let mod;
+  try {
+    mod = binaryen.readBinary(binary);
+  } catch (e) {
+    return null;
+  }
+  try {
+    const previousOptimizeLevel = typeof binaryen.getOptimizeLevel === "function" ? binaryen.getOptimizeLevel() : void 0;
+    const previousShrinkLevel = typeof binaryen.getShrinkLevel === "function" ? binaryen.getShrinkLevel() : void 0;
+    let features = 0;
+    if (gc) features |= (featureFlags.GC ?? 0) | (featureFlags.ReferenceTypes ?? 0);
+    if (referenceTypes) features |= featureFlags.ReferenceTypes ?? 0;
+    if (exceptionHandling) features |= featureFlags.ExceptionHandling ?? 0;
+    features |= featureFlags.BulkMemory ?? 0;
+    features |= featureFlags.MutableGlobals ?? 0;
+    features |= featureFlags.SignExt ?? 0;
+    features |= featureFlags.TruncSat ?? 0;
+    features |= featureFlags.TailCall ?? 0;
+    features |= featureFlags.Multivalue ?? 0;
+    features |= featureFlags.TypedFunctionReferences ?? 0;
+    features |= featureFlags.Strings ?? 0;
+    features |= featureFlags.GCNNLocals ?? 0;
+    features |= featureFlags.RelaxedSIMD ?? 0;
+    features |= featureFlags.ExtendedConst ?? 0;
+    features |= featureFlags.SIMD128 ?? 0;
+    features |= featureFlags.Atomics ?? 0;
+    features |= featureFlags.MultiMemory ?? 0;
+    features |= featureFlags.CallIndirectOverlong ?? 0;
+    if (featureFlags.CustomDescriptors !== void 0) {
+      features &= ~featureFlags.CustomDescriptors;
+    }
+    mod.setFeatures(features);
+    if (typeof binaryen.setOptimizeLevel === "function") {
+      binaryen.setOptimizeLevel(level >= 4 ? 3 : level);
+    }
+    if (typeof binaryen.setShrinkLevel === "function") {
+      binaryen.setShrinkLevel(level >= 4 ? 1 : 0);
+    }
+    try {
+      mod.optimize();
+      if (level >= 4) mod.optimize();
+    } finally {
+      if (typeof binaryen.setOptimizeLevel === "function" && previousOptimizeLevel !== void 0) {
+        binaryen.setOptimizeLevel(previousOptimizeLevel);
+      }
+      if (typeof binaryen.setShrinkLevel === "function" && previousShrinkLevel !== void 0) {
+        binaryen.setShrinkLevel(previousShrinkLevel);
+      }
+    }
+    const optimizedBinary = mod.emitBinary();
+    return { binary: new Uint8Array(optimizedBinary), optimized: true };
+  } finally {
+    mod.dispose();
+  }
+}
+function optimizeWithSystemBinary(binary, level, gc, referenceTypes, exceptionHandling) {
+  const n = getNodeImportsSync();
+  if (!n) return null;
+  let wasmOptPath;
+  try {
+    const p = n.execFileSync("which", ["wasm-opt"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (p) wasmOptPath = p;
+  } catch {
+  }
+  if (!wasmOptPath) {
+    try {
+      let req;
+      const getBuiltin = process.getBuiltinModule;
+      if (typeof getBuiltin === "function") {
+        const moduleNs = getBuiltin("node:module");
+        if (moduleNs && typeof moduleNs.createRequire === "function") {
+          req = moduleNs.createRequire(`file://${process.cwd()}/`);
+        }
+      }
+      if (req && typeof req.resolve === "function") {
+        const pkgJsonPath = req.resolve("binaryen/package.json");
+        const wasmOptCandidate = n.join(pkgJsonPath, "..", "bin", "wasm-opt");
+        n.execFileSync(wasmOptCandidate, ["--version"], {
+          stdio: ["ignore", "ignore", "ignore"],
+          timeout: 5e3
+        });
+        wasmOptPath = wasmOptCandidate;
+      }
+    } catch {
+    }
+  }
+  if (!wasmOptPath) return null;
+  const tmpDir = n.mkdtempSync(n.join(n.tmpdir(), "js2wasm-opt-"));
+  const inputPath = n.join(tmpDir, "input.wasm");
+  const outputPath = n.join(tmpDir, "output.wasm");
+  try {
+    n.writeFileSync(inputPath, binary);
+    const args = [
+      inputPath,
+      `-O${level}`,
+      "-o",
+      outputPath,
+      "--all-features",
+      "--disable-custom-descriptors"
+    ];
+    void gc;
+    void referenceTypes;
+    void exceptionHandling;
+    let stderr = "";
+    try {
+      n.execFileSync(wasmOptPath, args, {
+        timeout: 6e4,
+        // 60 second timeout
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (err) {
+      const e = err;
+      stderr = e.stderr ?? e.message ?? "unknown error";
+      const text = Buffer.isBuffer(stderr) ? stderr.toString("utf-8") : String(stderr);
+      return {
+        binary,
+        optimized: false,
+        warning: `wasm-opt -O${level} failed: ${text.slice(0, 800).trim()}`
+      };
+    }
+    const optimizedBinary = n.readFileSync(outputPath);
+    return { binary: new Uint8Array(optimizedBinary), optimized: true };
+  } finally {
+    try {
+      n.unlinkSync(inputPath);
+    } catch {
+    }
+    try {
+      n.unlinkSync(outputPath);
+    } catch {
+    }
+    try {
+      n.rmdirSync(tmpDir);
+    } catch {
+    }
+  }
+}
+export {
+  optimizeBinaryAsync
+};

package/dist/position-map.d.ts

@@ -0,0 +1,64 @@
+/**
+ * #1928 — source-position remapping for pre-parse rewrites.
+ *
+ * Diagnostics are computed by the TS checker against the *rewritten* source
+ * (timer shim prepended, imports replaced by `declare` stubs, CJS `require`
+ * rewritten, `define` substitutions), so a reported `(line, column)` is wrong
+ * — often by several lines — whenever any pre-parse rewrite fires. There is no
+ * way to recover the user's position from the processed source alone.
+ *
+ * A `PositionMap` records the character-level edits a rewriter applied (each in
+ * the coordinate space of the text it consumed) and translates an offset in the
+ * *output* text back to an offset in the *input* text. Rewriters run in a
+ * pipeline (define → CJS → eval/super → imports+shim), so the maps compose:
+ * `outer.compose(inner)` yields a map from the outermost output straight back
+ * to the original source.
+ *
+ * Mapping policy (matches the issue's pragmatic guidance):
+ *   - An offset OUTSIDE every edited span maps back by the net length delta of
+ *     all edits that ended before it — exact.
+ *   - An offset INSIDE a replaced span (e.g. within an injected `declare`
+ *     stub, which has no user-source counterpart) maps to the START of the
+ *     original replaced span. Diagnostics rarely point inside an injected stub;
+ *     anchoring at the original statement is the correct, stable fallback.
+ */
+/**
+ * One text edit, in the coordinate space of the INPUT this rewriter consumed:
+ * the half-open span `[origStart, origEnd)` was replaced by text of length
+ * `newLength`. A pure prepend is `origStart = origEnd = 0` with `newLength` =
+ * the prepended length.
+ */
+export interface SourceEdit {
+    readonly origStart: number;
+    readonly origEnd: number;
+    readonly newLength: number;
+}
+export declare class PositionMap {
+    /**
+     * A single-stage map is described by its edit list; a composed map is a
+     * chain `outer → inner` translated by function composition (apply `outer`'s
+     * single-stage transform, then defer to `inner`). Keeping composition as
+     * function composition (rather than flattening two edit lists into one)
+     * avoids the interleaving-delta correctness traps of merging transforms.
+     */
+    private readonly edits;
+    private readonly inner?;
+    constructor(edits: readonly SourceEdit[], inner?: PositionMap);
+    /** Identity map — output offsets equal input offsets. */
+    static identity(): PositionMap;
+    /** Apply only THIS stage's single transform (output → its direct input). */
+    private toDirectInputOffset;
+    /**
+     * Translate an offset in this map's OUTPUT text all the way back to the
+     * ORIGINAL source: apply this stage, then defer to the earlier stage(s).
+     */
+    toInputOffset(outOffset: number): number;
+    /**
+     * Compose with the map of an EARLIER pipeline stage. `this` maps
+     * stage-N-output → stage-N-input; `inner` maps stage-N-input (== stage-(N−1)
+     * output) → original. The result maps stage-N-output → original.
+     */
+    compose(inner: PositionMap): PositionMap;
+    /** True when this is the identity (no edits and no earlier stage). */
+    get isIdentity(): boolean;
+}

package/dist/process-stdin-prelude.d.ts

@@ -0,0 +1,16 @@
+import { PositionMap } from './position-map.js';
+export interface StdinPreludeResult {
+    /** The transformed source (prelude prepended + `process.stdin` rewritten), or the input unchanged. */
+    source: string;
+    /** Output→input position map (identity when nothing was injected). */
+    positionMap: PositionMap;
+    /** True when the prelude was injected (the program references `process.stdin`). */
+    injected: boolean;
+}
+/**
+ * #2632 Phase 3 — inject the faithful `process.stdin` Readable prelude when the
+ * program references `process.stdin`. Byte-neutral (identity map, unchanged
+ * source) otherwise. Only the caller decides WASI gating; this function injects
+ * whenever a `process.stdin` access is present.
+ */
+export declare function injectProcessStdinPrelude(source: string): StdinPreludeResult;