quickjs 0.21.0 → 0.22.0.rc1

data/ext/quickjsrb/quickjsrb_file.c

@@ -3,10 +3,25 @@
 
 static VALUE r_find_alive_rb_file(JSContext *ctx, JSValue j_handle)
 {
-  int64_t handle;
-  JS_ToInt64(ctx, &handle, j_handle);
+  // Initialised and checked like its siblings. Unreachable today, since the
+  // handle is the factory closure's own number and the bridges are never on
+  // the global, but it feeds a table lookup and would read a garbage key.
+  int64_t handle = 0;
+  if (JS_ToInt64(ctx, &handle, j_handle) < 0)
+  {
+    quickjsrb_drain_pending(ctx);
+    return Qnil;
+  }
   VMData *data = JS_GetContextOpaque(ctx);
-  return rb_hash_aref(data->alive_objects, LONG2NUM(handle));
+  VALUE r_file = rb_hash_aref(data->alive_objects, LL2NUM(handle));
+  // Only what this subsystem parked, the way both sibling readers check now.
+  // The table is shared with bridged exceptions and CryptoKeys, and the bridges
+  // below call File methods on whatever they are handed. Unreachable today,
+  // since the handle is the factory closure's own number, but the check is what
+  // makes that an invariant rather than an argument about reachability.
+  if (!rb_obj_is_kind_of(r_file, rb_cFile))
+    return Qnil;
+  return r_file;
 }
 
 static JSValue js_ruby_file_name(JSContext *ctx, JSValueConst _this, int argc, JSValueConst *argv)
@@ -99,8 +114,41 @@ static JSValue js_ruby_file_array_buffer(JSContext *ctx, JSValueConst _this, int
   return promise;
 }
 
+// Hands the guest back the throw it made, rather than an error of our own,
+// which would tell it less than it already knew.
+//
+// Deliberately without unparking: the throw is going back into JS, and it is
+// the handle that lets it come out the other side as the host exception it
+// started as. Taking the entry here would leave the JS error carrying a handle
+// that resolves to nothing, and a caller that expected ArgumentError would get
+// a generic Quickjs::RuntimeError instead. A throw the guest then catches and
+// keeps stays parked, which is what any caught bridged error does: #114.
+static JSValue j_rethrow_the_guests_own(JSContext *ctx)
+{
+  // JS_Throw clears the uncatchable flag, so a deadline that fired inside the
+  // guest's valueOf would come back catchable and a script that caught it and
+  // returned would finish past its budget. Thrown the way js_poll_interrupts
+  // throws it instead, which is what it was before this touched it.
+  if (eval_budget_lapsed_now(ctx))
+  {
+    // Drained, not freed. This branch is the one that does not hand the throw
+    // back, so the reasoning quickjsrb_drain_pending gives for unparking
+    // applies here and not to the return below: nothing will carry the guest's
+    // throw out now, and a bridge it reached on the way has already parked the
+    // host exception, so freeing the JS error is the one path that leaves that
+    // entry with nothing able to take it.
+    quickjsrb_drain_pending(ctx);
+    JS_ThrowInternalError(ctx, "interrupted");
+    JS_SetUncatchableException(ctx, TRUE);
+    return JS_EXCEPTION;
+  }
+
+  return JS_Throw(ctx, JS_GetException(ctx));
+}
+
 static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc, JSValueConst *argv)
 {
+  VMData *data = JS_GetContextOpaque(ctx);
   VALUE r_file = r_find_alive_rb_file(ctx, argv[0]);
   if (NIL_P(r_file))
     return JS_UNDEFINED;
@@ -111,8 +159,12 @@ static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc,
   long start = 0;
   if (argc > 1 && !JS_IsUndefined(argv[1]))
   {
-    int64_t s;
-    JS_ToInt64(ctx, &s, argv[1]);
+    // The conversion runs the guest's valueOf, which can reach a bridge: an
+    // unchecked failure both parks the host exception and leaves s
+    // uninitialized to be used as an offset.
+    int64_t s = 0;
+    if (JS_ToInt64(ctx, &s, argv[1]) < 0)
+      return j_rethrow_the_guests_own(ctx);
     start = (long)s;
     if (start < 0)
       start = file_size + start;
@@ -125,8 +177,9 @@ static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc,
   long end = file_size;
   if (argc > 2 && !JS_IsUndefined(argv[2]))
   {
-    int64_t e;
-    JS_ToInt64(ctx, &e, argv[2]);
+    int64_t e = 0;
+    if (JS_ToInt64(ctx, &e, argv[2]) < 0)
+      return j_rethrow_the_guests_own(ctx);
     end = (long)e;
     if (end < 0)
       end = file_size + end;
@@ -136,10 +189,6 @@ static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc,
       end = file_size;
   }
 
-  const char *content_type = "";
-  if (argc > 3 && JS_IsString(argv[3]))
-    content_type = JS_ToCString(ctx, argv[3]);
-
   long len = end > start ? end - start : 0;
 
   rb_funcall(r_file, rb_intern("rewind"), 0);
@@ -148,30 +197,91 @@ static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc,
   VALUE r_bytes = rb_funcall(r_file, rb_intern("read"), 1, LONG2NUM(len));
   rb_funcall(r_bytes, rb_intern("force_encoding"), 1, rb_str_new_cstr("BINARY"));
 
+  // Built after every call that can raise, and while the C string is still
+  // owned, so nothing here is holding a JS value when a Ruby raise unwinds and
+  // nothing is left to free on the paths that bail out below.
+  JSValue j_type_str;
+  if (argc > 3 && JS_IsString(argv[3]))
+  {
+    const char *content_type = JS_ToCString(ctx, argv[3]);
+    if (content_type == NULL)
+      // It threw on the way, and returning a Blob with that left pending would
+      // attribute it to whatever asks next.
+      return j_rethrow_the_guests_own(ctx);
+    j_type_str = JS_NewString(ctx, content_type);
+    JS_FreeCString(ctx, content_type);
+  }
+  else
+  {
+    j_type_str = JS_NewString(ctx, "");
+  }
+  if (JS_IsException(j_type_str))
+    return j_type_str;
+
+  // Built through JS_NewTypedArray and the constructor captured at init, not
+  // by calling globalThis.Uint8Array and globalThis.Blob: those are names the
+  // guest can delete or replace with a shim, and a slice of a host File is not
+  // something it gets to answer for. Every step is checked, so a sentinel is
+  // never stored into j_parts and handed on as an ordinary element.
   JSValue j_buf = JS_NewArrayBufferCopy(ctx, (const uint8_t *)RSTRING_PTR(r_bytes), RSTRING_LEN(r_bytes));
-  JSValue j_global = JS_GetGlobalObject(ctx);
-  JSValue j_uint8_ctor = JS_GetPropertyStr(ctx, j_global, "Uint8Array");
-  JSValue j_uint8 = JS_CallConstructor(ctx, j_uint8_ctor, 1, &j_buf);
+  if (JS_IsException(j_buf))
+  {
+    JS_FreeValue(ctx, j_type_str);
+    return j_buf;
+  }
+
+  JSValue j_ta_args[3] = {j_buf, JS_NewInt32(ctx, 0), JS_NewInt64(ctx, RSTRING_LEN(r_bytes))};
+  JSValue j_uint8 = JS_NewTypedArray(ctx, 3, (JSValueConst *)j_ta_args, JS_TYPED_ARRAY_UINT8);
+  JS_FreeValue(ctx, j_buf);
+  if (JS_IsException(j_uint8))
+  {
+    JS_FreeValue(ctx, j_type_str);
+    return j_uint8;
+  }
+
+  if (JS_IsUndefined(data->j_blob_ctor))
+  {
+    JS_FreeValue(ctx, j_uint8);
+    JS_FreeValue(ctx, j_type_str);
+    return JS_ThrowInternalError(ctx, "Blob is not available to build a slice");
+  }
 
   JSValue j_parts = JS_NewArray(ctx);
-  JS_SetPropertyUint32(ctx, j_parts, 0, j_uint8);
+  if (JS_IsException(j_parts))
+  {
+    JS_FreeValue(ctx, j_uint8);
+    JS_FreeValue(ctx, j_type_str);
+    return j_parts;
+  }
+  if (JS_DefinePropertyValueUint32(ctx, j_parts, 0, j_uint8, JS_PROP_C_W_E) < 0)
+  {
+    // The define freed the bytes on its way out, so carrying on would build the
+    // Blob from an empty array and hand the guest a zero-length slice of a file
+    // that is not empty, with a throw left pending behind it.
+    JS_FreeValue(ctx, j_parts);
+    JS_FreeValue(ctx, j_type_str);
+    return JS_EXCEPTION;
+  }
 
   JSValue j_opts = JS_NewObject(ctx);
-  JS_SetPropertyStr(ctx, j_opts, "type", JS_NewString(ctx, content_type));
+  if (JS_IsException(j_opts))
+  {
+    JS_FreeValue(ctx, j_parts);
+    JS_FreeValue(ctx, j_type_str);
+    return j_opts;
+  }
+  if (JS_DefinePropertyValueStr(ctx, j_opts, "type", j_type_str, JS_PROP_C_W_E) < 0)
+  {
+    JS_FreeValue(ctx, j_parts);
+    JS_FreeValue(ctx, j_opts);
+    return JS_EXCEPTION;
+  }
 
-  JSValue j_blob_ctor = JS_GetPropertyStr(ctx, j_global, "Blob");
   JSValueConst blob_args[2] = {j_parts, j_opts};
-  JSValue j_blob = JS_CallConstructor(ctx, j_blob_ctor, 2, blob_args);
+  JSValue j_blob = JS_CallConstructor(ctx, data->j_blob_ctor, 2, blob_args);
 
-  if (argc > 3 && JS_IsString(argv[3]))
-    JS_FreeCString(ctx, content_type);
-
-  JS_FreeValue(ctx, j_buf);
-  JS_FreeValue(ctx, j_uint8_ctor);
   JS_FreeValue(ctx, j_parts);
   JS_FreeValue(ctx, j_opts);
-  JS_FreeValue(ctx, j_blob_ctor);
-  JS_FreeValue(ctx, j_global);
 
   return j_blob;
 }
@@ -179,13 +289,28 @@ static JSValue js_ruby_file_slice(JSContext *ctx, JSValueConst _this, int argc,
 void quickjsrb_init_file_proxy(VMData *data)
 {
   const char *factory_src =
-      "(function(getName, getSize, getType, getLastModified, getText, getArrayBuffer, getSlice) {\n"
+      // Everything the closure needs is bound once, here, while this is the only
+      // code that has run: Object, Proxy, Reflect and Symbol are the guest's to
+      // replace by the time a File actually crosses, and this body runs per
+      // crossing. With `globalThis.Proxy = null` every crossing used to fail,
+      // and a replaced Object.defineProperty published the handle as an
+      // ordinary enumerable property.
+      //
+      // The handler object has a null prototype for a sharper reason: QuickJS
+      // resolves a missing trap with an ordinary property get, which walks the
+      // handler's prototype chain. With Object.prototype in it, a guest writing
+      // Object.prototype.getOwnPropertyDescriptor supplies the trap for the
+      // one read this branch made load-bearing, and the invariant check on the
+      // way back compares descriptor flags without comparing the value, so a
+      // handle of the guest's choosing comes back for a host File.
+      "(function(FileProto, ObjectCreate, DefineProperty, ProxyCtor, ReflectGet, ToStringTag,\n"
+      "          getName, getSize, getType, getLastModified, getText, getArrayBuffer, getSlice) {\n"
       "  return function(handle) {\n"
-      "    var target = Object.create(File.prototype);\n"
-      "    Object.defineProperty(target, 'rb_object_id', { value: handle, enumerable: false });\n"
-      "    return new Proxy(target, {\n"
-      "      getPrototypeOf: function() { return File.prototype; },\n"
-      "      get: function(target, prop, receiver) {\n"
+      "    var target = ObjectCreate(FileProto);\n"
+      "    DefineProperty(target, 'rb_object_id', { value: handle, enumerable: false });\n"
+      "    var handler = ObjectCreate(null);\n"
+      "    handler.getPrototypeOf = function() { return FileProto; };\n"
+      "    handler.get = function(target, prop, receiver) {\n"
       "        if (prop === 'name') return getName(handle);\n"
       "        if (prop === 'size') return getSize(handle);\n"
       "        if (prop === 'type') return getType(handle);\n"
@@ -193,39 +318,112 @@ void quickjsrb_init_file_proxy(VMData *data)
       "        if (prop === 'text') return function() { return getText(handle); };\n"
       "        if (prop === 'arrayBuffer') return function() { return getArrayBuffer(handle); };\n"
       "        if (prop === 'slice') return function(start, end, contentType) { return getSlice(handle, start, end, contentType); };\n"
-      "        if (prop === Symbol.toStringTag) return 'File';\n"
+      "        if (prop === ToStringTag) return 'File';\n"
       "        if (prop === 'toString') return function() { return '[object File]'; };\n"
-      "        return Reflect.get(target, prop, receiver);\n"
-      "      }\n"
-      "    });\n"
+      "        return ReflectGet(target, prop, receiver);\n"
+      "      };\n"
+      "    return new ProxyCtor(target, handler);\n"
       "  };\n"
       "})";
   JSValue j_factory_fn = JS_Eval(data->context, factory_src, strlen(factory_src), "<file-proxy>", JS_EVAL_TYPE_GLOBAL);
 
-  JSValue j_helpers[7];
-  j_helpers[0] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_name, "__rb_file_name", 1);
-  j_helpers[1] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_size, "__rb_file_size", 1);
-  j_helpers[2] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_type, "__rb_file_type", 1);
-  j_helpers[3] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_last_modified, "__rb_file_last_modified", 1);
-  j_helpers[4] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_text, "__rb_file_text", 1);
-  j_helpers[5] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_array_buffer, "__rb_file_array_buffer", 1);
-  j_helpers[6] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_slice, "__rb_file_slice", 4);
+  // The prototype is taken here too, not read from globalThis.File when a proxy
+  // is built: the closure below runs per crossing, which is after guest code,
+  // and a replaced File otherwise decides what a host File is an instance of.
+  // The handle keeps working either way, so what this closes is the shape of
+  // the value rather than the bridge.
+  JSValue j_global_for_proto = JS_GetGlobalObject(data->context);
+  JSValue j_file_class = JS_GetPropertyStr(data->context, j_global_for_proto, "File");
+  JS_FreeValue(data->context, j_global_for_proto);
+  JSValue j_file_proto = JS_GetPropertyStr(data->context, j_file_class, "prototype");
+  JS_FreeValue(data->context, j_file_class);
+  if (JS_IsException(j_file_proto))
+  {
+    // Checked like the Blob capture below. Left as the sentinel it would go
+    // into the factory call, come back out as j_file_proxy_creator, and every
+    // File crossing would call into it with a throw left pending for whatever
+    // asked next.
+    JS_FreeValue(data->context, JS_GetException(data->context));
+    j_file_proto = JS_UNDEFINED;
+  }
+
+  // The intrinsics the closure uses, taken now rather than resolved per
+  // crossing. Evaluated rather than read off the global one by one, so a value
+  // that is already missing cannot leave a sentinel in the argument list.
+  static const char intrinsics_src[] =
+      "[Object.create, Object.defineProperty, Proxy, Reflect.get, Symbol.toStringTag]";
+  JSValue j_intrinsics = JS_Eval(data->context, intrinsics_src, sizeof(intrinsics_src) - 1,
+                                 "<file-proxy-intrinsics>", JS_EVAL_TYPE_GLOBAL);
+  if (JS_IsException(j_intrinsics))
+  {
+    JS_FreeValue(data->context, JS_GetException(data->context));
+    JS_FreeValue(data->context, j_intrinsics);
+    JS_FreeValue(data->context, j_file_proto);
+    JS_FreeValue(data->context, j_factory_fn);
+    return;
+  }
 
-  data->j_file_proxy_creator = JS_Call(data->context, j_factory_fn, JS_UNDEFINED, 7, j_helpers);
+  JSValue j_helpers[13];
+  j_helpers[0] = j_file_proto;
+  for (int i = 0; i < 5; i++)
+    j_helpers[1 + i] = JS_GetPropertyUint32(data->context, j_intrinsics, (uint32_t)i);
+  JS_FreeValue(data->context, j_intrinsics);
+  j_helpers[6] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_name, "__rb_file_name", 1);
+  j_helpers[7] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_size, "__rb_file_size", 1);
+  j_helpers[8] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_type, "__rb_file_type", 1);
+  j_helpers[9] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_last_modified, "__rb_file_last_modified", 1);
+  j_helpers[10] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_text, "__rb_file_text", 1);
+  j_helpers[11] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_array_buffer, "__rb_file_array_buffer", 1);
+  j_helpers[12] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_slice, "__rb_file_slice", 4);
+
+  // Freed before it is replaced, for the reason the Blob capture below gives:
+  // initialize is private but reachable through send, and a second pass would
+  // otherwise leak this closure and the seven bridges it holds.
+  if (!JS_IsUndefined(data->j_file_proxy_creator))
+    JS_FreeValue(data->context, data->j_file_proxy_creator);
+  data->j_file_proxy_creator = JS_Call(data->context, j_factory_fn, JS_UNDEFINED, 13, j_helpers);
+
+  // Taken here, before a line of guest code has run, because slice builds its
+  // result with it and globalThis.Blob is the guest's to replace by then.
+  //
+  // Once per VM, like the Proxy probe: initialize is private but reachable
+  // through send, and a second pass would overwrite this reference without
+  // freeing the first, which outlives JS_FreeRuntime along with everything it
+  // holds.
+  if (!JS_IsUndefined(data->j_blob_ctor))
+    JS_FreeValue(data->context, data->j_blob_ctor);
+  JSValue j_global = JS_GetGlobalObject(data->context);
+  data->j_blob_ctor = JS_GetPropertyStr(data->context, j_global, "Blob");
+  JS_FreeValue(data->context, j_global);
+  if (JS_IsException(data->j_blob_ctor))
+  {
+    JS_FreeValue(data->context, JS_GetException(data->context));
+    data->j_blob_ctor = JS_UNDEFINED;
+  }
 
   JS_FreeValue(data->context, j_factory_fn);
-  for (int i = 0; i < 7; i++)
+  for (int i = 0; i < 13; i++)
     JS_FreeValue(data->context, j_helpers[i]);
 }
 
 JSValue quickjsrb_file_to_js(JSContext *ctx, VALUE r_file)
 {
   VMData *data = JS_GetContextOpaque(ctx);
-  VALUE r_object_id = rb_funcall(r_file, rb_intern("object_id"), 0);
-  rb_hash_aset(data->alive_objects, r_object_id, r_file);
-  JSValue j_handle = JS_NewInt64(ctx, NUM2LONG(r_object_id));
+  // Taken in the same raise-safe stretch as the draw, so the rollback below
+  // does not dispatch from inside a JSCFunction on its way out.
+  VALUE r_file_object_id = rb_obj_id(r_file);
+  bool registered_here = false;
+  VALUE r_object_id = alive_objects_register(data, r_file, &registered_here);
+  if (NIL_P(r_object_id))
+    return JS_ThrowInternalError(ctx, "quickjs: could not publish a handle for a host File");
+  JSValue j_handle = JS_NewInt64(ctx, NUM2LL(r_object_id));
   JSValue j_proxy = JS_Call(ctx, data->j_file_proxy_creator, JS_UNDEFINED, 1, &j_handle);
   JS_FreeValue(ctx, j_handle);
+  if (JS_IsException(j_proxy) && registered_here)
+    // The third writer, taught the rollback the other two already had: the
+    // creator can fail, and a row left behind anchors this File and its
+    // descriptor for the life of the VM with nothing in JS able to reach it.
+    alive_objects_unregister(data, r_object_id, r_file_object_id);
   return j_proxy;
 }
 
@@ -281,7 +479,12 @@ VALUE quickjsrb_try_convert_js_file(JSContext *ctx, JSValue j_val)
   JSValue j_file_ctor = JS_GetPropertyStr(ctx, j_global, "File");
   if (!JS_IsUndefined(j_file_ctor) && !JS_IsException(j_file_ctor))
   {
+    // instanceof runs Symbol.hasInstance, which is the guest's to define and
+    // can reach a bridge: a failure here leaves that throw pending and the host
+    // exception it parked with nothing able to take it back out.
     int is_file = JS_IsInstanceOf(ctx, j_val, j_file_ctor);
+    if (is_file < 0)
+      quickjsrb_drain_pending(ctx);
     JS_FreeValue(ctx, j_file_ctor);
     if (is_file > 0)
     {
@@ -320,6 +523,8 @@ VALUE quickjsrb_try_convert_js_file(JSContext *ctx, JSValue j_val)
   }
 
   int is_blob = JS_IsInstanceOf(ctx, j_val, j_blob_ctor);
+  if (is_blob < 0)
+    quickjsrb_drain_pending(ctx);
   JS_FreeValue(ctx, j_blob_ctor);
   if (is_blob <= 0)
     return Qnil;

data/lib/quickjs/crypto_key.rb

@@ -11,5 +11,18 @@ module Quickjs
       @usages = usages
       @key_data = key_data
     end
+
+    # The bytes stay out of the string form. to_js_value has no case for this
+    # class, so anything that hands a key back to JS, a pass-through
+    # define_function or a logged value, converts it by calling inspect: a key
+    # generated with extractable: false would otherwise reach the guest in full
+    # through a function that exportKey refuses one call away.
+    def inspect
+      format(
+        '#<%s type=%p extractable=%p algorithm=%p usages=%p key_data=[FILTERED]>',
+        self.class, @type, @extractable, @algorithm, @usages
+      )
+    end
+    alias to_s inspect
   end
 end

data/lib/quickjs/importable.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Quickjs
+  # An ES module compiled to bytecode once and importable into any number of
+  # VMs without reparsing. The module-map counterpart of `Runnable`, which does
+  # the same for classic scripts.
+  #
+  # Unlike `Quickjs.register_module`, nothing about this is process-global:
+  # hold the object, drop it when you're done. That matters for a library that
+  # ships JS of its own, since a global registry would make unrelated gems
+  # coordinate on a name none of their VMs ever share.
+  class Importable
+    # The name QuickJS keys its module map by, the same thing a module_loader
+    # calls `as:`. Not the `filename:` that was passed in: that is only a
+    # prefix of this. Useful for pointing a loader at this module by a
+    # friendlier specifier.
+    attr_reader :canonical_name
+
+    def initialize(bytecode, canonical_name)
+      @bytecode = bytecode
+      @canonical_name = canonical_name
+    end
+
+    def inspect
+      "#<#{self.class} #{@canonical_name} (#{@bytecode.bytesize} bytes)>"
+    end
+
+    private
+
+    # Deliberately not public. Handing out the blob would invite persisting it,
+    # and the bytecode format is tied to the QuickJS build with only a one-byte
+    # version tag to catch a mismatch.
+    def bytecode
+      @bytecode
+    end
+  end
+
+  # Compiles `source` as an ES module and returns an `Importable`.
+  #
+  # The module's name is generated rather than taken from the caller, because
+  # it is baked into the bytecode and becomes the module's identity in every VM
+  # that imports it. Generating it means two independently built Importables
+  # can never collide, which is the whole point when the JS ships inside a gem.
+  # `filename:` prefixes the generated name so stack traces stay readable; it is
+  # a label, not an identity.
+  #
+  # Compiles on a disposable VM: compilation installs a stub module loader to
+  # satisfy QuickJS's compile-time import resolution, and those stubs land in
+  # the compiling context's module map. The default timeout is generous because
+  # a VM's `timeout_msec` is a budget for its own JS, not for parsing.
+  def self.compile_module(source, filename: nil, **opts)
+    raise ::TypeError, "source must be a String, got #{source.class}" unless source.is_a?(String)
+    unless filename.nil? || filename.is_a?(String)
+      raise ::TypeError, "filename: must be a String, got #{filename.class}"
+    end
+
+    name = "#{filename || 'module'}-#{SecureRandom.hex(8)}"
+    vm = VM.new(**{timeout_msec: 60_000, features: []}.merge(opts))
+    Importable.new(vm.send(:_compile_module_to_bytecode, source, name), name)
+  ensure
+    vm&.dispose!
+  end
+
+  module ImportableSupport
+    # `from:` an Importable reads the bytecode into this VM and then imports it
+    # by name, so it takes the same path a preloaded module does: resolution
+    # finds it in the module map and `module_loader` is never asked about it.
+    # Reading is idempotent, so importing the same Importable repeatedly costs
+    # nothing after the first.
+    def import(imported, **opts)
+      importable = opts[:from]
+      return super unless importable.is_a?(Importable)
+
+      send(:_preload_module_bytecode, importable.send(:bytecode), importable.canonical_name)
+      super(imported, **opts.except(:from), filename: importable.canonical_name)
+    end
+  end
+
+  VM.prepend(ImportableSupport) unless VM.ancestors.include?(ImportableSupport)
+end

data/lib/quickjs/modules.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Quickjs
+  # Process-wide registry of ES modules; entries are lazily compiled to
+  # bytecode on first use and the bytecode is reused across VMs.
+  @_modules = {}
+
+  # `name` is the module's canonical name: the string JS code writes in its
+  # `import` statement, and the name QuickJS keys its module map by. It is
+  # baked into the compiled bytecode, so registering under it is what keeps
+  # the registry key and the module's identity from drifting apart.
+  #
+  # `source:` accepts either a `String` (eager) or a `Proc` returning one
+  # (lazy). The lazy form lets a gem register a module at require time
+  # without paying the file-read cost unless a VM actually preloads it.
+  #
+  # Registering only makes the module available; a VM picks it up with
+  # `VM.new(preload_modules: [name])`. Reading a module into a VM costs
+  # real time whether or not it ends up imported, so preloading is a
+  # per-VM decision rather than something registration forces on every VM.
+  def self.register_module(name, source:)
+    raise ::TypeError, "name must be a String, got #{name.class}" unless name.is_a?(String)
+    raise ::TypeError, "source: must be a String or Proc, got #{source.class}" unless source.is_a?(String) || source.is_a?(Proc)
+
+    @_modules[-name] = {source: source, bytecode: nil, mutex: Mutex.new}
+    nil
+  end
+
+  def self._module_registered?(name)
+    @_modules.key?(name)
+  end
+
+  def self._unregister_module(name)
+    @_modules.delete(name)
+    nil
+  end
+
+  def self._preload_modules(vm, names)
+    names.each do |name|
+      raise ::TypeError, "preload_modules: entries must be Strings, got #{name.class}" unless name.is_a?(String)
+
+      entry = @_modules[name]
+      unless entry
+        raise ::ArgumentError,
+          "#{name.inspect} is not a registered module; call Quickjs.register_module(#{name.inspect}, source: ...) first"
+      end
+
+      # Same locking as registered polyfills: `||=` alone isn't atomic
+      # because compilation yields the GVL, so threads racing to construct
+      # VMs could double-compile, or a loser could read entry[:source]
+      # after the winner cleared it. A compile failure leaves bytecode nil
+      # and source intact so a later VM can retry. The unlocked first read
+      # keeps the hot path off the lock once the bytecode exists.
+      bytecode = entry[:bytecode] || entry[:mutex].synchronize {
+        entry[:bytecode] ||= begin
+          compiled = _compile_registered_module(entry, name)
+          entry[:source] = nil # let the Proc's captured scope be GC'd
+          compiled
+        end
+      }
+      vm.send(:_preload_module_bytecode, bytecode, name)
+    end
+  end
+
+  # Compiled on a disposable VM: compilation installs a stub module loader
+  # to satisfy QuickJS's compile-time import resolution, and those stubs
+  # land in the compiling context's module map, so it must not be a VM
+  # anyone goes on to use. The generous timeout covers parsing large
+  # bundles, since the user's per-VM `timeout_msec` is a budget for their
+  # own JS. `features: []` keeps registered polyfills off the temp VM.
+  def self._compile_registered_module(entry, name)
+    source = entry[:source]
+    source = source.call if source.is_a?(Proc)
+    unless source.is_a?(String)
+      raise ::TypeError, "source: Proc for #{name.inspect} must return a String, got #{source.class}"
+    end
+
+    vm = VM.new(timeout_msec: 60_000, features: [])
+    vm.send(:_compile_module_to_bytecode, source, name)
+  ensure
+    vm&.dispose!
+  end
+
+  module ModulePreloader
+    def initialize(preload_modules: [], **opts)
+      super(**opts)
+      unless preload_modules.is_a?(Array)
+        raise ::TypeError, "preload_modules: must be an Array, got #{preload_modules.class}"
+      end
+
+      Quickjs._preload_modules(self, preload_modules)
+    end
+  end
+
+  # Prepended after PolyfillLoader so polyfills are installed first: a
+  # module body can reach for a polyfilled global when it evaluates.
+  VM.prepend(ModulePreloader) unless VM.ancestors.include?(ModulePreloader)
+end

data/lib/quickjs/polyfills.rb

@@ -12,6 +12,12 @@ module Quickjs
   # VM with the same feature: compilation is locked per entry, so that
   # recursion raises ThreadError instead of deadlocking silently.
   #
+  # The polyfill's top level must settle synchronously — no top-level
+  # await. `VM.new(features:)` promises a usable polyfill on return, but
+  # loads never drain the job queue, so nothing past the first await
+  # would have run by then; a pending load raises Quickjs::NoAwaitError
+  # instead of handing back a silently half-applied VM.
+  #
   # Re-registering a name replaces the entry wholesale, lock included: a
   # VM construction already compiling under the old entry finishes
   # against it (and loads the old bytecode) while the first construction
@@ -57,7 +63,15 @@ module Quickjs
           compiled
         end
       }
-      vm.send(:_load_polyfill_bytecode, bytecode)
+      begin
+        vm.send(:_load_polyfill_bytecode, bytecode)
+      rescue Quickjs::RuntimeError => e
+        # The C layer only sees bytecode; name the registration so a VM
+        # with several polyfill features points at the one that failed.
+        # `raise e, msg` clones — class, js_name, and any JS backtrace
+        # already set on the original all survive.
+        raise e, "#{feature}: #{e.message}"
+      end
     end
   end