@twinkle-lang/twinkle 0.2.0 → 0.4.0

package/index.mjs

@@ -10,6 +10,7 @@ import { readFileSync, writeFileSync, rmSync, mkdtempSync } from "node:fs";
 import { resolve, dirname, join, basename } from "node:path";
 import { tmpdir } from "node:os";
 import { runWasmBytesAsync } from "./runtime.mjs";
+import { nodeHost } from "./node_host.mjs";
 
 const here = import.meta.dirname;
 
@@ -95,6 +96,7 @@ export async function compile(input, opts = {}) {
       stdout: out,
       stderr: err,
       bridgeBytes,
+      host: nodeHost,
     });
     if (code !== 0) {
       throw new Error(`Twinkle compilation failed (exit ${code}):\n${err.text() || out.text()}`);
@@ -121,6 +123,7 @@ export async function run(wasmBytes, opts = {}) {
     stdout: opts.stdout ?? process.stdout,
     stderr: opts.stderr ?? process.stderr,
     bridgeBytes: loadBridgeWasm(),
+    host: nodeHost,
     imports: opts.imports ?? {},
   });
 }

package/node.mjs

@@ -9,6 +9,7 @@
 import { readFileSync, writeSync } from "node:fs";
 import { resolve } from "node:path";
 import { runWasmBytesAsync } from "./runtime.mjs";
+import { nodeHost } from "./node_host.mjs";
 
 const textEncoder = new TextEncoder();
 const here = import.meta.dirname;
@@ -104,6 +105,7 @@ async function main() {
     stdout: nodeStream(1),
     stderr: nodeStream(2),
     bridgeBytes: loadBridgeWasm(),
+    host: nodeHost,
   });
   process.exit(exitCode);
 }

package/node_host.mjs

@@ -0,0 +1,133 @@
+// Node/Deno host adapter for the shared Twinkle runtime.
+//
+// runtime.mjs is host-agnostic: it routes every filesystem and stdin host
+// import through an injected `host` object. This module provides that object
+// for Node and Deno (Deno satisfies node:fs / node:path via its node-compat
+// layer). A browser supplies its own adapter with the same shape.
+//
+// Host interface:
+//   resolvePath(cwd, p) -> string
+//   readFile(path)      -> Uint8Array   (throws on missing)
+//   writeFile(path, text)
+//   writeBytes(path, bytes: Uint8Array)
+//   exists(path)        -> boolean
+//   listDir(path)       -> string[]
+//   mkdirp(path)
+//   readStdin(maxBytes, timeoutMs, runtime)      -> Uint8Array   (sync)
+//   readStdinAsync(maxBytes, timeoutMs, runtime) -> Promise<Uint8Array>
+//
+// The stdin helpers set runtime.stdinEof when the stream reaches EOF.
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, readSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Stdin helpers
+// ---------------------------------------------------------------------------
+
+function sleepSyncMs(ms) {
+  if (ms <= 0) return;
+  const sab = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(sab), 0, 0, ms);
+}
+
+function readStdinTimeout(maxBytes, timeoutMs, runtime) {
+  const n = Number(maxBytes);
+  const timeout = Number(timeoutMs);
+  if (n <= 0) return Buffer.alloc(0);
+
+  // Accessing process.stdin asks Node/libuv to put fd 0 in non-blocking mode
+  // for pipes/ttys, which lets fs.readSync report EAGAIN instead of blocking
+  // forever when no LSP bytes are currently available.
+  void process.stdin;
+
+  const deadline = performance.now() + Math.max(0, timeout);
+  const buf = Buffer.allocUnsafe(n);
+  while (true) {
+    try {
+      const read = readSync(0, buf, 0, n, null);
+      if (read === 0) runtime.stdinEof = true;
+      return buf.subarray(0, read);
+    } catch (e) {
+      if (e?.code === "EAGAIN" || e?.code === "EWOULDBLOCK") {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) return Buffer.alloc(0);
+        sleepSyncMs(Math.min(10, remaining));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+function readStdinTimeoutAsync(maxBytes, timeoutMs, runtime) {
+  const n = Number(maxBytes);
+  const timeout = Number(timeoutMs);
+  if (n <= 0) return Promise.resolve(Buffer.alloc(0));
+
+  return new Promise((resolve) => {
+    let timer = null;
+    let settled = false;
+
+    const finish = (chunk) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== null) { clearTimeout(timer); timer = null; }
+      process.stdin.removeListener("readable", onReadable);
+      process.stdin.removeListener("end", onEnd);
+      resolve(chunk);
+    };
+
+    const tryRead = () => {
+      // read() with no argument returns whatever is buffered (1..any bytes),
+      // matching the sync path's "read up to n" semantics.
+      const chunk = process.stdin.read();
+      if (chunk !== null) {
+        // If the stream returned more than n bytes, push the excess back.
+        if (chunk.length > n) {
+          process.stdin.unshift(chunk.subarray(n));
+          finish(chunk.subarray(0, n));
+        } else {
+          finish(chunk);
+        }
+        return true;
+      }
+      return false;
+    };
+
+    const onReadable = () => { tryRead(); };
+
+    const onEnd = () => {
+      runtime.stdinEof = true;
+      finish(Buffer.alloc(0));
+    };
+
+    if (tryRead()) return;
+
+    if (process.stdin.readableEnded) {
+      runtime.stdinEof = true;
+      resolve(Buffer.alloc(0));
+      return;
+    }
+
+    timer = setTimeout(() => finish(Buffer.alloc(0)), Math.max(0, timeout));
+    process.stdin.once("readable", onReadable);
+    process.stdin.once("end", onEnd);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+export const nodeHost = {
+  resolvePath(cwd, p) { return resolve(cwd, p); },
+  readFile(path) { return readFileSync(path); },
+  writeFile(path, text) { writeFileSync(path, text); },
+  writeBytes(path, bytes) { writeFileSync(path, bytes); },
+  exists(path) { return existsSync(path); },
+  listDir(path) { return readdirSync(path); },
+  mkdirp(path) { mkdirSync(path, { recursive: true }); },
+  readStdin: readStdinTimeout,
+  readStdinAsync: readStdinTimeoutAsync,
+};

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@twinkle-lang/twinkle",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Twinkle — a statically typed language targeting WebAssembly GC. CLI (twk) plus an embeddable compile/run library.",
   "type": "module",
   "bin": { "twk": "node.mjs" },
-  "exports": { ".": "./index.mjs" },
-  "files": ["node.mjs", "index.mjs", "runtime.mjs", "boot.wasm", "bridge.wasm", "README.md"],
+  "exports": {
+    ".": "./index.mjs",
+    "./web": "./web.mjs",
+    "./runtime.mjs": "./runtime.mjs",
+    "./node_host.mjs": "./node_host.mjs",
+    "./boot.wasm": "./boot.wasm",
+    "./bridge.wasm": "./bridge.wasm"
+  },
+  "files": ["node.mjs", "index.mjs", "web.mjs", "runtime.mjs", "node_host.mjs", "boot.wasm", "bridge.wasm", "README.md"],
   "engines": { "node": ">=22" },
   "license": "MIT",
   "publishConfig": { "access": "public" },

package/runtime.mjs

@@ -4,11 +4,15 @@
 // bridge Wasm module to create/read Wasm GC values (since JS cannot directly
 // construct or inspect Wasm GC arrays/structs).
 //
+// Host-agnostic: all filesystem and stdin host imports are routed through an
+// injected `host` adapter (see tools/js_runtime/node_host.mjs for Node/Deno,
+// or the playground's browser adapter). This module contains no `node:`
+// imports, so it loads unchanged in a browser/worker.
+//
 // Used by:
-//   - tools/js_runtime/deno_main.mjs  (Deno standalone CLI)
-
-import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, readSync, writeSync } from "node:fs";
-import { resolve } from "node:path";
+//   - tools/js_runtime/deno_main.mjs  (Deno standalone CLI, host: nodeHost)
+//   - tools/js_runtime/node_main.mjs  (Node CLI, host: nodeHost)
+//   - tools/js_runtime/index.mjs      (embeddable library, host: nodeHost)
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -105,109 +109,11 @@ function decodeStringArray(b, arrRef) {
 
 function decodeByteArray(b, arrRef) {
   const len = b.array_len(arrRef);
-  if (len === 0) return Buffer.alloc(0);
+  if (len === 0) return new Uint8Array(0);
   ensureMemory(b, len);
   b.bulk_bytes_read(arrRef);
-  // ArrayBuffer.slice copies (unlike Buffer.slice which creates a view)
-  return Buffer.from(b.memory.buffer.slice(0, len));
-}
-
-// ---------------------------------------------------------------------------
-// Stdin helpers
-// ---------------------------------------------------------------------------
-
-function sleepSyncMs(ms) {
-  if (ms <= 0) return;
-  const sab = new SharedArrayBuffer(4);
-  Atomics.wait(new Int32Array(sab), 0, 0, ms);
-}
-
-function readStdinTimeout(maxBytes, timeoutMs, runtime) {
-  const n = Number(maxBytes);
-  const timeout = Number(timeoutMs);
-  if (n <= 0) return Buffer.alloc(0);
-
-  // Accessing process.stdin asks Node/libuv to put fd 0 in non-blocking mode
-  // for pipes/ttys, which lets fs.readSync report EAGAIN instead of blocking
-  // forever when no LSP bytes are currently available.
-  void process.stdin;
-
-  const deadline = performance.now() + Math.max(0, timeout);
-  const buf = Buffer.allocUnsafe(n);
-  while (true) {
-    try {
-      const read = readSync(0, buf, 0, n, null);
-      if (read === 0) runtime.stdinEof = true;
-      return buf.subarray(0, read);
-    } catch (e) {
-      if (e?.code === "EAGAIN" || e?.code === "EWOULDBLOCK") {
-        const remaining = deadline - performance.now();
-        if (remaining <= 0) return Buffer.alloc(0);
-        sleepSyncMs(Math.min(10, remaining));
-        continue;
-      }
-      throw e;
-    }
-  }
-}
-
-function readStdinTimeoutAsync(maxBytes, timeoutMs, runtime) {
-  const n = Number(maxBytes);
-  const timeout = Number(timeoutMs);
-  if (n <= 0) return Promise.resolve(Buffer.alloc(0));
-
-  return new Promise((resolve) => {
-    let timer = null;
-
-    let settled = false;
-
-    const finish = (chunk) => {
-      if (settled) return;
-      settled = true;
-      if (timer !== null) { clearTimeout(timer); timer = null; }
-      process.stdin.removeListener("readable", onReadable);
-      process.stdin.removeListener("end", onEnd);
-      resolve(chunk);
-    };
-
-    const tryRead = () => {
-      // read() with no argument returns whatever is buffered (1..any bytes),
-      // matching the sync path's "read up to n" semantics.
-      const chunk = process.stdin.read();
-      if (chunk !== null) {
-        // If the stream returned more than n bytes, push the excess back.
-        if (chunk.length > n) {
-          process.stdin.unshift(chunk.subarray(n));
-          finish(chunk.subarray(0, n));
-        } else {
-          finish(chunk);
-        }
-        return true;
-      }
-      return false;
-    };
-
-    const onReadable = () => { tryRead(); };
-
-    const onEnd = () => {
-      runtime.stdinEof = true;
-      finish(Buffer.alloc(0));
-    };
-
-    // Try immediate read from the stream buffer
-    if (tryRead()) return;
-
-    if (process.stdin.readableEnded) {
-      runtime.stdinEof = true;
-      resolve(Buffer.alloc(0));
-      return;
-    }
-
-    timer = setTimeout(() => finish(Buffer.alloc(0)), Math.max(0, timeout));
-
-    process.stdin.once("readable", onReadable);
-    process.stdin.once("end", onEnd);
-  });
+  // ArrayBuffer.slice copies, so the returned view owns its bytes.
+  return new Uint8Array(b.memory.buffer.slice(0, len));
 }
 
 // ---------------------------------------------------------------------------
@@ -215,11 +121,18 @@ function readStdinTimeoutAsync(maxBytes, timeoutMs, runtime) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve each wasm extern import to a JS function.
+ * Resolve each wasm extern import to a JS function (and its optional arg spec).
+ *
+ * A scoped `imports[module][name]` entry is either:
+ *   - a function — the implementation, with default arg marshaling, or
+ *   - `{ fn?, args? }` — `fn` is the implementation (omit it to fall back to
+ *     `globals[module][name]`), and `args` is the per-arg marshal spec, an array
+ *     of `"raw" | "string"` keyed by position.
+ *
  * Resolution order per import: scoped `imports[module][name]`, then
  * `globals[module][name]`. Imports already satisfied by `hostImports`, or that
- * are not functions, are skipped. Returns the resolved bindings plus a list of
- * unresolved "module.name" strings.
+ * are not functions, are skipped. Returns the resolved bindings (each with
+ * `fn`, `recv`, and `args`) plus a list of unresolved "module.name" strings.
  */
 export function resolveExternImports(importList, hostImports, imports = {}, globals = globalThis) {
   const found = [];
@@ -228,21 +141,33 @@ export function resolveExternImports(importList, hostImports, imports = {}, glob
     if (hostImports[imp.module]?.[imp.name] !== undefined) continue;
     if (imp.kind !== "function") continue;
 
-    const scopedRecv = imports[imp.module];
-    const scoped = scopedRecv?.[imp.name];
+    const scoped = imports[imp.module]?.[imp.name];
+    let fn;
+    let recv;
+    let args;
+
     if (typeof scoped === "function") {
-      found.push({ module: imp.module, name: imp.name, fn: scoped, recv: scopedRecv });
-      continue;
+      fn = scoped;
+      recv = imports[imp.module];
+    } else if (scoped && typeof scoped === "object") {
+      args = scoped.args;
+      if (typeof scoped.fn === "function") {
+        fn = scoped.fn;
+        recv = imports[imp.module];
+      } else {
+        fn = globals[imp.module]?.[imp.name];
+        recv = globals[imp.module];
+      }
+    } else {
+      fn = globals[imp.module]?.[imp.name];
+      recv = globals[imp.module];
     }
 
-    const globalRecv = globals[imp.module];
-    const global = globalRecv?.[imp.name];
-    if (typeof global === "function") {
-      found.push({ module: imp.module, name: imp.name, fn: global, recv: globalRecv });
-      continue;
+    if (typeof fn === "function") {
+      found.push({ module: imp.module, name: imp.name, fn, recv, args });
+    } else {
+      missing.push(`${imp.module}.${imp.name}`);
     }
-
-    missing.push(`${imp.module}.${imp.name}`);
   }
   return { found, missing };
 }
@@ -276,10 +201,16 @@ function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, impor
     );
   }
 
-  const marshalArgs = (args) => args.map((arg) => {
+  // Per-import arg marshaling honors the extern's optional `args` spec — an
+  // array of `"raw" | "string"` keyed by arg position. `"raw"` passes the value
+  // through untouched, essential for externref args (e.g. a canvas 2D context),
+  // since calling decodeString on an opaque host object recurses until a stack
+  // overflow in some engines (notably Safari). Without a spec entry, a
+  // non-numeric arg is assumed to be a Wasm GC string and decoded.
+  const makeMarshalArgs = (spec) => (args) => args.map((arg, i) => {
     if (typeof arg === "bigint") return Number(arg);
     if (typeof arg === "number") return arg;
-    // GC ref — assume string
+    if (spec?.[i] === "raw") return arg;
     return decodeString(b, arg);
   });
 
@@ -291,7 +222,8 @@ function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, impor
     return result;
   };
 
-  for (const { module, name, fn, recv } of found) {
+  for (const { module, name, fn, recv, args } of found) {
+    const marshalArgs = makeMarshalArgs(args);
     let bridgedFn;
     if (jspi) {
       // JSPI mode: async wrapper so Promise-returning JS functions suspend
@@ -321,17 +253,6 @@ function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, impor
 // Host imports
 // ---------------------------------------------------------------------------
 
-function writeAllFdSync(fd, bytes) {
-  let offset = 0;
-  while (offset < bytes.byteLength) {
-    const written = writeSync(fd, bytes, offset, bytes.byteLength - offset);
-    if (written <= 0) {
-      throw new Error("stdout write made no progress");
-    }
-    offset += written;
-  }
-}
-
 function write(stream, text) {
   stream.write(text);
 }
@@ -378,16 +299,17 @@ function makeHostImports(b, runtime, bridgeBytes) {
           stdout: runtime.stdout,
           stderr: runtime.stderr,
           imports: runtime.imports,
+          host: runtime.host,
           bridgeBytes,
         });
         return BigInt(exitCode);
       },
 
-      // --- File system ---
+      // --- File system (routed through the injected host adapter) ---
       read_file: (pathRef) => {
-        const filePath = resolve(runtime.cwd, decodeString(b, pathRef));
+        const filePath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
         try {
-          const bytes = readFileSync(filePath);
+          const bytes = runtime.host.readFile(filePath);
           return makeResultOk(b, makeByteArray(b, bytes));
         } catch (e) {
           const msg = `host.read_file failed for '${filePath}': ${e.message}`;
@@ -395,35 +317,33 @@ function makeHostImports(b, runtime, bridgeBytes) {
         }
       },
       write_file: (pathRef, contentRef) => {
-        const filePath = resolve(runtime.cwd, decodeString(b, pathRef));
-        writeFileSync(filePath, decodeString(b, contentRef));
+        const filePath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
+        runtime.host.writeFile(filePath, decodeString(b, contentRef));
       },
       write_bytes: (pathRef, bytesRef) => {
-        const filePath = resolve(runtime.cwd, decodeString(b, pathRef));
-        writeFileSync(filePath, decodeByteArray(b, bytesRef));
+        const filePath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
+        runtime.host.writeBytes(filePath, decodeByteArray(b, bytesRef));
       },
-      stdin_read_chunk: (maxBytes) => makeByteArray(b, readStdinTimeout(maxBytes, 2147483647, runtime)),
-      stdin_read_timeout: (maxBytes, timeoutMs) => makeByteArray(b, readStdinTimeout(maxBytes, timeoutMs, runtime)),
+      stdin_read_chunk: (maxBytes) => makeByteArray(b, runtime.host.readStdin(maxBytes, 2147483647, runtime)),
+      stdin_read_timeout: (maxBytes, timeoutMs) => makeByteArray(b, runtime.host.readStdin(maxBytes, timeoutMs, runtime)),
       stdin_eof: () => runtime.stdinEof ? 1 : 0,
       stdout_write_bytes: (bytesRef) => {
-        const bytes = decodeByteArray(b, bytesRef);
-        if (runtime.stdout?.fd !== undefined) {
-          writeAllFdSync(runtime.stdout.fd, bytes);
-        } else {
-          runtime.stdout.write(Buffer.from(bytes));
-        }
+        // Streams accept a Uint8Array chunk; each adapter's write() handles the
+        // platform write (fd write on Node, writeSync on Deno, postMessage in a
+        // worker), so no Buffer/fd handling is needed here.
+        runtime.stdout.write(decodeByteArray(b, bytesRef));
       },
       mkdirp: (pathRef) => {
-        const dirPath = resolve(runtime.cwd, decodeString(b, pathRef));
-        mkdirSync(dirPath, { recursive: true });
+        const dirPath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
+        runtime.host.mkdirp(dirPath);
       },
       list_dir: (pathRef) => {
-        const dirPath = resolve(runtime.cwd, decodeString(b, pathRef));
-        return makeStringArray(b, readdirSync(dirPath));
+        const dirPath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
+        return makeStringArray(b, runtime.host.listDir(dirPath));
       },
       exists: (pathRef) => {
-        const filePath = resolve(runtime.cwd, decodeString(b, pathRef));
-        return existsSync(filePath) ? 1 : 0;
+        const filePath = runtime.host.resolvePath(runtime.cwd, decodeString(b, pathRef));
+        return runtime.host.exists(filePath) ? 1 : 0;
       },
 
       // --- Parsing ---
@@ -441,6 +361,64 @@ function makeHostImports(b, runtime, bridgeBytes) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// In-memory host adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * A host adapter backed by an in-memory file map — the default for browsers and
+ * other environments without a real filesystem. Reads/writes a `Map<string,
+ * Uint8Array>`; stdin is always EOF. Pure JS (no `node:` deps), so it is safe to
+ * load anywhere.
+ *
+ * @param {Map<string,Uint8Array> | Iterable<[string,Uint8Array]>} [initialFiles]
+ */
+export function createMemoryHost(initialFiles) {
+  const files = initialFiles instanceof Map ? initialFiles : new Map(initialFiles ?? []);
+  const norm = (p) => (p.startsWith("/") ? p : "/" + p).replace(/\/+/g, "/");
+  return {
+    files,
+    resolvePath(cwd, p) {
+      if (p.startsWith("/")) return norm(p);
+      return norm((cwd.endsWith("/") ? cwd : cwd + "/") + p);
+    },
+    readFile(path) {
+      const data = files.get(norm(path));
+      if (data === undefined) throw new Error(`file not found: ${path}`);
+      return data;
+    },
+    writeFile(path, text) { files.set(norm(path), textEncoder.encode(text)); },
+    writeBytes(path, bytes) { files.set(norm(path), bytes); },
+    exists(path) {
+      const np = norm(path);
+      if (files.has(np)) return true;
+      const prefix = np.endsWith("/") ? np : np + "/";
+      for (const k of files.keys()) if (k.startsWith(prefix)) return true;
+      return false;
+    },
+    listDir(path) {
+      const prefix = norm(path).replace(/\/?$/, "/");
+      const names = new Set();
+      for (const k of files.keys()) {
+        if (k.startsWith(prefix)) {
+          const name = k.slice(prefix.length).split("/")[0];
+          if (name) names.add(name);
+        }
+      }
+      return [...names].sort();
+    },
+    mkdirp() { /* virtual dirs are implicit */ },
+    readStdin(_maxBytes, _timeoutMs, runtime) {
+      runtime.stdinEof = true;
+      return new Uint8Array(0);
+    },
+    readStdinAsync(_maxBytes, _timeoutMs, runtime) {
+      runtime.stdinEof = true;
+      return Promise.resolve(new Uint8Array(0));
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Bridge instantiation
 // ---------------------------------------------------------------------------
@@ -467,17 +445,21 @@ function prepareWasm(wasmBytes, opts, { jspi = false } = {}) {
   const {
     programPath = "<memory>.wasm",
     guestArgs = [],
-    cwd = process.cwd(),
-    env = process.env,
-    stdout = process.stdout,
-    stderr = process.stderr,
+    cwd = "/",
+    env = {},
+    stdout,
+    stderr,
     bridgeBytes,
+    host,
     imports = {},
   } = opts;
 
   if (!bridgeBytes) {
     throw new Error("runWasmBytes: bridgeBytes is required");
   }
+  if (!host) {
+    throw new Error("runWasmBytes: host adapter is required (see node_host.mjs)");
+  }
 
   const b = instantiateBridge(bridgeBytes);
   const runtime = {
@@ -487,6 +469,7 @@ function prepareWasm(wasmBytes, opts, { jspi = false } = {}) {
     stdout,
     stderr,
     stdinEof: false,
+    host,
     imports,
   };
 
@@ -520,13 +503,6 @@ export function runWasmBytes(wasmBytes, opts = {}) {
   }
 }
 
-export function runWasmFile(wasmPath, opts = {}) {
-  return runWasmBytes(readFileSync(wasmPath), {
-    programPath: resolve(wasmPath),
-    ...opts,
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Public API — async (JSPI-aware)
 // ---------------------------------------------------------------------------
@@ -535,21 +511,21 @@ export async function runWasmBytesAsync(wasmBytes, opts = {}) {
   const { mainModule, hostImports, b, runtime } = prepareWasm(wasmBytes, opts, { jspi: hasJspi });
 
   if (hasJspi) {
-    // Phase 3: wrap stdin reads as suspending imports so the Node event loop
-    // stays free while Twinkle waits for LSP input. Keep chunk and timeout
-    // reads on the same stream-based path; mixing process.stdin.read() with
-    // fs.readSync(0, ...) can strand bytes in Node's stream buffer.
+    // Wrap stdin reads as suspending imports so the event loop stays free while
+    // Twinkle waits for LSP input. Keep chunk and timeout reads on the same
+    // stream-based path; mixing process.stdin.read() with fs.readSync(0, ...)
+    // can strand bytes in Node's stream buffer.
     hostImports.host.stdin_read_chunk = new WebAssembly.Suspending(
       async (maxBytes) =>
-        makeByteArray(b, await readStdinTimeoutAsync(maxBytes, 2147483647, runtime)),
+        makeByteArray(b, await runtime.host.readStdinAsync(maxBytes, 2147483647, runtime)),
     );
     hostImports.host.stdin_read_timeout = new WebAssembly.Suspending(
       async (maxBytes, timeoutMs) =>
-        makeByteArray(b, await readStdinTimeoutAsync(maxBytes, timeoutMs, runtime)),
+        makeByteArray(b, await runtime.host.readStdinAsync(maxBytes, timeoutMs, runtime)),
     );
 
-    // Phase 4: wrap run_wasm as a suspending import so child programs can
-    // themselves use JSPI suspending imports.
+    // Wrap run_wasm as a suspending import so child programs can themselves use
+    // JSPI suspending imports.
     const childBridgeBytes = opts.bridgeBytes;
     hostImports.host.run_wasm = new WebAssembly.Suspending(
       async (bytesRef, argvRef) => {
@@ -564,6 +540,7 @@ export async function runWasmBytesAsync(wasmBytes, opts = {}) {
           stdout: runtime.stdout,
           stderr: runtime.stderr,
           imports: runtime.imports,
+          host: runtime.host,
           bridgeBytes: childBridgeBytes,
         });
         return BigInt(exitCode);
@@ -589,10 +566,3 @@ export async function runWasmBytesAsync(wasmBytes, opts = {}) {
     throw e;
   }
 }
-
-export async function runWasmFileAsync(wasmPath, opts = {}) {
-  return runWasmBytesAsync(readFileSync(wasmPath), {
-    programPath: resolve(wasmPath),
-    ...opts,
-  });
-}

package/web.mjs

@@ -0,0 +1,77 @@
+// Browser entry for embedding Twinkle.
+//
+//   import { run } from "@twinkle-lang/twinkle/web";
+//   await run(source, { stdout, stderr });
+//
+// Unlike index.mjs (Node: temp files, node:fs), this is browser-first: it
+// self-loads the compiler wasm that ships beside it and uses an in-memory
+// filesystem by default, so callers never touch boot.wasm/bridge.wasm or
+// construct a host adapter.
+
+import { runWasmBytesAsync, createMemoryHost } from "./runtime.mjs";
+
+const textEncoder = new TextEncoder();
+
+// boot.wasm / bridge.wasm are published next to this module. `new URL(...,
+// import.meta.url)` lets the consumer's bundler emit them as assets (Vite,
+// webpack, native ESM all understand this), so no `?url` import is needed.
+let assetsPromise;
+
+function loadAssets() {
+  if (!assetsPromise) {
+    assetsPromise = Promise.all([
+      fetch(new URL("./boot.wasm", import.meta.url)).then((r) => r.arrayBuffer()),
+      fetch(new URL("./bridge.wasm", import.meta.url)).then((r) => r.arrayBuffer()),
+    ]).then(([boot, bridge]) => ({
+      bootBytes: new Uint8Array(boot),
+      bridgeBytes: new Uint8Array(bridge),
+    }));
+  }
+  return assetsPromise;
+}
+
+/** Pre-fetch the compiler wasm so the first run() doesn't pay the load latency. */
+export function load() {
+  return loadAssets();
+}
+
+const defaultStream = (sink) => ({
+  write(chunk) {
+    sink(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+    return true;
+  },
+});
+
+/**
+ * Compile and run Twinkle source in the browser.
+ *
+ * @param {string | Uint8Array} source  Twinkle source for the entry module.
+ * @param {object} [opts]
+ * @param {object} [opts.stdout]   Stream with write(chunk); defaults to console.log.
+ * @param {object} [opts.stderr]   Stream with write(chunk); defaults to console.error.
+ * @param {object} [opts.env]      Environment map exposed to the program.
+ * @param {object} [opts.imports]  Extern imports — `module → fn | { fn?, args? }`
+ *   (else resolved via globalThis). `args` is the per-arg spec, e.g.
+ *   `{ canvas: { fill_rect: { fn, args: ['raw','raw','raw','raw','raw'] } } }`.
+ * @param {Iterable<[string,Uint8Array]>} [opts.files]  Extra in-memory files (multi-file projects).
+ * @param {object} [opts.host]     Override the host adapter entirely (advanced).
+ * @returns {Promise<number>} exit code
+ */
+export async function run(source, opts = {}) {
+  const { bootBytes, bridgeBytes } = await loadAssets();
+
+  const files = new Map(opts.files ?? []);
+  files.set("/input/main.tw", typeof source === "string" ? textEncoder.encode(source) : source);
+
+  return runWasmBytesAsync(bootBytes, {
+    programPath: "twk.wasm",
+    guestArgs: ["run", "/input/main.tw"],
+    cwd: "/",
+    env: opts.env ?? {},
+    stdout: opts.stdout ?? defaultStream((s) => console.log(s)),
+    stderr: opts.stderr ?? defaultStream((s) => console.error(s)),
+    bridgeBytes,
+    host: opts.host ?? createMemoryHost(files),
+    imports: opts.imports ?? {},
+  });
+}