@tinysandbox/js-runtime 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Goodman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# `@tinysandbox/js-runtime`
+
+A small, stateless QuickJS runtime for standard WebAssembly hosts. It has no
+runtime dependencies and uses the same checked-in QuickJS-ng artifact and guest
+glue as tinysandbox's Rust/Wasmtime `js` command.
+
+The package never reads a file or calls `fetch` itself. Supply the wasm bytes or
+a compiled `WebAssembly.Module` explicitly, compile an engine once, and call
+`runCode()` as needed. Every call creates a new bounded linear memory, wasm
+instance, QuickJS runtime, and context; no guest state survives the call.
+
+```js
+import { readFile } from "node:fs/promises";
+import { createEngine } from "@tinysandbox/js-runtime";
+
+const bytes = await readFile(new URL(
+  "./node_modules/@tinysandbox/js-runtime/quickjs.wasm",
+  import.meta.url,
+));
+const engine = await createEngine(bytes);
+
+const result = engine.runCode("console.log(tools.search({ query: 'hello' }))", {
+  globals: {
+    "tools.search": ({ query }) => ({ query, hits: 1 }),
+  },
+  timeoutMs: 1000,
+  wasmMemoryBytes: 16 * 1024 * 1024,
+  quickjsHeapBytes: 8 * 1024 * 1024,
+});
+```
+
+Browser callers can fetch the exported `quickjs.wasm` asset themselves. Hosts
+such as Convex that compile `.wasm` imports use the exported subpath directly:
+
+```ts
+import { createEngine } from "@tinysandbox/js-runtime";
+import quickjsModule from "@tinysandbox/js-runtime/quickjs.wasm";
+
+const value = await doConvexWork();
+const engine = await createEngine(quickjsModule);
+const result = engine.runCode("console.log(context.value(null))", {
+  globals: { "context.value": () => value },
+});
+```
+
+`runCode(code, options)` returns `exitCode`, UTF-8 `stdout` and `stderr`, and
+initial/peak wasm memory bytes. Its defaults are a 64 MiB wasm maximum, 32 MiB
+QuickJS heap, 30 second monotonic deadline, and 1 MiB each for source, serialized
+host responses, stdout, and stderr. A `wasmMemoryBytes` value below the artifact
+minimum of 1,245,184 bytes is rejected before instantiation. Non-page-aligned
+values are rounded down for the actual WebAssembly maximum.
+
+Global names use dot-separated JavaScript identifier segments. Each value must
+be a synchronous one-argument function. Guest arguments cross the boundary
+with JavaScript's normal `JSON.stringify` semantics (including its omission and
+coercion rules); host return values must already be strict JSON values and are
+validated without coercion. Promises, invalid returns, invalid names, namespace
+conflicts, and runtime-global shadowing fail deterministically. Complete awaited
+host work before calling `runCode()`; wasm execution is synchronous and blocks
+the V8 event loop until it finishes.
+
+## Optional filesystem capability
+
+Pass a synchronous `Vfs` implementation to enable the same `Buffer`, `fs`
+subset, and relative/absolute CommonJS loader as tinysandbox's `/bin/js`:
+
+```ts
+const result = engine.runFile("main.js", {
+  vfs,
+  cwd: "/app",
+  argv: ["js", "main.js", "one"],
+});
+```
+
+`runFile()` resolves the entry against `cwd`, reads it through
+`open`/`readAt`/`close`, rejects invalid UTF-8, and evaluates it with the
+resolved path as `__filename` and the stack filename. If `argv` is omitted, it
+defaults to `["js", originalPath]`, preserving the path string passed by the
+caller. Relative `require()` resolves from the requiring module; direct `fs`
+paths resolve from `cwd`.
+
+The exported `Vfs` interface is deliberately small and synchronous: `stat`,
+`readdir`, `mkdir`, `rename`, `unlink`, `rmdir`, `open`, `readAt`, `writeAt`,
+`truncate`, and `close`. Paths delivered to it are normalized absolute paths;
+handles and offsets are non-negative safe integers, and positional operations
+do not change the guest fd cursor. Implementations report one of the exported
+`VfsErrno` strings by throwing `new VfsError(code)`. Quotas and storage
+accounting belong to the supplied implementation. The package provides no
+production filesystem or storage backend; the repository's `TestVfs` exists
+only under `test/` for examples and conformance tests.
+
+Omitting `vfs` leaves the run storage-independent: `Buffer` is absent and both
+`require("fs")` and file-module requests throw
+`ERR_CAPABILITY_UNAVAILABLE` before any filesystem host call. This stateless
+package also does not provide network access, timers, guest ESM, TypeScript
+transpilation, Asyncify/JSPI, or persistent isolates. The compatibility glue's
+`fetch` never reaches ambient V8 networking and fails with unavailable-host
+capability behavior.

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+export type HostGlobal = (argument: JsonValue) => JsonValue;
+
+export type VfsErrno = "EBADF" | "EBUSY" | "EXDEV" | "EACCES" | "EEXIST" | "EFBIG" | "EIO" | "EINVAL" | "EISDIR" | "ENOENT" | "ENOSPC" | "ENOTDIR" | "ENOTEMPTY";
+
+export declare class VfsError extends Error {
+  readonly code: VfsErrno;
+  constructor(code: VfsErrno, message?: string);
+}
+
+export interface VfsMetadata {
+  fileType: "file" | "directory";
+  len: number;
+}
+
+export interface VfsDirEntry {
+  name: string;
+  metadata: VfsMetadata;
+}
+
+export interface VfsOpenMode {
+  read: boolean;
+  write: boolean;
+  create: boolean;
+  createNew: boolean;
+  truncate: boolean;
+  append: boolean;
+}
+
+/** Synchronous, absolute-path, handle-and-offset filesystem capability. */
+export interface Vfs {
+  stat(path: string): VfsMetadata;
+  readdir(path: string): VfsDirEntry[];
+  mkdir(path: string): void;
+  rename(from: string, to: string): void;
+  unlink(path: string): void;
+  rmdir(path: string): void;
+  open(path: string, mode: VfsOpenMode): number;
+  readAt(handle: number, offset: number, buffer: Uint8Array): number;
+  writeAt(handle: number, offset: number, data: Uint8Array): number;
+  truncate(handle: number, len: number): void;
+  close(handle: number): void;
+}
+
+export interface RunCodeOptions {
+  globals?: Record<string, HostGlobal>;
+  vfs?: Vfs;
+  wasmMemoryBytes?: number;
+  quickjsHeapBytes?: number;
+  timeoutMs?: number;
+  sourceBytes?: number;
+  hostResponseBytes?: number;
+  stdoutBytes?: number;
+  stderrBytes?: number;
+  scriptPath?: string;
+  argv?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export interface RunFileOptions extends Omit<RunCodeOptions, "vfs" | "scriptPath"> {
+  vfs: Vfs;
+}
+
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  initialWasmMemoryBytes: number;
+  peakWasmMemoryBytes: number;
+}
+
+export interface JsEngine {
+  runCode(code: string, options?: RunCodeOptions): RunResult;
+  runFile(path: string, options: RunFileOptions): RunResult;
+}
+
+export declare const QUICKJS_INITIAL_MEMORY_BYTES: number;
+export declare function createEngine(wasm: BufferSource | WebAssembly.Module): Promise<JsEngine>;

package/dist/index.js

@@ -0,0 +1,764 @@
+// @ts-nocheck -- this source intentionally uses only JavaScript syntax so the
+// zero-dependency build can copy it verbatim to the ESM distribution.
+const PAGE_BYTES = 64 * 1024;
+const INITIAL_PAGES = 19;
+const DEFAULT_WASM_MEMORY_BYTES = 64 * 1024 * 1024;
+const DEFAULT_QUICKJS_HEAP_BYTES = 32 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_SOURCE_BYTES = 1024 * 1024;
+const DEFAULT_HOST_RESPONSE_BYTES = 1024 * 1024;
+const DEFAULT_OUTPUT_BYTES = 1024 * 1024;
+const MAX_HOST_READ_BYTES = 16 * 1024 * 1024;
+const VFS_OPERATIONS = new Set([
+  "readFile", "writeFile", "appendFile", "mkdir", "readdir", "stat", "rename",
+  "rm", "unlink", "rmdir", "exists", "open", "read", "write", "ftruncate",
+  "close", "copyFile",
+]);
+const RESERVED_GLOBALS = new Set([
+  "Buffer", "Headers", "Response", "__dirname", "__filename", "console",
+  "exports", "fetch", "globalThis", "module", "process", "require",
+]);
+const ABI_VERSION = 12;
+const REQUIRED_IMPORTS = [
+  "env.memory:memory",
+  "tinysandbox.host_call:function",
+  "tinysandbox.host_response_len:function",
+  "tinysandbox.host_response_read:function",
+  "tinysandbox.should_interrupt:function",
+  "tinysandbox.write_stderr:function",
+  "tinysandbox.write_stdout:function",
+  "wasi_snapshot_preview1.clock_time_get:function",
+  "wasi_snapshot_preview1.fd_close:function",
+  "wasi_snapshot_preview1.fd_fdstat_get:function",
+  "wasi_snapshot_preview1.fd_seek:function",
+  "wasi_snapshot_preview1.fd_write:function",
+].sort();
+const REQUIRED_EXPORTS = [
+  "_initialize:function",
+  "memory:memory",
+  "tinysandbox_abi_version:function",
+  "tinysandbox_alloc:function",
+  "tinysandbox_free:function",
+  "tinysandbox_run:function",
+].sort();
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
+
+export const QUICKJS_INITIAL_MEMORY_BYTES = INITIAL_PAGES * PAGE_BYTES;
+
+const VFS_ERRNOS = Object.freeze({
+  EBADF: [-9, "bad file descriptor"],
+  EBUSY: [-16, "resource busy or locked"],
+  EXDEV: [-18, "cross-device link not permitted"],
+  EACCES: [-13, "permission denied"],
+  EEXIST: [-17, "file already exists"],
+  EFBIG: [-27, "file too large"],
+  EIO: [-5, "i/o error"],
+  EINVAL: [-22, "invalid argument"],
+  EISDIR: [-21, "illegal operation on a directory"],
+  ENOENT: [-2, "no such file or directory"],
+  ENOSPC: [-28, "no space left on device"],
+  ENOTDIR: [-20, "not a directory"],
+  ENOTEMPTY: [-66, "directory not empty"],
+});
+
+export class VfsError extends Error {
+  constructor(code, message = code) {
+    if (!Object.hasOwn(VFS_ERRNOS, code)) throw new TypeError(`unsupported VFS errno '${String(code)}'`);
+    super(message);
+    this.name = "VfsError";
+    this.code = code;
+  }
+}
+
+class RunLimitError extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
+
+function integerOption(name, value, fallback, minimum = 0) {
+  const result = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(result) || result < minimum) {
+    throw new TypeError(`${name} must be a safe integer of at least ${minimum}`);
+  }
+  return result;
+}
+
+function validateGlobals(globals) {
+  if (globals === undefined) return [];
+  if (globals === null || typeof globals !== "object" || Array.isArray(globals)) {
+    throw new TypeError("globals must be an object of synchronous functions");
+  }
+  const names = Object.keys(globals).sort();
+  for (const name of names) {
+    if (typeof globals[name] !== "function") {
+      throw new TypeError(`global '${name}' must be a function`);
+    }
+    const parts = name.split(".");
+    if (parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
+      throw new TypeError(`cannot register invalid name '${name}'; names are dot-separated paths of [A-Za-z_][A-Za-z0-9_]* segments`);
+    }
+    if (RESERVED_GLOBALS.has(parts[0])) {
+      throw new TypeError(`cannot register reserved name '${name}'; '${parts[0]}' is provided by the JavaScript runtime`);
+    }
+  }
+  for (let index = 1; index < names.length; index++) {
+    const previous = names[index - 1];
+    const current = names[index];
+    if (current.startsWith(`${previous}.`)) {
+      throw new TypeError(`cannot register '${current}'; it conflicts with '${previous}'`);
+    }
+  }
+  return names;
+}
+
+function requireArtifactAbi(module) {
+  const imports = WebAssembly.Module.imports(module);
+  const actualImports = imports.map((entry) => `${entry.module}.${entry.name}:${entry.kind}`).sort();
+  const actualExports = WebAssembly.Module.exports(module).map((entry) => `${entry.name}:${entry.kind}`).sort();
+  if (JSON.stringify(actualImports) !== JSON.stringify(REQUIRED_IMPORTS)) throw new TypeError(`incompatible QuickJS wasm imports: ${actualImports.join(", ")}`);
+  if (JSON.stringify(actualExports) !== JSON.stringify(REQUIRED_EXPORTS)) throw new TypeError(`incompatible QuickJS wasm exports: ${actualExports.join(", ")}`);
+}
+
+function probeArtifactAbi(module) {
+  const memory = new WebAssembly.Memory({ initial: INITIAL_PAGES, maximum: 65_536 });
+  const zero = () => 0;
+  let instance;
+  try {
+    instance = new WebAssembly.Instance(module, {
+      env: { memory },
+      tinysandbox: { host_call: zero, host_response_len: zero, host_response_read: zero, should_interrupt: zero, write_stderr: zero, write_stdout: zero },
+      wasi_snapshot_preview1: { clock_time_get: zero, fd_close: zero, fd_fdstat_get: zero, fd_seek: zero, fd_write: zero },
+    });
+  } catch (error) {
+    throw new TypeError(`incompatible QuickJS wasm memory contract: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (instance.exports.memory !== memory) throw new TypeError("incompatible QuickJS wasm: env.memory is not re-exported");
+  for (const [name, arity] of [["tinysandbox_abi_version", 0], ["tinysandbox_alloc", 1], ["tinysandbox_free", 1], ["tinysandbox_run", 3]]) {
+    if (instance.exports[name].length !== arity) throw new TypeError(`incompatible QuickJS wasm export signature '${name}'`);
+  }
+  if (instance.exports.tinysandbox_abi_version() !== ABI_VERSION) throw new TypeError(`incompatible QuickJS wasm ABI version; expected ${ABI_VERSION}`);
+}
+
+function writeU32(memory, pointer, value) {
+  new DataView(memory.buffer).setUint32(pointer, value >>> 0, true);
+}
+
+function monotonicNow() {
+  const now = globalThis.performance?.now;
+  if (typeof now !== "function") {
+    throw new Error("@tinysandbox/js-runtime requires performance.now() for monotonic deadlines");
+  }
+  return now.call(globalThis.performance);
+}
+
+function jsonError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error && typeof error === "object" && typeof error.code === "string" ? error.code : undefined;
+  return code === undefined ? { message } : { message, code };
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return;
+    throw new TypeError(`${path} must contain only finite JSON numbers`);
+  }
+  if (typeof value !== "object") throw new TypeError(`${path} must contain only JSON-safe values`);
+  if (seen.has(value)) throw new TypeError(`${path} must not contain cycles`);
+  const prototype = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`${path} must contain only plain objects and arrays`);
+  }
+  if (Object.getOwnPropertySymbols(value).length !== 0) throw new TypeError(`${path} must not contain symbol keys`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.hasOwn(value, index)) throw new TypeError(`${path} must not contain array holes`);
+      assertJsonValue(value[index], `${path}[${index}]`, seen);
+    }
+  } else {
+    for (const key of Object.keys(value)) assertJsonValue(value[key], `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+
+class HostCallFailure extends Error {
+  constructor(payload) {
+    super(payload.message);
+    this.payload = payload;
+  }
+}
+
+function vfsFailure(error, syscall, path) {
+  const code = error && typeof error === "object" && typeof error.code === "string" && Object.hasOwn(VFS_ERRNOS, error.code)
+    ? error.code
+    : "EIO";
+  const [errno, message] = VFS_ERRNOS[code];
+  return new HostCallFailure({ code, errno, message, syscall, ...(path === undefined ? {} : { path }) });
+}
+
+function invalidVfsCall(syscall, path) {
+  return vfsFailure(new VfsError("EINVAL"), syscall, path);
+}
+
+function validateVfs(vfs) {
+  if (vfs === null || typeof vfs !== "object") throw new TypeError("vfs must be an object implementing the synchronous Vfs interface");
+  for (const method of ["stat", "readdir", "mkdir", "rename", "unlink", "rmdir", "open", "readAt", "writeAt", "truncate", "close"]) {
+    if (typeof vfs[method] !== "function") throw new TypeError(`vfs.${method} must be a function`);
+  }
+  return vfs;
+}
+
+function callVfs(vfs, method, args, syscall, path) {
+  try {
+    const value = vfs[method](...args);
+    if (value && typeof value === "object" && typeof value.then === "function") {
+      // Async VFS methods are unsupported, but attach a rejection handler so a
+      // mistaken async implementation cannot escape this deterministic error.
+      try { value.then(() => {}, () => {}); } catch {}
+      throw new TypeError(`vfs.${method} returned a Promise; Vfs methods must be synchronous`);
+    }
+    return value;
+  } catch (error) {
+    throw vfsFailure(error, syscall, path);
+  }
+}
+
+function normalizeAbsolute(path) {
+  const parts = [];
+  for (const part of String(path).split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return parts.length === 0 ? "/" : `/${parts.join("/")}`;
+}
+
+function resolvePath(cwd, path) {
+  return normalizeAbsolute(String(path).startsWith("/") ? path : cwd === "/" ? `/${path}` : `${cwd}/${path}`);
+}
+
+function checkedInteger(value, syscall, path, nullable = false) {
+  if (nullable && (value === null || value === undefined)) return null;
+  if (!Number.isSafeInteger(value) || value < 0) throw invalidVfsCall(syscall, path);
+  return value;
+}
+
+function checkedMetadata(value, syscall, path) {
+  if (!value || typeof value !== "object" || !["file", "directory"].includes(value.fileType) || !Number.isSafeInteger(value.len) || value.len < 0) {
+    throw vfsFailure(new Error("invalid VFS metadata"), syscall, path);
+  }
+  return value;
+}
+
+function encodeBase64(data) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let output = "";
+  for (let index = 0; index < data.byteLength; index += 3) {
+    const first = data[index];
+    const second = index + 1 < data.byteLength ? data[index + 1] : 0;
+    const third = index + 2 < data.byteLength ? data[index + 2] : 0;
+    const bits = (first << 16) | (second << 8) | third;
+    output += chars[(bits >>> 18) & 63] + chars[(bits >>> 12) & 63]
+      + (index + 1 < data.byteLength ? chars[(bits >>> 6) & 63] : "=")
+      + (index + 2 < data.byteLength ? chars[bits & 63] : "=");
+  }
+  return output;
+}
+
+function decodeBase64(value) {
+  const input = String(value);
+  if (input.length === 0) return new Uint8Array();
+  if (input.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(input)) {
+    throw invalidVfsCall("tinysandbox");
+  }
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  const padding = input.endsWith("==") ? 2 : input.endsWith("=") ? 1 : 0;
+  const output = new Uint8Array(input.length / 4 * 3 - padding);
+  let outputIndex = 0;
+  for (let index = 0; index < input.length; index += 4) {
+    const bits = (chars.indexOf(input[index]) << 18) | (chars.indexOf(input[index + 1]) << 12)
+      | ((input[index + 2] === "=" ? 0 : chars.indexOf(input[index + 2])) << 6)
+      | (input[index + 3] === "=" ? 0 : chars.indexOf(input[index + 3]));
+    output[outputIndex++] = (bits >>> 16) & 255;
+    if (outputIndex < output.length) output[outputIndex++] = (bits >>> 8) & 255;
+    if (outputIndex < output.length) output[outputIndex++] = bits & 255;
+  }
+  return output;
+}
+
+function openMode(flags, path) {
+  switch (flags) {
+    case "r": return { read: true, write: false, create: false, createNew: false, truncate: false, append: false };
+    case "r+": return { read: true, write: true, create: false, createNew: false, truncate: false, append: false };
+    case "w": return { read: false, write: true, create: true, createNew: false, truncate: true, append: false };
+    case "wx": case "xw": return { read: false, write: true, create: true, createNew: true, truncate: true, append: false };
+    case "w+": return { read: true, write: true, create: true, createNew: false, truncate: true, append: false };
+    case "wx+": case "w+x": case "xw+": case "x+w": return { read: true, write: true, create: true, createNew: true, truncate: true, append: false };
+    case "a": return { read: false, write: true, create: true, createNew: false, truncate: false, append: true };
+    case "ax": case "xa": return { read: false, write: true, create: true, createNew: true, truncate: false, append: true };
+    case "a+": return { read: true, write: true, create: true, createNew: false, truncate: false, append: true };
+    case "ax+": case "a+x": case "xa+": case "x+a": return { read: true, write: true, create: true, createNew: true, truncate: false, append: true };
+    default: throw invalidVfsCall("open", path);
+  }
+}
+
+function openVfs(vfs, path, mode) {
+  const handle = callVfs(vfs, "open", [path, mode], "open", path);
+  if (!Number.isSafeInteger(handle) || handle < 0) {
+    try { callVfs(vfs, "close", [handle], "close"); } catch {}
+    throw vfsFailure(new Error("invalid VFS handle"), "open", path);
+  }
+  return handle;
+}
+
+function readAll(vfs, path, maximumBytes = Number.MAX_SAFE_INTEGER) {
+  const handle = openVfs(vfs, path, openMode("r", path));
+  const chunks = [];
+  let length = 0;
+  let failure;
+  try {
+    for (;;) {
+      const buffer = new Uint8Array(Math.min(8192, maximumBytes - Math.min(length, maximumBytes) + 1));
+      const count = callVfs(vfs, "readAt", [handle, length, buffer], "read");
+      if (!Number.isSafeInteger(count) || count < 0 || count > buffer.byteLength) throw vfsFailure(new Error("invalid VFS read count"), "read");
+      if (count === 0) break;
+      chunks.push(buffer.slice(0, count));
+      length += count;
+      if (length > maximumBytes) throw new RangeError(`source exceeded limit of ${maximumBytes} bytes`);
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    callVfs(vfs, "close", [handle], "close");
+  } catch (error) {
+    if (failure === undefined) failure = error;
+  }
+  if (failure !== undefined) throw failure;
+  return join(chunks, length);
+}
+
+function writeAll(vfs, path, data, append) {
+  const mode = openMode(append ? "a" : "w", path);
+  const handle = openVfs(vfs, path, mode);
+  let written = 0;
+  let failure;
+  try {
+    while (written < data.byteLength) {
+      const count = callVfs(vfs, "writeAt", [handle, written, data.subarray(written)], "write");
+      if (!Number.isSafeInteger(count) || count < 0 || count > data.byteLength - written) throw vfsFailure(new Error("invalid VFS write count"), "write");
+      if (count === 0) throw vfsFailure(new VfsError("ENOSPC"), "write");
+      written += count;
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    callVfs(vfs, "close", [handle], "close");
+  } catch (error) {
+    if (failure === undefined) failure = error;
+  }
+  if (failure !== undefined) throw failure;
+}
+
+function createVfsDispatcher(vfs, cwd) {
+  validateVfs(vfs);
+  const files = new Map();
+  let nextFd = 3;
+  const absolute = (value) => {
+    if (typeof value !== "string") throw invalidVfsCall("tinysandbox");
+    return resolvePath(cwd, value);
+  };
+  const metadata = (path, syscall = "stat") => checkedMetadata(callVfs(vfs, "stat", [path], syscall, path), syscall, path);
+  const mkdirRecursive = (path) => {
+    if (path === "/") return;
+    let current = "";
+    for (const part of path.slice(1).split("/")) {
+      current += `/${part}`;
+      try {
+        callVfs(vfs, "mkdir", [current], "mkdir", path);
+      } catch (error) {
+        if (!(error instanceof HostCallFailure) || error.payload.code !== "EEXIST" || metadata(current).fileType !== "directory") throw error;
+      }
+    }
+  };
+  const removePath = (path, recursive) => {
+    const info = metadata(path, "rm");
+    if (info.fileType === "file") return callVfs(vfs, "unlink", [path], "unlink", path);
+    if (!recursive) throw vfsFailure(new VfsError("EISDIR"), "rm", path);
+    const entries = callVfs(vfs, "readdir", [path], "scandir", path);
+    if (!Array.isArray(entries)) throw vfsFailure(new Error("invalid VFS directory entries"), "scandir", path);
+    for (const entry of entries) {
+      if (!entry || typeof entry.name !== "string" || entry.name.includes("/")) throw vfsFailure(new Error("invalid VFS directory entry"), "scandir", path);
+      removePath(path === "/" ? `/${entry.name}` : `${path}/${entry.name}`, true);
+    }
+    return callVfs(vfs, "rmdir", [path], "rmdir", path);
+  };
+  const dispatch = (op, args) => {
+    switch (op) {
+      case "readFile": {
+        const path = absolute(args?.path);
+        return encodeBase64(remapHostFailure(() => readAll(vfs, path), "open", path));
+      }
+      case "writeFile": {
+        const path = absolute(args?.path);
+        remapHostFailure(() => writeAll(vfs, path, decodeBase64(args?.data), false), "open", path);
+        return null;
+      }
+      case "appendFile": {
+        const path = absolute(args?.path);
+        remapHostFailure(() => writeAll(vfs, path, decodeBase64(args?.data), true), "open", path);
+        return null;
+      }
+      case "mkdir": { const path = absolute(args?.path); args?.recursive ? mkdirRecursive(path) : callVfs(vfs, "mkdir", [path], "mkdir", path); return null; }
+      case "readdir": {
+        const path = absolute(args?.path);
+        const entries = callVfs(vfs, "readdir", [path], "scandir", path);
+        if (!Array.isArray(entries)) throw vfsFailure(new Error("invalid VFS directory entries"), "scandir", path);
+        return entries.map((entry) => {
+          if (!entry || typeof entry.name !== "string" || entry.name.includes("/")) throw vfsFailure(new Error("invalid VFS directory entry"), "scandir", path);
+          if (!args?.withFileTypes) return entry.name;
+          const info = checkedMetadata(entry.metadata, "scandir", path);
+          return { name: entry.name, isFile: info.fileType === "file", isDirectory: info.fileType === "directory" };
+        });
+      }
+      case "stat": { const info = metadata(absolute(args?.path)); return { size: info.len, isFile: info.fileType === "file", isDirectory: info.fileType === "directory" }; }
+      case "rename": { const from = absolute(args?.from); const to = absolute(args?.to); callVfs(vfs, "rename", [from, to], "rename", from); return null; }
+      case "rm": {
+        const path = absolute(args?.path);
+        try { removePath(path, !!args?.recursive); } catch (error) { if (!(args?.force && error instanceof HostCallFailure && error.payload.code === "ENOENT")) throw error; }
+        return null;
+      }
+      case "unlink": { const path = absolute(args?.path); callVfs(vfs, "unlink", [path], "unlink", path); return null; }
+      case "rmdir": { const path = absolute(args?.path); args?.recursive ? removePath(path, true) : callVfs(vfs, "rmdir", [path], "rmdir", path); return null; }
+      case "exists": { try { metadata(absolute(args?.path)); return true; } catch { return false; } }
+      case "open": {
+        const path = absolute(args?.path);
+        const handle = openVfs(vfs, path, openMode(args?.flags, path));
+        const fd = nextFd++;
+        files.set(fd, { handle, position: 0, path });
+        return fd;
+      }
+      case "read": {
+        const fd = checkedInteger(args?.fd, "tinysandbox");
+        const file = files.get(fd);
+        if (!file) throw vfsFailure(new VfsError("EBADF"), "read");
+        const position = checkedInteger(args?.position, "tinysandbox", undefined, true);
+        const offset = position ?? file.position;
+        let length = Math.min(MAX_HOST_READ_BYTES, checkedInteger(args?.length, "tinysandbox"));
+        try { const info = metadata(file.path); if (info.fileType === "file") length = Math.min(length, Math.max(0, info.len - offset)); } catch {}
+        const buffer = new Uint8Array(length);
+        const count = callVfs(vfs, "readAt", [file.handle, offset, buffer], "read");
+        if (!Number.isSafeInteger(count) || count < 0 || count > length) throw vfsFailure(new Error("invalid VFS read count"), "read");
+        if (position === null) file.position += count;
+        return { bytesRead: count, data: encodeBase64(buffer.subarray(0, count)) };
+      }
+      case "write": {
+        const fd = checkedInteger(args?.fd, "tinysandbox");
+        const file = files.get(fd);
+        if (!file) throw vfsFailure(new VfsError("EBADF"), "write");
+        const position = checkedInteger(args?.position, "tinysandbox", undefined, true);
+        const offset = position ?? file.position;
+        const data = decodeBase64(args?.data);
+        const count = callVfs(vfs, "writeAt", [file.handle, offset, data], "write");
+        if (!Number.isSafeInteger(count) || count < 0 || count > data.byteLength) throw vfsFailure(new Error("invalid VFS write count"), "write");
+        if (position === null) file.position += count;
+        return count;
+      }
+      case "ftruncate": {
+        const fd = checkedInteger(args?.fd, "tinysandbox");
+        const file = files.get(fd);
+        if (!file) throw vfsFailure(new VfsError("EBADF"), "ftruncate");
+        callVfs(vfs, "truncate", [file.handle, checkedInteger(args?.len ?? 0, "tinysandbox")], "ftruncate");
+        return null;
+      }
+      case "close": {
+        const fd = checkedInteger(args?.fd, "tinysandbox");
+        const file = files.get(fd);
+        if (!file) throw vfsFailure(new VfsError("EBADF"), "close");
+        files.delete(fd);
+        callVfs(vfs, "close", [file.handle], "close");
+        return null;
+      }
+      case "copyFile": {
+        const source = absolute(args?.src);
+        const destination = absolute(args?.dest);
+        const data = remapHostFailure(() => readAll(vfs, source), "copyfile", source);
+        remapHostFailure(() => writeAll(vfs, destination, data, false), "copyfile", destination);
+        return null;
+      }
+      default: throw invalidVfsCall("tinysandbox");
+    }
+  };
+  const closeAll = () => {
+    for (const { handle } of files.values()) {
+      try { callVfs(vfs, "close", [handle], "close"); } catch {}
+    }
+    files.clear();
+  };
+  return { dispatch, closeAll };
+}
+
+function exposedHostError(payload) {
+  const where = payload.path === undefined ? (payload.syscall ? `, ${payload.syscall}` : "") : `, ${payload.syscall} '${payload.path}'`;
+  const error = new Error(`${payload.code}: ${payload.message}${where}`);
+  error.code = payload.code;
+  error.errno = payload.errno;
+  error.syscall = payload.syscall;
+  if (payload.path !== undefined) error.path = payload.path;
+  return error;
+}
+
+function remapHostFailure(operation, syscall, path) {
+  try {
+    return operation();
+  } catch (error) {
+    if (error instanceof HostCallFailure) throw vfsFailure(new VfsError(error.payload.code), syscall, path);
+    throw error;
+  }
+}
+
+export async function createEngine(wasm) {
+  let module;
+  if (wasm instanceof WebAssembly.Module) {
+    module = wasm;
+  } else if (ArrayBuffer.isView(wasm) || wasm instanceof ArrayBuffer) {
+    module = await WebAssembly.compile(wasm);
+  } else {
+    throw new TypeError("createEngine expects wasm bytes or a WebAssembly.Module");
+  }
+  requireArtifactAbi(module);
+  probeArtifactAbi(module);
+
+  const engine = {
+    runCode(code, options = {}) {
+      if (typeof code !== "string") throw new TypeError("code must be a string");
+      if (options === null || typeof options !== "object") throw new TypeError("options must be an object");
+
+      const wasmMemoryBytes = integerOption("wasmMemoryBytes", options.wasmMemoryBytes, DEFAULT_WASM_MEMORY_BYTES);
+      const maximumPages = Math.min(65_536, Math.floor(wasmMemoryBytes / PAGE_BYTES));
+      if (maximumPages < INITIAL_PAGES) {
+        throw new RangeError(`wasmMemoryBytes must be at least ${QUICKJS_INITIAL_MEMORY_BYTES} bytes`);
+      }
+      const quickjsHeapBytes = integerOption("quickjsHeapBytes", options.quickjsHeapBytes, DEFAULT_QUICKJS_HEAP_BYTES, 1);
+      if (quickjsHeapBytes > 0x7fff_ffff) throw new RangeError("quickjsHeapBytes must be at most 2147483647");
+      const timeoutMs = integerOption("timeoutMs", options.timeoutMs, DEFAULT_TIMEOUT_MS, 1);
+      const sourceBytes = integerOption("sourceBytes", options.sourceBytes, DEFAULT_SOURCE_BYTES);
+      const hostResponseBytes = integerOption("hostResponseBytes", options.hostResponseBytes, DEFAULT_HOST_RESPONSE_BYTES);
+      const stdoutBytes = integerOption("stdoutBytes", options.stdoutBytes, DEFAULT_OUTPUT_BYTES);
+      const stderrBytes = integerOption("stderrBytes", options.stderrBytes, DEFAULT_OUTPUT_BYTES);
+      const sourceLength = encoder.encode(code).byteLength;
+      if (sourceLength > sourceBytes) throw new RangeError(`source exceeded limit of ${sourceBytes} bytes`);
+      const globals = options.globals ?? {};
+      const globalNames = validateGlobals(globals);
+      const vfs = options.vfs === undefined ? undefined : validateVfs(options.vfs);
+      const started = monotonicNow();
+      const deadline = started + timeoutMs;
+      const memory = new WebAssembly.Memory({ initial: INITIAL_PAGES, maximum: maximumPages });
+      const stdout = [];
+      const stderr = [];
+      let stdoutLength = 0;
+      let stderrLength = 0;
+      let response = new Uint8Array();
+      let timedOut = false;
+      let limitFailure;
+      const vfsDispatcher = vfs === undefined ? undefined : createVfsDispatcher(vfs, resolvePath("/", options.cwd ?? "/"));
+
+      const read = (pointer, length) => {
+        if (!Number.isInteger(pointer) || !Number.isInteger(length) || pointer < 0 || length < 0 || pointer + length > memory.buffer.byteLength) {
+          throw new WebAssembly.RuntimeError("guest memory access out of bounds");
+        }
+        return new Uint8Array(memory.buffer, pointer, length);
+      };
+      const capture = (target, pointer, length, cap, stream) => {
+        const current = stream === "stdout" ? stdoutLength : stderrLength;
+        if (length > cap - current) {
+          limitFailure = new RunLimitError(stream, `${stream} exceeded limit of ${cap} bytes`);
+          throw limitFailure;
+        }
+        target.push(read(pointer, length).slice());
+        if (stream === "stdout") stdoutLength += length;
+        else stderrLength += length;
+        return length;
+      };
+      const setResponse = (value) => {
+        let bytes;
+        try {
+          bytes = encoder.encode(JSON.stringify(value));
+        } catch (error) {
+          bytes = encoder.encode(JSON.stringify({ error: jsonError(error) }));
+        }
+        if (bytes.byteLength > hostResponseBytes) {
+          bytes = encoder.encode(JSON.stringify({ error: { code: "E2BIG", message: `host response exceeded limit of ${hostResponseBytes} bytes` } }));
+          if (bytes.byteLength > hostResponseBytes) {
+            limitFailure = new RunLimitError("hostResponse", `host response exceeded limit of ${hostResponseBytes} bytes`);
+            throw limitFailure;
+          }
+        }
+        response = bytes;
+      };
+      const tinysandbox = {
+        should_interrupt() {
+          if (monotonicNow() >= deadline) timedOut = true;
+          return timedOut ? 1 : 0;
+        },
+        host_call(opPointer, opLength, jsonPointer, jsonLength) {
+          const op = decoder.decode(read(opPointer, opLength));
+          let argument;
+          try {
+            argument = JSON.parse(decoder.decode(read(jsonPointer, jsonLength)));
+          } catch (error) {
+            setResponse({ error: { code: "EINVAL", message: `invalid host call JSON: ${error instanceof Error ? error.message : String(error)}` } });
+            return 0;
+          }
+          if (op !== "global" && (!VFS_OPERATIONS.has(op) || vfsDispatcher === undefined)) {
+            setResponse({ error: { code: "ENOSYS", message: `host capability '${op}' is not available` } });
+            return 0;
+          }
+          if (op !== "global") {
+            try {
+              setResponse({ value: vfsDispatcher.dispatch(op, argument) });
+            } catch (error) {
+              setResponse({ error: error instanceof HostCallFailure ? error.payload : jsonError(error) });
+            }
+            return 0;
+          }
+          const name = argument?.name;
+          const handler = typeof name === "string" ? globals[name] : undefined;
+          if (typeof handler !== "function") {
+            setResponse({ error: { message: `unknown global '${String(name)}'` } });
+            return 0;
+          }
+          try {
+            const value = handler(argument.args ?? null);
+            if (value && typeof value === "object" && typeof value.then === "function") {
+              throw new TypeError(`global '${name}' returned a Promise; host globals must be synchronous`);
+            }
+            assertJsonValue(value, `global '${name}' response`);
+            setResponse({ value });
+          } catch (error) {
+            setResponse({ error: jsonError(error) });
+          }
+          return 0;
+        },
+        host_response_len() { return response.byteLength; },
+        host_response_read(pointer, length) {
+          const count = Math.min(length, response.byteLength);
+          read(pointer, count).set(response.subarray(0, count));
+          return count;
+        },
+        write_stdout(pointer, length) { return capture(stdout, pointer, length, stdoutBytes, "stdout"); },
+        write_stderr(pointer, length) { return capture(stderr, pointer, length, stderrBytes, "stderr"); },
+      };
+      const wasi = {
+        clock_time_get(clockId, _precision, pointer) {
+          const nanos = clockId === 1 ? BigInt(Math.floor((monotonicNow() - started) * 1_000_000)) : BigInt(Date.now()) * 1_000_000n;
+          new DataView(memory.buffer).setBigUint64(pointer, nanos, true);
+          return 0;
+        },
+        fd_close() { return 0; },
+        fd_fdstat_get() { return 8; },
+        fd_seek() { return 8; },
+        fd_write(fd, iovs, iovsLength, writtenPointer) {
+          if (fd !== 1 && fd !== 2) return 8;
+          let total = 0;
+          for (let index = 0; index < iovsLength; index++) {
+            const view = new DataView(memory.buffer);
+            const pointer = view.getUint32(iovs + index * 8, true);
+            const length = view.getUint32(iovs + index * 8 + 4, true);
+            capture(fd === 1 ? stdout : stderr, pointer, length, fd === 1 ? stdoutBytes : stderrBytes, fd === 1 ? "stdout" : "stderr");
+            total += length;
+          }
+          writeU32(memory, writtenPointer, total);
+          return 0;
+        },
+      };
+
+      let instance;
+      let exitCode = 1;
+      try {
+        instance = new WebAssembly.Instance(module, { env: { memory }, tinysandbox, wasi_snapshot_preview1: wasi });
+        if (instance.exports.memory !== memory) throw new TypeError("QuickJS wasm did not re-export env.memory");
+        if (typeof instance.exports._initialize === "function") instance.exports._initialize();
+        const configBytes = encoder.encode(JSON.stringify({
+          code,
+          scriptPath: options.scriptPath ?? "[eval]",
+          argv: options.argv ?? ["js", "-e"],
+          env: options.env ?? {},
+          cwd: options.cwd ?? "/",
+          globals: globalNames,
+          prelude: "",
+          vfs: vfs !== undefined,
+        }));
+        const pointer = instance.exports.tinysandbox_alloc(configBytes.byteLength);
+        if (!pointer) throw new WebAssembly.RuntimeError("QuickJS input allocation failed");
+        read(pointer, configBytes.byteLength).set(configBytes);
+        exitCode = instance.exports.tinysandbox_run(pointer, configBytes.byteLength, quickjsHeapBytes);
+        if (timedOut) {
+          return { exitCode: 124, stdout: "", stderr: "js: command timed out\n", initialWasmMemoryBytes: QUICKJS_INITIAL_MEMORY_BYTES, peakWasmMemoryBytes: memory.buffer.byteLength };
+        }
+        instance.exports.tinysandbox_free(pointer);
+      } catch (error) {
+        if (timedOut) {
+          return { exitCode: 124, stdout: "", stderr: "js: command timed out\n", initialWasmMemoryBytes: QUICKJS_INITIAL_MEMORY_BYTES, peakWasmMemoryBytes: memory.buffer.byteLength };
+        }
+        const isMemory = error instanceof WebAssembly.RuntimeError && /memory|allocation|out of bounds/i.test(error.message);
+        const message = limitFailure?.message ?? (isMemory ? "wasm memory limit exceeded" : `runtime trap: ${error instanceof Error ? error.message : String(error)}`);
+        return { exitCode: 1, stdout: decoder.decode(join(stdout, stdoutLength)), stderr: `js: ${message}\n`, initialWasmMemoryBytes: QUICKJS_INITIAL_MEMORY_BYTES, peakWasmMemoryBytes: memory.buffer.byteLength };
+      } finally {
+        vfsDispatcher?.closeAll();
+      }
+      return {
+        exitCode,
+        stdout: decoder.decode(join(stdout, stdoutLength)),
+        stderr: decoder.decode(join(stderr, stderrLength)),
+        initialWasmMemoryBytes: QUICKJS_INITIAL_MEMORY_BYTES,
+        peakWasmMemoryBytes: memory.buffer.byteLength,
+      };
+    },
+    runFile(path, options = {}) {
+      if (typeof path !== "string") throw new TypeError("path must be a string");
+      if (options === null || typeof options !== "object") throw new TypeError("options must be an object");
+      const vfs = validateVfs(options.vfs);
+      const cwd = resolvePath("/", options.cwd ?? "/");
+      const resolved = resolvePath(cwd, path);
+      const sourceBytes = integerOption("sourceBytes", options.sourceBytes, DEFAULT_SOURCE_BYTES);
+      let bytes;
+      try {
+        bytes = remapHostFailure(() => readAll(vfs, resolved, sourceBytes), "open", resolved);
+      } catch (error) {
+        if (error instanceof HostCallFailure) throw exposedHostError(error.payload);
+        throw error;
+      }
+      let code;
+      try {
+        code = fatalDecoder.decode(bytes);
+      } catch {
+        throw new TypeError(`runFile entry '${resolved}' is not valid UTF-8`);
+      }
+      return engine.runCode(code, {
+        ...options,
+        vfs,
+        cwd,
+        scriptPath: resolved,
+        argv: options.argv ?? ["js", path],
+      });
+    },
+  };
+  return Object.freeze(engine);
+}
+
+function join(chunks, length) {
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tinysandbox/js-runtime",
+  "version": "0.1.0",
+  "description": "Stateless QuickJS runtime for standard WebAssembly hosts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./quickjs.wasm": "./quickjs.wasm"
+  },
+  "files": [
+    "dist/",
+    "quickjs.wasm",
+    "README.md",
+    "LICENSE-APACHE",
+    "LICENSE-MIT"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && npm run typecheck && node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:browser": "node test/browser-smoke.mjs",
+    "test:convex": "npm run build && npm run typecheck && node test/convex-smoke.mjs"
+  },
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danthegoodman1/tinysandbox.git",
+    "directory": "tinysandbox-js-runtime"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2"
+  }
+}