Class: Capybara::Simulated::V8Runtime

Inherits:
Object
  • Object
show all
Defined in:
lib/capybara/simulated/v8_runtime.rb

Defined Under Namespace

Classes: Ctx

Constant Summary collapse

HOST_NAMESPACE_NAME =

The host namespace rusty_racer installs into every context (main and per-frame): ‘globalThis.RustyRacer.drainMicrotasks()` (a native, rendezvous-free microtask checkpoint), `contextGlobal(id)` / `contextOf(value)` (the per-frame realm machinery), and `setPromiseRejectHandler`. The bridge JS hard-codes the same `globalThis.RustyRacer` literal (timers.js / platform-globals.js / unhandled-rejection.js / bridge.entry.js) — a rename must touch both sides.

'RustyRacer'
SNAPSHOT_WARMUP =

Pre-warm script: exercises the JS surfaces that get JIT-compiled on every page load (HTML parse, selector tokenise + match, event dispatch, style-decl parse, cascade resolve). Runs once at snapshot creation; the resulting compiled-code state ships in the snapshot so each new context starts with these paths warm. (‘Snapshot#warmup!` follows the V8 WarmUpSnapshotDataBlob contract: the warmup runs in a throwaway context — only code, no heap state, survives into the blob.)

'logfile-per-isolate': nil)
  end
  # `CSIM_V8_FLAGS` passes arbitrary V8 flags through to
  # `set_flags_from_string` for perf experiments (JIT tier-up tuning,
  # GC, lite-mode). Whitespace-separated; each token is `--`-prefixed by
  # rusty's `set_flags!`, so write them WITHOUT the leading dashes:
  #   CSIM_V8_FLAGS='jitless'                 -> --jitless
  #   CSIM_V8_FLAGS='sparkplug no-turbofan'   -> --sparkplug --no-turbofan
  #   CSIM_V8_FLAGS='max-opt=1'               -> --max-opt=1
  # Flags may interact with the cached snapshot's compiled-code state, so
  # pair a sweep with `CSIM_SNAPSHOT_CACHE=off`.
  if (raw = ENV['CSIM_V8_FLAGS'].to_s.strip) && !raw.empty?
    flags = raw.split(/\s+/).map {|f| f.sub(/\A--/, '') }
    RustyRacer::Platform.set_flags!(*flags)
  end
rescue RustyRacer::PlatformAlreadyInitialized
end

module Capybara
  module Simulated
    class V8Runtime

@@snapshot_lock = Mutex.new
@@snapshot      = nil
@@live_lock     = Mutex.new
@@live          = []

at_exit do
  @@live_lock.synchronize {
    @@live.each {|c|
      begin
        c.terminate rescue nil
        c.dispose
      rescue StandardError
      end
    }
    @@live.clear
  }
end

# The host namespace rusty_racer installs into every context (main and
# per-frame): `globalThis.RustyRacer.drainMicrotasks()` (a native,
# rendezvous-free microtask checkpoint), `contextGlobal(id)` /
# `contextOf(value)` (the per-frame realm machinery), and
# `setPromiseRejectHandler`. The bridge JS hard-codes the same
# `globalThis.RustyRacer` literal (timers.js / platform-globals.js /
# unhandled-rejection.js / bridge.entry.js) — a rename must touch both
# sides.
HOST_NAMESPACE_NAME = 'RustyRacer'

# One isolate + its default context, presented as a single handle — the
# shape the rest of the runtime (and `ScriptCache`) passes around.
# rusty splits the VM into an `Isolate` (lifecycle / realms / microtasks /
# terminate) and the `Context`s it hands out (eval / call / attach /
# compile / reset); this class pairs them and replays recorded host-fn
# attaches onto per-frame realm contexts (rusty's attach is per-context).
class Ctx
  def initialize(snapshot: nil, timeout: 0)
    @iso        = RustyRacer::Isolate.new(host_namespace: HOST_NAMESPACE_NAME,
                                          snapshot:       snapshot,
                                          timeout_ms:     timeout.to_i)
    @ctx        = @iso.context
    @attached   = []
    @generation = 0
  end

  # ── Context surface ─────────────────────────────────────────
  # rusty drains microtasks at call-depth zero (V8's default kAuto
  # policy), so a returned eval/call has already run its end-of-script
  # microtasks.
  def eval(src)          = @ctx.eval(src)
  def call(name, *args)  = @ctx.call(name, *args)

  # Record every attach so `create_context` can replay them: the bridge
  # in a per-frame realm reaches the same Ruby host fns as the main
  # context, but rusty's attach is per-context.
  def attach(name, prc)
    @attached << [name, prc]
    @ctx.attach(name, prc)
  end

  # One rendezvous for the whole host-fn table (vs one per fn).
  def attach_many(fns)
    @attached.concat(fns.to_a)
    @ctx.attach_many(fns)
  end

  # Bumped on every realm reset: realm-bound caches (module handles)
  # key off `[object_id, generation]` so invalidation is intrinsic to
  # reset — the Ctx OBJECT survives a warm reset, so object_id alone
  # can't detect one.
  attr_reader :generation

  # Swap the realm for a snapshot-fresh one on the warm isolate. Per
  # rusty's contract the host fns die with the old context — drop the
  # replay record so the caller's re-attach doesn't accumulate stale
  # entries visit over visit.
  def reset
    @ctx.reset
    @attached.clear
    @generation += 1
  end

  def compile(src, **kw)        = @ctx.compile(src, **kw)
  def compile_module(src, **kw) = @ctx.compile_module(src, **kw)

  # ── Isolate surface ─────────────────────────────────────────
  def terminate                        = @iso.terminate
  def dispose                          = @iso.dispose
  def perform_microtask_checkpoint     = @iso.perform_microtask_checkpoint

  def dynamic_import_resolver=(prc)
    @iso.dynamic_import_resolver = prc
  end

  # A per-iframe realm: a fresh context in the SAME isolate (shared heap,
  # own global + intrinsics). Carries `.id` / eval / call / dispose — the
  # rest of the surface `create_frame_realm` needs.
  #
  # `to_h` dedups re-attached names to their latest proc, matching
  # attach's override semantics. NOTE: context-bound fns
  # (`__csim_runScript*`, `__csim_evalEsmEntry`) get realm-bound
  # overrides in `create_frame_realm` after this replay.
  def create_context
    realm = @iso.create_context
    realm.attach_many(@attached.to_h)
    realm
  end
end

def self.snapshot
  @@snapshot_lock.synchronize { @@snapshot ||= build_snapshot }
end

# Pre-warm script: exercises the JS surfaces that get JIT-compiled
# on every page load (HTML parse, selector tokenise + match, event
# dispatch, style-decl parse, cascade resolve). Runs once at
# snapshot creation; the resulting compiled-code state ships in
# the snapshot so each new context starts with these paths warm.
# (`Snapshot#warmup!` follows the V8 WarmUpSnapshotDataBlob contract:
# the warmup runs in a throwaway context — only code, no heap state,
# survives into the blob.)
SNAPSHOT_WARMUP = <<~JS.freeze
  (function () {
    // Drive a representative document through parse → script
    // eval → selector / event / cascade primitives so the
    // bytecode cache covers them when a real visit hits.
    const html = '<!doctype html><html><head><style>' +
      '.a { display: none } .a.show { display: block }' +
      '#m, .b > .c { visibility: hidden }' +
      '@media (max-width: 899px) { .b { display: none } }' +
      '</style></head><body>' +
      '<div id="m" class="a"><span class="b"><a class="c" href="/x">x</a></span></div>' +
      '<form><input name="q" type="text" value="hi"><button type="submit">go</button></form>' +
      '<script>document.querySelector("#m");</script>' +
      '</body></html>';
    try { __csimLoadDocument(html); } catch (_) {}
    try { __csimEvaluateXPath('//a', 0); } catch (_) {}
    try { __csimVisible(1); } catch (_) {}
    try { __csimQuery(0, '#m'); } catch (_) {}
    try { __csimQuery(0, '.b > .c'); } catch (_) {}
    try {
      const root = document.documentElement;
      if (root) {
        root.querySelectorAll('a');
        root.querySelectorAll('.b > .c, #m');
      }
    } catch (_) {}
  })();
JS
CALL_TIMEOUT_MS =

Per-call wall-clock cap (ms). Off by default. Opt in via ‘CSIM_V8_CALL_TIMEOUT_MS=30000` for long-running suites where an occasional JS-side infinite loop would otherwise stall the whole run; the timeout converts the hang into a `RustyRacer::ScriptTerminatedError` on that one example. The terminate escalates through any nested frames (it is isolate-global by design), and the isolate itself stays healthy for subsequent calls — csim treats a terminated call as fatal to that call only. The clean slate comes from the next rebuild: a warm `Context#reset` normally, or — if the terminate wedged a suspended request and reset is refused — the loud cold-rebuild fallback in `rebuild_ctx`.

(ENV['CSIM_V8_CALL_TIMEOUT_MS'] || '0').to_i
SCRIPT_CACHE_MIN_BYTES =

Override the JS-side ‘__csim_runScript` fallback with a Ruby host fn that bytecode-caches each script body in a process-wide hash + on-disk store (`Context#compile` + `Script#cached_data`). Discourse’s main chunk is ~140 ms of parse + JIT per visit otherwise; the cache reduces it to a deserialize + run path. Worker isolates run on their own threads — ‘compile` from the main thread against a Worker isolate is unsafe — so the class-level `attach_host_fns` (used by `build_worker`) intentionally skips this attach. V8’s bytecode cache only pays off above a body-size threshold — the rendezvous round-trip + Ruby-side SHA256 + compile + dispose runs ~150–300 µs, while ‘(0, eval)(body)` at V8 globalThis for a tiny script is sub-microsecond. Above the threshold, V8 parse + JIT cold-path is multiple ms — worth the cache. Redmine’s jQuery + Stimulus inline scripts (median ~400 B) dominated the regression: pre-threshold, routing every snippet through Ruby blew the 122-test suite from 56 s → 224 s. Threshold sweep:

threshold | Redmine wall
  1 KB    | 143 s
  8 KB    | 103 s
 32 KB    |  90 s
 64 KB    |  62 s  ← baseline parity

64 KB keeps Discourse’s main Ember chunk (140 KB+) on the cache path while Stimulus / Trix / etc. shorts stay on the JS-only fast path. ‘CSIM_SCRIPT_CACHE_MIN_BYTES=0` forces the cache for everything (debug / cross-process bench).

(ENV['CSIM_SCRIPT_CACHE_MIN_BYTES'] || '65536').to_i
@@snapshot_lock = 
Mutex.new
@@snapshot = 
nil
@@live_lock = 
Mutex.new
@@live = 
[]

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(browser) ⇒ V8Runtime

Returns a new instance of V8Runtime.



304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 304

def initialize(browser)
  @browser = browser
  @ctx     = nil
  # Every context is built from the base snapshot (bridge +
  # vendor bundle). Library scripts (`<script src>`) get evaluated
  # per-visit just like a real browser does on page navigation.
  # Pre-evaluating libraries into the snapshot heap is not safe:
  # jQuery's `readyList` Callbacks queue would carry `$(handler)`
  # registrations from a prior page's scripts, and a single
  # throwing handler (e.g. touching a DOM node that only existed
  # on the prior page) aborts iteration mid-fire and silently
  # drops every later callback — including the current page's.
  @snapshot = self.class.snapshot
  # `@compiled_module_urls` / `@compiled_script_keys` track what this
  # isolate has already compiled, for the no-cd paths in
  # `native_module_for` / `attach_run_script_with_cache`. They persist
  # across warm realm resets (same isolate, warm in-memory compilation
  # cache) and are cleared only on a true rebuild (different isolate,
  # cold cache).
  @compiled_module_urls = {}
  @compiled_script_keys = {}
end

Class Method Details

.attach_host_fns(c, browser) ⇒ Object

Class-level attach so Worker isolates (Ruby-thread-owned contexts that don’t have a Runtime instance wrapping them) reuse the same ‘BROWSER_HOST_FNS` + `STDLIB_HOST_FNS` table the main runtime wires up.



929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 929

def self.attach_host_fns(c, browser)
  fns = {}
  RuntimeShared::BROWSER_HOST_FNS.each {|name, body|
    fns[name] = ->(*a) { RuntimeShared.safe_call { body.call(browser, *a) } }
  }
  fns.update(RuntimeShared::STDLIB_HOST_FNS)
  # One rendezvous for the whole table (~50 fns) — this runs per cold
  # build, per worker, and per warm realm reset.
  c.attach_many(fns)
  # `dispatchEventForUserAction` calls `__csim_yield` between listener
  # invocations to match HTML spec "clean up after running script"
  # microtask-checkpoint semantics. Alias it to the namespace's native
  # in-isolate checkpoint so callers pay ~sub-µs instead of an
  # attached-fn cross-thread round-trip.
  c.eval("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
  # Register the bridge's recorder for V8's promise-reject notifications
  # — the channel that surfaces rejections NO handler ever sees
  # (fire-and-forget async functions, bare `Promise.reject`); the
  # bridge's `.then`-wrap can't observe those. Post-snapshot: the host
  # namespace doesn't exist while the snapshot is built, which is why
  # unhandled-rejection.js leaves registration to us. Main realm only —
  # the recorder routes per-realm via `contextGlobal` itself, and a
  # frame-realm registration would dangle once that realm is disposed.
  c.eval(<<~JS)
    if (typeof globalThis.#{HOST_NAMESPACE_NAME}.setPromiseRejectHandler === 'function' &&
        typeof globalThis.__csimPromiseRejected === 'function') {
      globalThis.#{HOST_NAMESPACE_NAME}.setPromiseRejectHandler(globalThis.__csimPromiseRejected);
    }
  JS
end

.build_snapshot ⇒ Object

‘Snapshot.new(source)` is non-deterministic — V8 embeds transient allocator state in the produced bytes, so the same source yields different blobs across runs. V8’s bytecode-cache validation (‘ScriptCompiler::CompileUnboundScript` with `kConsumeCodeCache`) keys on snapshot bytes, so re-`new`-ing in each process makes cross-process `ScriptCache` hits get rejected. Building once and persisting the dump fixes that: every process boots off byte-identical snapshot bytes and `cached_data` accepts.



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 218

def self.build_snapshot
  cache_path = snapshot_cache_path
  return build_snapshot_uncached unless cache_path
  begin
    FileUtils.mkdir_p(File.dirname(cache_path))
    # Serialize concurrent cold boots (parallel test workers):
    # `Snapshot.new` is non-deterministic, so two processes racing the
    # build would persist different bytes and every ScriptCache entry
    # keyed to the loser's blob gets `cache_rejected` forever after.
    # One process builds under the lock; the rest load its bytes.
    File.open("#{cache_path}.lock", File::CREAT | File::RDWR) do |lock|
      lock.flock(File::LOCK_EX)
      if (bytes = read_verified_snapshot(cache_path))
        return RustyRacer::Snapshot.load(bytes)
      end
      snap  = build_snapshot_uncached
      # Persist + reload so this process also boots from the same
      # bytes other processes will load — the produce-side snapshot
      # must equal the consume-side snapshot for `cached_data` to
      # accept (see the build_snapshot header rationale).
      bytes = snap.dump
      persist_snapshot_bytes(bytes, cache_path)
      return RustyRacer::Snapshot.load(bytes)
    end
  rescue StandardError
    # Cache plumbing must never break boot; fall back to an
    # in-process build (we just lose the cross-process savings).
    build_snapshot_uncached
  end
end

.build_snapshot_uncached ⇒ Object 



249
250
251
252
253
254
255
256
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 249

def self.build_snapshot_uncached
  snap = RustyRacer::Snapshot.new(RuntimeShared.snapshot_src)
  # `warmup!` runs `SNAPSHOT_WARMUP` once in a throwaway context and
  # keeps the resulting compiled code, so contexts created from this
  # snapshot inherit JIT-primed versions of the hot paths above.
  snap.warmup!(SNAPSHOT_WARMUP) rescue nil
  snap
end

.build_worker(browser, post_back) ⇒ Object

Worker-isolate factory: fresh isolate from the shared snapshot, host fns attached, ‘__csim_isWorker` flag set, + the per-worker postMessage host fn closed over `post_back`. Returns a uniform `WorkerRuntime` adapter that `Browser#run_worker` drives.



965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 965

def self.build_worker(browser, post_back)
  c = Ctx.new(snapshot: snapshot)
  attach_host_fns(c, browser)
  c.attach('__csim_workerPostMessage', ->(data) { post_back.call(data); nil })
  # Worker's timer table is independent from main's; routing the
  # worker's `setTimersActive` through `browser.timers_active=`
  # races the main isolate's polling? gate, dropping main-thread
  # pending XHRs the moment the worker's queue empties. The settle
  # loop already polls `worker_pending?` for worker thread activity.
  c.attach('__setTimersActive', ->(_flag) { nil })
  c.eval('__csim_installWorkerScope();')
  WorkerRuntime.new(
    eval_fn:           ->(s)     { c.eval(s.to_s) },
    call_fn:           ->(n, *a) { c.call(n.to_s, *a) },
    drain_microtasks:  ->        { c.perform_microtask_checkpoint },
    drain_timers:      ->        { c.call('__drainTimers', 50) },
    has_ready_timer:   ->        { !!c.call('__hasReadyTimer') },
    dispose:           ->        { c.dispose rescue nil }
  )
end

.cached_data_version_tag ⇒ Object

V8’s bytecode-cache version tag. Keys every ScriptCache entry so a V8 upgrade invalidates stale bytecode. Fixed per process → memoized.



519
520
521
522
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 519

def self.cached_data_version_tag
  return @cached_data_version_tag if defined?(@cached_data_version_tag)
  @cached_data_version_tag = RustyRacer.cached_data_version_tag
end

.persist_snapshot_bytes(bytes, path) ⇒ Object 



281
282
283
284
285
286
287
288
289
290
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 281

def self.persist_snapshot_bytes(bytes, path)
  tmp = "#{path}.#{Process.pid}.tmp"
  File.binwrite(tmp, bytes)
  File.write("#{path}.sha256", Digest::SHA256.hexdigest(bytes))
  File.rename(tmp, path)
  prune_snapshot_cache(path)
rescue StandardError
  # Best-effort: snapshot rebuild on every process is fine,
  # we just lose the cross-process startup savings.
end

.prune_snapshot_cache(current) ⇒ Object

A multi-MB blob per bridge edit / V8 upgrade accrues forever otherwise; only the current key is ever loadable again, so drop the rest.



295
296
297
298
299
300
301
302
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 295

def self.prune_snapshot_cache(current)
  keep = File.basename(current)
  Dir.glob(File.join(File.dirname(current), '*.bin')).each do |f|
    next if File.basename(f) == keep
    FileUtils.rm_f([f, "#{f}.sha256", "#{f}.lock"])
  end
rescue StandardError
end

.read_verified_snapshot(path) ⇒ Object

‘Snapshot.load` doesn’t validate — corrupt bytes surface as a V8 FATAL abort at the first ‘Isolate.new`, long past any rescue here. Verify against the SHA sidecar written at persist time, so a truncated / corrupted blob rebuilds instead of crash-looping every subsequent run.



263
264
265
266
267
268
269
270
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 263

def self.read_verified_snapshot(path)
  return nil unless File.exist?(path)
  bytes = File.binread(path)
  sha   = File.read("#{path}.sha256").strip
  Digest::SHA256.hexdigest(bytes) == sha ? bytes : nil
rescue StandardError
  nil
end

.snapshot ⇒ Object 



168
169
170
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 168

def self.snapshot
  @@snapshot_lock.synchronize { @@snapshot ||= build_snapshot }
end

.snapshot_cache_path ⇒ Object 



272
273
274
275
276
277
278
279
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 272

def self.snapshot_cache_path
  return nil if ENV['CSIM_SNAPSHOT_CACHE'].to_s.casecmp('off').zero?
  dir = ENV['CSIM_SNAPSHOT_CACHE_DIR'] ||
        File.join(ENV['HOME'] || '/tmp', '.cache', 'capybara-simulated', 'snapshot')
  sha = Digest::SHA256.hexdigest(RuntimeShared.snapshot_src + SNAPSHOT_WARMUP)
  tag = cached_data_version_tag
  File.join(dir, "#{tag}-#{sha[0, 16]}.bin")
end

Instance Method Details

#attach_frame_realm_loader(c) ⇒ Object

The bridge calls ‘__csim_createFrameRealm(url, body, contentType)` (from `iframe.contentWindow`’s getter) to spin up a real per-iframe realm. This runs re-entrantly inside the main ctx’s eval — rusty services nested requests while a host callback is in flight. Returns the realm’s context id (or nil on failure — then the bridge keeps its same-realm fallback). The bridge maps ‘iframe.contentWindow` to `RustyRacer.contextGlobal(id)`.



545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 545

def attach_frame_realm_loader(c)
  c.attach('__csim_createFrameRealm', ->(url, body, content_type) {
    RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type) }
  })
  # Re-navigating an iframe (src/srcdoc reassigned) builds a fresh realm;
  # the bridge calls this to tear down the superseded one so it doesn't
  # linger in @frame_realms and get re-drained on every poll tick.
  # Disposing a non-executing child realm mid-callback is safe.
  c.attach('__csim_disposeFrameRealm', ->(id) {
    @realm_module_handles&.delete(id)
    fr = frame_realms.delete(id)
    fr.dispose rescue nil if fr
    nil
  })
end

#attach_host_fns(c) ⇒ Object 



532
533
534
535
536
537
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 532

def attach_host_fns(c)
  self.class.attach_host_fns(c, @browser)
  attach_run_script_with_cache(c)
  attach_native_module_loader(c)
  attach_frame_realm_loader(c)
end

#attach_native_module_loader(c) ⇒ Object

‘import(’x’)‘ routes through this callback; rusty’s native side finishes the dynamic import per the V8 host contract — it instantiates + evaluates the returned Module (TLA-aware, via the evaluation promise) before resolving the outer ‘import()` promise. The resolver is per-ISOLATE; rusty hands it the INITIATING realm’s Context as the third argument, so a frame realm’s ‘import()` compiles + links in that realm with its own handle cache — same realm-correctness as static `<script type=module>` via `attach_realm_esm_entry`.



715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 715

def attach_native_module_loader(c)
  c.attach('__csim_evalEsmEntry', ->(url, inline) {
    RuntimeShared.safe_call { eval_esm_module(url, inline) }
    nil
  })
  c.dynamic_import_resolver = ->(specifier, referrer, initiating) {
    target, handles =
      if initiating && initiating.id != 0
        [initiating, realm_module_handles(initiating.id)]
      else
        [ctx, native_module_handles]
      end
    resolved = @browser.resolve_module_specifier(specifier, referrer)
    m = native_module_for(resolved, nil, target, handles)
    raise "module not found: #{resolved}" unless m
    instantiate_native_module(m, resolved, target, handles)
    m
  }
end

#attach_realm_esm_entry(realm) ⇒ Object

Frame-document ‘<script type=module>` entry, bound to the realm.



744
745
746
747
748
749
750
751
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 744

def attach_realm_esm_entry(realm)
  realm.attach('__csim_evalEsmEntry', ->(url, inline) {
    RuntimeShared.safe_call {
      eval_esm_module(url, inline, target: realm, handles: realm_module_handles(realm.id))
    }
    nil
  })
end

#attach_run_script_with_cache(c) ⇒ Object 



783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 783

def attach_run_script_with_cache(c)
  version_tag = self.class.cached_data_version_tag
  debug = ENV['CSIM_SCRIPT_CACHE_DEBUG']
  # Big bodies → Ruby-side bytecode cache. The dispatcher below
  # routes small bodies to a JS-only `(0, eval)` so they don't
  # pay the rendezvous round-trip.
  c.attach('__csim_runScriptCached', ->(label, body) {
    RuntimeShared.safe_call {
      # Trailing `;undefined` suppresses the script's COMPLETION VALUE so
      # `script.run`'s return crosses the V8→Ruby boundary on the trivial
      # marshalling fast path. Without it, a large inline script ending
      # in a jQuery-ish expression returns a `ce.fn.init` (array-like,
      # non-cloneable) that drags through the deep-copy filter —
      # pure waste, since the value is discarded (`nil` below). The SHA keys
      # the bytecode cache on the COMPILED source, so the suffix must be
      # hashed and fed to `queue_warm` too (else cached_data is rejected).
      src = "#{body}\n;undefined"
      # No-cd warm path, mirroring `native_module_for`: once this
      # isolate has compiled a (label, bytesize), re-visits compile
      # straight against V8's source-keyed in-memory cache — skipping
      # the SHA256 of a 140KB+ chunk per visit (rbspy: ~4.8% of the
      # Discourse perf sample was Digest#update) AND the disk lookup.
      # The key is a heuristic, but a false positive only costs a
      # plain recompile of the true source — never wrong code.
      key = [label.to_s, src.bytesize]
      if @compiled_script_keys.key?(key)
        script = c.compile(src, filename: label.to_s)
      else
        sha    = Digest::SHA256.hexdigest(src)
        cached = ScriptCache.lookup(sha, version_tag)
        script = c.compile(src, filename: label.to_s, cached_data: cached)
        $stderr.puts "[runScript] label=#{label.to_s[0,60]} hit=#{!cached.nil?} rejected=#{script.cache_rejected?}" if debug
        # V8 forbids `produce_cache: true` from inside a host-fn
        # callback so we queue misses + rejects for top-level
        # produce via `ScriptCache.warm_pending!` after the
        # current `V8Runtime#call` returns.
        if cached.nil? || script.cache_rejected?
          ScriptCache.queue_warm(c, sha, label, src, version_tag, stale: !cached.nil?)
        end
        @compiled_script_keys[key] = true if key
      end
      begin
        script.run
      ensure
        script.dispose
      end
    }
    nil
  })
  # Small bodies normally run JS-side via `(0, eval)(body)` — fast,
  # no Ruby↔V8 boundary. But `(0, eval)` block-scopes a script's
  # top-level `const`/`let`/`class` to the eval, so they vanish
  # instead of landing in the realm's *shared* global lexical
  # environment where a later `<script>` would see them. Real
  # browsers (and our big-body `compile().run` path above) keep
  # them. The shape that needs this is a leading lexical
  # declaration: `<script>const CFG=…</script><script>…use CFG…` and
  # every WPT helper pulled in via `// META: script=` that starts
  # `const TABLE = […]` (sab.js's `createBuffer`, encodings.js's
  # `encodings_table`, …). So route ONLY scripts whose first real
  # statement is a top-level `const`/`let`/`class` through `ctx.eval`
  # (a top-level V8 script → shared lexical env); everything else
  # (IIFEs, `var`/`function` — which already leak to globalThis
  # under `(0, eval)` — and plain calls) stays on the fast path. A
  # later `(0, eval)` script can READ those bindings from the global
  # lexical environment fine; only DEFINING them needed the
  # real-script path. No bytecode cache here — the SHA + compile +
  # dispose is the part that regressed tiny-script-heavy suites
  # (Redmine 56→224 s); plain `ctx.eval` is rendezvous-cheap, and
  # the leading-lexical gate keeps the boundary off the hot path for
  # the ~95% of inline scripts that don't lead with a declaration.
  # Limitation: a top-level `const` that is NOT the first statement
  # (after other top-level code) won't be shared — rare, and the
  # WPT helper corpus + the `<script>const CFG…` pattern both lead
  # with the declaration.
  # NOTE: do NOT wrap in `safe_call`. A JS throw from `c.eval`
  # raises RustyRacer::RuntimeError, which rusty re-raises as a
  # JS exception at the call site — so bridge.entry.js's
  # `try { __csim_runScript(…) } catch (e)` sees it and runs its
  # normal path (console diagnostic, `_ok=false`, fire the script
  # `error` event), exactly as the JS-side `(0, eval)` does and
  # as the QuickJS runner does. Swallowing here would turn a
  # throwing leading-`const` inline script into a silent `load`.
  c.attach('__csim_runScriptEval', ->(label, body) {
    # Trailing `;undefined` makes the script's COMPLETION VALUE undefined so
    # `c.eval`'s return crosses the V8→Ruby boundary on the trivial
    # marshalling fast path. Without it, a leading-lexical inline script
    # ending in a jQuery-ish expression (`const cfg=…; $(…)`) returns a
    # `ce.fn.init` (array-like, non-cloneable) here, which falls into the
    # deep-copy filter slow-path — pure waste, since the value
    # is discarded (`nil` below). The `//# sourceURL` line is a comment and
    # doesn't affect the completion value; lexical declarations persist as a
    # side effect of eval, independent of the completion value.
    c.eval("#{body}\n;undefined\n//# sourceURL=#{label.to_s.tr("\n", ' ')}")
    nil
  })
  install_run_script_dispatcher(c)
end

#build_and_track_ctx ⇒ Object

build_ctx + register for at_exit cleanup.



497
498
499
500
501
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 497

def build_and_track_ctx
  c = build_ctx
  @@live_lock.synchronize { @@live << c }
  c
end

#build_ctx ⇒ Object 



524
525
526
527
528
529
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 524

def build_ctx
  c = Ctx.new(snapshot: @snapshot || self.class.snapshot, timeout: CALL_TIMEOUT_MS)
  attach_host_fns(c)
  c.eval('__csim_installWorker();')
  c
end

#call(name, *args) ⇒ Object 



328
329
330
331
332
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 328

def call(name, *args)
  result = ctx.call(name, *args)
  ScriptCache.warm_pending!
  result
end

#create_frame_realm(parent_ctx, url, body, content_type) ⇒ Object

Build the iframe’s realm: a snapshot-built isolate replays the whole bridge into every new context automatically, so the realm already has ‘document` / `DOMParser` / the event loop; re-seed the post-snapshot JS state, point it at its own URL with the top frame as parent/top, then load its document (running its scripts in the realm). Tracked for event-loop draining + teardown.



567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 567

def create_frame_realm(parent_ctx, url, body, content_type)
  realm = parent_ctx.create_context
  # Re-evaling the snapshot source would redefine snapshot globals (e.g.
  # the `scrollX` accessor) and throw — re-entrantly. Only eval the
  # source on a bare no-snapshot dev ctx, where the realm boots empty.
  # Host fns are replayed onto the realm by `Ctx#create_context`.
  has_bridge = realm.eval("typeof __csimLoadDocument === 'function'")
  realm.eval(RuntimeShared.snapshot_src) unless has_bridge
  # The replayed `__csim_runScriptCached` / `__csim_runScriptEval` /
  # `__csim_evalEsmEntry` close over the context they EXECUTE in (the
  # main ctx) — left as-is, a frame script that routes through them
  # (leading-lexical, ≥64KB, or `type=module`) would run against the
  # PARENT realm's document. Rebind realm-executing variants on top.
  attach_run_script_with_cache(realm)
  attach_realm_esm_entry(realm)
  reseed_realm_js(realm)
  # Wire parent/top to the main realm (context id 0). No user data in
  # this eval — only the literal namespace.
  realm.eval(<<~JS)
    if (globalThis.#{HOST_NAMESPACE_NAME} && typeof globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal === 'function') {
      var __topWin = globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal(0);
      globalThis.parent = __topWin; globalThis.top = __topWin;
    }
  JS
  # Pass the URL + document body as call ARGUMENTS, not interpolated into
  # an eval string: the marshaller carries them losslessly, so arbitrary
  # HTML / control bytes survive (Ruby's String#inspect is NOT a faithful
  # JS string escaper — it mangles \a, \e, and binary bytes).
  realm.call('__csimUpdateLocation', url.to_s) unless url.to_s.empty?
  realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
  frame_realms[realm.id] = realm
  realm.id
rescue StandardError => e
  @browser.log_console('warn', "frame realm load failed: #{e.message}")
  # A realm created before the failure (load threw) is untracked — not in
  # frame_realms nor __csimChildRealmIds — so nothing would ever drain or
  # dispose it. Tear it down here (safe: it's non-executing in the rescue),
  # including any module handles its scripts compiled before the throw.
  if realm
    @realm_module_handles&.delete(realm.id)
    realm.dispose rescue nil
  end
  nil
end

#ctx ⇒ Object

Built lazily on first use, on the calling (main) thread. There is no pool / background pre-warm: under warm-compile the steady-state visit reuses this one isolate via ‘Context#reset` (rebuild_ctx) and never builds another, so a pool’s async pre-warm bought nothing — and a pool dispatched to its entries from a refill thread before the main thread used them, migrating an isolate’s caller thread. Building here keeps every isolate confined to one thread for its whole life. The one-time synchronous build is ~3 ms.



492
493
494
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 492

def ctx
  @ctx ||= build_and_track_ctx
end

#dispose_frame_realms ⇒ Object 



366
367
368
369
370
371
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 366

def dispose_frame_realms
  @realm_module_handles&.clear
  return if @frame_realms.nil?
  @frame_realms.each_value {|fr| fr.dispose rescue nil }
  @frame_realms.clear
end

#drain_microtasks ⇒ Object

One native microtask checkpoint — a checkpoint runs the queue until empty, and rusty already performs one at the end of every top-level eval/call (V8’s default kAuto policy), so a single explicit checkpoint is all ‘settle` needs to advance chained `await`/`.then` queues between ticks.



378
379
380
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 378

def drain_microtasks
  @ctx&.perform_microtask_checkpoint
end

#drain_timers(max_ms = nil) ⇒ Object

bridge.js owns the virtual clock; Ruby still drives it because Capybara’s polling cadence is wall-clock-anchored. Use ‘call` (function reference) rather than `eval` (string compile) — the polling loop hits these every retry tick.



338
339
340
341
342
343
344
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 338

def drain_timers(max_ms = nil)
  # The bridge's `__drainTimers`/`__runLoopStep` step iframe realms' event
  # loops themselves (timers.js `drainChildRealms`), so this one call covers
  # child frames too — no separate Ruby-side fan-out (which would
  # double-advance their clocks and fire intervals twice).
  max_ms.nil? ? ctx.call('__drainTimers') : ctx.call('__drainTimers', max_ms.to_i)
end

#eval(code) ⇒ Object 



327
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 327

def eval(code)         = ctx.eval(code.to_s)

#eval_esm_module(url, inline_src = nil, target: nil, handles: nil) ⇒ Object

‘target` is the context the module graph compiles + evaluates in, `handles` its module-handle cache — the main ctx + `native_module_handles` by default, or a frame realm + its realm-local cache (Module handles are context-bound; sharing the main cache would link a frame’s imports against main-context modules).



617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 617

def eval_esm_module(url, inline_src = nil, target: nil, handles: nil)
  target  ||= ctx
  handles ||= native_module_handles
  m = native_module_for(url, inline_src, target, handles)
  return nil unless m
  begin
    instantiate_native_module(m, url, target, handles)
    m.evaluate
  rescue RustyRacer::ParseError, RustyRacer::RuntimeError => e
    # A top-level module throw belongs on the page console
    # (trace-visible diagnostics), like a classic script's error —
    # not just safe_call's truncated stderr warn. ScriptTerminatedError
    # deliberately propagates (a watchdog terminate must escalate).
    @browser.log_console('error', "module evaluate error in #{url}: #{e.message}")
  end
  nil
end

#frame_realms ⇒ Object

Per-iframe realms (‘Isolate#create_context`): a separate V8 context —own global + intrinsics (Function/Error/DOMParser/onerror) — per nested browsing context, so cross-realm tests behave per spec. Keyed by context id; released explicitly by `dispose_frame_realms` on every rebuild — under warm-compile the isolate survives the visit, so nothing else would ever free them.



364
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 364

def frame_realms = (@frame_realms ||= {})

#has_ready_timer? ⇒ Boolean

Returns:

  • (Boolean) 


395
396
397
398
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 395

def has_ready_timer?
  return false if @ctx.nil?
  !!ctx.call('__hasReadyTimer')
end

#install_run_script_dispatcher(c) ⇒ Object

The JS-side ‘__csim_runScript` dispatcher routes each inline-script body to the bytecode-cache path, the shared-lexical `ctx.eval` path, or the JS-only `(0, eval)` fast path. It snapshots the CURRENT `__csim_runScriptCached` / `__csim_runScriptEval` host fns, so it must run after the attaches it captures (`attach_run_script_with_cache` installs it last for exactly that reason).



888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 888

def install_run_script_dispatcher(c)
  c.eval(<<~JS)
    (function () {
      const cached    = globalThis.__csim_runScriptCached;
      const runEval   = globalThis.__csim_runScriptEval;
      const threshold = #{SCRIPT_CACHE_MIN_BYTES};
      // Leading top-level lexical declaration, after optional BOM /
      // whitespace / line+block comments / a "use strict" prologue.
      const LEADS_LEXICAL = /^[\\s\\uFEFF]*(?:(?:\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/)\\s*)*(?:["']use strict["'];?\\s*)?(?:export\\s+)?(?:const|let|class)[\\s{\\[]/;
      // A "use strict" directive prologue. A classic <script> evaluates as a
      // top-level Script, where top-level `var` / `function` declarations
      // bind on the global object even in strict mode — but the JS-only
      // `(0, eval)(body)` fast path runs them as an INDIRECT eval, and a
      // strict indirect eval gets its OWN variable environment, so those
      // declarations never reach globalThis (a later <script> can't see
      // them). Route strict-prologue scripts through the real top-level
      // `ctx.eval` path too, same as leading lexical declarations.
      const LEADS_USE_STRICT = /^[\\s\\uFEFF]*(?:(?:\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/)\\s*)*["']use strict["']/;
      globalThis.__csim_runScript = function (label, body) {
        if (body.length >= threshold) return cached(label, body);
        if (LEADS_LEXICAL.test(body) || LEADS_USE_STRICT.test(body)) return runEval(label || 'csim-eval', body);
        (0, eval)(body + '\\n//# sourceURL=' + (label || 'csim-eval'));
      };
    })();
  JS
end

#instantiate_native_module(m, importer_url, target, handles) ⇒ Object 



695
696
697
698
699
700
701
702
703
704
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 695

def instantiate_native_module(m, importer_url, target, handles)
  return unless m.status == :uninstantiated
  browser = @browser
  m.instantiate do |specifier, referrer|
    resolved = browser.resolve_module_specifier(specifier, referrer || importer_url)
    child = native_module_for(resolved, nil, target, handles)
    raise "module not found: #{resolved}" unless child
    child
  end
end

#module_body(url, src) ⇒ Object

A ‘.json` module is exposed as the default export of its parsed value; every other body is the fetched source as-is. Module SOURCE is text, but it arrives as the raw Rack / File.binread body — tagged ASCII-8BIT (see `RuntimeShared.utf8_text`).



639
640
641
642
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 639

def module_body(url, src)
  src = RuntimeShared.utf8_text(src)
  url.to_s.match?(/\.json(?:\?|$)/) ? "export default #{src};" : src
end

#native_module_for(url, inline_src, target, handles) ⇒ Object 



657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 657

def native_module_for(url, inline_src, target, handles)
  return handles[url] if handles.key?(url)
  url_s = url.to_s
  src = inline_src || @browser.rack_fetch_body(url_s)
  return handles[url] = nil unless src
  body = module_body(url_s, src)
  # No-cd warm path: once this isolate has compiled a URL, its in-memory
  # compilation cache holds the bytecode keyed by source — skip
  # `cached_data` so V8 hits that cache directly (~0.04 ms/module)
  # instead of paying the forced kConsumeCodeCache deserialize
  # (~0.15 ms/module). The first compile of each URL goes through the
  # on-disk bytecode cache and warms it. The in-memory cache is
  # source-keyed and re-populated by every compile, so a changed body
  # or a GC-aged-out entry costs ONE re-parse and is warm again — no
  # sticky cliff. (Only the on-disk blob for a changed body stays
  # unwarmed; acceptable, module URLs here are fingerprinted-
  # immutable.) Realms share the isolate's cache, so the tracking
  # applies to frame-realm compiles too. On a cold rebuild
  # `@compiled_module_urls` is cleared and everything returns to the
  # `cached_data` path.
  if inline_src.nil? && @compiled_module_urls.key?(url_s)
    m = target.compile_module(body, filename: url_s)
  else
    sha     = Digest::SHA256.hexdigest(body)
    version = self.class.cached_data_version_tag
    cached  = ScriptCache.lookup(sha, version, kind: :module)
    m       = target.compile_module(body, filename: url_s, cached_data: cached)
    if cached.nil? || m.cache_rejected?
      ScriptCache.queue_warm(target, sha, url_s, body, version, kind: :module, stale: !cached.nil?)
    end
    @compiled_module_urls[url_s] = true if inline_src.nil?
  end
  handles[url] = m
rescue RustyRacer::ParseError => e
  @browser.log_console('error', "module parse error in #{url}: #{e.message}")
  handles[url] = nil
end

#native_module_handles ⇒ Object

‘RustyRacer::Module` handles are bound to their realm; both rebuild paths invalidate them. The key carries `Ctx#generation` because a warm reset keeps the same Ctx OBJECT — object_id alone can’t see it.



647
648
649
650
651
652
653
654
655
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 647

def native_module_handles
  @native_module_handles ||= {}
  key = [ctx.object_id, ctx.generation]
  if @native_module_handles_key != key
    @native_module_handles     = {}
    @native_module_handles_key = key
  end
  @native_module_handles
end

#next_timer_delay_ms ⇒ Object

Delay (ms) until the nearest scheduled timer relative to the virtual clock, or -1 if none. Drives the horizon-gated fast-forward in ‘Browser#tick_real_time`.



403
404
405
406
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 403

def next_timer_delay_ms
  return -1 if @ctx.nil?
  ctx.call('__nextTimerDelay').to_i
end

#realm_module_handles(realm_id) ⇒ Object

Per-realm module-handle caches, keyed by realm id (Module handles are context-bound). Shared by the realm’s static ‘__csim_evalEsmEntry` and the isolate resolver’s dynamic-import routing; dropped with the realm in the dispose paths.



739
740
741
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 739

def realm_module_handles(realm_id)
  (@realm_module_handles ||= {})[realm_id] ||= {}
end

#rebuild_ctx ⇒ Object

Brings up a snapshot-fresh realm for the next page via the warm path: ‘Context#reset` swaps in a brand-new global on the long-lived isolate —a FULL fresh realm, not a partial in-context reset (those are unsafe per feedback_visit_always_rebuilds: library init guards stick, delegates leak) — keeping the isolate’s in-memory compilation cache + tiered-up code warm across visits (measured −4.5..19% suite wall). Only a refused reset falls back to the cold route: dispose the isolate and build a fresh one (synchronously, on this thread).



421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 421

def rebuild_ctx
  # Produce any queued bytecode-cache blobs while every queued target
  # (frame realms included) is still alive — a job queued by the last
  # activity of a test (e.g. a timer-fired dynamic import in a lazy
  # frame) would otherwise compile against a disposed context and be
  # dropped, leaving the disk cache permanently cold for that body.
  ScriptCache.warm_pending!
  # Drop the previous page's iframe realms (a new visit = new nested
  # browsing contexts). Explicit — under warm-compile the isolate
  # survives, so nothing else would ever release them.
  dispose_frame_realms
  # Warm path: per rusty's reset contract the snapshot is REPLAYED —
  # including its precompiled code cache — so re-visited app modules
  # compile at in-memory-hit cost (~3.3× cheaper than a cold
  # `cached_data` deserialize; see `@compiled_module_urls`). Host fns,
  # module handles (invalidated via `Ctx#generation`), and every
  # post-snapshot `c.eval` died with the old realm — re-seed exactly
  # as `build_ctx` does after `Ctx.new`. A refused reset (mid-drain /
  # suspended request — can't happen from these top-level call sites,
  # but the contract reserves it, e.g. after a watchdog terminate
  # wedges a nested rendezvous) falls back to the cold rebuild below —
  # loudly, because a persistent fallback is an invisible perf cliff
  # (and log_console is trace-gated, nil during reset!).
  if @ctx
    begin
      @ctx.reset
      attach_host_fns(@ctx)
      @ctx.eval('__csim_installWorker();')
      return @ctx
    rescue StandardError => e
      warn "[capybara-simulated] warm context reset failed, falling back to cold rebuild: #{e.class}: #{e.message}"
      @browser.log_console('warn', "warm context reset failed, falling back to full rebuild: #{e.message}")
    end
  end
  old = @ctx
  @ctx = nil
  # The cold rebuild brings up a *different* isolate, whose in-memory
  # compilation cache is cold — drop the no-cd tracking so the next
  # visit goes back through the on-disk bytecode-cache path.
  @compiled_module_urls.clear
  @compiled_script_keys.clear
  # Tear the old isolate down synchronously, on this (the only) thread
  # that ever drove it. Each isolate is created, used, and disposed on
  # the main thread — never dispatched to from a second thread (see
  # `ctx`), which rusty_racer's thread-confined isolates require. This
  # cold path is only the rare reset-failure fallback, so the inline
  # teardown isn't on the steady-state path.
  if old
    @@live_lock.synchronize { @@live.delete(old) }
    begin
      old.terminate rescue nil
      old.dispose
    rescue StandardError
    end
  end
  @ctx = build_and_track_ctx
end

#reseed_realm_js(c) ⇒ Object

A fresh per-frame realm boots from the snapshot, so every ‘globalThis.…` assignment csim ran post-snapshot in `build_ctx` is missing (realm state). Re-seed the `__csim_yield` alias and the `__csim_installWorker()` post-snapshot init; the `__csim_runScript` dispatcher comes from `attach_run_script_with_cache` (realm-bound).



920
921
922
923
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 920

def reseed_realm_js(c)
  c.eval("globalThis.__csim_yield = globalThis.#{HOST_NAMESPACE_NAME}.drainMicrotasks;")
  c.eval('__csim_installWorker();')
end

#reset_page ⇒ Object

Capybara calls ‘Driver#reset!` between tests; Browser delegates here. With per-visit rebuild already running, the inter-test path is the same operation.



482
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 482

def reset_page = rebuild_ctx

#reset_timers ⇒ Object 



408
409
410
411
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 408

def reset_timers
  return if @ctx.nil?
  ctx.call('__resetTimers')
end

#run_loop_step(max_ms, max_iter = 10_000, yield_on_gen: false) ⇒ Object

One event-loop step (task → microtask-checkpoint → render). Returns the ‘{ ’fired’, ‘gen’, ‘dirtied’ }‘ hash — `dirtied` (settleGen changed during the step) is the authoritative find-cache-invalidation signal, since a render-phase rAF / microtask-delivered MutationObserver can mutate the DOM without firing a timer (fired == 0).



351
352
353
354
355
356
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 351

def run_loop_step(max_ms, max_iter = 10_000, yield_on_gen: false)
  # `__runLoopStep` steps child iframe realms itself (timers.js
  # `drainChildRealms`), folding their fired/dirtied into the result.
  r = ctx.call('__runLoopStep', max_ms.to_i, max_iter.to_i, !!yield_on_gen)
  r.is_a?(Hash) ? r : { 'fired' => 0, 'gen' => 0, 'dirtied' => false }
end

#settle_gen ⇒ Object 



391
392
393
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 391

def settle_gen
  ctx.call('__settleGenGet').to_i
end

#wrap_binary(bytes) ⇒ Object

Raw bytes pass through as-is: rusty marshals tag-driven — a BINARY-encoded Ruby String crosses as a JS Uint8Array (and Uint8Array/ArrayBuffer args come back as BINARY Strings) — one copy, no base64 / latin1 string inflation. ‘transfer_buffer_fetch` already returns ASCII-8BIT-tagged bytes.



387
388
389
 
# File 'lib/capybara/simulated/v8_runtime.rb', line 387

def wrap_binary(bytes)
  bytes
end