capybara-simulated 0.7.0 → 0.8.0

data/lib/capybara/simulated/node.rb

@@ -122,16 +122,31 @@ module Capybara
         self
       end
 
-      def scroll_to(*, **)       ; self ; end
+      # Capybara's driver `scroll_to` contract (from Element#scroll_to): a target element + align
+      # symbol, a position symbol (`:top`/`:bottom`/`:center`), or an `[x, y]` coordinate pair.
+      # `self` is the element it was called on — the document root for a session-level scroll (routed
+      # via `find('/html')`), else an element. Drives a real scroll offset in the layout engine.
+      def scroll_to(target = nil, arg = nil, coords = nil)
+        check_stale
+        if target
+          browser.scroll_to(handle_id, target.handle_id, arg)
+        elsif coords
+          browser.scroll_to(handle_id, nil, nil, coords[0], coords[1])
+        elsif arg
+          browser.scroll_to(handle_id, nil, arg)
+        end
+        self
+      end
 
       # Capybara's standard rect API. No layout engine — but
-      # Discourse's `wait_for_animation` helper polls `element.rect[:x]`
-      # twice and waits for the values to stabilise, which they
-      # immediately do here (constant zeros) since we never animate.
-      # That unblocks every test guarded by an animation settle.
+      # The element's coarse border-box (viewport-relative), from the layout engine — backs the
+      # spatial selectors (`:above`/`:below`/`:near`) and coordinate drag. Deterministic per layout
+      # generation (memoised; only a DOM/style mutation changes it), so Discourse's
+      # `wait_for_animation` — which polls `element.rect[:x]` twice and waits for it to stabilise —
+      # still settles immediately when nothing is animating.
       def rect
         check_stale
-        {x: 0, y: 0, width: 0, height: 0, top: 0, left: 0, bottom: 0, right: 0}
+        browser.rect(handle_id)
       end
 
       def send_keys(*keys)
@@ -195,7 +210,10 @@ module Capybara
       def selected?        = browser.option_selected?(handle_id)
       def checked?         = !!self['checked']
       def readonly?        = !!self['readonly']
-      def obscured?(*)     = !visible?
+      def obscured?(*)
+        check_stale
+        browser.obscured?(handle_id)
+      end
       def synchronize(*)   = yield
       def style(names = [])
         check_stale

data/lib/capybara/simulated/quickjs_runtime.rb

@@ -13,6 +13,23 @@
 
 require 'digest'
 require 'quickjs'
+begin
+  # Intl moved out of the quickjs gem in 0.19. bridge.js patches Intl.DateTimeFormat, so the
+  # companion gem is required for the QuickJS engine — say so plainly rather than letting a bare
+  # LoadError name a file the user never asked for.
+  require 'quickjs-polyfill-intl/datetimeformat'
+rescue LoadError
+  raise LoadError, <<~MSG
+    capybara-simulated's QuickJS engine needs the `quickjs-polyfill-intl` gem
+    (quickjs 0.19 moved Intl out of the core gem, and the DOM bridge uses
+    Intl.DateTimeFormat). Add it next to quickjs:
+
+        gem 'quickjs', '>= 0.19'
+        gem 'quickjs-polyfill-intl'
+
+    Or use the V8 engine (`gem 'rusty_racer'`), which has ICU built in.
+  MSG
+end
 
 require_relative 'runtime_shared'
 require_relative 'worker_runtime'
@@ -150,6 +167,19 @@ module Capybara
         normalize(result)
       end
 
+      # QuickJS has no per-frame realms (iframes share the one VM): `within_frame` falls back to
+      # the same realm, and any realm id routes to the single global context.
+      def supports_frames? = false
+
+      def realm_call(_realm_id, name, *args) = call(name, *args)
+
+      # No per-frame realms, so no realm is ever "alive" as a distinct browsing context —
+      # every client id resolves to 'client-window' (the single global). Defined so a
+      # caller that gates realm routing on it (deliver_worker_messages) works on both engines.
+      def frame_realm_alive?(_realm_id) = false
+
+      def frame_realm_ids = []
+
       # 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)
@@ -230,14 +260,17 @@ module Capybara
       # URL / TextEncoder / atob/btoa / crypto — already route through Ruby host fns,
       # so POLYFILL_INTL is the only one we strictly need).
       #
-      # PERF (rule 3): quickjs is pinned to `~> 0.18.0` in the Gemfile. quickjs 0.19
-      # both split the Intl polyfills into a separate quickjs-polyfill-intl gem (which
-      # eval's them per VM at ~226 ms — vs this single bundled flag's ~140 ms) AND
-      # regressed interpreter execution ~2.8× (measured: the QuickJS spec suite ran
-      # 5.6 min on 0.18 vs 15.5 min on 0.19 with an equivalent Intl set). The 0.19
-      # migration is recorded in the cross-window / quickjs-CI memory; re-migrate to
-      # 0.19 + quickjs-polyfill-intl once that upstream perf regression is fixed.
-      INTL_FEATURES = [Quickjs::POLYFILL_INTL].freeze
+      # Since 0.19 the Intl polyfills live in the separate `quickjs-polyfill-intl`
+      # gem, registered by name instead of quickjs's old bundled `POLYFILL_INTL`
+      # flag. `:polyfill_intl_datetimeformat_all` is the whole DateTimeFormat chain
+      # (getcanonicallocales → locale → pluralrules → numberformat → datetimeformat)
+      # as ONE registration — the only chain bridge.js needs, and cheaper than
+      # requiring the five links separately.
+      #
+      # PERF (rule 3): the polyfill source is eval'd per VM, and the VM-pool pre-warm
+      # used to be GVL-serial, which put every feature on the critical path. quickjs
+      # now releases the GVL while loading polyfills, so the pre-warm overlaps.
+      INTL_FEATURES = [:polyfill_intl_datetimeformat_all].freeze
       #
       # `max_stack_size: 0` — `JS_SetMaxStackSize` measures C stack
       # delta from runtime construction; Ruby callers reach QuickJS
@@ -352,11 +385,21 @@ module Capybara
       # 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)
+      def self.build_worker(browser, post_back, broadcast_out = nil, sw_hooks = {})
         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 }
+        # A worker's BroadcastChannel fan-out routes through the thread-safe outbox, not
+        # `browser.broadcast_to_windows` (cross-thread inbox mutation). See v8_runtime#build_worker.
+        vm.define_function('__csimBroadcast') {|name, data, _rid, origin| broadcast_out&.call(name, data, origin); nil } if broadcast_out
+        # Service-worker → main-thread signals via the outbox (see v8_runtime#build_worker).
+        vm.define_function('__csim_swPostToClient') {|client_id, data| sw_hooks[:post_to_client]&.call(client_id, data); nil } if sw_hooks[:post_to_client]
+        vm.define_function('__csim_swClaim') { sw_hooks[:claim]&.call; nil } if sw_hooks[:claim]
+        vm.define_function('__csim_swFetchRespond') {|fetch_id, resp, realm_id| sw_hooks[:fetch_respond]&.call(fetch_id, resp, realm_id); nil } if sw_hooks[:fetch_respond]
+        vm.define_function('__csim_swFetchStream') {|fetch_id, kind, payload, realm_id| sw_hooks[:fetch_stream]&.call(fetch_id, kind, payload, realm_id); nil } if sw_hooks[:fetch_stream]
+        vm.define_function('__csim_workerPortPost')     {|channel, data| sw_hooks[:port_post]&.call(channel, data); nil } if sw_hooks[:port_post]
+        vm.define_function('__csim_workerPortEndpoint') {|channel|       sw_hooks[:port_endpoint]&.call(channel); nil } if sw_hooks[:port_endpoint]
         # 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.

data/lib/capybara/simulated/runtime_shared.rb

@@ -41,7 +41,7 @@ module Capybara
       # 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], a[5], credentials: a[6] || 'same-origin', referrer_policy: a[7], referrer: a[8], cache_mode: a[9] || 'default') },
+        '__rackFetch'                => ->(b, *a) { b.rack_fetch(a[0], a[1], a[2], a[3], a[4], a[5], credentials: a[6] || 'same-origin', referrer_policy: a[7], referrer: a[8], cache_mode: a[9] || 'default', initiator: a[10], site_seed: a[11], origin_null: a[12]) },
         '__csimExternalAsset'        => ->(b, *a) { b.external_asset_source(a[0]) },
         '__locationAssign'           => ->(b, *a) { b.location_assign(a[0]); nil },
         '__locationReload'           => ->(b, *_) { b.location_reload; nil },
@@ -62,6 +62,10 @@ module Capybara
         # like __csimFrameNavigate — see Browser#frame_submit_self.
         '__csimFrameSubmit'          => ->(b, *a) { b.frame_submit_self(a[0].to_i); nil },
         '__csimFrameHistoryGo'       => ->(b, *a) { b.frame_history_go(a[0].to_i, a[1].to_i); nil },
+        # A frame `src=` re-navigation records a session-history entry (snapshotting the OUTGOING
+        # document) so history.go(-1) can traverse back — and a controlling SW sees
+        # isHistoryNavigation. Must run while the outgoing realm (a[0]) is still alive.
+        '__csim_recordFrameNav'      => ->(b, *a) { b.record_frame_nav(a[0].to_i, a[1]); 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 },
@@ -72,11 +76,24 @@ module Capybara
         '__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_storageSet'          => ->(b, *a) { b.storage_set(a[0], a[1], a[2]) },
         '__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]) },
+        '__csimStorageChanged'       => ->(b, *a) { b.storage_changed(a[0], a[1], a[2], a[3], a[4], a[5]); nil },
+        # Cache Storage — origin-partitioned (a[0] = origin key), Ruby-backed so it
+        # survives the per-visit VM rebuild and is shared between a service worker and
+        # the client it controls. The JS side (cache-storage.js) owns the spec matching;
+        # Ruby is a dumb ordered store keyed by (origin, cache name).
+        '__csim_cacheStorageOpen'    => ->(b, *a) { b.cache_storage_open(a[0], a[1]) },
+        '__csim_cacheStorageHas'     => ->(b, *a) { b.cache_storage_has(a[0], a[1]) },
+        '__csim_cacheStorageDelete'  => ->(b, *a) { b.cache_storage_delete(a[0], a[1]) },
+        '__csim_cacheStorageKeys'    => ->(b, *a) { b.cache_storage_keys(a[0]) },
+        '__csim_cacheEntries'        => ->(b, *a) { b.cache_entries(a[0], a[1]) },
+        '__csim_cacheEntryResponse'  => ->(b, *a) { b.cache_entry_response(a[0], a[1], a[2]) },
+        '__csim_cachePut'            => ->(b, *a) { b.cache_put(a[0], a[1], a[2], a[3], a[4]); nil },
+        '__csim_cacheDeleteEntries'  => ->(b, *a) { b.cache_delete_entries(a[0], a[1], a[2]) },
         '__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 },
@@ -98,7 +115,15 @@ module Capybara
         # forces noopener for a cross-partition blob: target.
         '__csimOpenAuxFromRealm'     => ->(b, *a) { b.open_aux_from_realm(a[0], a[1], a[2]); nil },
         '__csimWindowPostMessage'    => ->(b, *a) { b.post_message_to_window(a[0], a[1], a[2]); nil },
-        '__csimBroadcast'            => ->(b, *a) { b.broadcast_to_windows(a[0], a[1], a[2].to_i); nil },
+        '__csimBroadcast'            => ->(b, *a) { b.broadcast_to_windows(a[0], a[1], a[2].to_i, a[3]); nil },
+        # BroadcastChannel isolate-wide, creation-ordered registry (the multi-realm delivery path). A
+        # channel registers on construction / unregisters on close; `bc_post` snapshots the eligible
+        # targets at post time and queues one ordered delivery per target. Only consulted when a sibling
+        # same-isolate realm exists (`bc_siblings_exist?`); single-window pages never touch it.
+        '__csimBcRegister'           => ->(b, *a) { b.bc_register(a[0], a[1], a[2], a[3]); nil },
+        '__csimBcUnregister'         => ->(b, *a) { b.bc_unregister(a[0], a[1]); nil },
+        '__csimBcPost'               => ->(b, *a) { b.bc_post(a[0], a[1], a[2], a[3], a[4], a[5]); nil },
+        '__csimBcSiblingsExist'      => ->(b, *_a) { b.bc_siblings_exist? },
         '__csimWindowGet'            => ->(b, *a) { b.window_get(a[0], a[1]) },
         '__csimWindowDocGet'         => ->(b, *a) { b.window_doc_get(a[0], a[1]) },
         # Cross-window remote-ref RPC: route an opener's node/object proxy op to
@@ -115,13 +140,43 @@ module Capybara
         # Fire an aux window's OWN `load` event (in its VM) — deferred by the
         # opener so a child `window.onload` runs after the opener's current task.
         '__csimFireAuxWindowLoad'    => ->(b, *a) { b.fire_aux_window_load(a[0]); nil },
-        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0], shared: !!a[1]) },
+        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0], shared: !!a[1], creator_key: a[2]) },
         # navigator.serviceWorker.register (universal-server only) — spawn a worker
         # running the SW script as an executor context. Returns its handle.
-        '__csim_serviceWorkerRegister' => ->(b, *a) { b.worker_spawn(a[0], service: true) },
+        '__csim_serviceWorkerRegister' => ->(b, *a) { b.worker_spawn(a[0], service: true, creator_key: a[1]) },
         '__csim_workerPostToWorker'  => ->(b, *a) { b.worker_post_to_worker(a[0], a[1]); nil },
+        # ServiceWorker.postMessage from a client window → the SW's `message` event (source = client).
+        '__csim_serviceWorkerPostMessage' => ->(b, *a) { b.service_worker_post_message(a[0], a[1], a[2], a[3]); nil },
+        # Cross-isolate MessagePort channel (client-realm side): register this realm's endpoint, and
+        # relay a client-realm port's postMessage to its remote (worker/SW) peer.
+        '__csimClientPortEndpoint' => ->(b, *a) { b.port_channel_endpoint_realm(a[0], a[1]); nil },
+        '__csimClientPortPost'     => ->(b, *a) { b.client_port_post(a[0], a[1]); nil },
+        # A controlled client's fetch → the controlling SW's `fetch` event. Returns false if the SW
+        # is gone (client falls back to the network).
+        '__csim_serviceWorkerControllerFetch' => ->(b, *a) { b.service_worker_controller_fetch(a[0], a[1], a[2], a[3]) },
+        # A controlled client cancelled a streaming respondWith body → cancel the SW's source stream
+        # (routed to the worker that owns this [realm, fetch] stream). See sw_stream_cancel.
+        '__csim_swStreamCancel'               => ->(b, *a) { b.sw_stream_cancel(a[0], a[1]); nil },
+        # Client lifecycle mirrors scope→active-worker into Ruby so a navigation (fetched
+        # Ruby-side before the destination realm's JS exists) can find its controlling SW.
+        '__csim_swRegisterScope'      => ->(b, *a) { b.sw_register_scope(a[0], a[1]); nil },
+        '__csim_swUnregisterScope'    => ->(b, *a) { b.sw_unregister_scope(a[0]); nil },
+        # The active worker handle at an EXACT scope (0 if none), so a register() from a realm with no
+        # local registration (a different iframe registering an already-active scope) can synthesize a
+        # registration reflecting the shared active worker instead of installing a duplicate.
+        '__csim_swActiveHandleForScope' => ->(b, *a) { b.sw_active_handle_for_scope(a[0]) },
+        # Navigation Preload state (NavigationPreloadManager), keyed by the registration's active
+        # worker handle — reached identically from the client (registration.active._handle) and the
+        # worker (__csimWorkerHandle). Get returns {enabled, headerValue}; set leaves a nil field as-is.
+        '__csim_swNavPreloadState'    => ->(b, *a) { b.nav_preload_state(a[0]) },
+        '__csim_swNavPreloadSet'      => ->(b, *a) { b.nav_preload_set(a[0], a[1], a[2]); nil },
+        # A navigation (iframe/document load) → its controlling SW's `fetch` event, awaited
+        # synchronously. Returns the response wire hash, or nil to load from the network.
+        '__csim_swNavigationFetch'    => ->(b, *a) { b.service_worker_navigation_fetch(a[0], is_reload: !!a[1], is_history: !!a[2], referrer_source: a[3], method: a[4] || 'GET', body_b64: a[5] || '', content_type: a[6]) },
         '__csim_workerTerminate'     => ->(b, *a) { b.worker_terminate(a[0]); nil },
         '__csim_decodeImage'         => ->(b, *a) { b.decode_image(a[0], a[1], a[2]) },
+        '__csim_renderText'          => ->(b, *a) { b.render_text(a[0], a[1], a[2], a[3], a[4]) },
+        '__csim_loadImage'           => ->(b, *a) { b.load_image(a[0], !!a[1], a[2] || 'same-origin') },
         '__csim_blobRegister'        => ->(b, *a) { b.blob_register(a[0], a[1], a[2]); nil },
         # WHATWG/UTS46 IDNA for the URL parser's host processing (the JS tr46 stub
         # delegates non-ASCII / xn-- hosts here; ASCII stays in-VM).
@@ -144,6 +199,7 @@ module Capybara
         # eager-@app.calls a foreign URL (side effects: extra visit / log row).
         '__csim_allHostsLocal'       => ->(b, *a) { b.send(:all_hosts_local?) },
         '__csim_decodeVideoFrame'    => ->(b, *a) { b.decode_video_frame(a[0]) },
+        '__csim_videoBytesB64'       => ->(b, *a) { b.video_bytes_b64(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
@@ -215,15 +271,377 @@ module Capybara
         '__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.
+        # Web Crypto raw primitives, backed by OpenSSL. The JS side (js/src/webcrypto.js)
+        # owns the whole SubtleCrypto contract — algorithm normalization, CryptoKey
+        # objects, usage validation, the DOMException grammar — and calls these only for
+        # the actual number-crunching. Byte arguments cross as plain Arrays (JS packs a
+        # BufferSource into one); results return as byte Arrays.
+        #
+        # digest — algo is "SHA1"/"SHA256"/… (JS strips the dash and upcases).
         '__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
+        },
+        # HMAC sign — args: (hash "SHA256", keyBytes, dataBytes) → mac bytes. verify is
+        # done JS-side by re-signing and comparing, so no separate host fn is needed.
+        '__csim_hmacSign' => lambda {|*a|
+          hash = a[0].to_s.upcase.tr('-', '')
+          key  = a[1].is_a?(Array) ? a[1].pack('C*') : a[1].to_s
+          data = a[2].is_a?(Array) ? a[2].pack('C*') : a[2].to_s
+          OpenSSL::HMAC.digest(OpenSSL::Digest.new(hash), key, data).bytes
+        },
+        # AES encrypt/decrypt — args: (cipher "aes-256-gcm", key, iv, data, aad, tagBytes).
+        # For GCM the JS side follows the WebCrypto layout (ciphertext ‖ truncated tag), so
+        # encrypt appends the tagBytes-long tag and decrypt splits it back off before
+        # verifying; a tag mismatch / bad padding raises CipherError, which the JS layer
+        # maps to OperationError. CBC/CTR pass tagBytes 0 and an empty aad.
+        '__csim_aesEncrypt' => lambda {|*a|
+          name = a[0].to_s
+          key  = a[1].is_a?(Array) ? a[1].pack('C*') : a[1].to_s
+          iv   = a[2].is_a?(Array) ? a[2].pack('C*') : a[2].to_s
+          data = a[3].is_a?(Array) ? a[3].pack('C*') : a[3].to_s
+          aad  = a[4].is_a?(Array) ? a[4].pack('C*') : a[4].to_s
+          tagbytes = a[5].to_i
+          c = OpenSSL::Cipher.new(name)
+          c.encrypt
+          c.key = key
+          c.iv_len = iv.bytesize if name.end_with?('-gcm')   # GCM defaults to 12; allow any length
+          c.iv  = iv
+          if name.end_with?('-gcm')
+            c.auth_data = aad
+            ct = c.update(data) + c.final
+            (ct + c.auth_tag(tagbytes)).bytes
+          else
+            (c.update(data) + c.final).bytes
+          end
+        },
+        '__csim_aesDecrypt' => lambda {|*a|
+          name = a[0].to_s
+          key  = a[1].is_a?(Array) ? a[1].pack('C*') : a[1].to_s
+          iv   = a[2].is_a?(Array) ? a[2].pack('C*') : a[2].to_s
+          data = a[3].is_a?(Array) ? a[3].pack('C*') : a[3].to_s
+          aad  = a[4].is_a?(Array) ? a[4].pack('C*') : a[4].to_s
+          tagbytes = a[5].to_i
+          c = OpenSSL::Cipher.new(name)
+          c.decrypt
+          c.key = key
+          c.iv_len = iv.bytesize if name.end_with?('-gcm')
+          c.iv  = iv
+          if name.end_with?('-gcm')
+            ct  = data[0, data.bytesize - tagbytes]
+            tag = data[data.bytesize - tagbytes, tagbytes]
+            c.auth_data = aad
+            c.auth_tag  = tag
+            (c.update(ct) + c.final).bytes
+          else
+            (c.update(data) + c.final).bytes
+          end
+        },
+        # RSA — keys cross as their DER encoding (SPKI for public, PKCS#8 for private)
+        # in a byte Array; the host re-parses per call (OpenSSL::PKey.read auto-detects).
+        # generateKey returns the private PKCS#8 DER, from which the JS side derives the
+        # public key and parameters via the export / key-info fns below.
+        '__csim_rsaGenerate' => lambda {|*a|
+          bits = a[0].to_i
+          exp  = OpenSSL::BN.new(crypto_bytes(a[1]), 2).to_i
+          OpenSSL::PKey::RSA.generate(bits, exp).private_to_der.bytes
+        },
+        # Re-encode a key to 'spki' (public) or 'pkcs8' (private). Asking a private key
+        # for 'spki' yields its public half — how generateKey obtains the public key.
+        '__csim_rsaExport' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          a[1].to_s == 'spki' ? key.public_to_der.bytes : key.private_to_der.bytes
+        },
+        # Modulus length (bits) + public exponent (big-endian bytes) for key.algorithm.
+        '__csim_rsaKeyInfo' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          { 'modulusLength' => key.n.num_bits, 'publicExponent' => key.e.to_s(2).bytes }
+        },
+        # Build a key DER from JWK components (big-endian byte arrays). Public keys pass
+        # only n/e; private keys pass the full CRT set. Returns SPKI / PKCS#8 DER bytes.
+        '__csim_rsaImportJwk' => lambda {|*a|
+          RuntimeShared.rsa_jwk_to_der(*a).bytes
+        },
+        # Explode a key DER into JWK components (big-endian byte arrays). Private keys
+        # include the CRT parameters; public keys carry only n/e.
+        '__csim_rsaExportJwk' => lambda {|*a|
+          RuntimeShared.rsa_der_to_jwk(a[0])
+        },
+        # sign/verify — scheme 'pkcs1' (RSASSA-PKCS1-v1_5) or 'pss' (RSA-PSS, MGF1 with
+        # the same hash, saltLength in bytes). verify swallows OpenSSL errors to a false.
+        '__csim_rsaSign' => lambda {|*a|
+          key  = RuntimeShared.pkey_read(a[0])
+          hash = a[1].to_s
+          data = crypto_bytes(a[2])
+          if a[3].to_s == 'pss'
+            key.sign_pss(hash, data, salt_length: a[4].to_i, mgf1_hash: hash).bytes
+          else
+            key.sign(hash, data).bytes
+          end
+        },
+        '__csim_rsaVerify' => lambda {|*a|
+          key  = RuntimeShared.pkey_read(a[0])
+          hash = a[1].to_s
+          data = crypto_bytes(a[2])
+          sig  = crypto_bytes(a[3])
+          begin
+            if a[4].to_s == 'pss'
+              key.verify_pss(hash, sig, data, salt_length: a[5].to_i, mgf1_hash: hash)
+            else
+              key.verify(hash, sig, data)
+            end
+          rescue OpenSSL::PKey::PKeyError
+            false
+          end
+        },
+        # RSA-OAEP encrypt/decrypt — MGF1 + OAEP with the key's hash and an optional label.
+        # `rsa_oaep_label` takes a HEX string, not raw bytes (OpenSSL parses it via
+        # prepare_from_text), so the label crosses hex-encoded.
+        '__csim_rsaEncrypt' => lambda {|*a|
+          key   = RuntimeShared.pkey_read(a[0])
+          opts  = { rsa_padding_mode: 'oaep', rsa_oaep_md: a[1].to_s }
+          label = crypto_bytes(a[3])
+          opts[:rsa_oaep_label] = label.unpack1('H*') unless label.empty?
+          key.encrypt(crypto_bytes(a[2]), opts).bytes
+        },
+        '__csim_rsaDecrypt' => lambda {|*a|
+          key   = RuntimeShared.pkey_read(a[0])
+          opts  = { rsa_padding_mode: 'oaep', rsa_oaep_md: a[1].to_s }
+          label = crypto_bytes(a[3])
+          opts[:rsa_oaep_label] = label.unpack1('H*') unless label.empty?
+          key.decrypt(crypto_bytes(a[2]), opts).bytes
+        },
+        # Elliptic curve (ECDSA / ECDH). The JS side passes the OpenSSL curve name
+        # ('prime256v1' / 'secp384r1' / 'secp521r1') and the field byte length so the
+        # host stays curve-agnostic. Keys cross as SPKI / PKCS#8 DER.
+        '__csim_ecGenerate' => lambda {|*a|
+          OpenSSL::PKey::EC.generate(a[0].to_s).private_to_der.bytes
+        },
+        '__csim_ecExport' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          case a[1].to_s
+          when 'spki'  then key.public_to_der.bytes
+          when 'pkcs8' then key.private_to_der.bytes
+          else key.public_key.to_octet_string(:uncompressed).bytes   # 'raw' → uncompressed point
+          end
+        },
+        '__csim_ecKeyInfo' => lambda {|*a|
+          { 'curve' => RuntimeShared.pkey_read(a[0]).group.curve_name }
+        },
+        '__csim_ecImportRaw' => lambda {|*a|
+          RuntimeShared.ec_point_spki(a[0].to_s, crypto_bytes(a[1])).bytes
+        },
+        # args: (curve, isPrivate, x, y, [d, n]). The uncompressed public point is
+        # 0x04 ‖ x ‖ y; a private key additionally carries the scalar d (padded to n).
+        '__csim_ecImportJwk' => lambda {|*a|
+          curve = a[0].to_s
+          point = "\x04".b + crypto_bytes(a[2]) + crypto_bytes(a[3])
+          if a[1]
+            RuntimeShared.ec_priv_pkcs8(curve, crypto_bytes(a[4]), point, a[5].to_i).bytes
+          else
+            RuntimeShared.ec_point_spki(curve, point).bytes
+          end
+        },
+        '__csim_ecExportJwk' => lambda {|*a|
+          RuntimeShared.ec_der_to_jwk(a[0], a[1].to_i)
+        },
+        '__csim_ecdsaSign' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          der = key.sign(OpenSSL::Digest.new(a[1].to_s), crypto_bytes(a[2]))
+          RuntimeShared.ecdsa_der_to_raw(der, a[3].to_i).bytes
+        },
+        '__csim_ecdsaVerify' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          der = RuntimeShared.ecdsa_raw_to_der(crypto_bytes(a[3]), a[4].to_i)
+          begin
+            der ? key.verify(OpenSSL::Digest.new(a[1].to_s), der, crypto_bytes(a[2])) : false
+          rescue OpenSSL::PKey::PKeyError
+            false
+          end
+        },
+        # Key derivation — HKDF / PBKDF2 produce `nbytes` bytes; ECDH computes the raw
+        # shared secret (field size). The JS side truncates to the requested bit length.
+        '__csim_hkdf' => lambda {|*a|
+          OpenSSL::KDF.hkdf(crypto_bytes(a[1]), salt: crypto_bytes(a[2]), info: crypto_bytes(a[3]), length: a[4].to_i, hash: a[0].to_s).bytes
+        },
+        '__csim_pbkdf2' => lambda {|*a|
+          OpenSSL::KDF.pbkdf2_hmac(crypto_bytes(a[1]), salt: crypto_bytes(a[2]), iterations: a[3].to_i, length: a[4].to_i, hash: a[0].to_s).bytes
+        },
+        '__csim_ecdhDerive' => lambda {|*a|
+          priv = RuntimeShared.pkey_read(a[0])
+          pub  = RuntimeShared.pkey_read(a[1])
+          priv.dh_compute_key(pub.public_key).bytes
+        },
+        # AES-KW (RFC 3394 key wrap). The cipher width follows the wrapping key; OpenSSL's
+        # wrap mode supplies the default A6A6… IV. A tampered wrap raises on unwrap, which
+        # the JS layer maps to OperationError.
+        '__csim_aesKwWrap' => lambda {|*a|
+          key = crypto_bytes(a[0])
+          c = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-wrap")
+          c.encrypt
+          c.key = key
+          (c.update(crypto_bytes(a[1])) + c.final).bytes
+        },
+        '__csim_aesKwUnwrap' => lambda {|*a|
+          key = crypto_bytes(a[0])
+          c = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-wrap")
+          c.decrypt
+          c.key = key
+          (c.update(crypto_bytes(a[1])) + c.final).bytes
+        },
+        # OKP curves (Ed25519 signatures / X25519 key agreement). The JS side passes the
+        # OpenSSL curve name ('ED25519' / 'X25519'); keys cross as SPKI / PKCS#8 DER, and
+        # the raw form is the 32-byte public (or private, via JWK `d`) key.
+        '__csim_okpGenerate' => lambda {|*a|
+          OpenSSL::PKey.generate_key(a[0].to_s).private_to_der.bytes
+        },
+        '__csim_okpExport' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          case a[1].to_s
+          when 'spki'  then key.public_to_der.bytes
+          when 'pkcs8' then key.private_to_der.bytes
+          else key.raw_public_key.bytes                     # 'raw' → 32-byte public key
+          end
+        },
+        '__csim_okpImportRaw' => lambda {|*a|
+          OpenSSL::PKey.new_raw_public_key(a[0].to_s, crypto_bytes(a[1])).public_to_der.bytes
+        },
+        # Parse + re-emit a canonical OKP DER — validates the SPKI/PKCS#8 structure at
+        # import time (a truncated / malformed key raises, which JS maps to DataError)
+        # instead of storing the bytes blindly and only failing on first use.
+        '__csim_okpImportDer' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[1])
+          a[0].to_s == 'private' ? key.private_to_der.bytes : key.public_to_der.bytes
+        },
+        '__csim_okpImportJwk' => lambda {|*a|
+          type = a[0].to_s
+          if a[1]
+            key = OpenSSL::PKey.new_raw_private_key(type, crypto_bytes(a[3]))
+            # The JWK "x" (public) must equal the public key derived from "d" — a mismatch is
+            # an invalid key pair (DataError on the JS side).
+            raise OpenSSL::PKey::PKeyError, 'OKP JWK x does not match d' unless key.raw_public_key == crypto_bytes(a[2])
+            key.private_to_der.bytes
+          else
+            OpenSSL::PKey.new_raw_public_key(type, crypto_bytes(a[2])).public_to_der.bytes
+          end
+        },
+        '__csim_okpExportJwk' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          jwk = { 'x' => key.raw_public_key.bytes }
+          jwk['d'] = key.raw_private_key.bytes if a[1]      # a[1] = the key is private
+          jwk
+        },
+        '__csim_ed25519Sign' => lambda {|*a|
+          RuntimeShared.pkey_read(a[0]).sign(nil, crypto_bytes(a[1])).bytes
+        },
+        '__csim_ed25519Verify' => lambda {|*a|
+          key = RuntimeShared.pkey_read(a[0])
+          begin
+            key.verify(nil, crypto_bytes(a[2]), crypto_bytes(a[1]))
+          rescue OpenSSL::PKey::PKeyError
+            false
+          end
+        },
+        '__csim_x25519Derive' => lambda {|*a|
+          RuntimeShared.pkey_read(a[0]).derive(RuntimeShared.pkey_read(a[1])).bytes
         }
       }.freeze
 
+      # Pack a host-fn byte argument (a JS BufferSource crosses as an Array) into a
+      # binary String for OpenSSL.
+      def self.crypto_bytes(a)
+        a.is_a?(Array) ? a.pack('C*') : a.to_s
+      end
+
+      # Parse an RSA / EC key from its DER bytes (SPKI public or PKCS#8 private —
+      # OpenSSL::PKey.read auto-detects both).
+      def self.pkey_read(der_bytes)
+        OpenSSL::PKey.read(crypto_bytes(der_bytes))
+      end
+
+      # ECDSA signatures cross as the WebCrypto IEEE-P1363 form — r ‖ s, each padded to
+      # the curve's field byte length — while OpenSSL speaks DER. Convert both ways.
+      def self.ecdsa_der_to_raw(der, n)
+        asn = OpenSSL::ASN1.decode(der)
+        r = asn.value[0].value.to_s(2).rjust(n, "\x00".b)
+        s = asn.value[1].value.to_s(2).rjust(n, "\x00".b)
+        r + s
+      end
+
+      def self.ecdsa_raw_to_der(raw, n)
+        return nil unless raw.bytesize == 2 * n   # wrong length → verify fails, not raises
+        r = OpenSSL::BN.new(raw[0, n], 2)
+        s = OpenSSL::BN.new(raw[n, n], 2)
+        OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(r), OpenSSL::ASN1::Integer(s)]).to_der
+      end
+
+      def self.ec_algid(curve)
+        OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId(curve)])
+      end
+
+      # SPKI DER for an EC public key from its uncompressed point (0x04 ‖ x ‖ y).
+      def self.ec_point_spki(curve, point)
+        OpenSSL::ASN1::Sequence([ec_algid(curve), OpenSSL::ASN1::BitString(point)]).to_der
+      end
+
+      # PKCS#8 DER for an EC private key from the private scalar `d` and public point,
+      # via the RFC 5915 ECPrivateKey structure (OpenSSL 3 dropped component setters).
+      def self.ec_priv_pkcs8(curve, d, point, n)
+        ec_priv = OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::Integer(1),
+          OpenSSL::ASN1::OctetString(d.rjust(n, "\x00".b)),
+          OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::ObjectId(curve)], 0, :CONTEXT_SPECIFIC),
+          OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::BitString(point)], 1, :CONTEXT_SPECIFIC)
+        ]).to_der
+        OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(0), ec_algid(curve), OpenSSL::ASN1::OctetString(ec_priv)]).to_der
+      end
+
+      # Explode an EC key DER into JWK coordinates (x, y, and d for a private key), each a
+      # big-endian byte Array padded to the field length; plus the OpenSSL curve name.
+      def self.ec_der_to_jwk(der_bytes, n)
+        key   = pkey_read(der_bytes)
+        point = key.public_key.to_octet_string(:uncompressed)   # 0x04 ‖ x ‖ y
+        jwk   = { 'curve' => key.group.curve_name, 'x' => point[1, n].bytes, 'y' => point[1 + n, n].bytes }
+        jwk['d'] = key.private_key.to_s(2).rjust(n, "\x00".b).bytes if key.private_key?
+        jwk
+      end
+
+      # Assemble an RSA key DER from JWK components. `is_private` selects between a
+      # public SPKI (n, e) and a private PKCS#8 with the full CRT set. Each component is
+      # a big-endian byte Array. Building the ASN.1 by hand is the OpenSSL-3-supported
+      # path (the deprecated `rsa.n = …` setters are gone).
+      def self.rsa_jwk_to_der(is_private, n, e, d = nil, p = nil, q = nil, dp = nil, dq = nil, qi = nil)
+        bn     = ->(b) { OpenSSL::BN.new(crypto_bytes(b), 2) }
+        alg_id = OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('rsaEncryption'), OpenSSL::ASN1::Null(nil)])
+        if is_private
+          pkcs1 = OpenSSL::ASN1::Sequence([
+            OpenSSL::ASN1::Integer(0),
+            OpenSSL::ASN1::Integer(bn.(n)), OpenSSL::ASN1::Integer(bn.(e)), OpenSSL::ASN1::Integer(bn.(d)),
+            OpenSSL::ASN1::Integer(bn.(p)), OpenSSL::ASN1::Integer(bn.(q)),
+            OpenSSL::ASN1::Integer(bn.(dp)), OpenSSL::ASN1::Integer(bn.(dq)), OpenSSL::ASN1::Integer(bn.(qi))
+          ]).to_der
+          OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(0), alg_id, OpenSSL::ASN1::OctetString(pkcs1)]).to_der
+        else
+          pkcs1 = OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(bn.(n)), OpenSSL::ASN1::Integer(bn.(e))]).to_der
+          OpenSSL::ASN1::Sequence([alg_id, OpenSSL::ASN1::BitString(pkcs1)]).to_der
+        end
+      end
+
+      # Explode an RSA key DER into JWK components (big-endian byte Arrays). Private keys
+      # carry the full CRT set; public keys only n/e.
+      def self.rsa_der_to_jwk(der_bytes)
+        key = pkey_read(der_bytes)
+        jwk = { 'n' => key.n.to_s(2).bytes, 'e' => key.e.to_s(2).bytes }
+        if key.private?
+          jwk.merge!(
+            'd'  => key.d.to_s(2).bytes,   'p'  => key.p.to_s(2).bytes,   'q'  => key.q.to_s(2).bytes,
+            'dp' => key.dmp1.to_s(2).bytes, 'dq' => key.dmq1.to_s(2).bytes, 'qi' => key.iqmp.to_s(2).bytes
+          )
+        end
+        jwk
+      end
+
       def self.safe_call
         yield
       rescue StandardError => e