quickjs 0.17.0 → 0.19.0.pre1

data/ext/quickjsrb/quickjsrb.c

@@ -13,6 +13,7 @@ const char *featurePolyfillCryptoId = "feature_polyfill_crypto";
 
 const char *undefinedId = "undefined";
 const char *nanId = "NaN";
+const char *vmInternalFilename = "<vm>";
 
 const char *native_errors[] = {
     "SyntaxError",
@@ -32,6 +33,9 @@ static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited);
 static VALUE vm_m_memoryUsage(VALUE r_self);
 static VALUE vm_m_runGC(VALUE r_self);
 static VALUE vm_m_memoryPoisoned(VALUE r_self);
+static VALUE vm_m_dispose(VALUE r_self);
+static VALUE vm_m_disposed(VALUE r_self);
+static VALUE vm_m_drainJobs(VALUE r_self);
 
 JSValue j_error_from_ruby_error(JSContext *ctx, VALUE r_error)
 {
@@ -187,6 +191,28 @@ VALUE r_try_json_parse(VALUE r_str)
   return rb_funcall(rb_const_get(rb_cClass, rb_intern("JSON")), rb_intern("parse"), 1, r_str);
 }
 
+// Convert a JS Error.stack string into a Ruby Array suitable for
+// Exception#set_backtrace. Lines are stripped; empty lines (including the
+// trailing newline that QuickJS appends) are dropped. The frames keep
+// QuickJS's native format ("at func (file:line)") — Ruby's backtrace API
+// doesn't enforce a layout, and reshaping into "file:line:in 'method'"
+// would lose information for no real win.
+static VALUE r_backtrace_from_js_stack(const char *stack)
+{
+  if (stack == NULL || stack[0] == '\0')
+    return Qnil;
+
+  VALUE r_lines = rb_str_split(rb_str_new_cstr(stack), "\n");
+  VALUE r_filtered = rb_ary_new();
+  for (long i = 0; i < RARRAY_LEN(r_lines); i++)
+  {
+    VALUE r_line = rb_funcall(rb_ary_entry(r_lines, i), rb_intern("strip"), 0);
+    if (RSTRING_LEN(r_line) > 0)
+      rb_ary_push(r_filtered, r_line);
+  }
+  return RARRAY_LEN(r_filtered) > 0 ? r_filtered : Qnil;
+}
+
 VALUE to_r_json(JSContext *ctx, JSValue j_val)
 {
   JSValue j_stringified = JS_JSONStringify(ctx, j_val, JS_UNDEFINED, JS_UNDEFINED);
@@ -431,14 +457,11 @@ static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited)
       VMData *data = JS_GetContextOpaque(ctx);
       VALUE r_headline = rb_str_new2(headline);
       dispatch_log(data, "error", rb_ary_new3(1, r_log_body_new(r_headline, r_headline)));
-
-      JS_FreeValue(ctx, j_errorClassMessage);
-      JS_FreeValue(ctx, j_errorClassName);
-      JS_FreeValue(ctx, j_stackTrace);
-      JS_FreeCString(ctx, stackTrace);
       free(headline);
 
       VALUE r_error_class, r_error_message = rb_str_new2(errorClassMessage);
+      VALUE r_error_name = rb_str_new2(errorClassName);
+      VALUE r_backtrace = r_backtrace_from_js_stack(stackTrace);
       if (is_native_error_name(errorClassName))
       {
         r_error_class = QUICKJSRB_ERROR_FOR(errorClassName);
@@ -464,11 +487,18 @@ static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited)
       {
         r_error_class = QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR);
       }
+      JS_FreeValue(ctx, j_errorClassMessage);
+      JS_FreeValue(ctx, j_errorClassName);
+      JS_FreeValue(ctx, j_stackTrace);
+      JS_FreeCString(ctx, stackTrace);
       JS_FreeCString(ctx, errorClassName);
       JS_FreeCString(ctx, errorClassMessage);
       JS_FreeValue(ctx, j_exceptionVal);
 
-      rb_exc_raise(rb_funcall(r_error_class, rb_intern("new"), 2, r_error_message, rb_str_new2(errorClassName)));
+      VALUE r_exc = rb_funcall(r_error_class, rb_intern("new"), 2, r_error_message, r_error_name);
+      if (!NIL_P(r_backtrace))
+        rb_funcall(r_exc, rb_intern("set_backtrace"), 1, r_backtrace);
+      rb_exc_raise(r_exc);
     }
     else // exception without Error object
     {
@@ -514,24 +544,48 @@ static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited)
 struct module_loader_call_args
 {
   VALUE proc;
-  VALUE r_module_name;
+  VALUE r_specifier;
+  VALUE r_importer;
 };
 
+// Calls the user's loader with one or two args based on its arity. Procs
+// declared with a single positional (`->(name) { ... }`) get the legacy
+// 1-arg form so existing callers keep working; everything else (2-arity
+// lambdas, varargs procs) receives `(specifier, importer)`.
 static VALUE r_module_loader_call(VALUE r_args_val)
 {
   struct module_loader_call_args *args = (struct module_loader_call_args *)r_args_val;
-  return rb_funcall(args->proc, rb_intern("call"), 1, args->r_module_name);
+  int arity = NUM2INT(rb_funcall(args->proc, rb_intern("arity"), 0));
+  if (arity == 1)
+    return rb_funcall(args->proc, rb_intern("call"), 1, args->r_specifier);
+  return rb_funcall(args->proc, rb_intern("call"), 2, args->r_specifier, args->r_importer);
 }
 
-static JSModuleDef *quickjsrb_module_loader(JSContext *ctx, const char *module_name, void *opaque, JSValueConst attributes)
+// Normalize hook. Resolves `(specifier, importer)` to a canonical name by
+// consulting the resolution cache or invoking the user's loader Proc.
+// The Proc's return value drives both the canonical name AND the source
+// the load hook will eval:
+//   - String          → canonical = specifier, source = the string
+//   - { code:, as: }  → canonical = as,        source = code
+//   - nil / false     → ReferenceError
+// Source is stashed in `module_source_cache` keyed by canonical so the
+// load hook can pick it up. The resolution cache memoizes the call so
+// the Proc fires at most once per `(specifier, importer)` pair.
+static char *quickjsrb_module_normalize(JSContext *ctx, const char *base_name, const char *name, void *opaque)
 {
   VMData *data = JS_GetContextOpaque(ctx);
-  if (NIL_P(data->module_loader))
-    return js_module_loader(ctx, module_name, opaque, attributes);
 
-  struct module_loader_call_args args = {data->module_loader, rb_str_new_cstr(module_name)};
+  VALUE r_specifier = rb_str_new_cstr(name);
+  VALUE r_importer = rb_str_new_cstr(base_name);
+  VALUE r_key = rb_ary_new3(2, r_specifier, r_importer);
+
+  VALUE r_cached_canonical = rb_hash_aref(data->module_resolution_cache, r_key);
+  if (!NIL_P(r_cached_canonical))
+    return js_strdup(ctx, StringValueCStr(r_cached_canonical));
+
+  struct module_loader_call_args args = {data->module_loader, r_specifier, r_importer};
   int state;
-  VALUE r_source = rb_protect(r_module_loader_call, (VALUE)&args, &state);
+  VALUE r_return = rb_protect(r_module_loader_call, (VALUE)&args, &state);
   if (state)
   {
     VALUE r_error = rb_errinfo();
@@ -541,17 +595,61 @@ static JSModuleDef *quickjsrb_module_loader(JSContext *ctx, const char *module_n
     return NULL;
   }
 
-  if (NIL_P(r_source) || r_source == Qfalse)
+  if (NIL_P(r_return) || r_return == Qfalse)
   {
-    JS_ThrowReferenceError(ctx, "module loader returned no source for '%s'", module_name);
+    JS_ThrowReferenceError(ctx, "module loader returned no source for '%s'", name);
     return NULL;
   }
 
-  if (!RB_TYPE_P(r_source, T_STRING))
+  VALUE r_canonical, r_source;
+  if (RB_TYPE_P(r_return, T_STRING))
+  {
+    r_canonical = r_specifier;
+    r_source = r_return;
+  }
+  else if (RB_TYPE_P(r_return, T_HASH))
+  {
+    r_source = rb_hash_aref(r_return, ID2SYM(rb_intern("code")));
+    r_canonical = rb_hash_aref(r_return, ID2SYM(rb_intern("as")));
+    if (!RB_TYPE_P(r_source, T_STRING))
+    {
+      JS_ThrowTypeError(ctx, "module loader Hash must include code: (String, the module source)");
+      return NULL;
+    }
+    if (!RB_TYPE_P(r_canonical, T_STRING))
+    {
+      JS_ThrowTypeError(ctx, "module loader Hash must include as: (String, the canonical module name)");
+      return NULL;
+    }
+  }
+  else
+  {
+    JS_ThrowTypeError(ctx, "module loader must return a String, a Hash with code: and as:, or nil; got %s",
+                      rb_obj_classname(r_return));
+    return NULL;
+  }
+
+  rb_hash_aset(data->module_source_cache, r_canonical, r_source);
+  rb_hash_aset(data->module_resolution_cache, r_key, r_canonical);
+
+  return js_strdup(ctx, StringValueCStr(r_canonical));
+}
+
+static JSModuleDef *quickjsrb_module_loader(JSContext *ctx, const char *module_name, void *opaque, JSValueConst attributes)
+{
+  VMData *data = JS_GetContextOpaque(ctx);
+
+  VALUE r_canonical = rb_str_new_cstr(module_name);
+  VALUE r_source = rb_hash_aref(data->module_source_cache, r_canonical);
+  if (NIL_P(r_source))
   {
-    JS_ThrowTypeError(ctx, "module loader must return a String or nil, got %s", rb_obj_classname(r_source));
+    // Defensive: normalize populates this on every miss.
+    JS_ThrowReferenceError(ctx, "module loader: no cached source for '%s'", module_name);
     return NULL;
   }
+  // QuickJS won't call load again for this canonical — its own module cache
+  // takes over — so the source is dead weight once we've compiled it.
+  rb_hash_delete(data->module_source_cache, r_canonical);
 
   JSValue j_func = JS_Eval(ctx, RSTRING_PTR(r_source), RSTRING_LEN(r_source), module_name,
                            JS_EVAL_TYPE_MODULE | JS_EVAL_FLAG_COMPILE_ONLY);
@@ -564,6 +662,95 @@ static JSModuleDef *quickjsrb_module_loader(JSContext *ctx, const char *module_n
   return m;
 }
 
+// When no Ruby loader is set we hand resolution back to QuickJS's defaults
+// (URL-style normalize + filesystem load). When a loader is set we own both
+// phases so we can thread (specifier, importer) through and honor `as:`.
+static void register_module_loader_funcs(VMData *data)
+{
+  JSRuntime *runtime = JS_GetRuntime(data->context);
+  if (NIL_P(data->module_loader))
+    JS_SetModuleLoaderFunc2(runtime, NULL, js_module_loader, js_module_check_attributes, NULL);
+  else
+    JS_SetModuleLoaderFunc2(runtime, quickjsrb_module_normalize, quickjsrb_module_loader, js_module_check_attributes, NULL);
+}
+
+static VALUE r_exception_from_js_reason(JSContext *ctx, JSValueConst j_reason)
+{
+  if (JS_IsError(ctx, j_reason))
+  {
+    VALUE r_maybe_ruby_error = find_ruby_error(ctx, j_reason);
+    if (!NIL_P(r_maybe_ruby_error))
+      return r_maybe_ruby_error;
+
+    JSValue j_name = JS_GetPropertyStr(ctx, j_reason, "name");
+    JSValue j_message = JS_GetPropertyStr(ctx, j_reason, "message");
+    JSValue j_stack = JS_GetPropertyStr(ctx, j_reason, "stack");
+    const char *name = JS_ToCString(ctx, j_name);
+    const char *message = JS_ToCString(ctx, j_message);
+    const char *stack = JS_ToCString(ctx, j_stack);
+
+    VALUE r_class = is_native_error_name(name)
+                        ? QUICKJSRB_ERROR_FOR(name)
+                        : QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR);
+    VALUE r_exc = rb_funcall(r_class, rb_intern("new"), 2,
+                             rb_str_new2(message), rb_str_new2(name));
+    VALUE r_backtrace = r_backtrace_from_js_stack(stack);
+    if (!NIL_P(r_backtrace))
+      rb_funcall(r_exc, rb_intern("set_backtrace"), 1, r_backtrace);
+
+    JS_FreeCString(ctx, name);
+    JS_FreeCString(ctx, message);
+    if (stack)
+      JS_FreeCString(ctx, stack);
+    JS_FreeValue(ctx, j_name);
+    JS_FreeValue(ctx, j_message);
+    JS_FreeValue(ctx, j_stack);
+    return r_exc;
+  }
+
+  const char *str = JS_ToCString(ctx, j_reason);
+  VALUE r_exc = rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"),
+                           2, rb_str_new2(str ? str : "(non-stringifiable rejection)"), Qnil);
+  if (str)
+    JS_FreeCString(ctx, str);
+  return r_exc;
+}
+
+struct rejection_call_args
+{
+  VALUE proc;
+  VALUE r_reason;
+};
+
+static VALUE r_rejection_call(VALUE r_args_val)
+{
+  struct rejection_call_args *args = (struct rejection_call_args *)r_args_val;
+  return rb_funcall(args->proc, rb_intern("call"), 1, args->r_reason);
+}
+
+static void quickjsrb_promise_rejection_tracker(
+    JSContext *ctx, JSValueConst promise, JSValueConst reason,
+    JS_BOOL is_handled, void *opaque)
+{
+  if (is_handled)
+    return;
+
+  VMData *data = JS_GetContextOpaque(ctx);
+  if (NIL_P(data->on_unhandled_rejection))
+    return;
+
+  VALUE r_reason = r_exception_from_js_reason(ctx, reason);
+  struct rejection_call_args args = {data->on_unhandled_rejection, r_reason};
+  int state;
+  rb_protect(r_rejection_call, (VALUE)&args, &state);
+  if (state)
+  {
+    // Longjmping out of a QuickJS host callback corrupts the runtime, so
+    // a raise inside the user's tracker has to be dropped on the floor.
+    rb_set_errinfo(Qnil);
+  }
+}
+
 static VALUE r_try_call_proc(VALUE r_try_args)
 {
   return rb_funcall(
@@ -860,7 +1047,8 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
   JS_SetMemoryLimit(runtime, NUM2UINT(r_memory_limit));
   JS_SetMaxStackSize(runtime, NUM2UINT(r_max_stack_size));
 
-  JS_SetModuleLoaderFunc2(runtime, NULL, quickjsrb_module_loader, js_module_check_attributes, NULL);
+  register_module_loader_funcs(data);
+  JS_SetHostPromiseRejectionTracker(runtime, quickjsrb_promise_rejection_tracker, NULL);
   js_std_init_handlers(runtime);
 
   JSValue j_global = JS_GetGlobalObject(data->context);
@@ -870,7 +1058,7 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
     js_init_module_std(data->context, "std");
     const char *enableStd = "import * as std from 'std';\n"
                             "globalThis.std = std;\n";
-    JSValue j_stdEval = JS_Eval(data->context, enableStd, strlen(enableStd), "<vm>", JS_EVAL_TYPE_MODULE);
+    JSValue j_stdEval = JS_Eval(data->context, enableStd, strlen(enableStd), vmInternalFilename, JS_EVAL_TYPE_MODULE);
     JS_FreeValue(data->context, j_stdEval);
   }
 
@@ -879,7 +1067,7 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
     js_init_module_os(data->context, "os");
     const char *enableOs = "import * as os from 'os';\n"
                            "globalThis.os = os;\n";
-    JSValue j_osEval = JS_Eval(data->context, enableOs, strlen(enableOs), "<vm>", JS_EVAL_TYPE_MODULE);
+    JSValue j_osEval = JS_Eval(data->context, enableOs, strlen(enableOs), vmInternalFilename, JS_EVAL_TYPE_MODULE);
     JS_FreeValue(data->context, j_osEval);
   }
   else if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featureTimeoutId))))
@@ -889,15 +1077,8 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
         JS_NewCFunction(data->context, js_quickjsrb_set_timeout, "setTimeout", 2));
   }
 
-  if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillIntlId))))
-  {
-    const char *defineIntl = "Object.defineProperty(globalThis, 'Intl', { value:{} });\n";
-    JSValue j_defineIntl = JS_Eval(data->context, defineIntl, strlen(defineIntl), "<vm>", JS_EVAL_TYPE_GLOBAL);
-    JS_FreeValue(data->context, j_defineIntl);
-
-    JSValue j_polyfillIntlResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_intl_en_min, qjsc_polyfill_intl_en_min_size);
-    JS_FreeValue(data->context, j_polyfillIntlResult);
-  }
+  // POLYFILL_INTL is registered Ruby-side via Quickjs.register_polyfill and
+  // applied by the wrapper around VM#initialize in lib/quickjs/polyfills.rb.
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillFileId))))
   {
@@ -984,6 +1165,15 @@ static void check_oom_poisoned(VMData *data)
   }
 }
 
+static void check_disposed(VMData *data)
+{
+  if (data->disposed)
+  {
+    VALUE r_msg = rb_str_new2("VM has been disposed; create a new Quickjs::VM");
+    rb_exc_raise(rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"), 2, r_msg, Qnil));
+  }
+}
+
 // Validate that r_code is a String and resolve the :filename option (default "<code>")
 // from the keyword-args hash that rb_scan_args(... "1:") collects. Both eval_code and
 // compile share this argument shape.
@@ -1014,6 +1204,7 @@ static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
   check_oom_poisoned(data);
 
   VALUE r_code, r_opts;
@@ -1052,6 +1243,8 @@ static VALUE vm_m_compile(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
+
   VALUE r_code, r_opts;
   rb_scan_args(argc, argv, "1:", &r_code, &r_opts);
   const char *filename = parse_code_and_filename(r_code, r_opts);
@@ -1086,6 +1279,8 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
+
   if (!RB_TYPE_P(r_bytecode, T_STRING))
   {
     VALUE r_class = rb_class_name(CLASS_OF(r_bytecode));
@@ -1115,6 +1310,36 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
   return to_rb_return_value(data->context, j_returnedValue);
 }
 
+// Loads pre-compiled polyfill bytecode without arming the eval timer.
+// The user's `timeout_msec` is a budget for *their* code; running our
+// own polyfill (~140 ms for FormatJS Intl) under that budget would
+// interrupt the load on tight defaults. Unlike load_polyfill_bytecode
+// above we hold the GVL through JS_ReadObject + JS_EvalFunction: the
+// bytecode buffer is a Ruby String, so releasing would let GC compact
+// the backing storage out from under us. The static-symbol path can
+// release safely; this path cannot.
+static VALUE vm_m_loadPolyfillBytecode(VALUE r_self, VALUE r_bytecode)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_disposed(data);
+  StringValue(r_bytecode);
+
+  JSValue j_func = JS_ReadObject(data->context,
+                                 (const uint8_t *)RSTRING_PTR(r_bytecode),
+                                 (size_t)RSTRING_LEN(r_bytecode),
+                                 JS_READ_OBJ_BYTECODE);
+  if (JS_IsException(j_func))
+    return to_rb_value(data->context, j_func); // raises
+
+  JSValue j_result = JS_EvalFunction(data->context, j_func); // frees j_func
+  if (JS_IsException(j_result))
+    return to_rb_value(data->context, j_result); // raises
+  JS_FreeValue(data->context, j_result);
+  return Qnil;
+}
+
 static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
 {
   rb_need_block();
@@ -1127,6 +1352,8 @@ static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
+
   if (RB_TYPE_P(r_name, T_ARRAY))
   {
     long path_len = RARRAY_LEN(r_name);
@@ -1170,7 +1397,7 @@ static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
     {
       VALUE r_first_str = rb_funcall(RARRAY_AREF(r_name, 0), rb_intern("to_s"), 0);
       const char *first_seg = StringValueCStr(r_first_str);
-      j_parent = JS_Eval(data->context, first_seg, strlen(first_seg), "<vm>", JS_EVAL_TYPE_GLOBAL);
+      j_parent = JS_Eval(data->context, first_seg, strlen(first_seg), vmInternalFilename, JS_EVAL_TYPE_GLOBAL);
 
       if (JS_IsException(j_parent) || !JS_IsObject(j_parent))
       {
@@ -1247,6 +1474,7 @@ static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
   check_oom_poisoned(data);
 
   JSValue j_this = JS_UNDEFINED;
@@ -1307,7 +1535,7 @@ static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
     const char *first_seg = StringValueCStr(r_first_str);
 
     // JS_Eval accesses both global object properties and lexical (const/let) bindings
-    JSValue j_cur = JS_Eval(data->context, first_seg, strlen(first_seg), "<vm>", JS_EVAL_TYPE_GLOBAL);
+    JSValue j_cur = JS_Eval(data->context, first_seg, strlen(first_seg), vmInternalFilename, JS_EVAL_TYPE_GLOBAL);
     if (JS_IsException(j_cur))
       return to_rb_value(data->context, j_cur); // raises
 
@@ -1384,6 +1612,11 @@ static VALUE vm_m_set_module_loader(VALUE r_self, VALUE r_loader)
     rb_raise(rb_eTypeError, "module_loader must be a Proc or nil");
 
   data->module_loader = r_loader;
+  // Stale entries from the previous loader's policy would survive the
+  // swap and silently shadow the new behavior.
+  rb_hash_clear(data->module_resolution_cache);
+  rb_hash_clear(data->module_source_cache);
+  register_module_loader_funcs(data);
   return r_loader;
 }
 
@@ -1394,6 +1627,17 @@ static VALUE vm_m_get_module_loader(VALUE r_self)
   return data->module_loader;
 }
 
+static VALUE vm_m_on_unhandled_rejection(VALUE r_self)
+{
+  rb_need_block();
+
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  data->on_unhandled_rejection = rb_block_proc();
+  return Qnil;
+}
+
 static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
 {
   VALUE r_import_string, r_opts;
@@ -1408,12 +1652,17 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
     rb_exc_raise(rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"), 2, r_error_message, Qnil));
     return Qnil;
   }
+  if (!NIL_P(r_from) && !NIL_P(r_filename))
+    rb_raise(rb_eArgError, "pass either from: (inline source) or filename: (loader-resolved), not both");
   VALUE r_custom_exposure = rb_hash_aref(r_opts, ID2SYM(rb_intern("code_to_expose")));
 
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_disposed(data);
+
   char *filename;
+  VALUE r_seeded_key = Qnil;
   if (!NIL_P(r_filename))
   {
     filename = StringValueCStr(r_filename);
@@ -1429,6 +1678,18 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
       return to_rb_value(data->context, module);
     }
     js_module_set_import_meta(data->context, module, TRUE, FALSE);
+    // The bridge module below will `import` this filename; without a
+    // resolution-cache seed, our normalize hook would ask the user's
+    // module_loader for it (and fail), even though QuickJS already has
+    // the module loaded from the JS_Eval just above. Each `from:` call
+    // mints a fresh random filename, so we also delete the entry once
+    // the bridge eval finishes — otherwise the cache grows unboundedly.
+    if (!NIL_P(data->module_loader))
+    {
+      VALUE r_filename_str = rb_str_new_cstr(filename);
+      r_seeded_key = rb_ary_new3(2, r_filename_str, rb_str_new2(vmInternalFilename));
+      rb_hash_aset(data->module_resolution_cache, r_seeded_key, r_filename_str);
+    }
     JS_FreeValue(data->context, module);
   }
 
@@ -1456,9 +1717,21 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
   char *result = (char *)malloc(length + 1);
   snprintf(result, length + 1, importAndGlobalizeModule, import_name, filename, globalize);
 
-  JSValue j_codeResult = JS_Eval(data->context, result, strlen(result), "<vm>", JS_EVAL_TYPE_MODULE);
+  JSValue j_codeResult = JS_Eval(data->context, result, strlen(result), vmInternalFilename, JS_EVAL_TYPE_MODULE);
   free(result);
-  JS_FreeValue(data->context, j_codeResult);
+  if (JS_IsException(j_codeResult))
+    return to_rb_value(data->context, j_codeResult);
+
+  // Module eval returns a Promise. Awaiting it surfaces top-level throws,
+  // rejected dynamic imports, and rejected top-level awaits as Ruby
+  // exceptions instead of silently dropping them.
+  JSValue j_awaited = js_std_await(data->context, j_codeResult);
+  if (JS_IsException(j_awaited))
+    return to_rb_value(data->context, j_awaited);
+  JS_FreeValue(data->context, j_awaited);
+
+  if (!NIL_P(r_seeded_key))
+    rb_hash_delete(data->module_resolution_cache, r_seeded_key);
 
   return Qtrue;
 }
@@ -1478,15 +1751,20 @@ RUBY_FUNC_EXPORTED void Init_quickjsrb(void)
   rb_define_method(r_class_vm, "eval_code", vm_m_evalCode, -1);
   rb_define_private_method(r_class_vm, "_compile_to_bytecode", vm_m_compile, -1);
   rb_define_private_method(r_class_vm, "_run_bytecode", vm_m_evalBytecode, 1);
+  rb_define_private_method(r_class_vm, "_load_polyfill_bytecode", vm_m_loadPolyfillBytecode, 1);
   rb_define_method(r_class_vm, "call", vm_m_callGlobalFunction, -1);
   rb_define_method(r_class_vm, "define_function", vm_m_defineGlobalFunction, -1);
   rb_define_method(r_class_vm, "import", vm_m_import, -1);
   rb_define_method(r_class_vm, "module_loader", vm_m_get_module_loader, 0);
   rb_define_method(r_class_vm, "module_loader=", vm_m_set_module_loader, 1);
+  rb_define_method(r_class_vm, "on_unhandled_rejection", vm_m_on_unhandled_rejection, 0);
   rb_define_method(r_class_vm, "on_log", vm_m_on_log, 0);
   rb_define_method(r_class_vm, "memory_usage", vm_m_memoryUsage, 0);
   rb_define_method(r_class_vm, "gc!", vm_m_runGC, 0);
   rb_define_method(r_class_vm, "memory_poisoned?", vm_m_memoryPoisoned, 0);
+  rb_define_method(r_class_vm, "dispose!", vm_m_dispose, 0);
+  rb_define_method(r_class_vm, "disposed?", vm_m_disposed, 0);
+  rb_define_method(r_class_vm, "drain_jobs!", vm_m_drainJobs, 0);
   r_define_log_class(r_class_vm);
 }
 
@@ -1494,6 +1772,7 @@ static VALUE vm_m_memoryUsage(VALUE r_self)
 {
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  check_disposed(data);
   JSMemoryUsage s;
   JS_ComputeMemoryUsage(JS_GetRuntime(data->context), &s);
   VALUE h = rb_hash_new();
@@ -1516,13 +1795,90 @@ static VALUE vm_m_runGC(VALUE r_self)
 {
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  check_disposed(data);
   JS_RunGC(JS_GetRuntime(data->context));
   return Qnil;
 }
 
+static VALUE vm_m_drainJobs(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_oom_poisoned(data);
+
+  JSRuntime *runtime = JS_GetRuntime(data->context);
+  if (!JS_IsJobPending(runtime))
+    return INT2NUM(0);
+
+  arm_eval_timer(data);
+
+  int executed = 0;
+  for (;;)
+  {
+    int err = JS_ExecutePendingJob(runtime, NULL);
+    if (err == 0)
+      break;
+    if (err < 0)
+      return to_rb_value(data->context, JS_EXCEPTION); // raises
+    executed++;
+  }
+  return INT2NUM(executed);
+}
+
 static VALUE vm_m_memoryPoisoned(VALUE r_self)
 {
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
   return data->oom_poisoned ? Qtrue : Qfalse;
 }
+
+// JS_FreeContext + JS_FreeRuntime walk the entire heap to run finalisers.
+// On a VM with polyfills loaded this can be tens of milliseconds — run it
+// without the GVL so other Ruby threads (e.g. the next pool builder) keep
+// progressing. Safe to release because nothing in the teardown path calls
+// back into Ruby: module_loader, console, and define_function callbacks
+// only fire during JS execution, not during free.
+static void *vm_dispose_no_gvl(void *p)
+{
+  vm_teardown_context((JSContext *)p);
+  return NULL;
+}
+
+static VALUE vm_m_dispose(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  if (data->disposed)
+    return Qnil;
+
+  if (!JS_IsUndefined(data->j_file_proxy_creator))
+  {
+    JS_FreeValue(data->context, data->j_file_proxy_creator);
+    data->j_file_proxy_creator = JS_UNDEFINED;
+  }
+
+  // Mark disposed before releasing the GVL so a concurrent dfree finds
+  // disposed=true and skips its own teardown.
+  data->disposed = true;
+
+  rb_thread_call_without_gvl(vm_dispose_no_gvl, data->context, NULL, NULL);
+
+  // Drop references to user-supplied closures so Ruby GC can reclaim them
+  // (and anything they captured) before the wrapping VM object itself is
+  // collected. Matters for pool-rebuild workloads that dispose eagerly.
+  data->defined_functions = rb_hash_new();
+  data->alive_objects = rb_hash_new();
+  data->log_listener = Qnil;
+  data->module_loader = Qnil;
+
+  return Qnil;
+}
+
+static VALUE vm_m_disposed(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  return data->disposed ? Qtrue : Qfalse;
+}