capybara-simulated 0.0.6 → 0.1.0

data/lib/capybara/simulated/quickjs_runtime.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+# QuickJS-backed Runtime, alternate to `V8Runtime`. The DOM still lives
+# in JS (same bridge.js, same vendor bundle); this class swaps the engine to
+# trade JIT speed for ~10× smaller per-VM footprint — useful when the
+# scaling target is "many parallel workers on a fixed RAM budget"
+# rather than absolute per-spec wall time.
+#
+# Surface mirrors `V8Runtime` exactly: `eval` / `call` / `drain_timers`
+# / `drain_microtasks` / `settle_gen` / `has_ready_timer?` /
+# `reset_timers` / `rebuild_ctx` / `reset_page`. Browser code is
+# engine-agnostic.
+
+require 'digest'
+require 'quickjs'
+
+require_relative 'runtime_shared'
+require_relative 'worker_runtime'
+
+module Capybara
+  module Simulated
+    class QuickJSRuntime
+      # Compile the vendor bundle + bridge.js into bytecode once per process.
+      # Every per-visit VM replays this in ~10–20 ms (PR 31's microbench: 504KB
+      # bundle in ~4 ms; vendor + bridge is ~10× larger). Side effects (class
+      # definitions, the xpathway `Document.prototype.evaluate` install) run on
+      # each new VM — `compile` itself is pure (`COMPILE_ONLY` flag).
+      @@bridge_lock     = Mutex.new
+      @@bridge_runnable = nil
+
+      def self.bridge_runnable
+        @@bridge_lock.synchronize { @@bridge_runnable ||= Quickjs::VM.new.compile(RuntimeShared.snapshot_src, filename: 'csim_bridge.js') }
+      end
+
+      # Process-wide cache of compiled `<script>` bodies (classic + ESM
+      # factory wrappers). Bridge.js routes each body through
+      # `__csim_runScript`; first encounter compiles into bytecode, every
+      # subsequent visit replays the cached `Runnable` against the
+      # current VM. The compile (PR 31 microbench: 504 KB → ~4 ms; Avo's
+      # bundle is ~10×) is the cost we're skipping.
+      #
+      # No size cap: typical app surface is a few hundred unique bodies
+      # (jQuery, Stimulus, Turbo, app bundle, per-page inlines). If a
+      # test suite generates pathological cardinality we can add LRU
+      # later — for now the parser-overhead saving dwarfs the cache RSS.
+      @@runnable_cache_lock = Mutex.new
+      @@runnable_cache      = {}
+
+      # Sharing one compiler VM serialises compile calls, but compilation
+      # is CPU-bound C and parallel workers each have their own
+      # `QuickJSRuntime` class state (Ruby's `@@` is per-class, shared
+      # in-process). One compile-only VM is enough; creating a fresh
+      # `Quickjs::VM.new` per compile (~140 ms each for POLYFILL_INTL)
+      # would dwarf the compile itself.
+      @@compiler_lock = Mutex.new
+      @@compiler_vm   = nil
+
+      def self.runnable_for(body, label)
+        key    = Digest::SHA256.hexdigest(body)
+        cached = @@runnable_cache_lock.synchronize { @@runnable_cache[key] }
+        return cached if cached
+        fresh = @@compiler_lock.synchronize {
+          @@compiler_vm ||= Quickjs::VM.new
+          @@compiler_vm.compile(body, filename: label.to_s)
+        }
+        @@runnable_cache_lock.synchronize { @@runnable_cache[key] ||= fresh }
+      end
+
+      # Pre-warmed pool of bare `Quickjs::VM` instances. `Quickjs::VM.new`
+      # with `POLYFILL_INTL` is ~140 ms (FormatJS locale tables + IANA TZ
+      # bytecode); quickjs.rb #36 released the GVL during construction,
+      # so warmer threads build in parallel with the main thread.
+      # `build_vm` pops a pre-built VM and only pays for bridge replay +
+      # host-fn attach (~30 ms) on the hot path.
+      class VmPool
+        # 4 warmers × ~140 ms ≈ 28 VMs/sec — covers sustained demand for
+        # shared-spec-shaped runs. CAPACITY buffers short bursts before
+        # warmers backfill.
+        WARMER_COUNT = 4
+        CAPACITY     = 6
+
+        def initialize(vm_options)
+          @vm_options = vm_options
+          @queue      = SizedQueue.new(CAPACITY)
+          @threads    = WARMER_COUNT.times.map {|i|
+            Thread.new { warmer_loop }.tap {|t| t.name = "csim-qjs-warmer-#{i}" }
+          }
+        end
+
+        def checkout = @queue.pop
+
+        # SizedQueue#close unblocks pushers + makes future pops return
+        # nil — necessary at process exit because a warmer mid-`VM.new`
+        # has the GVL released and would SEGV on interpreter teardown.
+        def shutdown
+          @queue.close
+          @threads.each {|t| t.join(2) }
+        end
+
+        private
+
+        def warmer_loop
+          loop { @queue.push(Quickjs::VM.new(**@vm_options)) }
+        rescue ClosedQueueError
+          # process exit
+        end
+      end
+
+      @@pool_lock = Mutex.new
+      @@pool      = nil
+
+      def self.pool
+        @@pool_lock.synchronize { @@pool ||= VmPool.new(VM_OPTIONS) }
+      end
+
+      at_exit do
+        @@pool_lock.synchronize { @@pool&.shutdown }
+      rescue StandardError
+        # Best-effort at process exit.
+      end
+
+      def initialize(browser)
+        @browser  = browser
+        @vm       = nil
+        @runnable = self.class.bridge_runnable
+        self.class.pool # eager-start the warmers on first Browser
+      end
+
+      def eval(code)
+        v = vm
+        result = v.eval_code(code.to_s)
+        v.drain_jobs!
+        normalize(result)
+      end
+
+      # the V8 engine drains its microtask queue at
+      # the end of every call (V8's default microtask policy). QuickJS
+      # does not: `js_std_await` only pumps pending jobs while it's
+      # waiting for an actual Promise to resolve, and host-fn returns
+      # are plain values. Without a manual pump after every call,
+      # Promise.then chains queued during a host-fn body (Turbo's
+      # await fetch / Stimulus controllers, `evaluate_async_script`
+      # test scripts) stall until the next async boundary.
+      # `drain_jobs!` (quickjs.rb 0.18+) wraps `JS_ExecutePendingJob`
+      # in a loop to empty the queue, bounded by the VM's `timeout_msec`.
+      def call(name, *args)
+        v = vm
+        result = v.call(name.to_s, *args)
+        v.drain_jobs!
+        normalize(result)
+      end
+
+      # bridge.js owns the virtual clock; we drive it from Ruby because
+      # Capybara's polling cadence is wall-clock-anchored.
+      def drain_timers(max_ms = nil)
+        max_ms.nil? ? vm.call('__drainTimers') : vm.call('__drainTimers', max_ms.to_i)
+      end
+
+      # One event-loop step; returns `{ 'fired', 'gen', 'dirtied' }` (see
+      # V8Runtime#run_loop_step). `dirtied` = settleGen changed during the step.
+      def run_loop_step(max_ms, max_iter = 10_000, yield_on_gen: false)
+        r = vm.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
+
+      # `drain_jobs!` loops to queue-empty — one call is a full checkpoint,
+      # same contract as `V8Runtime#drain_microtasks`.
+      def drain_microtasks
+        vm.drain_jobs!
+      end
+
+      # No binary marshaler: QuickJS reinterprets high-bit bytes as UTF-8 and
+      # corrupts them, so binary payloads cross as base64 and the JS shim's
+      # `fetchedToBytes` atob's them back (see Browser#transfer_buffer_fetch_for_js).
+      def wrap_binary(bytes)
+        Base64.strict_encode64(bytes)
+      end
+
+      def settle_gen
+        vm.call('__settleGenGet').to_i
+      end
+
+      def has_ready_timer?
+        return false if @vm.nil?
+        !!vm.call('__hasReadyTimer')
+      end
+
+      # 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`.
+      def next_timer_delay_ms
+        return -1 if @vm.nil?
+        vm.call('__nextTimerDelay').to_i
+      end
+
+      def reset_timers
+        return if @vm.nil?
+        vm.call('__resetTimers')
+      end
+
+      # Tear down the current VM and build a fresh one from the
+      # precompiled bytecode. Partial in-VM resets carry the same
+      # library-init-leak hazards V8Runtime documents.
+      #
+      # We don't `@vm&.dispose!` before swapping: per-visit rebuilds
+      # happen on every spec example, and `dispose!` blocks on the
+      # quickjs GC running with the GVL held. Ruby GC will eventually
+      # reach the unreferenced VM and the gem's dfree handler frees
+      # the JSRuntime. The transient C-heap growth between GCs is the
+      # tradeoff for not paying ~hundreds of ms per spec.
+      def rebuild_ctx
+        @vm = build_vm
+      end
+
+      # Same operation as `rebuild_ctx` since per-visit rebuilds are
+      # already the inter-test reset point.
+      def reset_page = rebuild_ctx
+
+      # bridge.js patches `Intl.DateTimeFormat`; rusty_racer ships ICU
+      # built-in but QuickJS gates it behind a polyfill flag. Other JS
+      # surfaces bridge.js touches (URL / TextEncoder / atob/btoa /
+      # crypto) are already routed through Ruby-side host fns, so
+      # POLYFILL_INTL is the only one we strictly need.
+      #
+      # `max_stack_size: 0` — `JS_SetMaxStackSize` measures C stack
+      # delta from runtime construction; Ruby callers reach QuickJS
+      # through deep stacks (Capybara `synchronize` + RSpec matchers +
+      # bridge.js's class init closures), so the default 4 MB trips on
+      # routine `check_stale → __csimAlive` calls. `0` disables the
+      # check; OS thread stack is the real ceiling.
+      #
+      # `timeout_msec: (2**31)-1` — quickjs.rb default eval timeout is
+      # 100 ms; bridge.js's `__csimEvaluateXPath` / `__csimDispatchEvent`
+      # chains routinely exceed that on Avo-scale documents under
+      # QuickJS's interpreter. 0 means "interrupt immediately" (the
+      # handler returns `elapsed >= limit_ms`, so 0 fires on the first
+      # check), so practical no-limit.
+      VM_OPTIONS = {
+        features:       [Quickjs::POLYFILL_INTL].freeze,
+        max_stack_size: 0,
+        # quickjs.rb's 128 MB default trips "out of memory in regexp
+        # execution" on class-attribute-heavy polls and the heaviest
+        # Mastodon hydrate (cumulative heap, not a single allocation).
+        # 512 MB clears the ceiling without idle cost — `JS_SetMemoryLimit`
+        # is a malloc ceiling, not a reservation.
+        memory_limit:   512 * 1024 * 1024,
+        # `drain_jobs!` loops `JS_ExecutePendingJob` until the
+        # queue empties — but Forem's article-feed render schedules
+        # new microtasks faster than they drain, so without a timer
+        # the call never returns. Real per-spec eval rarely runs over
+        # a second, and a 30 s ceiling is far below "hung CI worker"
+        # while leaving headroom for the heaviest Mastodon hydrate.
+        timeout_msec:   30_000
+      }.freeze
+
+      # Evaluates `url` as an ES module. For external `<script
+      # type="module" src="…">`, pass `src=nil` so QuickJS goes through
+      # `module_loader` to fetch — the URL becomes the module's
+      # identity. For inline `<script type="module">{…}</script>`,
+      # pass the body as `src` and let QuickJS compile it inline (the
+      # synthesised `#inline-…` URL becomes the module's identity, but
+      # transitive imports still go through `module_loader`).
+      #
+      # `quickjs.rb`'s `vm.import` distinguishes these by which keyword
+      # arg you pass: `filename:` alone → loader fetch; `from:` alone →
+      # inline compile. Passing both makes the gem ignore the body.
+      def eval_esm_module(url, src = nil)
+        v = vm
+        opts = src ? { from: src.to_s } : { filename: url.to_s }
+        opts[:code_to_expose] = ''
+        v.import("* as __csim_entry_#{rand(1 << 32)}", **opts)
+        v.drain_jobs!
+      end
+
+      private
+
+      def vm
+        @vm ||= build_vm
+      end
+
+      def build_vm
+        v = self.class.pool.checkout
+        @runnable.run(on: v)
+        attach_host_fns(v)
+        attach_module_loader(v)
+        attach_rejection_tracker(v)
+        v.eval_code('__csim_installWorker();')
+        v
+      end
+
+      def attach_host_fns(v)
+        self.class.attach_host_fns(v, @browser)
+        # Re-enter the same VM to run the body. `Runnable` is portable
+        # bytecode (no scope binding); replaying on `v` evaluates at
+        # globalThis, matching `(0, eval)(body)` semantics that
+        # bridge.js previously used directly. Script-throwing errors
+        # propagate as JS exceptions for bridge.js's caller-side
+        # try/catch.
+        v.define_function('__csim_runScript') {|label, body|
+          self.class.runnable_for(body.to_s, label).run(on: v)
+          nil
+        }
+        # Native-ESM entry. `bridge.js`'s `runModuleScript` calls this
+        # for every `<script type="module">`; V8 registers it too via
+        # `V8Runtime#attach_native_module_loader`.
+        browser = @browser
+        v.define_function('__csim_evalEsmEntry') {|url, inline_src|
+          RuntimeShared.safe_call { browser.eval_esm_module(url, inline_src) }
+          nil
+        }
+      end
+
+      # Class-level attach so Worker isolates (per-thread VMs that
+      # don't have a Runtime instance) reuse the same host-fn table.
+      def self.attach_host_fns(v, browser)
+        RuntimeShared::BROWSER_HOST_FNS.each {|name, body|
+          v.define_function(name) {|*a| RuntimeShared.safe_call { body.call(browser, *a) } }
+        }
+        RuntimeShared::STDLIB_HOST_FNS.each {|name, body|
+          v.define_function(name, &body)
+        }
+        # `dispatchEventForUserAction` calls this between listener
+        # invocations. `drain_jobs!` loops `JS_ExecutePendingJob` until
+        # the queue is empty, matching V8's
+        # `MicrotasksScope::PerformCheckpoint`. Older quickjs.rb
+        # without `drain_jobs!` falls back to a no-op.
+        if v.respond_to?(:drain_jobs!)
+          v.define_function('__csim_yield') { v.drain_jobs!; nil }
+        else
+          v.define_function('__csim_yield') { nil }
+        end
+      end
+
+      # Worker-isolate factory: fresh VM, bridge bytecode replayed,
+      # host fns attached *after* the replay (so snapshot_stubs.js's
+      # no-ops don't overwrite real ones), `__csim_isWorker` set, +
+      # the per-worker postMessage routed through `post_back`.
+      def self.build_worker(browser, post_back)
+        vm = Quickjs::VM.new(**VM_OPTIONS)
+        bridge_runnable.run(on: vm)
+        attach_host_fns(vm, browser)
+        vm.define_function('__csim_workerPostMessage') {|data| post_back.call(data); nil }
+        # Override main's __setTimersActive so worker's empty-timer-map
+        # flip doesn't race main's `polling?` gate. See v8_runtime's
+        # build_worker for the long-form rationale.
+        vm.define_function('__setTimersActive') {|_flag| nil }
+        vm.eval_code('__csim_installWorkerScope();')
+        vm.drain_jobs!
+        WorkerRuntime.new(
+          eval_fn:           ->(s)     { v = vm.eval_code(s.to_s); vm.drain_jobs!; v },
+          call_fn:           ->(n, *a) { v = vm.call(n.to_s, *a); vm.drain_jobs!; v },
+          drain_microtasks:  ->        { vm.drain_jobs! },
+          drain_timers:      ->        { vm.call('__drainTimers', 50) },
+          has_ready_timer:   ->        { !!vm.call('__hasReadyTimer') },
+          # quickjs.rb has no explicit dispose; GC reclaims the VM.
+          dispose:           ->        { nil }
+        )
+      end
+
+      # QuickJS's native ESM loader. The Ruby block returns the source
+      # for each module URL; QuickJS handles parsing, live bindings,
+      # `import.meta`, and `import()` natively. quickjs.rb 0.18 passes
+      # the raw specifier + importer URL. Bare specifiers go through
+      # `Browser#resolve_module_specifier` so importmap entries
+      # (Stimulus / unbundled apps) resolve correctly; relative paths
+      # resolve against the importer. `nil` from `rack_fetch_body`
+      # propagates to QuickJS which raises a ReferenceError mirroring
+      # a real-browser 404.
+      def attach_module_loader(v)
+        browser = @browser
+        v.module_loader = ->(specifier, importer) {
+          resolved = browser.resolve_module_specifier(specifier, importer)
+          body = browser.rack_fetch_body(resolved)
+          return nil unless body
+          # `.json` (and `?import` JSON) imports come from Vite's
+          # `import.meta.glob` and `import x from './data.json'`
+          # patterns. quickjs.rb's loader passes the source through
+          # `JS_EVAL_TYPE_MODULE` regardless of extension, so we wrap
+          # JSON bodies in `export default …` ourselves. Real
+          # browsers gate on `with { type: 'json' }`; Vite's bundler
+          # output already injected that, but the resulting module
+          # source is just the raw JSON so we need the wrap either way.
+          code = resolved.to_s.match?(/\.json(?:\?|$)/) ? "export default #{body};" : body
+          # Return `{ code:, as: }` so QuickJS caches by the resolved
+          # absolute URL — necessary for subsequent relative imports
+          # to use this URL as their importer, not the raw specifier.
+          {code: code, as: resolved.to_s}
+        }
+      end
+
+      # Funnel unhandled Promise rejections into `console.error` so
+      # they show up in trace output / user-installed `log_console`
+      # overrides. Without this, an async chain that rejects without
+      # a `.catch` disappears silently — the same class of bug that
+      # cost half a session debugging Intl.Collator (the throw fired
+      # inside a module body we couldn't see).
+      def attach_rejection_tracker(v)
+        browser = @browser
+        v.on_unhandled_rejection do |reason|
+          msg = "#{reason.class}: #{reason.message}"
+          stack = reason.backtrace&.any? ? "\n#{reason.backtrace.first(20).join("\n")}" : ''
+          browser.log_console('error', "unhandled rejection: #{msg}#{stack}")
+        end
+      end
+
+      # QuickJS marshals JS `undefined` as the symbol
+      # `Quickjs::Value::UNDEFINED`; rusty_racer marshals it as `nil`. The
+      # rest of the gem expects `nil`, so normalize at the boundary.
+      # NaN gets the same treatment for consistency (the bridge never
+      # surfaces it as a load-bearing value).
+      UNDEFINED = Quickjs::Value::UNDEFINED
+      NAN       = Quickjs::Value::NAN
+
+      def normalize(value)
+        case value
+        when UNDEFINED, NAN then nil
+        when Hash  then value.transform_values {|v| normalize(v) }
+        when Array then value.map {|v| normalize(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/capybara/simulated/runtime_shared.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'securerandom'
+
+require_relative 'webauthn_state'
+
+
+module Capybara
+  module Simulated
+    # Bits common to `V8Runtime` and `QuickJSRuntime` — JS asset paths,
+    # the host-fn table that bridge.js reaches back through, the
+    # error-swallowing wrapper. Each engine plugs the table into its
+    # own attach API (rusty_racer's `Context#attach` vs quickjs.rb's
+    # `Quickjs::VM#define_function`).
+    module RuntimeShared
+      BRIDGE_JS         = File.expand_path('js/bridge.bundle.js',                 __dir__).freeze
+      SNAPSHOT_STUBS_JS = File.expand_path('js/snapshot_stubs.js',                __dir__).freeze
+      VENDOR_BUNDLE_JS  = File.expand_path('../../../vendor/js/vendor.bundle.js', __dir__).freeze
+
+      def self.snapshot_stubs_src = File.read(SNAPSHOT_STUBS_JS)
+      def self.bridge_src         = File.read(BRIDGE_JS)
+      def self.vendor_bundle_src  = File.read(VENDOR_BUNDLE_JS)
+
+      # Combined source baked into the V8 Snapshot / QuickJS bytecode.
+      # Order matters: stubs first (so bridge's IIFE can reference the
+      # `globalThis.__rackFetch` etc. slots), then the vendor bundle
+      # (so bridge can reference `globalThis.__csimVendor.cssSelect` and
+      # `.xpathway`), then bridge proper — which installs the xpathway-backed
+      # `Document.prototype.evaluate` itself (see js/src/xpath.js). The
+      # standalone xpathway engine in the vendor blob replaces the old wgxpath.
+      def self.snapshot_src
+        snapshot_stubs_src +
+          vendor_bundle_src + ";\n" +
+          bridge_src
+      end
+
+      # Host fns whose body touches `Browser` — wrap with `safe_call`
+      # so a Ruby-side bug in the Browser path doesn't propagate as a
+      # JS exception that crashes the whole script chain. Bodies take
+      # `(browser, *js_args)` and return whatever the JS caller expects.
+      BROWSER_HOST_FNS = {
+        '__rackFetch'                => ->(b, *a) { b.rack_fetch(a[0], a[1], a[2], a[3], a[4]) },
+        '__csimExternalAsset'        => ->(b, *a) { b.external_asset_source(a[0]) },
+        '__locationAssign'           => ->(b, *a) { b.location_assign(a[0]); nil },
+        '__locationReload'           => ->(b, *_) { b.location_reload; nil },
+        '__setTimersActive'          => ->(b, *a) { b.timers_active = !!a[0]; nil },
+        '__setCurrentUrl'            => ->(b, *a) { b.history_state(a[0], a[1]); nil },
+        '__pushHistoryEntry'         => ->(b, *a) { b.history_push(a[0], a[1]); nil },
+        '__historyGo'                => ->(b, *a) { b.history_go(a[0]); nil },
+        '__historyLength'            => ->(b, *_) { b.history_length },
+        '__csimReadFilePick'         => ->(b, *a) { b.read_file_pick(a[0], a[1], a[2], a[3]) },
+        '__getDocumentCookie'        => ->(b, *_) { b.document_cookie },
+        '__setDocumentCookie'        => ->(b, *a) { b.write_document_cookie(a[0].to_s); nil },
+        '__getDocumentReferrer'      => ->(b, *_) { b.current_referer },
+        '__csim_storageGet'          => ->(b, *a) { b.storage_get(a[0], a[1]) },
+        '__csim_storageSet'          => ->(b, *a) { b.storage_set(a[0], a[1], a[2]); nil },
+        '__csim_storageRemove'       => ->(b, *a) { b.storage_remove(a[0], a[1]); nil },
+        '__csim_storageClear'        => ->(b, *a) { b.storage_clear(a[0]); nil },
+        '__csim_storageKey'          => ->(b, *a) { b.storage_key(a[0], a[1]) },
+        '__csim_storageLength'       => ->(b, *a) { b.storage_length(a[0]) },
+        '__csimGeolocationState'     => ->(b, *_) { b.geolocation_state_json },
+        '__modalDialog'              => ->(b, *a) { b.handle_modal(a[0], a[1], a[2]) },
+        '__csim_pushImportmap'       => ->(b, *a) { b.set_importmap(a[0]); nil },
+        '__csim_logConsole'          => ->(b, *a) { b.log_console(a[0], a[1]); nil },
+        '__csim_eventSourceOpen'     => ->(b, *a) { b.event_source_open(a[0]) },
+        '__csim_eventSourceClose'    => ->(b, *a) { b.event_source_close(a[0]); nil },
+        '__csim_rackFetchAsync'      => ->(b, *a) { b.rack_fetch_async(a[0], a[1], a[2], a[3]) },
+        '__csim_rackFetchAsyncAbort' => ->(b, *a) { b.rack_fetch_async_abort(a[0]); nil },
+        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0]) },
+        '__csim_workerPostToWorker'  => ->(b, *a) { b.worker_post_to_worker(a[0], a[1]); nil },
+        '__csim_workerTerminate'     => ->(b, *a) { b.worker_terminate(a[0]); nil },
+        '__csim_decodeImage'         => ->(b, *a) { b.decode_image(a[0], a[1], a[2]) },
+        '__csim_blobRegister'        => ->(b, *a) { b.blob_register(a[0], a[1]); nil },
+        '__csim_blobResolve'         => ->(b, *a) { b.blob_resolve(a[0]) },
+        '__csim_blobUnregister'      => ->(b, *a) { b.blob_unregister(a[0]); nil },
+        '__csim_transferStash'       => ->(b, *a) { b.transfer_buffer_stash(a[0]) },
+        '__csim_transferFetch'       => ->(b, *a) { b.transfer_buffer_fetch_for_js(a[0]) },
+        '__csim_decodeVideoFrame'    => ->(b, *a) { b.decode_video_frame(a[0]) },
+        '__csim_encodeImage'         => ->(b, *a) { b.encode_image(a[0], a[1], a[2], a[3], a[4]) },
+        # WebAuthn create / get raise `WebauthnState::Error` carrying
+        # the DOMException name (`InvalidStateError`, …); rescue here
+        # so the JS shim sees `{error:, name:}` instead of the
+        # `safe_call`-flattened nil that would collapse every failure
+        # to a generic NotAllowedError.
+        '__csimWebauthnCreate' => ->(b, *a) {
+          begin b.webauthn.create(a[0]); rescue WebauthnState::Error => e
+            {'error' => e.message, 'name' => e.webauthn_name}
+          end
+        },
+        '__csimWebauthnGet' => ->(b, *a) {
+          begin b.webauthn.get(a[0]); rescue WebauthnState::Error => e
+            {'error' => e.message, 'name' => e.webauthn_name}
+          end
+        },
+        '__csimWebauthnAddVirtualAuthenticator'    => ->(b, *a) { b.webauthn.add_virtual_authenticator(a[0]) },
+        '__csimWebauthnRemoveVirtualAuthenticator' => ->(b, *a) { b.webauthn.remove_virtual_authenticator(a[0]); nil },
+        '__csimWebauthnAddCredential'              => ->(b, *a) { b.webauthn.add_credential(a[0], a[1]); nil },
+        '__csimWebauthnRemoveCredential'           => ->(b, *a) { b.webauthn.remove_credential(a[0], a[1]); nil },
+        '__csimWebauthnGetCredentials'             => ->(b, *a) { b.webauthn.get_credentials(a[0]) },
+        '__csimWebauthnSetUserVerified'            => ->(b, *a) { b.webauthn.set_user_verified(a[0], a[1]); nil }
+      }.freeze
+
+      # Host fns that route to pure stdlib — no Browser surface,
+      # nothing to safe_call, no allocation needed for the wrap. Skip
+      # the rescue overhead on every per-find / per-event invocation.
+      # Process-wide cascade-rule cache (mirrors the script bytecode cache). The
+      # built {hide, layout} rules are deterministic per (stylesheet-set,
+      # viewport), so the JS side caches the serialized rules keyed by a digest of
+      # the sheet sources and skips the ~12-15 ms css-tree parse + per-rule
+      # specificity + terminalKey rebuild on every per-visit VM rebuild. Lives in
+      # Ruby (not the VM) so it survives `rebuild_ctx`. Key space is tiny (one app
+      # ships one stylesheet set), so the map stays small; no eviction needed.
+      CASCADE_RULE_CACHE       = {}
+      CASCADE_RULE_CACHE_MUTEX = Mutex.new
+
+      # Process-wide PER-SHEET parse cache (companion to CASCADE_RULE_CACHE). The
+      # built whole-cascade is cached above, but it misses whenever a page's inline
+      # `<style>` changes (Avo injects per-page styles), forcing a rebuild that
+      # re-parses every sheet — including unchanged linked bundles (avo.base.css).
+      # `parseSheet` is pure, so the JS side caches its serialized `{hide,layout}`
+      # keyed by (cssText hash, viewport) here, surviving the per-visit VM rebuild
+      # that wipes the in-VM `__sheetCache` — the CSS analogue of the JS bytecode
+      # cache. Keyed by content, so a content change yields a new key. Capped.
+      SHEET_PARSE_CACHE       = {}
+      SHEET_PARSE_CACHE_MUTEX = Mutex.new
+      SHEET_PARSE_CACHE_MAX   = 2048
+
+      STDLIB_HOST_FNS = {
+        '__csimCascadeCacheGet' => ->(*a) { CASCADE_RULE_CACHE_MUTEX.synchronize { CASCADE_RULE_CACHE[a[0].to_s] } },
+        '__csimCascadeCachePut' => lambda {|*a|
+          CASCADE_RULE_CACHE_MUTEX.synchronize { CASCADE_RULE_CACHE[a[0].to_s] = a[1].to_s }
+          nil
+        },
+        '__csimSheetCacheGet' => ->(*a) { SHEET_PARSE_CACHE_MUTEX.synchronize { SHEET_PARSE_CACHE[a[0].to_s] } },
+        '__csimSheetCachePut' => lambda {|*a|
+          SHEET_PARSE_CACHE_MUTEX.synchronize {
+            SHEET_PARSE_CACHE.clear if SHEET_PARSE_CACHE.size >= SHEET_PARSE_CACHE_MAX
+            SHEET_PARSE_CACHE[a[0].to_s] = a[1].to_s
+          }
+          nil
+        },
+        '__csim_randomUUID'   => ->(*_) { SecureRandom.uuid },
+        '__csim_randomBytes'  => ->(*a) { SecureRandom.bytes(a[0].to_i).bytes },
+        '__csim_atob'         => ->(*a) { Base64.decode64(a[0].to_s) },
+        '__csim_btoa'         => ->(*a) { Base64.strict_encode64(a[0].to_s) },
+        '__csim_utf8Encode'   => ->(*a) { a[0].to_s.b.bytes },
+        '__csim_utf8Decode'   => ->(*a) { a[0].pack('C*').force_encoding('UTF-8') },
+        # `__csim_parseUrl` is defined in JS now (js/src/url-parse.js, backed by
+        # the vendored whatwg-url) — spec-correct + no V8↔Ruby boundary per parse.
+        # Web Crypto SubtleCrypto.digest — algo is "SHA-1"/"SHA-256"/etc.
+        # JS hands us the byte array; we return the digest as bytes.
+        '__csim_subtleDigest' => lambda {|*a|
+          algo  = a[0].to_s.upcase.tr('-', '')
+          bytes = a[1].is_a?(Array) ? a[1].pack('C*') : a[1].to_s
+          OpenSSL::Digest.new(algo).digest(bytes).bytes
+        }
+      }.freeze
+
+      def self.safe_call
+        yield
+      rescue StandardError => e
+        warn "[capybara-simulated] host fn error: #{e.class}: #{e.message[0, 200]}"
+        warn "  at #{e.backtrace&.first(4)&.join("\n  at ")}" if ENV['CSIM_HOSTFN_TRACE'] == '1'
+        nil
+      end
+
+      # Re-tag a text string for the Ruby→JS crossing. Marshalling is
+      # tag-driven: a BINARY-tagged String crosses as a Uint8Array, and a
+      # UTF-8-tagged string with invalid bytes raises — but Rack bodies,
+      # socket reads, and header values all arrive BINARY-tagged even when
+      # they ARE text. Decoding response bytes into text is the document
+      # layer's job (csim owns the charset knowledge; the contract is UTF-8),
+      # so every text crossing funnels through here: re-tag as UTF-8, scrub
+      # only actually-invalid bytes.
+      def self.utf8_text(s)
+        s = s.dup.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+        s.valid_encoding? ? s : s.scrub
+      end
+    end
+  end
+end