mini_racer-csim 0.21.1.2 → 0.21.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 876af5088db34f57853916faa39e0568268bfcce946d44078a263de4f9e45867
-  data.tar.gz: 887bf5d80fd136be29e5f6243bc5fd3185b1020eee67002ae5c03176e75f3a85
+  metadata.gz: b0e53581dc8063ed19c418dfc9ea450a7fc027adf5ea7732b32fb5dbabd6b0c7
+  data.tar.gz: 100100878b0966db7d6b0d8a38723993ac33eff9252bd6c48adccfcec65bf92c
 SHA512:
-  metadata.gz: 365acff79cbaca1871707ea32e50d1d91dc7f15c23002e260449c1e1a553cb50c211fdb2406bc54b5bb40aa4e5848e915064891943b68dc8b4ca3ac02589a728
-  data.tar.gz: 48dec93bf2a431bedc18c6c7d5b79890d833db748b525bc5f19c22a796adcd6a0e045acf43d5ac9226a5094dbacf4bc5a48a0214dab71983fd993f930d1ce465
+  metadata.gz: c9a3e14d28a170e7d60201c490e0c695c92684e88f77935c733812206cd7a158d07cd96b76cb0bbfdc9a2f9804c3add1a33d189c47ef2b304873980448ce3ab2
+  data.tar.gz: c74e8ae6b9acac62be7a1099e7464564f08ac3e485f4e2f992b879d27d91c636d412c17506e0e972646e69780cc81dfd70e3de3bdbf961b4c1e3bcf19c808e84

data/CHANGELOG

@@ -1,3 +1,10 @@
+- 0.21.1.3 - 08-06-2026
+  - **Breaking (realm JS API):** move the per-frame-realm JS helpers off bare `globalThis` globals onto the opt-in host namespace, so globalThis pollution is decided once (by `host_namespace:`) rather than per feature
+    - `__mr_realmGlobal(id)` → `<host_namespace>.realmGlobal(id)`
+    - `__mr_realmOf(fn)` → `<host_namespace>.realmOf(fn)`
+    - the embedder-defined `globalThis.__mr_emitUnhandledRejection` hook → a `<host_namespace>.onUnhandledRejection(fn)` registration method (the engine stores the handler per realm and calls it)
+    - **using these JS helpers now requires `Context.new(host_namespace:)`.** Realms themselves do not: `Context#create_realm` + `Realm#eval`/`call`/`attach` work without it (isolated realms driven from Ruby) — only cross-realm wiring *in JS* needs the namespace, which is why the helpers live there
+
 - 0.21.1.2 - 07-06-2026
   - **Breaking:** move off the `mini_racer` require path / `MiniRacer` namespace to a fork-specific identity so the gem never collides with — and loads deterministically alongside — upstream `mini_racer` in the same bundle
     - require path: `require 'mini_racer_csim'` (was `require 'mini_racer'`); the `require 'mini_racer-csim'` autorequire shim now points here

data/README.md

@@ -12,7 +12,7 @@ MiniRacer has an adapter for [execjs](https://github.com/rails/execjs) so it can
 
 ## This repository is `mini_racer-csim` (a fork)
 
-This is **`mini_racer-csim`**, a private fork of [`mini_racer`](https://github.com/rubyjs/mini_racer) maintained for [capybara-simulated](https://github.com/ursm/capybara-simulated). It adds browser-fidelity extensions (ES modules, realm reset, …) that capybara-simulated needs but most users do not — **if you are not using capybara-simulated, use upstream `mini_racer`.**
+This is **`mini_racer-csim`**, a private fork of [`mini_racer`](https://github.com/rubyjs/mini_racer) maintained for [capybara-simulated](https://github.com/ursm/capybara-simulated). It adds browser-fidelity extensions (ES modules, per-frame realms, realm reset, …) that capybara-simulated needs but most users do not — **if you are not using capybara-simulated, use upstream `mini_racer`.**
 
 It has its **own require path and namespace** so it never collides with — and loads deterministically alongside — upstream `mini_racer` in the same bundle: load it with `require 'mini_racer_csim'` and use the `MiniRacerCsim` module (e.g. `MiniRacerCsim::Context`). The native extensions are `mini_racer_csim_extension` / `mini_racer_csim_loader`. (The JS-side host-namespace brand, `globalThis.MiniRacer` by default, is embedder-chosen and unrelated to the Ruby namespace.)
 
@@ -24,10 +24,11 @@ It has its **own require path and namespace** so it never collides with — and
 | ES Module API | `Context#compile_module` → `MiniRacerCsim::Module` (`#instantiate` / `#evaluate` / `#namespace` / `#status` / `#cached_data` / `#dispose`); `Context#dynamic_import_resolver=` | V8's ES module pipeline, `import.meta.url`, dynamic `import()` |
 | Batched module-graph loader | `Context#load_module_graph(resolve:, …)` | Loads an ESM graph in one batched, native (C++) pass; one `Module` per URL shared across every load path |
 | Realm reset | `Context#reset_realm` | Discards the user realm (`globalThis`) while keeping the warm isolate (browser per-navigation model); re-binds attached host functions and the host namespace |
+| Per-frame realms | `Context#create_realm` → `MiniRacerCsim::Realm` (`#eval` / `#call` / `#attach` / `#dispose` / `#disposed?`) | Multiple V8 realms (Contexts) in one isolate with browser-iframe semantics: realms share one security token for cross-realm access. JS-side helpers live on the [host namespace](#host-namespace) (so using them needs `host_namespace:`): `<ns>.realmGlobal(id)` exposes a realm's live `globalThis`, `<ns>.realmOf(fn)` reports a callback's `[[Realm]]`, and `<ns>.onUnhandledRejection(fn)` registers a per-realm unhandled-rejection handler. Realms themselves work without the namespace (driven from Ruby). |
 | Host namespace | `Context.new(host_namespace: "MiniRacer")` → `globalThis.MiniRacer.drainMicrotasks()` | Opt-in JS namespace exposing an inline, rendezvous-free microtask checkpoint |
 | GVL release on boot | (automatic) | Releases the Ruby GVL while the V8 thread boots the isolate |
 
-The fork is periodically rebased on upstream `mini_racer` to pick up V8 / `libv8-node` bumps and bug fixes.
+This is a hard fork: it no longer tracks upstream `mini_racer`, and follows only `libv8-node` for V8 version bumps.
 
 ## Supported Ruby Versions & Troubleshooting
 

data/ext/mini_racer_csim_extension/mini_racer_v8.cc

@@ -134,6 +134,11 @@ struct Realm
     // graph_resolve_callback can resolve imports from the pre-walked graph
     // with zero Ruby round-trips. Null otherwise.
     struct GraphLoad *active_graph = nullptr;
+    // Embedder-registered handler for promises that reject with no handler in
+    // this realm, set via <host_namespace>.onUnhandledRejection(fn). Called by
+    // notify_unhandled_rejections with (reason, promise). Global so its dtor
+    // releases the function when the realm is disposed; reset on reset_realm.
+    v8::Global<v8::Function> unhandled_rejection_handler;
 };
 
 struct State
@@ -768,13 +773,14 @@ void v8_drain_microtasks_callback(const v8::FunctionCallbackInfo<v8::Value>& inf
     info.GetReturnValue().SetUndefined();
 }
 
-// __mr_realmGlobal(id): returns the globalThis of realm `id` as a LIVE V8
-// object in the calling realm (same isolate, not a copy), or undefined for an
-// unknown realm. Installed on every realm's global. Because all realms share
-// one security token (see install_realm), the caller can read/write the
-// returned global's properties — this is how csim wires frames[i] /
-// iframe.contentWindow to the right realm. Cross-realm object identity holds:
-// mutating a property here is visible in the target realm and vice versa.
+// <host_namespace>.realmGlobal(id): returns the globalThis of realm `id` as a
+// LIVE V8 object in the calling realm (same isolate, not a copy), or undefined
+// for an unknown realm. Hung off the host namespace (opt-in via
+// Context.new(host_namespace:)) rather than a bare global, so globalThis stays
+// unpolluted. Because all realms share one security token (see install_realm),
+// the caller can read/write the returned global's properties — this is how csim
+// wires frames[i] / iframe.contentWindow to the right realm. Cross-realm object
+// identity holds: mutating a property here is visible in the target realm.
 void v8_realm_global_callback(const v8::FunctionCallbackInfo<v8::Value>& info)
 {
     auto isolate = info.GetIsolate();
@@ -815,13 +821,13 @@ static int32_t realm_id_of_context(v8::Local<v8::Context> ctx)
     return v.As<v8::Int32>()->Value();
 }
 
-// __mr_realmOf(fn): returns the realm id where `fn` (any object/function) was
-// created — its [[Realm]] / creation context — or undefined if unknown. This is
-// the realm WebIDL's "invoke a callback function" reports errors against (e.g.
-// a setTimeout callback's uncaught throw is reported on the realm that *created*
-// the callback, not the scheduling realm nor the thrown Error's realm). csim
-// uses it to dispatch an ErrorEvent on __mr_realmGlobal(__mr_realmOf(cb)) from
-// its own per-callback try/catch.
+// <host_namespace>.realmOf(fn): returns the realm id where `fn` (any
+// object/function) was created — its [[Realm]] / creation context — or
+// undefined if unknown. This is the realm WebIDL's "invoke a callback function"
+// reports errors against (e.g. a setTimeout callback's uncaught throw is
+// reported on the realm that *created* the callback, not the scheduling realm
+// nor the thrown Error's realm). csim uses it to dispatch an ErrorEvent on
+// <ns>.realmGlobal(<ns>.realmOf(cb)) from its own per-callback try/catch.
 void v8_realm_of_callback(const v8::FunctionCallbackInfo<v8::Value>& info)
 {
     auto isolate = info.GetIsolate();
@@ -842,6 +848,27 @@ void v8_realm_of_callback(const v8::FunctionCallbackInfo<v8::Value>& info)
     info.GetReturnValue().Set(v8::Integer::New(isolate, rid));
 }
 
+// <host_namespace>.onUnhandledRejection(fn): register fn as the calling realm's
+// handler for promises that reject with no handler. notify_unhandled_rejections
+// calls it with (reason, promise) at the next microtask checkpoint, entered in
+// the rejecting promise's realm (HTML notify-rejected-promises). The handler is
+// stored per realm (keyed by the calling context's realm id) instead of as a
+// bare globalThis property, so globalThis stays unpolluted. Passing a non-
+// function clears the handler.
+void v8_set_unhandled_rejection_handler(const v8::FunctionCallbackInfo<v8::Value>& info)
+{
+    auto isolate = info.GetIsolate();
+    State& st = *static_cast<State*>(isolate->GetData(0));
+    int32_t rid = realm_id_of_context(isolate->GetCurrentContext());
+    auto it = st.realms.find(rid);
+    if (it == st.realms.end())
+        return; // unknown realm: no-op
+    if (info.Length() >= 1 && info[0]->IsFunction())
+        it->second->unhandled_rejection_handler.Reset(isolate, info[0].As<v8::Function>());
+    else
+        it->second->unhandled_rejection_handler.Reset();
+}
+
 // V8 calls this when a promise's rejection state changes. We implement the
 // HTML "notify rejected promises" bookkeeping: queue promises that reject with
 // no handler (tagged with the realm they were created in), and drop them again
@@ -1041,12 +1068,13 @@ static void clear_realm_locals(State& st)
 }
 
 // HTML notify-rejected-promises: for each promise that rejected with no handler
-// since the last checkpoint, enter its realm and call the embedder's
-// globalThis.__mr_emitUnhandledRejection(reason, promise) if present (csim
-// turns that into a PromiseRejectionEvent so addEventListener('unhandledrejection')
-// fires natively in the right realm). The list is snapshotted and cleared first
-// so rejections triggered by a handler queue for the next checkpoint instead of
-// looping. A realm disposed in the meantime is skipped.
+// since the last checkpoint, enter its realm and call that realm's handler
+// (registered via <host_namespace>.onUnhandledRejection) with (reason, promise)
+// if one was set (csim turns that into a PromiseRejectionEvent so
+// addEventListener('unhandledrejection') fires natively in the right realm). The
+// list is snapshotted and cleared first so rejections triggered by a handler
+// queue for the next checkpoint instead of looping. A realm disposed in the
+// meantime is skipped.
 static void notify_unhandled_rejections(State& st)
 {
     if (st.pending_rejections.empty())
@@ -1067,18 +1095,17 @@ static void notify_unhandled_rejections(State& st)
         auto context = v8::Local<v8::Context>::New(st.isolate, it->second->persistent_context);
         if (context.IsEmpty())
             continue;
+        if (it->second->unhandled_rejection_handler.IsEmpty())
+            continue; // realm registered no onUnhandledRejection handler
         st.active_realm_id = pr.second;
         restore_realm_locals(st);
         v8::Context::Scope context_scope(context);
         auto global = context->Global();
-        auto name = v8::String::NewFromUtf8Literal(st.isolate, "__mr_emitUnhandledRejection");
-        v8::Local<v8::Value> hook;
-        if (!global->Get(context, name).ToLocal(&hook) || !hook->IsFunction())
-            continue;
+        auto hook = v8::Local<v8::Function>::New(st.isolate, it->second->unhandled_rejection_handler);
         auto promise = v8::Local<v8::Promise>::New(st.isolate, pr.first);
         v8::TryCatch try_catch(st.isolate); // swallow errors from the handler itself
         v8::Local<v8::Value> args[2] = { promise->Result(), promise };
-        (void)hook.As<v8::Function>()->Call(context, global, 2, args);
+        (void)hook->Call(context, global, 2, args);
     }
     st.active_realm_id = prev;
     st.context = saved_context;
@@ -1133,47 +1160,41 @@ static bool install_realm(State& st)
     v8::Context::Scope context_scope(context);
     // If the embedder opted in via Context.new(host_namespace:), install a
     // single host-namespace object (in the spirit of Deno's `Deno` / Bun's
-    // `Bun`) under that global name and hang native helpers off it. The object
-    // closes over native code pointers so it cannot live in the (de)serialized
-    // snapshot; it is installed here on every fresh realm. The namespace is
-    // non-enumerable on globalThis so it stays out of Object.keys(globalThis)/
-    // for-in; its methods are ordinary enumerable properties so they remain
-    // discoverable on the object.
+    // `Bun`) under that global name and hang EVERY native JS helper off it:
+    // drainMicrotasks(), realmGlobal(id), realmOf(fn), onUnhandledRejection(fn).
+    // Keeping them on one opt-in object (rather than bare __mr_* globals) means
+    // globalThis pollution is decided once, by the opt-in — not relitigated per
+    // feature. The object closes over native code pointers so it cannot live in
+    // the (de)serialized snapshot; it is installed here on every fresh realm.
+    // The namespace is non-enumerable on globalThis (out of Object.keys/for-in);
+    // its methods are ordinary properties so they remain discoverable.
+    //
+    // Consequence: the JS-side realm-reflection helpers (realmGlobal/realmOf)
+    // and per-realm unhandled-rejection delivery require host_namespace. Realms
+    // themselves do NOT — Context#create_realm + Realm#eval/call/attach work
+    // without it (isolated realms driven from Ruby); only cross-realm wiring *in
+    // JS* needs these helpers, which is why they live on the namespace.
     if (!st.host_namespace.empty()) {
         v8::Local<v8::String> ns_name;
         if (!v8::String::NewFromUtf8(st.isolate, st.host_namespace.c_str()).ToLocal(&ns_name))
             return false;
         auto ns = v8::Object::New(st.isolate);
         auto data = v8::External::New(st.isolate, pst);
-        auto drain_name = v8::String::NewFromUtf8Literal(st.isolate, "drainMicrotasks");
-        v8::Local<v8::Function> drain;
-        if (!v8::Function::New(context, v8_drain_microtasks_callback, data).ToLocal(&drain))
-            return false;
-        if (!ns->Set(context, drain_name, drain).FromMaybe(false)) return false;
+        v8::Local<v8::Function> drain, rg, ro, onrej;
+        // drainMicrotasks + realmGlobal read State via info.Data() (the External);
+        // realmOf + onUnhandledRejection take none (onUnhandledRejection uses
+        // isolate->GetData(0)), so they are created without data.
+        if (!v8::Function::New(context, v8_drain_microtasks_callback, data).ToLocal(&drain)) return false;
+        if (!v8::Function::New(context, v8_realm_global_callback, data).ToLocal(&rg)) return false;
+        if (!v8::Function::New(context, v8_realm_of_callback).ToLocal(&ro)) return false;
+        if (!v8::Function::New(context, v8_set_unhandled_rejection_handler).ToLocal(&onrej)) return false;
+        if (!ns->Set(context, v8::String::NewFromUtf8Literal(st.isolate, "drainMicrotasks"), drain).FromMaybe(false)) return false;
+        if (!ns->Set(context, v8::String::NewFromUtf8Literal(st.isolate, "realmGlobal"), rg).FromMaybe(false)) return false;
+        if (!ns->Set(context, v8::String::NewFromUtf8Literal(st.isolate, "realmOf"), ro).FromMaybe(false)) return false;
+        if (!ns->Set(context, v8::String::NewFromUtf8Literal(st.isolate, "onUnhandledRejection"), onrej).FromMaybe(false)) return false;
         if (!context->Global()->DefineOwnProperty(context, ns_name, ns, v8::DontEnum).FromMaybe(false))
             return false;
     }
-    // Install __mr_realmGlobal(id) on every realm (not gated by host_namespace):
-    // it returns realm `id`'s live globalThis so realms can reach each other
-    // (per-frame realms / iframes). Non-enumerable so it stays out of
-    // Object.keys(globalThis).
-    {
-        auto rg_name = v8::String::NewFromUtf8Literal(st.isolate, "__mr_realmGlobal");
-        auto rg_data = v8::External::New(st.isolate, pst);
-        v8::Local<v8::Function> rg;
-        if (!v8::Function::New(context, v8_realm_global_callback, rg_data).ToLocal(&rg))
-            return false;
-        if (!context->Global()->DefineOwnProperty(context, rg_name, rg, v8::DontEnum).FromMaybe(false))
-            return false;
-        // __mr_realmOf(fn) -> realm id where fn was created (for per-realm error
-        // attribution; the embedder dispatches error events on that realm).
-        auto ro_name = v8::String::NewFromUtf8Literal(st.isolate, "__mr_realmOf");
-        v8::Local<v8::Function> ro;
-        if (!v8::Function::New(context, v8_realm_of_callback).ToLocal(&ro))
-            return false;
-        if (!context->Global()->DefineOwnProperty(context, ro_name, ro, v8::DontEnum).FromMaybe(false))
-            return false;
-    }
     // Re-attach host functions onto the fresh global. Empty at boot; populated
     // when install_realm runs from v8_reset_realm. bind_callback reads st.context,
     // so point the members at the new realm for the duration of the loop, and
@@ -2999,6 +3020,10 @@ extern "C" void v8_reset_realm(State *pst)
     cur(st).scripts.clear();
     cur(st).modules.clear();
     cur(st).module_id_by_url.clear();
+    // The realm-0 struct is reused across reset, so its onUnhandledRejection
+    // handler points at a function in the now-discarded old realm. Drop it; the
+    // embedder re-registers on the fresh realm (the namespace is reinstalled).
+    cur(st).unhandled_rejection_handler.Reset();
     // Same rationale as the scripts/modules above: a not-yet-delivered rejection
     // recorded against the old realm would, after the swap, fire against the
     // fresh realm's globalThis (reset reuses the realm id). Drop them.
@@ -3067,6 +3092,7 @@ State::~State()
             Realm& r = *kv.second;
             r.modules.clear();
             r.scripts.clear();
+            r.unhandled_rejection_handler.Reset();
             r.persistent_safe_context_function.Reset();
             r.persistent_safe_context.Reset();
             r.persistent_context.Reset();

data/lib/mini_racer_csim/version.rb

@@ -4,6 +4,6 @@ module MiniRacerCsim
   # mini_racer-csim fork: upstream version + a fork revision segment.
   # 0.21.1.0 = first fork release on upstream 0.21.1; bump the 4th segment for
   # fork-only changes, reset it when rebasing onto a new upstream version.
-  VERSION = "0.21.1.2"
+  VERSION = "0.21.1.3"
   LIBV8_NODE_VERSION = "~> 24.12.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer-csim
 version: !ruby/object:Gem::Version
-  version: 0.21.1.2
+  version: 0.21.1.3
 platform: ruby
 authors:
 - Keita Urashima
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,11 +110,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 24.12.0.1
 description: 'A private fork of mini_racer (minimal embedded V8 for Ruby) adding browser-level
-  behavior used by capybara-simulated: the V8 ES Module API, cross-process bytecode
-  caching, an opt-in host namespace, realm reset, and a batched module-graph loader
-  with a URL module registry. These are niche browser-fidelity features; general users
-  should use upstream mini_racer. The library is still required as `mini_racer` and
-  exposes the `MiniRacer` module, so it stays a drop-in for code targeting mini_racer.'
+  behavior used by capybara-simulated: the V8 ES Module API, per-frame realms, realm
+  reset, cross-process bytecode caching, an opt-in host namespace, and a batched module-graph
+  loader with a URL module registry. These are niche browser-fidelity features; general
+  users should use upstream mini_racer. It loads under its own `mini_racer_csim` require
+  path and `MiniRacerCsim` namespace, so it never collides with upstream mini_racer
+  in the same bundle.'
 email:
 - ursm@ursm.jp
 executables: []